Plans, comparisons, code reviews, status reports, throwaway editors — they read dramatically better as self-contained HTML than as markdown documents. This skill teaches Claude when to make an HTML artifact instead, and equally important, when to leave well enough alone.
Six artifacts below, each produced by the skill in response to a real prompt. This page is itself one of them.
Markdown is optimized for documents — files you edit by hand, diff in version control, scroll through linearly. Agents are increasingly producing artifacts: things you read once and act on, share by link, or manipulate. For those, markdown's restrictions actively obscure the content.
HTML lifts those restrictions. Side-by-side comparison instead of stacked sections. A real flowchart instead of ASCII boxes. A live demo instead of paragraphs about how something would feel. A throwaway editor that round-trips back to markdown so you stay in the loop.
## Approach 1: inline useEffect - pro: zero deps - pro: easy to debug - con: duplicated everywhere ## Approach 2: custom hook - pro: reusable - pro: testable - con: one more file ## Approach 3: library - pro: edge cases handled - pro: well-tested - con: +1.4 kb
Each is a self-contained .html file. None has a build step; none calls a server at view time; each is the kind of artifact the skill produces on prompt. Open any of them directly.
Three approaches in three columns, identical structure. Code, pro/con tables, hard metrics, and an actual recommendation at the bottom — the thing markdown structurally can't do.
01-sse-comparison.html 02 Research & learningConcept explainer with a live golden-car simulation — drag the bump amplitude up, watch IRI climb. Comparison to RMS-of-profile, marginal glossary, "where you'll meet it."
02-iri-explainer.html 03 Custom editorEight pre-filled tickets, drag between Now / Next / Later / Cut, click tags to filter. Ends with the non-negotiable feature: a copy as markdown button that round-trips your work back into a paste-able doc.
03-triage-editor.html 04 ReportShipped / in flight / blocked, color-coded, 14 items in 90 seconds of reading. Inline sparkline of PR throughput, asks separated from the body. Designed for the skim.
04-status-report.html 05 DiagramReal flowchart drawn as inline SVG — nodes, edges, happy path in green, failure paths dashed in red. Click any step for what runs there, expected duration, and the failure mode.
05-flowchart.html 06 DeckTen slides on the thesis, navigable with arrow keys. Self-referential by design: a slide deck arguing for HTML, in HTML. Press F for fullscreen.
SKILL.md is the entry point. It teaches recognition (when does a request want HTML?), the universal rules every artifact must follow, and the carve-outs. Each per-category reference is pulled in only when the task fits — most artifacts only need one or two.
SKILL.mdrecognition heuristic, universal rules, carve-outs · always loadedreferences/exploration-and-planningreferences/code-review-and-prreferences/design-and-prototypesreferences/diagrams-and-illustrationsreferences/reports-and-researchreferences/decksreferences/custom-editorsreferences/matching-your-styleA skill that mechanically rewrote every prompt as HTML would be worse than no skill — it would obscure the cases where markdown is genuinely the right answer. The recognition heuristic in SKILL.md explicitly defers to markdown for the categories below.
"What does this regex do?" gets answered in chat. The skill doesn't manufacture a deliverable for a question that wants a sentence.
"Write a hash function" gets the hash function. No wrapping document, no pre-amble — just the code, the way the user asked.
Things the reader will scan once and discard. Markdown bullets are exactly the right shape; HTML structure would be ceremony.
Specs and design docs reviewed in PRs across many revisions. HTML diffs are noisy; markdown diffs cleanly. The skill prefers markdown for these even when HTML would render better.
html-artifacts.skill from the repo..skill file.skill/ into your skills directory.git clone https://github.com/dogum/html-artifacts.git cp -r html-artifacts/skill ~/.claude/skills/html-artifacts~30 seconds