Note: This post was written by Claude, directed and proofread by me.
When I ask an agent for a report — a research summary, a project plan, a comparison, a daily digest — I used to take whatever it gave me. Usually markdown. Sometimes a wall of text.
Then I started asking for HTML. Not just styled HTML — a single self-contained file with inline styles and inline scripts. Filters, sortable tables, collapsible sections, charts. The jump in output quality was bigger than I expected.
Markdown is fine when you're reading inside a chat window that renders it. The moment you take it anywhere else, it breaks:
.md file — half your tools open it as plain text## headings and **bold** like raw syntaxIt's a portable format that's only beautiful at the source. Anywhere downstream, you're a step away from a polished artifact.
When I ask for the same content as a single HTML file, I get something I can:
That last bit — "work for the person on the other end" — is the part I underestimated for too long. HTML is a runtime, not just a layout. Once you ask the agent to inline a bit of JavaScript, the report stops being a document and starts being a small app:
localStorageNo backend, no build step, no framework. One .html file the agent wrote. You attach it, the recipient double-clicks, and they're inside an interactive report — sorting, filtering, ticking off tasks. No screen share, no "let me show you," no live demo.
A few things I've stopped asking for in markdown:
localStorage. Drag the file into the team chat, done.For anything I'd want to keep or share, HTML wins. Markdown stays where it's good: inside the chat I'm having right now.
Don't repeat the spec every time. Don't even write a spec. One line in CLAUDE.md (or a saved memory) does the job:
# Reports
Default to a single self-contained, interactive HTML file for any report,
plan, or digest — unless I ask for a different format.That's the whole rule. No bullet list of "use inline CSS, sortable tables, callouts." The agent knows what a good report looks like — let it decide. If I don't like the result, I correct it once — "darker background, more whitespace, persist checkbox state" — and ask the agent to fold that into the rule. The baseline gets better over time, without the rule getting longer.
Now the actual prompt is whatever I would have typed anyway. No "as an HTML report" suffix. I just ask for the report and get one.
This isn't free. An HTML report is easily 5–10x more output tokens than the markdown version of the same content — inline CSS, scripts, ARIA attributes, the lot. That means:
So I don't do this for everything. Quick answers, chat replies, scratch notes — markdown is right. The moment I want something I'll keep, share, or hand to someone else, the extra tokens are worth it. The artifact lives much longer than the request that made it.
Format is part of the output. Asking for markdown when you want a document is like asking for a sketch when you want a finished drawing. The agent is happy to do either — you just have to ask for the right one.
HTML is a single-file artifact and a runtime. No build step, no framework, no "open it in the right tool" — but the moment you want it to do something, it already can.
Markdown is a transport format, not a deliverable. Good for the conversation. Wrong for the result.
The next time you catch yourself reading a long markdown response and thinking "I wish this looked nicer" — ask for HTML. You'll get the same content as something you actually want to keep.
If you want to discuss, find me on X.