"HTML is the new markdown."
That's Thariq Shihipar, Claude Code at Anthropic, on X last week.
BUT
CLAUDE.md, AGENTS.md, SKILL.md... Markdown everywhere. It became the air you breathe in a Claude Code project, the default format nobody actually decided on. So when the agent produces an output, it ships Markdown. That's what it has seen everywhere.
Then Thariq drops a gallery of twenty HTML artifacts to back the claim.
TLDR: Markdown took over our projects through config files (CLAUDE.md, AGENTS.md, SKILL.md), then leaked into everything else, including the agent outputs nobody ever reads. A member of the Claude Code team just explained why he switched to HTML, and it boils down to one short command.
For a config file, that's perfect. Short, instructional, read once and stored in context. But when the agent hands you a 200-line plan or a code review report? Different story. You open it, read fifteen lines, close the tab. Three days later you ask the agent again because you have zero memory of what it decided.
The agent worked fine. The format made it disappear.
Back to basics. HTML predates Markdown by more than a decade. The browser was built around it. Markdown was always a shorthand.
Why Markdown Won: The 8,192-Token Excuse
In 2022, ChatGPT shipped with a context window of 8,192 tokens. That's not a lot. For the same content, HTML burns roughly 3x more tokens than Markdown (the figures from web2md.org are about 8,000 tokens for HTML versus 2,800 for the Markdown equivalent). When your budget is 8K and your output cuts into your input, every token saved is a paragraph that survives.
Markdown won that fight on cost.
Simon Willison, one of the loudest voices in the AI dev community, admitted it publicly last week: he had been writing Markdown for LLMs since the GPT-4 days for exactly that reason. He was not wrong. Nobody was wrong, given the math at the time, and the math worked.
It doesn't anymore. Context windows in 2026 sit at one million tokens and counting. The constraint that made Markdown rational has evaporated. The behavior didn't. We kept stuffing .md files into our projects because that's what we had always done, not because it was the right call for what we're doing now.
Pure inertia at this point.
The Community Has Done This Before
The AI community adopts formats in waves. Someone tries something, it works, it spreads, and three years later we look up and notice that the obvious choice from day one was sitting right there.
Same cycle for Markdown in agent outputs: adopted fast, questioned late.
The same instinct led me to argue, a few months back, that CLIs beat MCP for AI agents. The community had jumped on MCP because it was new and shiny, while the boring stable solution had been deployed in production for decades. We do this every twelve months without fail.
The difference this time? It's somebody from inside Anthropic ringing the bell.
What a Member of the Claude Code Team Actually Does
Thariq Shihipar, on the Claude Code team at Anthropic, just published a post with twenty concrete examples. Not theory. Real prompts, real outputs, and artifacts you can open in your browser right now.
The gallery shows what an agent can hand you in HTML that Markdown can't structurally do. A side-by-side spec comparison with two columns, color-coded differences, and a verdict box at the bottom. A code review report where the diff sits annotated inline, severity dots in red/amber/green, jump links to each finding. Or the throwaway editor that comes with a "copy as JSON" button you never asked for but immediately use.
What HTML brings: tables that render, colors that mean something, SVG diagrams, tabs, mobile-responsive layouts, interactive bits when you need them. What Markdown brings: a long scroll.
The thing that matters isn't prettiness. It's this line from Thariq's post:
"I feel more in the loop than ever when using HTML. I have honestly stopped using Markdown altogether for almost everything."
In the loop. That's the entire game. An agent that produced a perfect plan you didn't read is an agent that did nothing. The output exists in a metaphysical sense, sure. The decision it documented is gone the moment you close the tab. A Markdown file you scroll past is the same as no file at all. An HTML file you open in your browser, share by link, screenshot for Slack? That file exists. People read it. You read it. You stay aware of what your agent decided.
The actual unlock is staying part of the workflow. Better-looking artifacts are a side effect.
A plan that's never read is a plan that was never written.
The Honest Caveats
HTML costs more tokens. The token cost is the whole pushback against Thariq's post. When the announcement landed, an account on X (@EXM7777) replied: "yeah sure i will spend 5x the amount of tokens for good looking text files." The reply got traction because it sounds right.
It is right, for one specific case. It's wrong for the case Thariq is talking about.
If your output's primary reader is another LLM (a downstream agent that's going to consume the file, parse it, and act on it), Markdown is fine. The agent doesn't care about colors. It doesn't render tables. Tokens are the only thing that matters. Same logic for quick scratch outputs you'll throw away in three minutes, for high-throughput pipelines where you generate two hundred files an hour, for anything where the cost per output dominates the value of the output.
If your output's primary reader is a human (and you, dear builder, are a human, even on the Friday afternoon when you have already mentally checked out and the boat to spot dolphins leaves in two hours), the calculation flips. The cost is a few cents extra in tokens. The value is whether you actually read the thing. A 5-cent plan you read beats a 1-cent plan you ignored, every time.
The other real caveat Thariq admits himself: HTML files are painful to diff in git. Markdown reads cleanly in a pull request. HTML wraps everything in a soup of tags that makes line-by-line review miserable. If the artifact will live in a repo and be reviewed across commits, Markdown still wins.
Cloudflare also pushes Markdown for the agent input flow, converting web pages to Markdown so agents can consume them efficiently. Different conversation. Web → agent is input. Agent → human is output. Both can be true at the same time without contradiction.
If your reader is a model, Markdown. If your reader is you, HTML.
One Prompt. No Setup.
The whole switch fits in one sentence at the end of your prompt:
"Make this as a single HTML file."
That's it. No CLAUDE.md edit, no skill scaffolding, no setup. Thariq is explicit about this: don't over-engineer it. Try the prompt on your next planning task. See what comes out. If you find yourself reaching for it three times in a row, then maybe think about a skill. Not before.
Same don't-overengineer reflex as when a single open-source repo turned Claude Code into a working n8n architect. The repo was the unlock. Everything I tried to scaffold around it just got in the way.
The gallery has twenty examples sorted by use case: planning, code review, design, prototyping, diagrams, decks, research, reports, custom editors. Pick the one closest to what you're doing tomorrow. Steal the prompt structure. Ship.
My last plan opened in the browser with tabs, a color-coded diff, and a "copy as JSON" button I never asked for. I read all of it. For the first time in a while, I knew exactly what my agent had decided without having to go back and read it three times.
Try "make this as a single HTML file" on your next plan. You'll read it.
Sources
- The Unreasonable Effectiveness of HTML, examples gallery, Thariq Shihipar's 20 examples across 9 categories.
- Simon Willison: Using Claude Code, the Unreasonable Effectiveness of HTML, May 8, 2026.
- Markdown Is Not The Future of LLM Data Infrastructure, DEV Community.
- Markdown for Agents, Cloudflare on the input-side flow.
Top comments (0)