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.
Nine artifacts below, each produced by the skill in response to a real prompt, and each rendered headless and checked before it shipped. 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.
The diff is the spine; six numbered notes sit in the margin, pinned to lines. Severity is worded as well as colored, jump links at the top, and a verdict that actually decides.
07-code-review.html 08 Design & prototypesEvery token rendered as itself: swatches, a type scale at real size, spacing bars, radii, shadows, and easing curves you can hover to play. One-click copy of the value or the name.
08-design-tokens.html 09 Reports & researchImpact summary first, then a drawn timeline with the pace visible: log excerpts at the moments that matter, a gap annotation where nothing happened, action items with owners. Prints cleanly.
09-postmortem.htmlSKILL.md is the entry point. It teaches recognition (when does a request want HTML?), the universal rules every artifact must follow, the carve-outs, and a five-step workflow that ends with verifying the page before handing it over. Each reference is pulled in only when the task fits; most artifacts need one or two. Eight are per-category patterns; four are cross-cutting: data and charts, accessibility and print, harness mechanics (the one file that knows which surface you're on), and the pre-delivery check.
SKILL.mdrecognition heuristic, universal rules, carve-outs · always loadedreferences/exploration-and-planningreferences/code-review-and-prreferences/design-and-prototypesreferences/diagrams-and-illustrationsreferences/data-and-chartsreferences/reports-and-researchreferences/decksreferences/custom-editorsreferences/matching-your-stylereferences/accessibility-and-printreferences/harness-mechanicsreferences/verify-before-deliveringA 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.
/plugin update./plugin marketplace add dogum/html-artifacts /plugin install html-artifacts@html-artifacts~20 seconds · auto-updatable
html-artifacts.skill from the latest release..skill file.skills/html-artifacts/ into your skills directory. Any Agent Skills-compatible runtime works.git clone https://github.com/dogum/html-artifacts.git cp -r html-artifacts/skills/html-artifacts ~/.claude/skills/~30 seconds