Skip to main content
skill CX Codex

html-over-markdown — Claude Code skill: what it does, how to install

html-over-markdown generates self-contained HTML files with visual layouts, SVG diagrams, and interactive controls instead of plain Markdown.

MIT ★ 138 updated 2026-09-03

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add happycapy-ai/Happycapy-skills --skill html-over-markdown -a claude-code
Open on GitHub

What html-over-markdown does

This skill instructs Claude Code to output a single .html file in ./outputs/ rather than standard Markdown text. It embeds inline CSS, JavaScript, and SVG diagrams instead of ASCII art, drawing layout styles from assets/base-template.html. You can open the resulting document directly in any browser without running a build step.

It covers five concrete scenarios: specs and plans, PR reviews with side-by-side diffs, component prototypes, incident reports, and throwaway editors. Interactive tools include a button that copies data back to the clipboard as JSON, Markdown, or a prompt.

Keep Markdown if you track the document directly in Git and your teammates depend on line-by-line diffs: large HTML files break clean version control diffs.

What it helps with

  • build self-contained visual specs with embedded SVG diagrams
  • review pull requests with side-by-side diffs and margin notes
  • compare multiple design or architecture options in a structured grid
  • create throwaway interactive editors with clipboard export

Example prompts for the agent

  • Prepare an incident report with a timeline and SVG architecture diagram as an HTML file
  • Review this pull request and generate an annotated diff explainer
  • Compare three caching strategies side by side in an interactive report

How to install html-over-markdown

1Skills CLI (Vercel)

npx skills add happycapy-ai/Happycapy-skills --skill html-over-markdown -a claude-code

2Manually: put the files in place

~/.claude/skills/html-over-markdown/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/html-over-markdown/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about html-over-markdown

How do I install html-over-markdown in Claude Code?

Run npx skills add happycapy-ai/Happycapy-skills --skill html-over-markdown -a claude-code in your terminal.

What files does this skill generate?

It outputs a standalone .html document inside ./outputs/ with inline CSS, SVG, and JavaScript.

When should I avoid using html-over-markdown?

Skip it when teammates need clean line-by-line Git diffs, when producing real .docx or .pdf files, or when building multi-file web apps.

Source text

SKILL.md · MIT
---
name: html-over-markdown
description: Generate rich, self-contained HTML documents instead of Markdown when output needs visual hierarchy, diagrams, or interactivity. Use for specs, implementation plans, side-by-side design comparisons, PR writeups and code explainers, research and status and incident reports, slide decks, SVG flowcharts, and throwaway editors like triage boards, feature-flag editors, and prompt tuners. Prefer this skill whenever the user asks for a report, plan, or explainer they'll actually want to read — even if they don't explicitly say "HTML".
---

# HTML Over Markdown

Produce a single self-contained `.html` file as the primary output format instead of Markdown.

## Why this exists

Markdown flattens spatial information — diffs, dependency graphs, side-by-side comparisons — into linear text. It has no color, no diagrams, no interaction, and people rarely read past ~100 lines. HTML trades a document the user would skim for one they would actually read.

Concrete wins over Markdown:
- **Information density**: tables, SVG, CSS, scripts, images — all in one file
- **Visual clarity**: tabs, collapsible sections, responsive layout, typographic hierarchy
- **Sharing**: one link, any browser, no special viewer
- **Two-way interaction**: sliders, toggles, editors, and a copy-back-to-prompt loop
- **Expressiveness**: no more ASCII diagrams or unicode color approximations

## When to use vs. skip

Use this skill when the user asks for:
- A spec, plan, proposal, brainstorm, or multi-option exploration
- A PR writeup, code review, or code/feature explainer
- A report — status, research, incident, weekly
- A side-by-side comparison of designs, approaches, or benchmarks
- A slide deck or visual walkthrough
- A throwaway interactive editor (triage board, feature flags, prompt tuner)
- Anything they'd "actually want to read" — even without the word HTML

Do NOT use this skill when:
- The deliverable is a real `.pdf` / `.docx` / `.pptx` / `.xlsx` file → use those skills
- The user wants a production web app (multi-file React/Vue/Next) → use `frontend-design` or `artifacts-builder`
- The spec is Git-tracked and teammates need clean diffs → keep Markdown
- The user wants a poster or visual artwork → use `canvas-design`
- The answer is a one-paragraph reply → just answer

If unsure, read `references/principles.md` → "What this skill is NOT for".

## Workflow

1. **Identify the scenario** from the 5 families in the table below.
2. **Read the matching section in `references/playbook.md`** for patterns and a prompt template.
3. **Pull reusable snippets from `references/snippets.md`** (grids, diffs, SVG, sliders, export buttons).
4. **Start from `assets/base-template.html`** — it has the default style already wired up. Copy it, then fill in.
5. **Write the result to `./outputs/<descriptive-kebab-case>.html`** and declare it in the `<attachments>` block as `<file type="static">outputs/<name>.html</file>`.
6. **Only if the HTML needs a real server** (e.g., `fetch`, complex event handlers that fail on `file://`), run `python -m http.server 8080 --directory outputs` and `/app/export-port.sh 8080`. For plain static pages, skip this.

## The 5 scenarios

| # | Scenario | Typical trigger | Signature patterns |
|---|---|---|---|
| 1 | **Spec, Planning & Exploration** | "Help me plan…", "explore approaches…", "compare options" | Side-by-side grid, labeled tradeoffs, mockups, data-flow SVG |
| 2 | **Code Review & PR** | "Explain this PR", "review this code", "help onboard a reviewer" | Annotated diff with margin notes, severity chips, module graph |
| 3 | **Design & Prototype** | "Design system", "component variants", "prototype an animation" | Variant matrix, color swatches, tunable sliders + Copy-as-CSS |
| 4 | **Report, Research & Explainer** | "Status report", "explain how X works", "incident writeup" | TL;DR, collapsible sections, tabbed samples, SVG diagrams, timeline |
| 5 | **Custom Editor** | "Let me reorder…", "tune this config", "edit this prompt with live preview" | Drag-drop or forms, live preview, **required**: Copy-as-{JSON,Prompt,Markdown} button |

Open `references/playbook.md` and jump to the matching scenario for full patterns, structural templates, and prompt seeds.

## The 5 principles (keep these in mind throughout)

1. **Self-contained**: one `.html`, all CSS/JS/SVG inline. CDN links are OK; build steps are not.
2. **SVG, never ASCII**: any diagram — flow, sequence, architecture, dependency — must be SVG.
3. **Spatial, not linear**: if you'd use a bullet list for it in Markdown, think again. Options go in a grid, diffs go inline with margins, dependencies go in a graph.
4. **Export-to-prompt**: any interactive control must have a button that writes something to the clipboard (JSON, Markdown, or a natural-language prompt) so the loop closes back into Claude Code.
5. **Readable at a glance**: responsive, quiet palette, obvious hierarchy. Optimize for "opens file → understands in 10 seconds".

Full rationale, reasoning, and the default style blueprint are in `references/principles.md`.

## Default style and output conventions

The default aesthetic is **Anthropic warm-editorial** — ivory `#FAF9F5` background, clay `#D97757` as the single accent, serif headings with mono uppercase eyebrows, 1.5px warm-gray borders. Full tokens, typography, and signature patterns live in **`references/design-language.md`** — read it before producing output.

The starter template in `assets/base-template.html` has the full palette wired up (`--ivory`, `--clay`, `--oat`, `--olive`, `--rust`, warm grays `--g100…--g700`, serif/sans/mono stacks, h1 with `<em>` in clay, callouts with clay stripe, mono chips).

Prefer adapting this template over writing new CSS from scratch. If the user references a design system of their own, mirror its tokens. If they ask explicitly for Anthropic brand styling, optionally combine with `brand-guidelines`.

File naming: `./outputs/<descriptive-kebab-case>.html`. Pick a name that would make sense six months later — `rate-limiter-explainer.html`, not `output.html`.

## A note on philosophy

The author of the underlying methodology deliberately warned against turning this into a rigid `/html` template skill, because the *knowing-when-and-what* matters more than the generation mechanics. This skill honors that: it teaches decision-making and patterns, bundles copy-paste snippets rather than generators, and trusts you to compose. Don't over-engineer — most of the time, the right move is to start from the base template, pick a scenario pattern, and write the thing.

© happycapy-ai · MIT · happycapy-ai/Happycapy-skills

Similar skills

All skills for Writing and docs →

From the same set41

The whole set →
pptx Create a PowerPoint deck from a topic or content brief. The skill saves the finished .pptx file in outputs/. CX Codex +1 ★ 138repo stars agent-0-repo-qualifier agent-0-repo-qualifier grades GitHub repositories before issue hunting starts: commit recency, license, maintainer response, CLA blockers. Hands a scored shortlist to the next agent. CX Codex ★ 138repo stars agent-7-pr-creator The agent-7-pr-creator subagent reviews completed changes, prepares commits and a PR description, then opens a pull request with gh. It runs after Agents 4, 5, and 6. CX Codex ★ 138repo stars agent-1-issue-scout agent-1-issue-scout — a Claude subagent that scans pre-qualified GitHub repos for unclaimed good first issues and hands one scored pick to the next agent in the chain. CX Codex ★ 138repo stars contract-first-agents The contract-first-agents skill gives a multi-agent team a shared contract before parallel work begins, then checks the combined output. Use it when separate modules or document sections must fit together. CX Codex +1 ★ 138repo stars agent-9-status-monitor agent-9-status-monitor — a Claude subagent that polls your open pull requests, catches merges, closures, new reviews and CI failures, then updates the contribution history and alerts the other agents in the swarm. CX Codex ★ 138repo stars generate-image generate-image generates images from text prompts and edits existing pictures via the AI Gateway API. Connects Claude Code to Gemini, Byteplus Seedream, and GPT-Image models. CX Codex +1 ★ 138repo stars agent-0-strategic-planner The agent-0-strategic-planner subagent ranks GitHub issues by user impact and feasibility. Use it to find meaningful contribution opportunities instead of spending effort on cosmetic fixes. CX Codex ★ 138repo stars

Project sponsors

Companies that keep this analytics open