One question routes everything: is this for reading or editing? Read → HTML. Edit → Markdown.
Markdown became the AI default in the GPT-4 era: cheap tokens, machine-readable, hand-editable. That default assumed a human would open the file and edit it. Mostly false now. Most AI output gets read once, on a phone, by someone who never opens a Markdown viewer. HTML renders on open, looks designed, shares as a link. Same words, different perceived value, different odds it gets read at all.
The routing rule
Reader is a human consuming once → HTML. Reader is a human (or AI) who will edit, version, or re-parse → Markdown. This single test handles nearly every case.
| Format | Use for | Why |
|---|---|---|
| HTML | Reports, briefings, summaries, plans, retros, status pages, memos, decks, client-facing docs | Read once, renders on open, shareable, commands attention |
| Markdown | READMEs, specs, configs, working drafts, CLAUDE.md, skill files, agent prompts | Edited by hand or re-parsed by AI; clean diffs; cheaper tokens |
The tips
1. Set the default once in CLAUDE.md
One paragraph in global or project CLAUDE.md flips every session. No per-prompt nagging. The “reading vs editing” line handles edge cases on its own. Prompt below.
2. One file, zero dependencies
Single .html: CSS inline in <style>, charts inline as SVG, no CDN fonts, no external JS unless genuinely interactive. Survives email, Slack paste, Notion drop, compliance archive. Self-contained = the artifact actually travels.
3. Print stylesheet, always
A @media print block: strip backgrounds, fix margins, force page breaks at sections. Executives print reports more than expected. Cheap to add, disproportionate payoff.
4. Restrain the design
Default model instinct: icons, gradients, Tailwind-playground energy. Counter it in the instruction. Three rules: max two accent colors, generous whitespace, sans-serif body. Looks like a careful human made it, not a demo.
5. Don’t build an HTML template skill
Tempting failure mode: a /html skill with 20 fixed templates (weekly_report, pr_review, incident…). Adds a slot grammar the content has to contort into. The slots never match what you want this time. Thariq, who started the whole thing, warned against exactly this — “just ask it to make an HTML file.” The model already knows how.
The cost nobody mentions: tokens
HTML isn’t free. Clean HTML runs 2–3x the tokens of equivalent Markdown. Real HTML with CSS and JS: 8–10x. Million-token context windows soften this, but it compounds at scale — every scheduled report, every agent run. The reason this is worth it for human output: a report nobody opens cost infinity per read regardless of token count.
Where Markdown still wins outright
Not nostalgia. Three places Markdown is the correct answer, not the lazy one.
- Agent-to-agent — output another model will parse. Markdown parses more accurately: ~61% table-extraction accuracy vs ~54% for HTML in GPT benchmarks; RAG pipelines gain up to 35% on Markdown over raw HTML. Cheaper and cleaner for the machine reader.
- Repo docs — READMEs, API specs, architecture notes. Edited by humans, rendered by GitHub. The platform handles the look.
- Working drafts — anything revised over days or weeks. Clean diffs, better editing. Switch to HTML only when it’s done and meant to be read.
The security caveat
AI-generated HTML can carry JavaScript → XSS and injection risk if rendered in a trusted environment. Fine for a report you open yourself; a real concern for agent output piped into production surfaces. Google’s A2UI protocol exists specifically so agents declare UI components instead of writing arbitrary HTML. For self-contained reports you generate and read, drop the JS and the risk goes with it.
FAQ
Do I need a skill or plugin for this?
No. Ask for an HTML file, or set the CLAUDE.md default. A template skill usually makes it worse, not better.
Why not just render the Markdown when I need it?
The “I’ll render it later” intention almost never fires. The file sits in a folder and gets deleted unopened. Render-on-open is the entire point.
Isn’t the token cost a dealbreaker for scheduled reports?
Weigh it against read rate. A daily briefing opened every morning beats a cheaper one opened 40% of mornings. At very high volume, or for agent-to-agent steps, the math flips back to Markdown.
What about version control on HTML?
HTML diffs are noisy — closing tags and attributes drown the actual change. If the file gets versioned and reviewed, keep it Markdown. HTML is for the read-once output, not the tracked source.
Do this once
- Pick one artifact you generate regularly but rarely reread — standup notes, weekly summary, client brief.
- Add the CLAUDE.md block below.
- Re-run it. Open the HTML version. Note the perceived-value jump.
- After a week, check which artifacts you actually opened. The HTML ones dominate.
Snippets
CLAUDE.md output-format default
Drop this in your global or project CLAUDE.md to make HTML the default for human-facing artifacts and keep Markdown for editable ones. The reading-vs-editing line does the routing.
## Output format
When you produce an artifact, decide first: is this for someone to READ,
or for someone to EDIT? Read = HTML. Edit = Markdown.
READ (reports, briefings, summaries, plans, retros, status updates, memos,
decks, anything client- or stakeholder-facing):
- Single self-contained .html file: inline CSS, inline SVG for charts,
no external fonts/CDN/JS (unless the artifact is genuinely interactive)
- Semantic HTML (h1, h2, sections)
- Clean typography, generous whitespace, max two accent colors, sans-serif body
- Include an @media print block (strip backgrounds, fix margins,
page breaks at sections)
- Save as .html alongside any Markdown source
EDIT (specs, configs, READMEs, project notes, CLAUDE.md, skill/agent files,
drafts still in progress):
- Keep Markdown as the primary format
When unsure, ask the read-vs-edit question and follow it.Variables: accent-color count, body font, the read/edit category lists (tune to your own artifact types).
Tags: claude-md, output-format, html, markdown, defaults, claude-code, reports
Read-vs-edit routing test
A one-line decision rule for any AI output, reusable far beyond this topic. Apply before choosing a format.
Is this artifact going to be READ (consumed once, by a human) or
EDITED / RE-PARSED (revised by a person, versioned, or fed to another model)?
Read -> HTML (rendered, shareable, self-contained)
Edit -> Markdown (clean diffs, cheap tokens, machine-parseable)Tags: decision-rule, format-choice, ai-output, workflow
Self-contained HTML report checklist
Run through this whenever you want an AI-generated HTML doc that survives sharing and printing. Paste as a one-shot instruction or keep as a review pass.
- All CSS inline in
<style>— no external sheets - Charts as inline SVG — no image hosts, no chart libraries
- No CDN fonts, no external JS (unless truly interactive)
@media printblock: strip backgrounds, fix margins, break at sections- Max two accent colors, generous whitespace, sans-serif body
- Semantic structure: h1, h2, sections
- Opens correctly from a saved file with no network
Tags: checklist, html, reports, self-contained, print, design