explorable

Files (6)

• .DS_Store
• SKILL.md
• aesthetics.md
• openai.yaml · agents/
• primitives.md
• writing.md

SKILL.md (first lines)

# /explorable — turn markdown into a single-file interactive

## Thesis

A wall of text is often a diagram, map, model, or simulation that hasn't
been rendered yet.

> Don't make the reader reconstruct what the machine can render.

If the source's argument is visual, temporal, spatial, causal, comparative,
procedural, or branching, prose alone is a tax. Render the structure
directly. If none of that applies, the source probably doesn't want this
skill.

The user opted in by invoking `/explorable`. Treat that as license to build
something explorable, unless the source would make exploration dishonest,
wasteful, or silly.

## What this does

Reads a long markdown doc and produces one self-contained `.html` file:
hand-written SVG, interactive widgets where the source has kinetic
structure, deliberate aesthetic, voice tuned to the source. No build step.
Runs identically in `file://`, Claude Artifacts, and on static hosting.

## Files in this skill

This skill is self-contained. Four files, all in this directory:

- **SKILL.md** (this file) — phase scaffold, decision logic, hard rules. Loaded every invocation.
- **writing.md** — full Zinsser canon, walk-through voice, copy procedures (`sample`, `review`). Read before Phase 1's voice sample and Phase 4's Zinsser pass.
- **aesthetics.md** — source-genre starting patterns, anti-slop filter, color-stable variables. Read before Phase 2.
- **primitives.md** — interactive primitives table, teaching test with worked examples, predict-then-reveal evidence, defaults. Read before Phase 5.

Pointers below are imperative ("**read X**"). Treat them as instructions, not suggestions.

## Genre is the ceiling

The input's genre caps the output's interactive density. A founder letter
won't become *Parable of the Polygons* by adding sliders. A research
synthesis won't become Ciechanowski's *Mechanical Watch* in one pass.
Name this honestly instead of overselling.

The realistic agent ceiling for one-shot output is **Sam Rose / Red Blob
Games quality**: color-stable palette, hand-written SVG, prose that earns
its place, widgets where the source genuinely calls for them. Aim for that.
Ciechanowski's auteur level is unattainable in one pass.

The source dictates how many widgets, not a target range — see the
Density section below.

---

## Writing standard (applies throughout)

Every phase that produces text — body prose, figure captions, scene
transitions, button labels, error messages — follows Zinsser's four
principles: clarity, simplicity, brevity, humanity. The governing test
for every sentence: **is this sentence doing new work?** If not, cut it.

The three LLM-tics most likely to leak into agent-generated copy:

- **Hedges** — "a bit", "sort of", "arguably", "perhaps". Either claim or cut the sentence.
- **Throat-clearing openers** — "It's interesting to note that…", "At this point in time…". Cut the opener; start with the sentence.
- **Passive voice when actor is known** — "was deleted by Jorge" → "Jorge deleted".

Preserve voice, specifics (dates, names, hashes, quotes, numbers),
deliberate fragments, and the source author's distinctive rhythm. Make it
easier to read without making it dumber.

**writing.md holds the full canon.** Read it before Phase 1 and before Phase 4.

---

## Phase 1 — Plan the piece and the voice, confirm in one line

Read the source completely. Find the structure trapped inside the prose:
temporal, spatial, causal, comparative, procedural, branching, taxonomic,
evidentiary. Most pieces have one dominant shape and one or two secondary.

Generate one voice sample at the target tone — run the writing.md `sample`
procedure on the source's first paragraph. Skip the sample for quick
internal artifacts under 1500 words.

Then propose the plan AND the voice sample to the user in one screen,
plain language, no jargon. **One confirmation gate, not two** — the user
redirects either the plan or the voice in a single line.

*A Phase 1 proposal might read:*

> Reading this as a research synthesis with a temporal arc (3 phases of
> the Purple Crayon experiment) and a comparative core (three parallel
> agent runs).
>
> Building a chaptered walkthrough — sketch gallery, 3-up comparison
> scrubber, scope explorer for the MVP cuts. About 6 scenes, 4 interactive
> moments.
>
> Look and feel: warm picture-book colors on cream paper, hand-drawn marks.
>
> Voice sample (your first paragraph at the target tone):
>
> *[rewritten paragraph appears here]*
>
> Say "go" or change anything — different shape, more/less playful,
> warmer/colder voice, drop a scene.

### Default modes by source

Pick the form first. The agent's first job is to map the source genre to a
default form, then confirm.

| Source | Default form |
|---|---|
| Research synthesis | Visual case study with thesis-carrying interactive |
| Product / project plan | Scope explorer + comparison scrubber |
| Methodology / how-to | Step-through walkthrough or sticky figure |
| Commit history / repo analysis | Chronological case study |
| History / civics | Timeline + map + predict-then-reveal |

From Kevin-Zhouu/OpenAtlas, MIT.

More from Kevin-Zhouu/OpenAtlas