Markdown has become the dominant file format for AI agents to communicate with us. It's simple, portable, supports basic rich text, and is easy to edit. But as agents have grown more powerful, I've started to feel like markdown is a straitjacket. I find it hard to read a markdown file over a hundred lines—my eyes glaze over. I want richer visualizations, color, diagrams, and the ability to share them effortlessly.
I'm also increasingly not editing these files myself. Instead, I use them as specs, reference files, brainstorming outputs. When I do make edits, I usually prompt Claude to do it, which removes one of markdown's biggest advantages.
So I've started preferring HTML as an output format instead of markdown. I'm not alone—others on the Claude Code team are doing the same. Here's why.
(If you want to jump straight to examples, you can see a bunch here — but come back to read the reasoning.)
HTML can convey much richer information compared to markdown. Sure, it can handle simple document structure like headers and formatting, but it can also represent:
- Tabular data with tables
- Design data with CSS
- Illustrations with SVG
- Code snippets with script tags
- Interactions using HTML elements with JavaScript + CSS
- Workflows using SVG and HTML
- Spatial data using absolute positioning and canvases
- Images with image tags
I'd go so far as to say there's almost no set of information that Claude can read that you can't efficiently represent with HTML. That makes it a highly efficient way for the model to communicate in-depth information to you—and for you to review it.
Without HTML, the model does inefficient things in markdown, like ASCII diagrams or, my favorite, estimating colors with Unicode characters. Here's a screenshot from Claude Code:
Claude Code trying to show color in markdown.
As Claude tackles more complex work, it writes larger specs and plans. In practice, I've found I rarely read more than 100 lines of a markdown file, and I certainly can't get anyone else in my organization to read it.
But HTML documents are much easier to read. Claude can organize the structure visually with tabs, illustrations, links, and even make it mobile-responsive so you can read it differently on different devices.
Markdown files are hard to share because most browsers don't render them natively. You often have to attach them to emails or messages. With HTML, you can upload the file (to S3, for example) and share a link. Your colleagues can open it anywhere and easily reference it. The chance of someone actually reading your spec, report, or PR writeup is much, much higher if it's in HTML.
HTML lets you interact with the document. You might ask Claude to add sliders or knobs to adjust a design, or tweak options in an algorithm to see what happens. You can even copy those changes into a prompt to paste back into Claude Code. (Check out my playgrounds post for examples of this two-way interaction.)
Data Ingestion
Why use Claude Code to make HTML files instead of, say, ClaudeAI or Claude Design? One of the biggest reasons is all the context Claude Code can ingest. For example, when writing this article, I asked Claude Code to read through my code folder, find all the HTML files I've generated, group and categorize them, and then make an HTML file with diagrams representing each type. The diagrams you see in this article are a direct result of that.
Besides the file system, Claude Code can find additional context using your MCPs (like Slack, Linear, etc.), your web browser (with Claude in Chrome), your git history, and more.
Making HTML documents with Claude is just more fun. It makes me feel more involved and invested in the creation—and that by itself is enough.
I'm a little afraid that people will read this and turn it into a /html skill or something. While there might be some value in that, I want to emphasize that you don't need much to get Claude to do this. Just ask it to "make an HTML file" or "make an HTML artifact."
The real trick is knowing what you want the artifact to do and how you'll use it. You might eventually make a skill, but for now I'd suggest prompting from scratch to get a feel for it.
To make this more concrete, I've made many different HTML files for different use cases. You can view all of them here:
but here's an overview.
Think of HTML as Claude’s canvas. When I start working on a problem, I don’t just jot down a markdown plan — I build a web of HTML files. For example, I might begin by asking Claude Code to brainstorm and explore different options. Then I ask it to expand on one, maybe with mockups or code snippets. Finally, when it feels right, I ask for an implementation plan. Once I’m happy with that plan, I spin up a new session, feed it all those files, and let it implement.
When I’m verifying, I also ask the verification agent to read those files — it gets a much broader context on what’s needed.
Example Prompts:
I'm not sure what direction to take the onboarding screen. Generate 6 distinctly different approaches — vary layout, tone, and density — and lay them out as a single HTML file in a grid so I can compare them side by side. Label each with the tradeoff it's making.
Create a thorough implementation plan in a HTML file, be sure to make some mockups, show data flow and add important code snippets I might want to review. Make it easy to read and digest.
Use Cases:
Exploring other ways to implement something in code
Exploring multiple visual designs
Code can be difficult to read in a Markdown file. But with HTML we can render diffs, annotations, flowcharts, modules, etc. Use this to understand code that the agent has written, to get code review or to explain a PR to someone reviewing your code. I find this often works better than the default Github diff view, and I attach a HTML code explainer to every PR I make now.
Example prompt:
Help me review this PR by creating an HTML artifact that describes it. I'm not very familiar with the streaming/backpressure logic so focus on that. Render the actual diff with inline margin annotations, color-code findings by severity and whatever else might be needed to convey the concept well.
Use Cases:
Creating a PR
Reviewing a PR
Understanding a topic in Code
Claude Design is based on HTML because HTML is incredibly expressive at design, even if your end surface is not HTML. Claude can sketch out a design in HTML and then write it in your language of choice, be it React, Swift, etc.
You can also prototype interactions, such as animations, actions, etc. Consider asking Claude to make sliders, knobs, etc. to tune in exactly what you’re looking for.
Example prompt:
I want to prototype a new checkout button, when clicked it does a play animation and then turns purple quickly. Create a HTML file with several sliders and options for me to try different options on this animation, give me a copy button to copy the parameters that worked well.
Use this for:
Creating design system artifacts
Adjusting components
Visualizing component libraries
Prototyping Joyful Animations
Claude Code is incredibly good at synthesizing information across multiple data sources and converting it into a report for readability. You can prompt Claude to search your Slack, your codebase, git history, the internet, etc. and use it to generate extremely readable reports for yourself, for leadership, for your team, etc.
You could assemble this in the form of a long HTML document, an interactive explainer or even a slideshow/deck. Ask Claude to use SVG for diagrams to help visualize it. For example, for my posts on prompt caching, I asked Claude to prepare an in-depth research file in HTML for me to read on all of our changes to prompt caching after reading the git history.
Example prompt: I don't understand how our rate limiter actually works. Read the relevant code and produce a single HTML explainer page: a diagram of the token-bucket flow, the 3–4 key code snippets annotated, and a "gotchas" section at the bottom. Optimize it for someone reading it once.
Use this for:
Summarize how a feature works
Explain a concept to me
Weekly status reports to your boss
Incident reports to your leadership
SVG illustrations, flowcharts, technical diagrams, etc
Sometimes it’s hard to describe what you want purely in a text box. In this case, I'll ask Claude to build me a throwaway editor for the exact thing I'm working on. Not a product, or a reusable tool, but a single HTML file, purpose-built for this one piece of data.
The trick is always to end with an export: a "copy as JSON" or "copy as prompt" button that turns whatever I did in the UI back into something I can paste into Claude Code.
Example prompts:
I need to reprioritize these 30 Linear tickets. Make me an HTML file with each ticket as a draggable card across Now / Next / Later / Cut columns. Pre-sort them by your best guess. Add a "copy as markdown" button that exports the final ordering with a one-line rationale per bucket.
Here's our feature flag config. Build a form-based editor for it, group flags by area, show dependencies between them, warn me if I enable a flag whose prerequisite is off. Add a "copy diff" button that gives me just the changed keys.
I'm tuning this system prompt. Make a side-by-side editor: editable prompt on the left with the variable slots highlighted, three sample inputs on the right that re-render the filled template live. Add a character/token counter and a copy button.
Use this for:
- Reordering, triaging, or bucketing anything — tickets, test cases, feedback
- Editing structured config — feature flags, env vars, JSON/YAML with constraints
- Tuning prompts, templates, or copy with live preview
- Curating datasets — approve/reject rows, tag examples, export the selection
- Annotating a document, transcript, or diff and exporting the annotations
- Picking values that are painful to express in text: colors, easing curves, crop regions, cron schedules, regexes
I've been telling people about my switch to HTML, and a few questions keep coming up.
Isn't it less token efficient? While markdown often uses fewer tokens, the added expressiveness of HTML and the much higher likelihood that I'll actually read it means I get better output overall. With the 1M context window in Opus 4.7, the increased token usage barely registers.
When do you still use markdown? I've honestly stopped using markdown for almost everything. I'm probably on the far end of the HTML maximalist spectrum.
How do you view the HTML file? I just open it in a browser locally — you can ask Claude to open it — or upload to S3 for a shareable link.
Doesn't this take longer to generate? Yes, it does. HTML can take 2-4x longer than Markdown, but the results are worth it.
What about version control? That's one of the biggest downsides. HTML diffs are noisy and hard to review compared to Markdown.
How do you get Claude to match your taste and not make it ugly? The frontend design plugin helps Claude make good HTML files. To match your own company's style, you can create a single design system HTML file by pointing Claude at your codebase. Then use that as a reference for other HTML files.
All of this is to say that the real reason I use HTML is that I feel much more in the loop with Claude. I was starting to worry that because I'd stopped reading plans in depth, I'd have to just trust Claude's choices blindly. But I'm happy to say that with HTML, I feel more in the loop than ever. I hope you do too.