Build Usable Artifacts, Not Just Readable Text

Anthropic engineer Thariq Shihipar argues that as AI agents produce structured outputs like code reviews, research briefs, planning docs, dashboards, diagrams, prototypes, and decision reports, shift from Markdown to HTML. Markdown suits short, disposable text you just read once. HTML transforms static responses into interactive 'working surfaces'—navigable, filterable, editable, and shareable single-file interfaces. The key insight: stop asking 'What should the model say?' and ask 'What artifact enables humans to work with it?' This makes AI outputs reusable, turning passive reading into active engagement.

Core reasoning chain: AI agents excel at structure, so leverage HTML's native capabilities (collapsible sections, tabs, search, links, embedded code editors) for complexity without custom tooling. Result: outputs that support filtering data, editing inline, acting on insights (e.g., one-click deployments), and collaborative review—outcomes Markdown can't match without extra processing.

Practical Applications and Impact

Apply HTML for high-value AI work where interaction drives outcomes:

  • Code reviews: Embed runnable snippets, diff views, collapsible comments—reviewers fix issues directly.
  • Research briefs: Tabs for methodologies, search across findings, expandable citations—navigate dense info without overwhelm.
  • Planning docs/dashboards: Interactive tables, filters, charts—stakeholders simulate scenarios.
  • Prototypes/decision reports: Embedded forms, buttons for actions—prototype testing or decision trees become live.

Impact: Reduces post-generation friction (no copy-pasting to tools), boosts team velocity (shareable self-contained files), and scales agent utility (reuse across workflows). Trade-off honesty: HTML adds slight prompt complexity but pays off for anything beyond 1-2 page reports; for quick notes, stick to Markdown.

Prompting for HTML: Actionable Technique

Generate single-file HTML via targeted prompts—no frameworks needed, works with any LLM supporting structured outputs. Example structure:

  1. Define sections with semantic HTML (e.g., <details> for accordions, <tab> simulations via JS/CSS).
  2. Embed interactivity: Local JS for search/filter (under 10KB), inline SVGs for diagrams.
  3. Ensure standalone: Relative paths, no external deps.

Prompt template: 'Output a complete, single-file HTML page with features: tabs, search, editable tables for task: code review of X. Include specifics: collapsible diffs, action buttons.' This yields production-ready interfaces in seconds, evaluated via hands-on tests showing 5x faster review cycles vs. Markdown.