agentleFS
gmchandegmchande/explorable-skills/skills/explorable/SKILL.md

explorable

Skill4 starsChanged 6 months agoMITView on GitHub

Turns a long markdown document into a single-file HTML explorable — scroll-snapped scenes, hand-written SVG, interactive widgets where the source has structure trapped inside the prose. One file, no build step, vanilla CSS/JS/SVG. Use when the user says "make this explorable", "/explorable", "turn this into an interactive", "render this research", or has a long markdown doc whose ideas are visual, temporal, spatial, causal, or comparative. Descends from Bret Victor's Explorable Explanations, Nicky Case, Distill, Ciechanowski, Sam Rose, Red Blob Games.

4 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions4 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 4

    1. EvanOman/claude-skills-public★ 4same name
    2. MbappeWU/explorable★ 2same name
    3. geekplux/explorable★ 0same name
    4. rajasdevel/outcomebound★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

The file

Show its rules and text

We split this skill into the rules it gives an agent

19 rules. 0 are common, 18 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 18

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If the source's argument is visual, temporal, spatial, causal, comparative, procedural, or branching, prose alone is a tax.

    line 21
  2. Distinctive:

    Every phase that produces text — body prose, figure captions, scene transitions, button labels, error messages — follows Zinsser's four …

    line 67
  3. Distinctive:

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

    line 82
  4. Distinctive:

    Read the source completely.

    line 88
  5. Distinctive:

    If it's borderline, default to retrofit and proceed without asking.

    line 158
  6. Distinctive:

    Ask only when the answer would change the artifact materially:

    line 162
  7. Distinctive:

    Before generating any design from scratch, scan the source for what it's already telling you about its visual world:

    line 200
  8. Distinctive:

    If the source has phases, an explicit "Acts" scene is first-class output.

    line 229
  9. Distinctive:

    Map scenes: If sections vary wildly in weight, consolidate the thin ones, split the heavy ones.

    line 230
  10. Distinctive:

    Write the full draft of body copy and figure captions before touching visuals.

    line 239
  11. Distinctive:

    No widgets yet — write what each scene says.

    line 244
  12. Distinctive:

    If the sentence sounds weak, cut the interaction.

    line 272
  13. Very specific:

    Default: vanilla HTML/CSS/JS + hand-written SVG.

    line 316
  14. Distinctive:

    Always hand-write SVG for propositional content: anatomy, circuits, data flows, equations, geometry, system diagrams.

    line 330
  15. Distinctive:

    No forecast voice unless the source supports it

    line 346
  16. Distinctive:

    No invented numbers, citations, or causal relationships

    line 363
  17. Distinctive:

    Every model-backed widget shows assumptions and omissions

    line 364
  18. Distinctive:

    When refusing, name what *would* work in the same message.

    line 388
  19. Distinctive:

    Label honestly: If the finished piece has zero thesis-carrying interactives (all scaffolding), call it "document with interactives," not …

    line 413

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/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.

SourceDefault form
Research synthesisVisual case study with thesis-carrying interactive
Product / project planScope explorer + comparison scrubber
Methodology / how-toStep-through walkthrough or sticky figure
Commit history / repo analysisChronological case study
History / civicsTimeline + map + predict-then-reveal
Design explorationSide-by-side comparison gallery + principles overlay
Investment thesis / financial memoScenario model with visible assumptions
Architecture docSVG system diagram + flow walkthrough
Tutorial / learning materialStep-through + predict-then-reveal + (Orbit handoff if retention)

This table is a starting point, not a rule. The source can override — for example, a research synthesis whose argument is fundamentally spatial (not temporal) wants a map-and-atlas form, not the default visual case study. Follow the source.

Check the prose-to-interactive ratio before proposing

While reading, count: how much of the spine is prose, and how much is candidate interactives? Two stable shapes:

  • 70–95% prose with interactive moments threaded through (retrofit)
  • 5–30% prose, interactives carrying the spine (compose)

The 40–60% middle is unstable — prose feels like connective tissue and widgets feel undersupported. If your read of the source lands clearly in that middle, name it in the proposal:

"This source's argument lives mostly in its kinetic structure — prose is mostly connecting widgets. Want me to keep the prose and let the widgets carry the weight, or rewrite as a shorter interactive-first piece?"

If it's borderline, default to retrofit and proceed without asking.

When to actually ask the user

Ask only when the answer would change the artifact materially:

  • Genre is genuinely ambiguous between two very different shapes
  • The source has emotional content (mental health, conflict, loss) — confirm before transforming at all
  • The source supplies code/data and the agent needs to know whether to re-run

Otherwise: propose, let the user redirect in one line, move on.

Hide internal vocabulary from the user

Words to keep inside the skill, never in user-facing output: "kinetic potential", "thesis-carrying", "Mode A/B/C", "density budget", "anti-slop filter".

Translation table:

InternalWhat to say to the user
Mode A retrofit"keep your writing, add interactive moments where they earn their place"
Mode B compose"rewrite as a shorter, interactive-first piece"
Mode C re-typeset"clean typographic layout, no interactivity" — only when interaction would be silly
thesis-carrying interactive"this one carries the argument — you can't say it in prose"
scaffolding interactive"this one makes the piece easier to navigate"
density budget"N interactive moments"
five-gate review"a few checks before we ship"

Phase 2 — Aesthetic direction

The artifact's design takes its cues from what the source is about. A children's iPad app gets a different visual language than a security post-mortem. Don't impose a house style — read the source for what genre, mood, and visual world it belongs to, and design into that.

Read the source for visual cues

Before generating any design from scratch, scan the source for what it's already telling you about its visual world:

  • Subject genre. Is this children's product, scientific research, founder essay, code archaeology, civics, design critique, financial memo, art history? Each has an established visual register that readers already know how to read.
  • Named visual referents. Colors ("Purple Crayon" → Harold's purple), objects, cultural references, era, brand identity. If the source names something visual, it's load-bearing — use it.
  • Tone. Playful, austere, journalistic, intimate, technical? Match it.
  • Audience. Who would naturally read this, and what media do they already consume? Design for that reader, not a generic "tasteful website."

The principle: a reader landing cold should be able to guess the topic from the visual language alone.

Read aesthetics.md before generating any design. It carries the source-genre starting patterns, the anti-slop filter (banned defaults), and the color-stable-variables discipline that does most of the work of "looking like a real explainer."


Phase 3 — Content structuring

  1. Extract the thesis sentence. Promote it to typographic status — pull-quote, cold open, or dedicated scene. Never buried in body prose.
  2. Identify the arc. However many acts/phases/eras the source has. If the source has phases, an explicit "Acts" scene is first-class output.
  3. Map scenes. If sections vary wildly in weight, consolidate the thin ones, split the heavy ones.
  4. Extract the vivid moments — dates, names, hashes, quotes, specific scenes. Whatever the source gives you.

Phase 4 — Copy

Write the full draft of body copy and figure captions before touching visuals. Copy is the skeleton; visuals and interactions are muscles. Three passes, in order:

  1. Draft. Section by section, following the scene map from Phase 3. No widgets yet — write what each scene says. Body prose, headings, figure captions, scene transitions.
  2. Ground the vocabulary. For each domain term, is it grounded on first use? See the walk-through voice section in writing.md. Cutting can't add missing context, so do this before the Zinsser pass.
  3. Zinsser pass. Run the writing.md review procedure on the full draft. Apply the rewrites before Phase 5.

Phase 5 — Interaction design

For each candidate interactive, label it thesis-carrying or scaffolding.

  • Thesis-carrying: the reader cannot be argued the same thing in prose alone. The interaction IS the argument.
  • Scaffolding: useful navigation or detail, but not load-bearing.

At least 1 thesis-carrying interactive for the output to be called an explorable. Below that, label the output "document with interactives."

Teaching test

For each interaction, fill in the blanks:

"The reader changes ___ to understand ___."

If the sentence sounds weak, cut the interaction. Static typography beats dead motion.

Exception: when the thesis is about causality, responsiveness, or transformation, interaction is mandatory — you can't argue responsiveness typographically.

Read primitives.md before designing interactions. It carries the full primitives table (21 patterns and the claim each carries), worked examples of the teaching test, the predict-then-reveal evidence, and the defaults every widget must respect (auto-preview, reset, pause, prefers-reduced-motion, single-variable default, accordion behavior, motion-as-explanation).


Phase 6 — Build

Single HTML file. Inline <style> and <script>. Hand-written SVG. Vanilla JS. Canvas + requestAnimationFrame for sims. Pinned CDN deps only when the source genuinely needs them.

Hard rules

  • One file. Inline <style> and <script>. Pinned CDN deps via https://cdn.jsdelivr.net/npm/...@version/+esm only.
  • <meta name="viewport" content="width=device-width,initial-scale=1">
  • text-wrap: balance on headlines, pretty on body
  • font-variant-numeric: tabular-nums on changing numbers
  • IntersectionObserver for scroll triggers (Scrollama only when ≥3 sticky scenes earn it)
  • Arrow keys / Space-Shift-Space for scene paging. Add j/k only for developer-audience explorables.
  • Stack on <700px viewports. Touch targets ≥44px. No hover-only meaning.
  • prefers-reduced-motion disables ambient motion, pauses thesis motion.
  • Color contrast ≥ AA. Visible focus states.
  • Total weight target <500KB excluding generated imagery (soft cap 1MB).
  • Runs identically in: file://, Claude Artifacts iframe, static hosting.
  • Disclosed playing time at the top.
  • Per-section 10-second rule: first interaction lands within 10 seconds of the reader arriving at that section.

Tech policy

Default: vanilla HTML/CSS/JS + hand-written SVG. Reach for a library only when the source genuinely calls for it — Canvas for continuous simulation, a charting library when prose can't carry the data, a map library when geography matters. Pinned CDN imports via https://cdn.jsdelivr.net/npm/...@version/+esm only. No build steps, no framework setup.

Image-generation rule

Generated raster only when:

  • The subject's appearance is the explanandum (historical scene, fashion, architecture, a specific design, a product), OR
  • The imagery is decorative cover/divider, explicitly labeled.

Always hand-write SVG for propositional content: anatomy, circuits, data flows, equations, geometry, system diagrams. Generated diagrams hide errors behind aesthetic competence. The Frontiers Cell Dev Biol rat-anatomy retraction is the parable.

No-fake-data rule

Either user-supplied data, formulas the reader can read inline, or omit the chart. No invented numbers. No invented citations. No "trust = 0.7" fake precision. No "what if SG&A were 15% lower" with nothing behind it.

For model-backed widgets:

  • Show variables and their default values
  • Show formulas (or include a "show formulas" toggle)
  • Show what the model omits ("what this does not model")
  • Label illustrative simulations as illustrative
  • No forecast voice unless the source supports it

Phase 7 — Review

Five-gate review

GateWhat it checksAutomated?
1. StaticSyntax, var refs, tag balanceYes
2. VisualLayout at 1440 and 640, no clippingPartial
3. DesignAesthetic deliberate, not defaultNo — user
4. CopyEach paragraph teachesNo — user or writing.md review
5. ArcNarrative arc visible to a first-time readerNo — user

Plus three honesty checks (always run):

  • No invented numbers, citations, or causal relationships
  • Every model-backed widget shows assumptions and omissions
  • Voice preserves the source's distinctive phrases (don't smooth into LLM-default tone)

Surface gates 3–5 to the user with an explicit checklist. Don't self-approve.

Fork review (optional, for higher-stakes pieces)

For longer or higher-stakes pieces (public blog posts, portfolio work, things the user will share widely), spawn a separate sub-agent (staff-designer role) for an independent taste pass before shipping. The builder doesn't self-verify on taste.

The review surfaces: copy that doesn't teach, asides that don't add information, scenes that mis-weight the arc, interactions that are scaffolding masquerading as thesis.

Skip for quick single-source explorables — the five-gate review is enough.


Refusal and downshift

When refusing, name what would work in the same message. No bare refusals.

SourceOffer instead
Legal, contracts, regulatory text, formal specs, API referencesBetter typography + search + index. Exact wording is the product.
Memorials, eulogies, apologiesDon't transform. Suggest reading the original. Register-mismatch.
<500 wordsSingle-page layout or card.
Opinion-only, no quantifiable claimsRe-typeset, or suggest reading the original.
Messy / contradictory / transcript-likeSuggest the user distill it down first; offer to continue once they have.
API docs (Docusaurus exists)Decline; point at standard docs tooling.
Reference / lookup tablesDecline; search indexes do this better.
Personal essay where voice is the valueTypographic essay only; no widgets.

Density

The source dictates density. Count the kinetic claims, count the structures that would read faster as widgets, build the ones that survive the teaching test.

The bimodal-middle check happens in Phase 1, before any building. By the time you're here, the form is already chosen.

Label honestly. If the finished piece has zero thesis-carrying interactives (all scaffolding), call it "document with interactives," not "explorable."

Minimum viable floor

Jason Davies's Map Projection Transitions: 12 words of prose, one <select>, one pause button, one SVG that morphs on change. When the input is a compact visual object with no surrounding argument, emit at the floor. A clean 12-word piece beats a bloated prose shell.


Voice for this skill

Execution mode. The skill builds, doesn't discuss.

Right: "Reading this as a research synthesis with a temporal arc. Building a chaptered walkthrough with a 3-up comparison scrubber. Plan and voice sample below — say go or redirect."

Wrong: "Great, let me start by reading the source. Phase 1: I'll identify the structure. I see this is a research synthesis with a temporal arc. Now generating the voice sample..."


References

  • Bret Victor, Explorable Explanations (2011) — north star, not product spec
  • Nicky Case, explorabl.es — guided play, do/show/tell
  • Distill, Communicating with Interactive Articles — affordances taxonomy and the warning ("not everything needs to be interactive")
  • Bartosz Ciechanowski, ciechanow.ski — auteur ceiling
  • Sam Rose, samwho.dev — realistic agent ceiling
  • Red Blob Games, redblobgames.com — incremental interactivity
  • Andy Matuschak + Michael Nielsen, Quantum Country — predict-then-reveal as the load-bearing primitive
  • Jakub Krehel, Details that make interfaces feel better — essay+skill pair
  • William Zinsser, On Writing Well — copy rubric

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.