Anthropic's html-effectiveness: 20 Examples for HTML vs Markdown Agent Output

If you build agents, you eventually hit the question of what format they should emit. Most people default to Markdown because it's readable, cheap in tokens, and renders everywhere. But Markdown runs out of room fast once you want tabs, status badges, collapsible sections, diagrams, or an interactive control panel. Anthropic's html-effectiveness repo is a direct response to that gap: a collection of 20 worked HTML examples showing where HTML output earns its keep over Markdown.

What it actually is

The repo is not a library or a framework. It's a set of standalone `.html` files plus an `index.html` to browse them, along with a README and the usual contributing and license files. Each numbered file is a self-contained example of an agent producing HTML for a specific task. Looking at the filenames tells you the scope pretty clearly:

• Exploration outputs (`01-exploration-code-approaches`, `02-exploration-visual-designs`)
• Code work (`03-code-review-pr`, `04-code-understanding`, `17-pr-writeup`)
• Design artifacts (`05-design-system`, `06-component-variants`, `10-svg-illustrations`)
• Prototypes (`07-prototype-animation`, `08-prototype-interaction`)
• Documents and reports (`09-slide-deck`, `11-status-report`, `12-incident-report`, `16-implementation-plan`)
• Diagrams (`13-flowchart-diagram`)
• Explainers (`14-research-feature-explainer`, `15-research-concept-explainer`)
• Editor-style tools (`18-editor-triage-board`, `19-editor-feature-flags`, `20-editor-prompt-tuner`)

That spread is the point. These are the kinds of outputs where a flat Markdown document feels cramped: a status report that wants color-coded severity, an incident writeup with a timeline, a triage board with columns, or a slide deck with actual slides. The repo shows what "good" looks like for each so you can copy the pattern rather than reinvent it.

It's an Anthropic project, which matters mainly because it reflects how their models tend to be prompted and what they can reliably produce. But nothing here is Claude-specific. The output is plain HTML, so the same techniques apply whether you're driving Claude, OpenAI, or another model.

Why this matters for automation

When you wire a model into a workflow, the output format is a design decision, not an afterthought. If your agent's job ends in a human reading a report, Markdown is usually fine and cheaper on tokens. But a lot of automation output is meant to be consumed as an artifact: a report emailed to a stakeholder, a dashboard embedded in a Notion page, a status page, a slide deck handed to a client. In those cases HTML lets the model carry structure and presentation together instead of leaving you to post-process.

The examples double as prompt scaffolding. If you want your agent to produce a consistent incident report every time, you can lift the structure from `12-incident-report.html` and feed it as a template or few-shot example. The same goes for the triage board or the implementation plan. This turns a vague instruction like "summarize the incident" into a repeatable, styled output your team recognizes at a glance.

There's a practical tradeoff worth naming. HTML is more verbose than Markdown, so it costs more tokens on both input examples and generation. It's also easier to get wrong: unclosed tags, broken inline CSS, or SVG that doesn't render. And if you're going to inject model-generated HTML into a page or email, you're now responsible for sanitizing it, because HTML can carry script and styling you don't want. The repo shows you what effective HTML looks like; it doesn't handle the security side of embedding untrusted output, so treat that as your job.

Where it fits versus alternatives

The honest comparison is Markdown, and the repo isn't arguing you should abandon it. The framing is about effectiveness for a given task. For plain chat responses, notes, and anything a person skims in a terminal or a chat window, Markdown wins on simplicity and cost. HTML earns its place when the output is a deliverable with layout, interactivity, or visual encoding that Markdown can't express: tabs, badges, columns, animations, embedded SVG diagrams.

For builders on n8n, Make, or Zapier, the fit is straightforward. If a step generates an HTML artifact, you can drop it into an email node, save it to a file, or render it to PDF downstream. The examples give you known-good structures to prompt against, which reduces the trial-and-error of getting a model to produce clean, consistent HTML. If you're already generating Markdown and converting it to HTML with a rendering step, this is a nudge to consider having the model produce the richer format directly when the layout matters.

A few caveats before you commit. This is a small, example-driven repo, not a maintained toolkit, so treat it as reference material rather than a dependency. There are no benchmarks here proving HTML "works better" in a measurable sense; the value is in the concrete patterns. And every HTML output you emit is more to review, test, and sanitize than the Markdown equivalent. Use it where the format genuinely buys you something.

If you want help deciding where richer agent output pays off and wiring it into a real pipeline, browse the provider directory to find someone who can put it to work.