html-writeups

A Claude Code skill for generating self-contained, styled HTML files instead of Markdown for specs, plans, reports, PR reviews, and design explorations.

Why?

Markdown is the default output format for AI coding agents, but it's limiting. As agents produce more complex work (implementation plans, code reviews, research reports), nobody actually reads a 100+ line Markdown file. HTML gives you:

• Rich structure: tabs, cards, color-coded badges, collapsible sections
• Visual clarity: SVG diagrams, data visualizations, semantic color
• Interactivity: sliders, toggles, and export buttons for exploring options
• Shareability: one self-contained file, opens in any browser, share as a link
• Actually gets read: visual documents have higher engagement than text walls

Inspired by Theo's video and Thariq Shihipar's article on the unreasonable effectiveness of HTML for agent outputs.

Installation

Claude Code (via Skills CLI)

npx skills add cappy-dev/html-writeups --skill html-writeups --yes --global

Manual

Copy SKILL.md and templates/ into your project's .claude/skills/ directory:

mkdir -p .claude/skills/html-writeups/templates
cp SKILL.md .claude/skills/html-writeups/
cp templates/base.html .claude/skills/html-writeups/templates/

Usage

Just ask Claude Code to produce an HTML writeup:

• "Create an implementation plan as an HTML file for the new auth system"
• "Write a PR review explainer as HTML with inline diffs and severity badges"
• "Generate six design directions for the onboarding screen as a single HTML file"
• "Make an HTML report from our git history showing what changed this sprint"

Claude will use the skill to produce a self-contained .html file you can open in any browser.

What's included

html-writeups/
  SKILL.md            # Skill instructions (loaded by Claude Code)
  templates/
    base.html         # Dark-theme base template to start from
  LICENSE             # AGPL-3.0
  README.md           # This file

Design philosophy

• Not AI slop: No gradient heroes, emoji headings, or vague decorative copy
• Self-contained: Single .html file, inline CSS/JS, no CDN dependencies
• Dark by default: Easy on the eyes, high contrast, system fonts
• Mobile responsive: Works at 400px width
• Token-efficient: HTML costs more tokens than Markdown, so reserve it for documents that benefit from structure and visual hierarchy
• Exportable: Interactive writeups always include copy/export buttons

License

AGPL-3.0