An agent skill that writes plans, specs, brainstorms, design systems, and status reports as standalone HTML files instead of Markdown — so you actually read them. Works with any agent that supports the open Agent Skills spec (Claude Code, Codex, Gemini CLI, …).
Based on the pattern Thariq Shihipar (Anthropic, Claude Code team) demoed on the How I AI podcast: a thousand-line Markdown plan gets skimmed; a scrollable HTML plan with mockups, code excerpts, and an "export your edits" button gets engaged with.
As agents run longer (Opus 4.7 sessions hit hours), the artifacts they produce — plans, PRDs, design docs — got long enough that humans stop reading them. The fix isn't shorter plans. It's a richer medium.
HTML gives you:
- Scrollable, scannable layouts instead of a wall of bullets
- Inline SVG mockups instead of ASCII art
<details>sections that hide deep dives until you want them- Throwaway micro-UIs for editing a specific section, with a "Copy as Markdown" button to paste back into your agent
- Side-by-side option comparisons for brainstorming
You also get the same model intelligence — the model reads HTML as well as Markdown — but you read HTML much better.
Clone it into your agent's skills directory:
# Claude Code
git clone https://github.com/mattkuda/html-spec.git ~/.claude/skills/html-spec
# Codex
git clone https://github.com/mattkuda/html-spec.git ~/.agents/skills/html-specAny other harness that implements the Agent Skills spec works the same way — clone into whatever directory it loads personal skills from.
Restart your agent. The skill auto-triggers when you ask to brainstorm, plan, spec, mock up, document a design system, or write a status report.
Just talk to your agent normally. The skill kicks in on prompts like:
- "Brainstorm 6 directions for the new onboarding flow"
- "Write a plan for migrating the candidates table to Postgres FTS"
- "Spec out the AI chat feature with mockups and types"
- "Document our design system as a reference"
- "Give me this week's status update"
Output lands in ./plans/<slug>.html (or ./design-system.html). The agent gives you a clickable file:// path and offers to open it.
For short tasks (chat replies, commit messages, READMEs), the skill stays out of the way — Markdown is still the right answer there.
- Brainstorm fan-out — grid of options with mockups, "why this," "risk," and an export button so you can pick one.
- Plan / spec — TL;DR, types, file changes, code excerpts, mockups, test plan, open questions. Heavy use of
<details>so the top stays scannable. - Design system — colors, type, spacing, components, all click-to-copy. Living reference you can point future agents at.
- Custom editor (micro-app) — for when one section of a plan (a rules table, a config map) needs interactive editing. Renders a focused form with a "Copy as Markdown" output.
- Status report — TL;DR, shipped, in flight, blocked, next. Skim in 30 seconds.
The skill ships with a simple dark theme as its default look (pure-black background, white headings, muted-gray body, monospace code). It's just a preference — open SKILL.md and edit the Style baseline section to match your own taste (light theme, brand colors, a different font, wider columns, whatever). The agent reads that section verbatim, so any change there reshapes every artifact it produces. The mockup carve-out is independent: previews of apps/components keep their own palette regardless of the document theme.
The examples/ directory has reference HTML files the agent uses as style guides. Open them in a browser to see what the skill produces:
examples/brainstorm.html— fan-out grid with 6 optionsexamples/plan.html— full implementation plan with mockupsexamples/design-system.html— design system reference
html-spec/
├── SKILL.md # the prompt the agent reads
├── README.md
├── LICENSE
└── examples/
├── brainstorm.html
├── plan.html
└── design-system.html
The pattern is from Thariq Shihipar (Claude Code, Anthropic) and his HTML effectiveness gallery. This skill packages it as a reusable trigger for your coding agent.
MIT — see LICENSE.