HTML Artifacts

Markdown is the default agent output. For anything longer than a handful of sentences it is a poor one: it cannot put two options side by side, draw a real diagram, be interactive, or be shared as a page. When the artifact is the deliverable, the reader will do something with it: read it carefully, share it, hand it to an implementer, paste edits back. Make it HTML.

The skill is a judgment call, not a format switch. Most of what follows is about deciding well and then checking the result, because the model already knows how to write HTML.

Reach for HTML when any of these hold

• Comparison. Two or more options the reader must weigh. Side by side beats stacked.
• Spatial information. Diffs, call graphs, module maps, flowcharts, timelines, before/after. Position carries meaning.
• Interaction matters. Easing curves, parameter tuning, state machines, simulations. Things the reader needs to feel.
• Reference material. Navigated non-linearly: tabs, collapsibles, a glossary in the margin, jump links.
• Color or hierarchy carries meaning. Severity, status, syntax, design tokens, data series.
• Data. More than a dozen numbers, a trend, a distribution. A table with sort and filter, or a chart.
• One-off editor. The reader manipulates a thing (drags tickets, toggles flags, tunes a prompt) and needs the result back as text.
• It will be shared. A spec to leadership, a PR writeup to reviewers, a report to a team. People read pages; they skim files.
• Length. Past roughly 100 lines of markdown, navigation and layout earn their keep.

Stay in markdown when