The unreasonable effectiveness of HTML
Why agents should hand back artifacts, not walls of markdown — distilled from Thariq Shihipar's argument and the 20 demos that ship with it.
Markdown became the default because it's portable, easy to edit, and rich-enough. But as agents have grown more capable, markdown has started to feel like a ceiling: hard to read past 100 lines, hard to share, blind to color, motion, spatial structure, and interaction.
The argument here, drawn from Thariq Shihipar's post and his 20 worked examples, is that a single-file .html artifact does almost everything a markdown report does — and several things it can't.
This page is itself a single .html file, composed via the composing-html skill — which exists in spite of Thariq's plea that nobody build a /html skill out of his post. The irony is noted; the convenience won.
What HTML can convey that markdown can't
Markdown handles document structure, lists, code blocks, and a few flavors of emphasis. HTML handles those and:
- Tabular data with real
<table>elements that wrap, sort, and align. - Design tokens with CSS — actual color swatches, type scales, spacing, the lot.
- Illustrations with inline SVG, tweakable by hand and copy-pasteable.
- Interaction via JS + CSS — sliders, toggles, drag-and-drop, copy-as-prompt buttons.
- Workflows drawn as nodes-and-arrows instead of ASCII art that wraps on narrow terminals.
- Spatial layout — absolute positioning, canvases, comparison grids that put options literally next to each other.
- Images via
<img>, including data-URI screenshots inline.
The pathological case Thariq points at: agents reaching for unicode block characters to estimate colors because markdown gives them no other tool. Smell If your output format makes the agent invent escape hatches, the format is wrong.
Color: ▓▓▓ (approximately Anthropic clay, ~#D97757)
Status: 🟢 healthy 🟡 watching 🔴 page
# This is what an agent reaches for when it has no CSS.
# It works, sort of. It is also a small tragedy.<div class="swatch" style="background:#D97757"></div>
<span class="badge badge--ok">healthy</span>
<span class="badge badge--warn">watching</span>
<span class="badge badge--err">page</span>Reading, navigation, sharing
Three failure modes of long markdown that HTML fixes:
- The 100-line wall. Past about a hundred lines, nobody reads markdown — not the author, not their teammates. HTML can use a TOC, collapsible
<details>, tabs, anchored sections, and a sidebar to make a 1000-line spec genuinely navigable. - Sharing. Most browsers don't render
.mdnatively. Markdown gets emailed as attachments or pasted into chat. An.htmlfile uploaded to S3 (or anywhere) is just a link. - Mobile. A media query is one line. Markdown's response to small screens is "good luck."
The second-order effect: if a colleague is more likely to read it, the agent's work has more leverage. Specs, PR writeups, status reports, postmortems — all benefit disproportionately.
Documents that talk back
The unlock that markdown can't touch at all: artifacts you can interact with, not just read. Sliders to tune an animation. Knobs to try design parameters. Drag-and-drop columns to reorder a backlog. A live preview of a prompt template as you type the variables.
The trick that closes the loop is always the same: end with an export button — "copy as JSON", "copy diff", "copy as prompt" — that turns what you did in the UI back into something pasteable into the next agent turn. The artifact stops being a deliverable and becomes a sub-tool you built for thirty seconds of work.
Throwaway editor. Not a product, not a reusable tool. A single HTML file purpose-built for one piece of data, with one export button. Discard after use.
Why Claude Code in particular
Claude.ai and Claude Design can both produce HTML. Claude Code's edge is context: it can read your repo, your git history, your MCPs (Slack, Linear, Jira), pages you've fetched, and synthesize across all of them into one artifact. The article's diagrams were themselves generated by pointing Claude Code at a folder of prior HTML outputs and asking it to categorize them.
The implication for workflow: instead of a single markdown plan, expect a web of HTML files. Brainstorm explorations, expand into one, mock it up, write the plan, hand the whole bundle to a fresh session for implementation. The verifier reads the bundle too, so it has broader context than any single-file plan would give it.
The nine categories
Across his demo set, Thariq groups the work into nine kinds. Each tab below is one of his example prompts — copy and adapt as needed. (The composing-html skill ships templates that map almost one-to-one onto these categories, which is either suspicious or flattering depending on perspective.)
- Exploration & Planning — fan out across directions, then plan the pick.
- Code Review & Understanding — annotated diffs, module maps, PR writeups.
- Design — design system swatches, component variants.
- Prototyping — animation sandboxes, click-through flows.
- Illustrations & Diagrams — SVG figure sheets, real flowcharts.
- Decks — arrow-key slides from a Slack thread.
- Research & Learning — feature explainers, concept explainers with live demos.
- Reports — weekly status, incident postmortems.
- Custom Editors — triage boards, flag editors, prompt tuners.
I'm not sure what direction to take the onboarding screen. Generate 6
distinctly different approaches — vary layout, tone, and density — and lay
them out as a single HTML file in a grid so I can compare them side by side.
Label each with the tradeoff it's making.Create a thorough implementation plan in a HTML file, be sure to make some
mockups, show data flow and add important code snippets I might want to
review. Make it easy to read and digest.Help me review this PR by creating an HTML artifact that describes it.
I'm not very familiar with the streaming/backpressure logic so focus on
that. Render the actual diff with inline margin annotations, color-code
findings by severity and whatever else might be needed to convey the
concept well.I want to prototype a new checkout button — when clicked it does a play
animation and then turns purple quickly. Create a HTML file with several
sliders and options for me to try different options on this animation, give
me a copy button to copy the parameters that worked well.I don't understand how our rate limiter actually works. Read the relevant
code and produce a single HTML explainer page: a diagram of the token-
bucket flow, the 3–4 key code snippets annotated, and a "gotchas" section
at the bottom. Optimize it for someone reading it once.I need to reprioritize these 30 Linear tickets. Make me an HTML file with
each ticket as a draggable card across Now / Next / Later / Cut columns.
Pre-sort them by your best guess. Add a "copy as markdown" button that
exports the final ordering with a one-line rationale per bucket.Here's our feature flag config. Build a form-based editor for it, group
flags by area, show dependencies between them, warn me if I enable a flag
whose prerequisite is off. Add a "copy diff" button that gives me just the
changed keys.I'm tuning this system prompt. Make a side-by-side editor: editable prompt
on the left with the variable slots highlighted, three sample inputs on
the right that re-render the filled template live. Add a character/token
counter and a copy button.The objections, answered
Isn't HTML less token-efficient?
Yes, often. But the expressiveness gain — and the much higher chance you'll actually read it — usually wins. With a 1MM-token context window in Opus 4.7, the extra tokens are not pinching anywhere they used to.
When do you still use markdown?
Almost never, on Thariq's account. He's at the maximalist end. A reasonable middle: short notes, chat-friendly status pings, anything that's going to be read once in a terminal — markdown. Anything you'd want a colleague to read, or that has structure beyond linear prose — HTML.
How do I view the file?
Open it locally in a browser (you can ask Claude to open it for you). For sharing, upload to S3 or any static host and pass the link.
Doesn't generation take longer?
2–4× longer than equivalent markdown. The output quality usually justifies it. Caveat for skill users: a templated build via composing-html is closer to markdown's speed because the chrome is pre-baked — only the spec gets generated.
What about version control?
The honest weakness. HTML diffs are noisy and a pain to review. If something is going to be diffed regularly, markdown still wins. If it's an artifact you produce once and read many times, HTML wins.
How do I keep it from being ugly?
Two routes: (a) the frontend design plugin, which gives Claude solid defaults; (b) a single design system HTML file generated from your codebase, then passed as a reference to every subsequent artifact. The composing-html skill takes a third route — design tokens are baked into the page chrome, so the artifact inherits them automatically.
The real reason
Behind the engineering arguments is a softer one. As agents do more, the temptation is to stop reading their output carefully — and to drift out of the loop on choices the agent is making. Long markdown plans accelerate this drift because they're tedious to read.
HTML artifacts pull the human back in. They're more fun to make, more fun to read, easier to share, and the interactive ones — sliders, knobs, drag-and-drop, copy-as-prompt — close the loop in the other direction. The author isn't reviewing the agent's work; they're collaborating with the artifact. That's the unreasonable part.