# Html Explainer

> Default output format for any substantive explanation, walkthrough, comparison, deep-dive, spec, mockup, diagram, cheatsheet, or report. Generates a fun, editorial, single-file HTML artifact (Tailwind + Mermaid + rough-notation + Alpine + Lucide via CDN, no build step) — warm-cream magazine aesthetic, NOT SaaS dashboard. Strongly prefer this skill over a long markdown reply whenever the answer wo…

- **Type:** Skill
- **Install:** `agentstack add skill-adaminspaceship-html-explainer-html-explainer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [adaminspaceship](https://agentstack.voostack.com/s/adaminspaceship)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [adaminspaceship](https://github.com/adaminspaceship)
- **Source:** https://github.com/adaminspaceship/html-explainer

## Install

```sh
agentstack add skill-adaminspaceship-html-explainer-html-explainer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# html-explainer

Produce a **single, self-contained HTML file** that explains, compares, or visualizes something — using a curated stack of CDN-loaded UI libraries. Inspired by https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html — HTML beats markdown for density, interactivity, and staying in the loop.

## Aesthetic (read this first)

The look is **editorial magazine**, not SaaS dashboard. If your output feels like Stripe's docs, you've overshot toward "tech-y." If it feels like a Notion page, you've undershot toward "default." Aim for *The Pudding*, *Quanta Magazine*, a *Stripe Press* book page, or a tasteful personal blog.

- **Warm cream background** (`#FBF7F1`), deep ink text (`#1A1A1A`), generous whitespace.
- **Instrument Serif** for headlines (large, expressive, occasionally italic).
- **Inter** for body, with `leading-[1.75]` and ~65ch max line length.
- **Caveat** (handwritten) for marginalia, dividers, arrows, eyebrows — sparingly, like ink in the margin.
- **Coral / butter / sky / blush** accents — not blue-purple SaaS gradients.
- **No grid of cards** for its own sake. Cards are for actual comparisons; prose is for prose.
- **Hand-drawn touches** via rough-notation: underline 2-4 key phrases, never more.
- **Soft shadows, big rounded corners, paper-grain background gradients.**

When in doubt: would a designer at a magazine make this? If not, simplify.

## When to use this skill

**Default to this skill** for any substantive explanation. The bar is low: if the chat answer would be more than ~3 short paragraphs, or would have a diagram, comparison, list of options, or any visual structure — make an HTML artifact instead.

Fire on phrases like:
- "explain X", "walk me through X", "how does X work", "teach me X", "tell me about X"
- "what's the difference between X and Y", "compare X and Y", "X vs Y"
- "deep dive on X", "break down X", "overview of X"
- "diagram X", "visualize X", "mock up X", "sketch X"
- "write a spec / report / cheatsheet / explainer for X"

Also fire when no phrase matches but the answer wants:
- side-by-side comparison or tradeoffs
- a flowchart / sequence / state / ERD diagram
- an interactive node graph (React Flow style via Drawflow)
- a step-by-step walkthrough with annotated prose
- mockups or multiple variants in one view
- a dense reference table or cheatsheet
- anything that would otherwise become a wall of markdown

**Don't** fire for: one-line answers, single short code snippets, yes/no questions, quick lookups, simple commands, or follow-up clarifications. When in doubt: would the user enjoy opening this in a browser tab and keeping it? If yes, use the skill.

## Output protocol (always — copy-then-edit, never write from scratch)

**Never regenerate the boilerplate.** Doing so is slow and unnecessary — the whole template (CDN stack, Tailwind config, custom CSS, explain-on-select widget) is identical for every artifact. Always start by copying `base.html`, then make small edits to the content sections only.

1. **Copy the template first** with a single Bash call:
   ```
   cp ~/.claude/skills/html-explainer/base.html ./.html
   ```
   Use a descriptive filename — e.g. `how-react-fiber-works.html`, `auth-approaches.html`.

2. **Plan the visual pieces alongside the prose.** A complete artifact has, by default:
   - 1-3 **baked illustrations** (`` with `data-prompt`)
   - **1 Lottie animation** chosen for the topic (see the "Lottie animation" section below — this is a default, not optional)
   - 0-2 **Mermaid diagrams** if the content benefits
   - **2-4 rough-notation** annotations on key phrases

   For the Lottie, do the search + curl-verify step BEFORE writing the body. Picking it later breaks flow.

3. **Edit only the content sections** using the Edit tool (NOT Write). The placeholders in `base.html` are clearly marked with HTML comments and are the only things you should touch:
   - `Untitled explainer` → real title
   - `` block → category label ("An explainer", "A comparison", "A spec"…)
   - `` block → h1 + lead paragraph
   - `` block → the gist (one sentence)
   - `` block → replace with your real sections (multiple ``s, diagrams, comparison grids, illustrations, the Lottie, etc.)
   - Keep the hand-drawn divider; reuse it between sections

   **Never** edit: the CDN includes, the `tailwind.config` script, the `` block, the Mermaid init script, the rough-notation auto-wiring, the explain-on-select widget HTML/CSS/JS. Those are part of the runtime — leave them alone.

4. **Open the file** so the user sees it immediately:
   ```
   open .html
   ```

5. **Reply in one or two sentences.** The file is the answer; don't restate it in chat. If you skipped the Lottie, name it: "(couldn't find a fitting free Lottie for X; skipped)."

If a brand-new section type doesn't exist in `base.html` (e.g. a Drawflow node graph), add it via Edit in the body — don't rewrite the file.

## What's already in base.html (reference only — don't retype it)

`base.html` already includes the full runtime. You inherit all of this by copying the file:

- **Tailwind** (utilities only — no DaisyUI; too dashboardy) + custom config: `font-display`, `font-hand`, the cream/ink/coral palette, `shadow-soft`/`shadow-lift`
- **Fonts**: Instrument Serif (display), Inter (body), JetBrains Mono (code), Caveat (handwritten)
- **Mermaid 11** + custom cream/butter/sky theme — drop in `…` anywhere
- **rough-notation** — auto-wires every `[data-annotate]` element on load
- **Alpine.js 3** — `x-data`, `x-show`, `@click` work out of the box
- **Lucide icons** — `` auto-rendered on load
- **Paper-grain background gradient** (coral top-left, sky top-right)
- **Explain-on-select widget** (`#ex-menu`, `#ex-popover`, the IIFE script) — highlight → ✦ Explain
- **Baked-image runtime** — `.ex-img-frame[data-prompt]` divs auto-fill from `gpt-image-2` after load
- **Font-aware annotations** — rough-notation waits for `document.fonts.ready` and re-renders on resize, with `mix-blend-mode: multiply` so highlights blend with text instead of covering it

### Adding optional libraries

If a specific artifact needs them, add via Edit to the existing ``:

```html

```

(There are commented-out lines for both already inside `base.html`'s `` — uncommenting them is a small Edit.)

## Explain-on-select widget (included by default)

Every artifact ships with an interactive widget: the reader **highlights any text** → a small `✦ Explain` pill appears next to the selection → click → `gemini-3.1-flash-lite` streams an inline explanation into a popover anchored below the selection.

- Calls Google's Gemini API directly from the browser (`streamGenerateContent?alt=sse`)
- Text model: `gemini-3.1-flash-lite` (single `TEXT_MODEL` constant at the top of the widget script — change to swap models)
- API key (Gemini, starts with `AIza…`) prompted once on first click; stored in `localStorage` under `html-explain-gemini-key`; popover has a `⚙ reset key` button. Same key is reused by the image baker.
- Free key: https://aistudio.google.com/apikey
- **Rich context** sent to the model: document title, subtitle, nearest section heading, AND the containing paragraph — not just the immediate sentence. This is what makes explanations grounded in the actual document.
- Selections inside `.mermaid`, `svg`, `canvas`, inputs/textareas are skipped to avoid garbage prompts
- ESC / click-outside / × dismisses; popover position is viewport-clamped

**Do not strip this widget when generating new artifacts.** It is part of the default reading experience. The HTML markup lives at the bottom of `` (`#ex-menu`, `#ex-popover`), the CSS lives in the main `` block, and the JS is an IIFE in its own `` tag. Copy all three together from `base.html`.

## Illustrations (baked images via gemini-3.1-flash-image)

The runtime ships an image generator: drop a `` with a `data-prompt`, and after page load the script calls Google's `gemini-3.1-flash-image` (using the same Gemini key the explain widget holds) and slots the result into the frame. The reader sees a "drawing…" placeholder until it arrives.

**Use illustrations the way an article would** — sometimes informative (the actual thing being explained, a process), sometimes light decoration tying to nearby context. **Never AI-bloat** with random images for the sake of it. Cap: **1-3 per artifact**, max.

Pattern:

```html

  
  tiny caveat-font caption tying it to the prose

```

Prompt-writing rules (the runtime auto-appends a style suffix; you only describe the *scene*):

- Describe **subject + action + 2-3 concrete props/elements**. Keep prose-light.
- Always **wide composition**. The frame is 16:10.
- Anchor to the surrounding paragraph: if the section talks about caches, illustrate caches — not generic "abstract data flow."
- Don't ask for text/labels/numbers in the image (the model can't render them cleanly).
- Don't ask for specific colors — the suffix locks the palette to cream/coral/butter/sky.

Good prompt examples:

- *"A whimsical filing cabinet overflowing with paper notes spilling onto the floor, a tiny stick figure sorting one into a drawer."*
- *"A desk from above: an open laptop showing a wide rectangular document, two curved arrows leaving the screen toward thumbnail doodles of a flowchart and a chart, a steaming coffee mug."*
- *"A paper airplane mid-flight over a winding dotted line, dropping tiny envelopes at three stops along the path."*

Bad prompts: *"AI explaining things"*, *"data flowing"*, *"complex concept"* — too abstract, will produce generic slop.

## Lottie animation (default: 1 per artifact — only if topic-relevant)

**Aim for 1 Lottie per artifact**, but the bar is **topic relevance**, not just "a verified URL." A generic "developer at laptop" animation on a DuckDB explainer is worse than no animation. The reader should glance at the Lottie and feel "ah, that *is* about the topic." If a fitting one can't be verified, skip and say so — don't fill the slot with filler.

### Selection workflow

Perform this BEFORE writing the body, alongside picking baked illustrations:

1. **Name the anchor noun** — the literal subject of the artifact, or its central metaphor. For DuckDB → "duck." For React Fiber → "linked list" or "thread." For OAuth → "passport" or "handshake." Write it down before searching.
2. **Search**:
   - `WebSearch` for `free  lottie animation lottiefiles lf20 json`
   - If that fails, search GitHub for sample lottie JSON URLs with the noun in their filename / path
3. **Curl-verify before embedding** — every candidate URL must:
   - Return HTTP `200` on `curl -s -o /dev/null -w "%{http_code}" --max-time 4 `
   - Have an `nm` field in the JSON that **plausibly matches your anchor noun** (`nm` is the animation's internal name — read it with `python3 -c "import sys,json; print(json.load(sys.stdin)['nm'])" )`)
4. **Embed** with the small-size pattern below.

### Hard rules

- **No filler.** If no URL passes both the 200 check AND the anchor-noun-match check, **skip the Lottie**. Don't substitute a generic "loading" or "developer" animation.
- **No hero usage.** Lotties sit *beside* a section, not above the headline. The baked illustration is the hero slot.
- **Small.** Default 160px square. Hard ceiling 200px. They're punctuation, not centerpieces.
- **One per artifact.** Two competes for attention; three is busy.
- **Cute is fine** (a swimming duck, a bouncing rocket, a tipping coffee cup) — but cute and **relevant**. Cute and generic is still filler.

### Embed pattern

```html

  .json"
    background="transparent"
    speed="1"
    style="width: 160px; height: 160px;"
    loop autoplay>
  

```

### When you skip, name it

In your end-of-turn reply add a short line: *"couldn't verify a fitting Lottie for <anchor noun>; skipped."* The user explicitly asked for honesty about this — silently omitting reads as forgetting.

## Type ramp

```
font-display text-6xl md:text-7xl   → page headline (Instrument Serif)
font-display text-4xl                → section headline
font-hand text-2xl text-coral        → marginalia, eyebrows, "the gist", dividers
text-xl leading-relaxed              → subtitle / lead paragraph
text-lg leading-[1.75]               → body
text-sm text-ink-mute                → metadata
font-mono                            → code
```

## Palette (Tailwind tokens, set in base.html)

```
cream      #FBF7F1   background
cream-deep #F4EFE6   panels
cream-edge #E8E2D5   borders / dividers
ink        #1A1A1A   primary text
ink-soft   #3A3A3A   secondary text
ink-mute   #6B6B6B   metadata / captions
coral      #FF8B6B   primary accent (annotations, eyebrow flourishes)
butter     #FFE889   highlight accent
plum       #3B2F5C   deep accent for emphasis
sky        #A8D5E2   diagram accent
blush      #F4B5C8   diagram accent
```

Never hard-code other grays/colors. Use these tokens.

## Library cookbook

### Mermaid — declarative diagrams

Drop a `…` anywhere. Use:

- `flowchart LR` / `flowchart TD` — process / architecture
- `sequenceDiagram` — request/response, protocols
- `stateDiagram-v2` — state machines, lifecycles
- `erDiagram` — schemas
- `mindmap` — concept maps

```html

flowchart LR
  A([User clicks]) --> B{Logged in?}
  B -->|yes| C[Fetch data]
  B -->|no|  D[Redirect to login]
  C --> E([Render])

```

Keep node labels ≤4 words. Long descriptions go in prose *next to* the diagram, not inside nodes. The base template's Mermaid theme is already coral/butter/sky on cream — don't override it.

### Drawflow — React Flow–style interactive nodes

Only when nodes must be **draggable / connectable**. For static, use Mermaid.

```html

  const editor = new Drawflow(document.getElementById('drawflow'));
  editor.start();
  const n1 = editor.addNode('Input',  0, 1,  60, 100, 'card', {}, 'Inputuser query');
  const n2 = editor.addNode('LLM',    1, 1, 320, 100, 'card', {}, 'LLMgpt-4o');
  const n3 = editor.addNode('Output', 1, 0, 580, 100, 'card', {}, 'Output');
  editor.addConnection(n1, n2, 'output_1', 'input_1');
  editor.addConnection(n2, n3, 'output_1', 'input_1');

  .drawflow .drawflow-node { background:#fff; border:1px solid #E8E2D5; border-radius:16px; box-shadow:0 1px 2px rgba(20,14,4,0.04),0 8px 24px rgba(20,14,4,0.04); }
  .drawflow .connection .main-path { stroke:#1A1A1A; stroke-width:2px; }

```

### rough-notation — hand-drawn annotations (the fun layer)

Animate underlines, circles, highlights, boxes on any element. **2-4 per page max.** Annotate the prose that explains a thing, never the thing itself.

```html

  React Fiber is a
  linked-list re-implementation
  of the virtual DOM that makes rendering
  interruptible.

```

Types: `underline`, `box`, `circle`, `highlight`, `strike-through`, `crossed-off`, `bracket`. base.html wires up `[data-annotate]` automatically — just add the attributes.

### Alpine.js — tiny interactivity

Tabs, toggles, accordions, copy buttons. No build, no JSX, just attributes.

```html

  
    Before
    After
  
  // old
  // new

```

### Lucide — icons

``. Use sparingly; this is an editorial document, not a control panel. Common: `arrow-right`, `quote`, `book-open`, `feather`, `sparkles`.

## Composition patterns

### Hero header (editorial)

```html

  ✦
  An explainer

  How React Fiber works

  Why React rewrote its reconciler in 2017 and what it bought us.

```

### TL;DR aside (margin-note style)

```html

  
    ↳
    
      the gist
      One-sentence key insight.
    
  

```

### Comparison (2-up or 3-up) — only when actually comparing

```html

  
    
      Option A
      recommended
    
    One-line pitch.
    
      +pro
      −con
    
  
  

```

### Diagram + caption

```html

  
flowchart LR
  A([request]) --> B[middleware] --> C[handler] --> D([response])
  
  
    every request walks this path
  

```

### Hand-drawn divider

```html

  ~
  

```

### Stat callout (big number, label)

```html

  42%
  of queries return from cache — the rest hit Postgres.

```

### Pu

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [adaminspaceship](https://github.com/adaminspaceship)
- **Source:** [adaminspaceship/html-explainer](https://github.com/adaminspaceship/html-explainer)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-adaminspaceship-html-explainer-html-explainer
- Seller: https://agentstack.voostack.com/s/adaminspaceship
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.