HTML or Markdown for AI Agents? Let the Reader Decide

A one-minute Short claimed Anthropic had stopped using Markdown for agent output and switched to HTML. The comment thread under it passed a million views and split cleanly in two: “HTML is the future of agent output” against “simplicity is the feature.” Thomas at DIY Smart Code did what a comment thread can’t, and measured it: four formats, four jobs, 72 Claude Code runs. This is our reading of his results, what they mean for anyone running agents at volume, and a way to choose.

What freeform HTML actually spends tokens on

The first job was a status report. In Markdown it cost 883 output tokens. Asked for HTML with no constraints, the same report cost 7,204, more than eight times as much (1:34). The content was the same. The difference was everything around it: roughly three quarters of the freeform output was CSS, hand-drawn SVG and JavaScript the model invented from scratch.

It gets worse with visual jobs. An architecture diagram and a drag-and-drop task board ran up to 21 times the Markdown cost (2:29). The diagram run burned 5,091 thinking tokens just working out SVG coordinates. And it wasn’t predictable: freeform boards ranged from 10.8k to 17.5k tokens between runs of the same prompt.

The fix is a template, not a format war

The interesting result isn’t that HTML is expensive. It’s that the cost comes almost entirely from design, so you can remove it (3:19). His agent-html-kit puts the design in one shared kit.js file and gives the agent content-only components to fill. Kit boards cost 573 to 625 tokens: about Markdown’s price, with a spread of 52 tokens instead of 6,700. Markdown plus a renderer was cheapest of all, at 569 tokens for the report.

A predictable cost is often worth more than a low one. You can budget a page that always costs 600 tokens. A page that costs anywhere from 10,000 to 17,500 is hard to budget, and it uses up your subscription limits unevenly.

Plans for agents: the format didn’t matter, the price did

The test that matters most for agentic coding is plans one agent writes for another to build from. Both formats produced code that passed 19 of 19 hidden tests (4:54). HTML plans cost about two thirds more and bought nothing. Then came a small edit to an existing plan: in Markdown it was a clean change, while the freeform HTML plan picked up a bug (6:31). Prose inside markup is harder to edit precisely, and harder to review in a diff.

This is why CLAUDE.md, AGENTS.md, SKILL.md and llms.txt are all Markdown. The reader is a model, and models read structure, not styling. The four-rule CLAUDE.md works partly because it is short plain text that every session loads cheaply.

Where the numbers stop

• At volume. 1,000 boards at list price came to about $361 freeform against $39 with the kit (7:15). On a subscription, the cost shows up as hitting usage limits sooner instead.
• One person, one setup. 72 runs is a careful test, not a study. Treat the ratios as direction, not constants, and measure your own prompts.
• No screenshots. The benchmark counted tokens and test passes. It didn’t score how good each page looked, which is the whole reason to choose HTML.
• Disclosure. The channel says its videos are made with AI tools, and this one includes paid promotion. The repository and run data are public, which is what matters for checking the claims.

Choosing by the reader

His closing advice (8:02) comes down to three questions: who opens the file, how often you generate it, and whether it has to be interactive. We turned that into a chooser.

For websites, the same split holds. Pages people read should be real, semantic HTML with structured data, because that is what AI search engines read and cite. The working files behind them, like specs, plans and rules, should stay Markdown. That is how one person can run the whole website pipeline without the token bill growing with every page. Payback is quick: if you generate more than a few dozen pages, an afternoon spent on a template is cheaper than letting the agent redesign every page.

For the bigger picture, see Harness² on how standing rules improve over time, and the agent harness those files sit inside.

The comment thread asked the wrong question. Markdown versus HTML is really about who reads the file, and whether you pay for design once or on every page.