prefer-html — Claude skill for HTML-over-markdown artifacts

prefer-html_SKILL.md

name

prefer-html

description

When the answer is spatial, interactive, comparative, or skim-and-scan, produce a single self-contained .html file instead of a wall of markdown. Use for side-by-side option comparisons, implementation plans with diagrams, annotated diffs and PR writeups, module maps, design system snapshots, animation and interaction prototypes, SVG figures, flowcharts, slide decks, concept explainers, status reports, post-mortems, and throwaway editors (triage boards, flag toggles, prompt tuners). Trigger when the user says "show me", "lay them side by side", "mock it up", "make a deck/board/flowchart", "let me play with it", asks for a comparison, plan, dashboard, or any artifact that benefits from being clickable, draggable, or navigable rather than read top-to-bottom.

Prefer HTML

A wall of markdown is a document you skim. A single .html file is one you read.

When the answer is spatial, interactive, comparative, or skim-and-scan, write it as one self-contained file instead of prose. The user opens it in a browser. No build step, no export, no chat-window renderer in the middle.

Adapted from Tariq Sheikh, The unreasonable effectiveness of HTML.

Pick a recipe

Match the request to one of these. Each replaces something an agent would otherwise dump as markdown.

• Multiple options to compare → three code approaches, four design directions, six layouts. Side by side, so the user points at one instead of holding three walls of text in their head.
• A plan with shape → milestones on a timeline, a data-flow diagram, the risky code inline, a risk table. The thing you actually hand off to the implementer.
• A code change → an annotated diff with margin notes, severity tags and jump links; or a PR writeup with motivation, before/after, file-by-file tour, and where to focus the review.
• An unfamiliar module → boxes and arrows, hot path highlighted, entry points listed. Markdown flattens call graphs; HTML draws them.
• A design surface → tokens as swatches, every component variant on one sheet. HTML is the medium your design system ships in — use it.
• Motion or interaction → the transition in isolation with sliders for duration and easing; or four screens linked together. Felt in five seconds; impossible to describe in prose.
• A figure or flowchart → inline SVG. Vector art the user can tweak by hand or paste into the final doc. Click steps to reveal timings, logs, failure paths.
• A deck → a handful of <section> tags and twenty lines of JS. Arrow keys to navigate. Skip Keynote.
• An explainer → TL;DR box, collapsible steps, tabbed code samples, hover-linked glossary. Reads very differently from the same words dumped linearly.
• A recurring report → small chart, colored timeline, what shipped vs what slipped. For status updates, post-mortems, incident timelines — turns a skim into a read.
• A throwaway editor → when it's hard to describe what you want in a text box, build a tiny UI for the exact thing. Drag a triage board, toggle feature flags with dependency warnings, tune a prompt with live preview.

If the request straddles two recipes, pick the dominant one and mention the other in a header note. Don't try to do all of them in one file.

Rules that apply to all of them

1. One self-contained .html file. Inline the CSS and JS. No build step, no package.json, no install. The user double-clicks the file and it works. CDN script tags (Tailwind, a single React UMD bundle, Chart.js) are fine; npm-installed dependencies are not.
2. Open in a browser, not a renderer. Test that file:// opens it correctly. Don't write something that only renders inside a chat-window viewer.
3. Spatial information gets a spatial layout. Diffs, comparisons, call graphs, timelines, board states — never collapse them back to prose. If you'd reach for a |---| markdown table, reach for a real one.
4. Always provide an export back to text. A "copy as markdown" button, a "copy diff" button, a serialized JSON dump, a downloadable file. The user did work in your UI; they need it back inside the agent loop. This is what closes the loop.
5. Throwaway by default, no scaffolding. No router, no state library, no test setup. If the artifact outlives its purpose, the user extracts what's worth keeping. Don't pre-engineer for a v2.
6. Surface the state. For interactive artifacts, render the current state visibly somewhere — selected option, current variant, drag-ordered list, toggled flags. The user should never have to wonder what they've done.
7. No persistence unless asked. State lives in memory; refresh resets. The artifact answers a question once and gets thrown away.
8. Mark it as a prototype. A small banner, a comment at the top of the file, or a footer line — anything that signals this is a throwaway artifact, not production output.

When not to reach for HTML

• The answer is one paragraph or one code block. Just write it.
• The user is piping the output through another tool that expects markdown or plain text.
• The artifact would be mostly prose with no interaction, comparison, or spatial structure — that's a styled blog post, and markdown is fine.
• The user explicitly asked for markdown, a code patch, or a terminal-friendly format.

When done

The HTML file is the medium, not the deliverable. If it produced a decision — one of three options picked, a triaged ordering, a tuned prompt, a flag set — capture that in something durable: a commit, a PRD, an ADR, a message pasted back to the agent. Then delete the HTML, or leave it next to the work it informed with a comment marking it as the prototype that produced the decision.