HTML

html

You are producing a single self-contained .html file, not a markdown document. The reader will open it directly in a browser. No build step, no framework, no install. Treat the file as the deliverable.

Based on Thariq Shihipar's The unreasonable effectiveness of HTML — the observation that markdown flattens information that is inherently spatial, comparative, or interactive, and a small HTML file fixes this.

What this skill is for (read this first)

Agent-generated artifacts for a human reader. Throwaway or reference, not production.

Concretely, the things this skill produces are:

• Working documents the reader will read once and act on (a plan, an options comparison, a PR writeup, a status report).
• Reference pages the reader will return to (a design-tokens page, a codemap, an explainer).
• Throwaway tools the reader uses for a few minutes to do a piece of work, then exports out of (a triage board, a feature-flag toggler, a motion tuner).

What this skill is not for:

• Production websites or apps shipped to end users. The conventions here (single file, no build step, no framework, no server, vanilla JS, in-memory state) exist for fast disposability, not for production quality. If the user is building something they ship to customers, this is the wrong tool — use a real frontend skill.
• Long-form prose with no shape (an email, a paragraph of analysis, a conversational reply). HTML doesn't earn its place when the content is just sentences. Use markdown.
• Things that need persistence, multi-user state, or a backend. State here lives in memory and dies on refresh. The export button is how work survives.

If you're not sure which side a request falls on, ask yourself: would a human be happy reading this once in a browser tab and then closing it? If yes, this skill applies. If they need to bookmark it, share it with twenty colleagues, and have it still work in six months — that's a different skill.

When this skill applies (signals)

If the user invoked /html or a pattern slash command directly, just produce HTML. They've already chosen.

Otherwise, the strong signals are:

• Comparison — "show me my options", "compare X vs Y", "trade-offs of A, B, C"
• Code review or PR — annotate a diff, write the PR description, map a codebase
• Design — tokens, component variants, contact sheet
• Motion — animation, transition, click-through where feel matters
• Diagram — flowchart, architecture, data flow, illustrative figures
• Deck — a short presentation you'd arrow-key through
• Explainer — concept or feature, with collapsibles and tabs
• Recurring report — weekly status, incident timeline, post-mortem
• Editor — a throwaway UI for the specific thing the user is wrestling with
• Table — rows × columns the reader needs to sort, filter, or scan

If the request is plain prose without shape, use markdown. HTML is not a universal hammer; it earns its place when the content has structure.

What every output looks like

Every artifact this skill produces obeys these conventions. Patterns assume you've followed them.

1. Single file. One .html. No external CSS, no external JS, no build step. Inline everything.
2. No network at render time. No CDN, no Google Fonts, no remote images. The artifact must render offline.
3. Locked look — Claude editorial system. Start from templates/base.html. Do not redesign tokens per artifact. The look (cream canvas #faf9f5, coral accent #cc785c, dark navy #181715, EB Garamond serif display at weight 400 with negative tracking, Inter / system sans body, JetBrains Mono code) is fixed across every artifact this skill produces so the reader recognizes the genre on sight. If you need to tune a token, change base.html, not the per-artifact <style>.
4. Mobile-readable. Viewport meta is in the template. Multi-column layouts collapse below ~720px.
5. Semantic HTML. <section>, <article>, <details>/<summary>, <figure>, <table>. Headings nest properly.
6. Information has shape. Don't pour markdown into a <div>. Side-by-side things go in a grid. Sequences go on a timeline. Risks go in a table. If the content has no shape, you're producing the wrong artifact — use markdown.
7. A "Prompt:" block near the top. Small italic callout with the user's request, near-verbatim. Makes the artifact legible later and makes it forkable. Already styled in the template as .prompt.
8. Inline SVG over images. The agent has a real pen — use it. Diagrams are <svg>, not <img>.
9. Vanilla JS only, sparingly. One <script> tag at the bottom. State in a single in-memory object. No React, no Vue, no jQuery, no framework. No localStorage unless explicitly requested.
10. Close the loop: export back to text. Any artifact the user can do something to (toggle, reorder, tune, edit) MUST end with a button that emits the result as something pasteable — markdown, JSON, a diff, a prompt. The artifact is throwaway; the export is the durable output. This is the single most important convention.
11. Export-first design. Decide what text the user will copy out before designing the UI. The data model serves that export; the UI mutates the data model; the data model must always be derivable into the export string. Applies to any interactive pattern — editor, motion, tokens, table, and interactive variants of plan or pr. Detailed in patterns/editor.md.
12. Live tuning uses primitives from the gallery. When the user asks to tune values live (sliders, toggles, drag-and-drop, sort, filter, swatch pickers), lift the primitive from gallery/interactions.html rather than writing one from scratch. Keeps interaction style consistent across artifacts.

How to start

In this order, every time:

1. Identify the pattern(s). Skim the table below. Pick the closest one. If a request spans two patterns (planning + comparison, explainer + diagram), pick a primary and borrow structure from the secondary — don't refuse to combine.
2. Read the relevant pattern playbook(s). patterns/<name>.md, ~70–150 lines each, opinionated and prescriptive. The playbook owns the shape of the artifact: sections, order, what the export emits.
3. Read the shared template. templates/base.html — boilerplate, CSS variables, utility classes. Start from this rather than rewriting it. Do not redefine the tokens.
4. Decide the export format before the UI (if interactive). What text would the user paste somewhere after they're done? Markdown? A diff? A JSON blob? A re-issuable prompt? The data model serves that export.
5. Write the file. One pass: head → header (title + prompt block) → main content → export button + script.

Reference files (don't copy structure from these)

The gallery/ folder is a look + interaction reference, not a shape reference. Each file shows primitives in isolation; structure for the artifact you're producing comes from the pattern playbook, not from gallery files.

• gallery/look.html — color swatches, type ramp, callout / chip / card / glance / timeline variants. After producing an artifact, mentally compare its surfaces, type, and chips to this file. If they don't match, your tokens drifted — fix them.
• gallery/interactions.html — sliders, toggles, switches, drag-and-drop columns, sortable lists, filter bars, segmented controls, swatch pickers, number steppers. Pull the primitive you need when the user wants to tune values live.
• gallery/navigation.html — tabs, arrow-key deck, sticky side-nav, anchor row, collapsible details, sticky export bar. Pull from here when the artifact needs to move the reader around.

Where the file goes

• If a working directory or output path is implied, write there.
• Otherwise: current working directory, kebab-case filename from the topic. debounced-search-options.html, cycle-14-triage.html, comment-threads-plan.html.
• After writing, tell the user the path and suggest they open it.

Patterns

Each lives at patterns/<name>.md. Read the one you need.

Universal patterns (work for any domain — software, marketing, research, ops, life admin):

Software-specific patterns (assume the user is working with code; descriptions reflect this):

Combining patterns

Real requests cross pattern boundaries. That's normal — combine, don't refuse.

Common combinations:

• plan + options. "Plan the feature, but show me three ways to do the realtime part." → Use plan as the spine, drop an options block inside section 02 (data flow) showing the alternatives for the contested decision.
• explainer + diagram. "Explain how X works." Most good explainers have one or two diagrams. Use explainer as the spine, embed diagram-pattern SVG figures inline.
• status + diagram. A post-mortem with an architecture diagram showing where the failure was. Use status as the spine, embed a diagram in the root-cause section.
• editor + options. "Help me pick which of these features to cut, and show me what the cut and remaining feature lists look like." → An editor (drag-to-cut) whose export emits two markdown lists.

When combining, pick the primary pattern by which one most determines the overall shape of the file. The secondary pattern contributes a section or a component, not the whole structure. Read both playbooks; resolve conflicts in favor of the primary.

Anti-patterns

• Markdown-in-a-<div>. If your <body> is one big <div> of paragraphs and headers, you've produced HTML but not a useful artifact. The content has no shape — use markdown.
• Generic-LLM aesthetics. Avoid the gradient hero, the floating shadowed card, rainbow emoji bullets. These telegraph "AI made this" and undermine authority. Use the base template's restrained tokens; don't reach for decoration.
• No export on an editor. An interactive artifact without a "copy as ..." button is half-built. The user can't get the work back out.
• Frameworks. No React, no Vue, no Tailwind, no Bootstrap. The point is no build step. (Exception: if the user explicitly asks for "a React component", that's a different request — not this skill.)
• External assets. System fonts, inline SVG, no <link rel="stylesheet">, no <img src="https://...">. Render offline.
• Overlong files. A good artifact in any of these patterns is 200–700 lines of HTML. Past 1000, you're building a website when the user wanted a page.

Self-check before declaring done

1. Does it open standalone with no network?
2. Is there a "Prompt:" block near the top?
3. Does the content have shape — grid, timeline, table, diagram — not stacked paragraphs?
4. If interactive: working export button? Export format chosen before the UI?
5. Mobile-readable (columns collapse, type scales)?
6. Kebab-case filename, descriptive of the topic?
7. Did you read the pattern playbook(s)? If no, go back.
8. Did you keep the locked look — cream canvas, coral accent, EB Garamond display, Inter body — straight from base.html? Compare visually against gallery/look.html if unsure.