Agent Config Adapter

---
name: explainer
description: Turns an explanation of any concept, article, or book into standalone, interactive HTML page(s) that teach it as clearly as possible. Use when the user wants to explain, teach, illustrate, or visualize a topic — "make an explainer", "create an interactive explanation", "build a visual/interactive page that explains X", "teach me X as a webpage" — or points at an article (URL/paste) or a book ("explain this article", "make an explainer for <book>", "teach me chapter N of <book>").
---

# Explainer Generator

Takes a concept (text the user wants explained, a topic, a paste of docs/code) and produces **one self-contained interactive HTML file** that teaches it — progressive sections, live demos the reader can poke, diagrams, and callouts. The artifact IS the deliverable; it is meant to be opened and read, not to feed a prompt back to Claude.

Think "the explanation a great teacher would build if they could make any interactive widget" — not a slide deck, not a wall of text.

## When to use

The user wants something **explained** and an interactive page would land it better than prose: anything with a process, a cause-and-effect relationship, parameters that trade off, a structure, or a "watch it happen" moment. If they just want plain text, don't reach for this.

> Sibling skill `playground`: a *playground* lets the user configure something and copy out a prompt. An *explainer* teaches a concept and ends in understanding. If the goal is "help me understand X" → explainer. If it's "help me specify X to send back to Claude" → playground.

## Process

1. **Pin down the one big idea.** Before any HTML, write (for yourself) the single sentence the reader should walk away with. Everything serves that sentence. If the input is vague, ask 1–2 clarifying questions (audience level? the specific angle?).
2. **Decompose into 3–6 sections** that build on each other: the problem/motivation → the core mechanism → an interactive demo → the knobs/edge cases → recap. Concrete before abstract.
3. **Pick interactions per section** from the catalog below. Every meaty idea earns a visual or an interaction, not another paragraph. Reach for **at least one** thing the reader can manipulate.
4. **Write a single HTML file** — inline all CSS/JS, no external dependencies. Use the design system below so it looks good by default.
5. **Verify by rendering it and looking** (see Verify). A blank or broken page = not done.
6. **Open it for the user** (`google-chrome <file>` / `open <file>` / `xdg-open <file>`), and tell them the path.

## Source-grounded inputs: articles & books

The flow above assumes a *concept*. When the input is an **article** (URL or pasted text) or a **book** (title, or supplied excerpts/notes/highlights), switch to source-grounded mode: the deliverable teaches *that source's argument*, not the general topic. The most likely failure here is quietly producing a topic explainer wearing the source's title — don't.

### Articles

1. **Ingest first.** Given a URL, fetch it (WebFetch / `curl`) before writing anything. Given a paste, the paste is canonical. Never write from memory of the topic when a source is in hand.
2. **Fidelity rules.** The one big idea is *the author's thesis*, stated in the author's terminology, illustrated with the author's examples. General knowledge only fills gaps, and every fill is marked with a `context` callout (same construction as `.insight`/`.gotcha`, neutral tint) — never silently blended in.
3. **Cite.** The hero links back to the source: title, author, URL.
4. Otherwise the normal concept flow applies — articles fit the one-big-idea / 3–6 section shape.

### Books — spine, slice, or both

A book doesn't fit one page. Scope it up front (ask one question unless the user already chose):

- **Spine** — one page: the book's central thesis plus its 5–8 load-bearing ideas and how the chapters build toward them.
- **Slice** — a full-depth explainer for each chosen chapter; each chapter is treated as a "concept" and gets the complete normal flow.
- **Both** — spine as the hub, chapter slices linked from it. This is the best default when the user wants the whole book seriously.

Be honest about sourcing: from a bare title you're working from training knowledge — say so, and ask whether they have notes/highlights/excerpts/an ebook to ground it. If they do, that text is canonical and the article fidelity rules apply.

**Output layout** — a directory, one self-contained HTML file per page, relative links between them (each file still inlines all its own CSS/JS):

```
<book-slug>/
  index.html               ← spine (or a minimal linked TOC if slice-only)
  chapter-03-<slug>.html   ← one per sliced chapter
```

**Spine page specifics:** centerpiece is an annotated idea-map (inline SVG) showing how the load-bearing ideas connect and build; add a sticky TOC sidebar once past ~6 sections (the only sanctioned departure from pure single-column). When slices exist, each idea/chapter card links to its chapter page.

**Interaction fits for books:** timeline for narrative books; claim → evidence → counterargument toggles for argument-driven nonfiction; check-your-understanding quizzes for framework-heavy books — and apply the "operable gotcha" rule at book scale: let the reader *trigger* the bias/effect the chapter describes, not just read about it.

### Slices run as a workflow — ultracode, one agent per chapter

When slicing **more than one chapter**, do not write them serially in the main loop — orchestrate with the **Workflow tool**, one agent per chapter, in parallel. This skill explicitly authorizes that Workflow call. (A single chapter is just the normal flow inline.)

1. **Scope inline first.** Settle the chapter list and each chapter's one big idea — from the source if supplied, otherwise from your knowledge of the book, confirmed with the user. This is the work-list; don't enter the workflow without it.
2. **Fan out** — one `agent()` per chapter. Each prompt must carry everything the agent needs (agents share no context): the book + chapter scope and its key ideas, source excerpts if available, the fidelity rules, the absolute output path, the design system (tell it to Read `examples/bloom-filter.html` and reuse its `:root` palette and component CSS so all chapters look like one book), the full pedagogy rules, and the headless-Chrome verify step. Use a schema so each agent returns `{file, title, oneBigIdea, verified}`.
3. **No worktree isolation** — agents write distinct files; isolation buys nothing here.
4. **Assemble.** After the fan-out: spot-check at least one chapter screenshot yourself, write/update `index.html` (spine or TOC) linking every chapter page, render-verify it, and open *it* — the hub is the entry point you hand the user.

Sketch:

```javascript
export const meta = {
  name: 'book-slices',
  description: 'One full-depth chapter explainer per agent, in parallel',
  phases: [{ title: 'Chapters' }],
}
const results = await parallel(args.chapters.map(ch => () =>
  agent(chapterPrompt(ch), { label: `ch:${ch.num}`, phase: 'Chapters', schema: CHAPTER_SCHEMA })))
return results.filter(Boolean)
```

## Interaction catalog — your toolbox

Pick what fits the concept. A strong explainer usually combines 2–4 of these.

| Pattern | Use it when… | Mechanics |
|---|---|---|
| **Progressive sections** | always — the spine of the page | numbered sections, generous whitespace, a scroll progress bar |
| **Live demo** | there's a thing the reader can *operate* to build intuition (a data structure, an algorithm, a regex) | inputs/buttons mutate a single `state` object → re-render instantly on every change, no "Apply" button |
| **Parameter sliders** | output depends on knobs that trade off (math, tuning, physics, cost curves) | `<input type=range>` → recompute a number/formula and a visual gauge live; surface the *optimum* and what's past it |
| **Stepper** | a sequence or process is best understood one frame at a time (an algorithm, a request lifecycle) | Prev/Next over an array of step states; highlight what changed each step |
| **Before/after toggle** | comparing two states or "naive vs better" | a switch that swaps the rendered view |
| **Hover-to-define terms** | jargon the reader may not know, inline | `<span class=term>word<span class=def>…</span></span>` — tooltip on hover, no clutter |
| **Callout boxes** | a key insight, an analogy, or a gotcha deserves to break the flow | tinted left-border card: `insight` / `gotcha` / plain |
| **Annotated diagram** | spatial/structural relationships (architecture, data flow, anatomy of a thing) | inline SVG, or a `<canvas>` with manual draw calls + hover hit-testing |
| **Check-your-understanding** | the concept has a common misconception worth testing | 1–2 multiple-choice questions that reveal an explanation on answer |

Don't cram all of these in. Match the concept; cut the rest.

## Pedagogy rules (this is what separates it from a pretty README)

- **One big idea, stated early and plainly.** Then build to it; don't bury it.
- **Concrete before abstract.** Show a specific worked example, *then* generalize. The Bloom-filter example shows the bits flipping before it shows the formula.
- **Earn every paragraph.** If a point can be a diagram, a demo, or a callout, make it that. Long unbroken prose is the failure mode.
- **Use an analogy** for the central mechanism, in a callout.
- **Name the gotcha.** The thing that surprises people gets its own `gotcha` callout — ideally one the reader can *trigger* in a demo (e.g. push a slider past the optimum and watch error rise).
- **Recap at the end** — the one sentence again, now that they've earned it.

## Design system (reuse this — it's proven)

Dark, calm, one accent gradient. System font for UI, monospace for code/values. Copy the `:root` palette and component CSS from `examples/bloom-filter.html` as your starting stylesheet — it already has: progress bar, hero, numbered `h2`, `.callout` (+ `.insight`/`.gotcha`; add a neutral-tint `.context` variant for source-grounded pages), `.term` tooltip, `.panel`, `.bit` grid, sliders, `.gauge`, and stepper styles.

```
--bg:#0e1117  --bg-elev:#161b22  --border:#2a3240  --text:#e6edf3  --text-dim:#9aa7b4
--accent:#58a6ff  --accent2:#a371f7  --good:#3fb950  --bad:#f85149  --warn:#d29922
```

- Single column, `max-width: ~760px`, centered. Reading-first, not dashboard-first.
- Live preview means **live**: every control calls one `updateAll()` that re-renders. No submit buttons for state changes.
- Animate state changes (`transition`/`@keyframes`) so cause→effect is visible, not instant-snap.
- Self-contained: if a CDN being down breaks it, you did it wrong.

## State pattern

```javascript
const state = { /* everything configurable */ };
function updateAll() { renderViz(); renderReadout(); }  // every control calls this
```

For deterministic demos (hashing, RNG-driven visuals) write your own small pure function so output is reproducible across reloads — see `hashes()` in the example.

## Verify (do not skip)

You must render the file and **look at it** before claiming it's done.

**Quick static check** — headless Chrome screenshots a `file://` directly (no server needed):

```bash
google-chrome --headless=new --disable-gpu --no-sandbox --hide-scrollbars \
  --window-size=820,3200 --virtual-time-budget=2000 \
  --screenshot=/tmp/explainer.png "file:///ABS/PATH/TO/page.html"
```

Then Read `/tmp/explainer.png`. Blank/error/cramped → fix and re-render.

**Interactivity check** — drive it with `playwright-cli` (the user's preferred browser tool). It **blocks `file://`**, so serve over HTTP first:

```bash
cd <dir-with-html> && python3 -m http.server 8731 &   # then kill when done
playwright-cli --config /root/.playwright/cli.config.json goto "http://localhost:8731/page.html"
# call your page's functions / dispatch input events to exercise demos:
playwright-cli --config /root/.playwright/cli.config.json eval "() => { /* operate the demo, return a readout */ }"
playwright-cli --config /root/.playwright/cli.config.json screenshot --full-page
playwright-cli --config /root/.playwright/cli.config.json close
```

`eval` takes a bare arrow function string (`"() => {...}"`), **not** an IIFE. Confirm the demo's logic (e.g. that a query returns the right verdict, that a slider recomputes the gauge), then screenshot an *active* state and Read it.

## Worked reference

`examples/bloom-filter.html` is a complete, verified explainer ("How a Bloom Filter Works") that exercises every core pattern: progressive sections, a live add/query demo with a real false-positive, a stepper, tuning sliders with the FP-rate formula, hover-terms, and all three callout styles. `examples/bloom-filter-screenshot.png` is what it renders to. **Read the HTML for the structure and CSS; adapt, don't copy the topic.**

## Common mistakes

- **Wall of text with a banner on top.** If there's nothing to operate and nothing to see, it's a styled README — add a demo or cut the skill.
- **Static "interactive" page.** Controls that don't re-render live, or a demo that only shows one frozen state.
- **External dependencies** (Tailwind CDN, charting libs, web fonts). Inline everything; it must work offline forever.
- **Burying the big idea** under setup. Lead with it.
- **Decoration over explanation.** Animations and gradients serve comprehension; they're not the point.
- **Claiming done without rendering.** You didn't see it → it's not done.
- **Topic explainer wearing the source's title.** Given an article or book, teaching the general topic from memory instead of the author's actual argument. Fetch/use the source; mark knowledge fills with `context` callouts.
- **Serial chapter writing.** Slicing multiple book chapters one-by-one in the main loop instead of fanning out one Workflow agent per chapter.
- **Orphan chapter pages.** Slices with no hub — always finish with an `index.html` (spine or TOC) that links every chapter and is what you open for the user.

Companion Files