html-effectiveness

Agent Skill that teaches Cursor & Claude Code to output single-file HTML when the answer's shape is spatial, parallel, comparable, or interactive — instead of flattening everything into markdown.

9 categories · 20 patterns · 12 ready-to-use templates · single-file, zero-dependency.

Inspired by Thariq Shihipar's The unreasonable effectiveness of HTML.

Requires Node ≥ 16.7.0 (uses fs.cpSync).

Why this exists

Markdown flattens everything into a linear text stream. Diffs are spatial. Comparisons are side-by-side. Flows are graph-shaped. Interactions can only be felt. When agents collapse those dimensions into prose, you have to rebuild them in your head.

This skill teaches the agent to switch to a single-file HTML page at the right moment — so you can point at the thing instead of scrolling three walls of text.

Quick install

The package isn't on the npm registry yet — until then, install directly from GitHub (works today, no setup):

# Install for both Cursor and Claude Code (recommended)
npx -y github:Azhi-ss/html-effectiveness --all

# Or pick one
npx -y github:Azhi-ss/html-effectiveness --cursor   # → ~/.cursor/skills/html-effectiveness/
npx -y github:Azhi-ss/html-effectiveness --claude   # → ~/.claude/skills/html-effectiveness/

# Or install into the current project
npx -y github:Azhi-ss/html-effectiveness --project .

# Interactive (no flags) → asks where to install
npx -y github:Azhi-ss/html-effectiveness

# Uninstall
npx -y github:Azhi-ss/html-effectiveness --uninstall

Pin to a specific version (after a release exists):

npx -y github:Azhi-ss/html-effectiveness#v0.2.1 --all

Once published to npm, the shorter form npx html-effectiveness … will work too.

Restart your agent (Cursor / Claude Code) after install. The skill auto-activates when output should be spatial / parallel / interactive.

What gets installed

The installer copies skills/ and templates/ into:

<target>/html-effectiveness/
├── SKILL.md                  ← main router (decision framework)
├── shared/
│   ├── base.css              ← shared design tokens
│   └── components.html       ← reusable HTML snippets
├── 01-explore/SKILL.md       ← 9 sub-skills, one per category
├── 02-review/SKILL.md
├── 03-design/SKILL.md
├── 04-proto/SKILL.md
├── 05-diagram/SKILL.md
├── 06-slides/SKILL.md
├── 07-research/SKILL.md
├── 08-report/SKILL.md
├── 09-editor/SKILL.md
└── templates/                ← 12 production-ready templates
    ├── compare.html
    ├── plan.html
    ├── pr.html
    ├── diff.html
    ├── design-tokens.html
    ├── animation.html
    ├── flowchart.html
    ├── concept.html
    ├── slides.html
    ├── status.html
    ├── postmortem.html
    └── prompt.html

Where <target> is ~/.cursor/skills/, ~/.claude/skills/, or your project's .cursor/skills/ & .claude/skills/.

How it activates

When you ask the agent to:

• Compare approaches / designs / options → side-by-side compare.html
• Plan an implementation / RFC → plan.html with milestones, data flow SVG, risks
• Review a PR → annotated diff.html with risk map
• Write a PR description → pr.html with TL;DR, before/after, focus areas, rollout
• Status report for the week → status.html with KPIs, shipped table, carryover
• Postmortem for an incident → postmortem.html with minute-by-minute timeline, action items
• Explain a concept → concept.html with interactive visualization (e.g. consistent-hashing ring)
• Make slides → slides.html with keyboard navigation
• Tune a prompt → prompt.html with live preview across multiple sample inputs

…the agent reads the main SKILL.md (decision framework), routes to the matching sub-skill (e.g. 08-report/SKILL.md), pulls the template, fills it with real content (not Lorem ipsum), and saves the file with a path you can open.

When NOT to use it

The skill stays out of the way for tasks that genuinely fit markdown:

• Single-paragraph answers
• Quick step-by-step (e.g. shell commands)
• Simple bullet lists
• Casual conversation

It only triggers when the output's shape is spatial, parallel, comparable, interactive, or structured.

Where agent output lands

All HTML the agent produces is written inside your workspace — never to ~/Downloads/, never to /tmp/, never anywhere outside your project. There's exactly one rule:

• Default: ephemeral output goes to <workspace>/.agent-html/{slug}-{timestamp}.html. Add .agent-html/ to your .gitignore (the project's own .gitignore already does this) so one-shot artifacts don't pollute commits.
• Long-lived output (implementation plans, status reports, postmortems, design tokens, feature explainers, slide decks) — the agent proposes writing to the matching standard doc directory instead, e.g. <workspace>/rfcs/, <workspace>/reports/status/, <workspace>/postmortems/, <workspace>/docs/explainers/. If a matching directory already exists in your repo it's reused; otherwise the agent asks before creating.

Every save is reported as a workspace-relative path with the open command:

✓ Saved to .agent-html/compare-debounce-20260514-1103.html
  Open: xdg-open .agent-html/compare-debounce-20260514-1103.html

The full ruleset (including the per-sub-skill default paths and the upgrade decision tree) lives in skills/SKILL.md under "输出位置（强制约定）".

The 9 categories

Sub-skill	Use case	Templates
01-explore	Multi-approach comparison · visual design directions · implementation plans	compare.html plan.html
02-review	PR review (reviewer) · PR writeup (author) · module / call-stack maps	pr.html diff.html
03-design	Design system reference · component variant contact-sheets	design-tokens.html
04-proto	Animation sandbox · clickable screen flow	animation.html
05-diagram	Annotated flowcharts / state machines · inline-SVG figure sheets	flowchart.html
06-slides	Keyboard-driven slide deck (no Keynote)	slides.html
07-research	Feature explainer (TL;DR + tabs + FAQ) · interactive concept explainer	concept.html
08-report	Weekly status report · incident postmortem	status.html postmortem.html
09-editor	Drag-to-triage board · feature-flag editor · prompt tuner — always with a Copy/Export button	prompt.html

The 6 production constraints

Every HTML output the agent produces must satisfy:

1. Single-file self-contained — HTML, CSS, JS, SVG all inline. No CDN, no npm install, no build.
2. file:// runnable — saves to disk, double-click to open, no server.
3. Modern but restrained — system font stack, warm palette from shared/base.css, restrained motion.
4. Real content — no Lorem ipsum, no User A. Concrete scenarios, real names, real numbers.
5. Editors must export — every interactive page has a "Copy as markdown / Copy diff / Copy prompt" button so UI state can flow back to the agent.
6. Desktop-responsive — 1280px laptop and 1920px monitor both look right.

Try the templates without installing

git clone https://github.com/Azhi-ss/html-effectiveness.git
cd html-effectiveness/templates

# Open any template in your default browser
xdg-open concept.html         # Linux
open concept.html             # macOS
wslview concept.html          # WSL
explorer.exe concept.html     # Windows from WSL

Several templates are fully interactive offline:

• concept.html — live consistent-hashing ring; add/remove nodes and watch keys re-shard
• animation.html — transition tuner with duration / easing sliders, 5 presets, Copy CSS
• flowchart.html — click any pipeline node to expand its run details + timing
• design-tokens.html — light/dark toggle covering palette / type / spacing / radius / shadow
• slides.html — keyboard-driven deck (←/→ navigate, f fullscreen)
• prompt.html — live preview prompt editor with copy-to-clipboard
• diff.html — PR review with risk map and inline reviewer notes

Manual install (without npx)

If you'd rather not run npx, you have two options.

Option A · clone-and-copy (simplest)

git clone https://github.com/Azhi-ss/html-effectiveness.git
cd html-effectiveness
node install.js --all          # same flags as `npx ... --all` above

Option B · symlink for source-of-truth single point

This is useful if you want pulling the repo to update both Cursor and Claude in place. The trick is that the agent expects templates/ to be a sibling of SKILL.md under <target>/html-effectiveness/, but in this repo templates/ sits at the root, not inside skills/. So we need to assemble the target directory by symlinking each piece.

# 1. Clone once into a stable location
git clone https://github.com/Azhi-ss/html-effectiveness.git ~/skills/html-effectiveness

# 2. Helper function that wires up one target
install_html_effectiveness() {
  local target=$1
  local repo=$HOME/skills/html-effectiveness
  mkdir -p "$target"
  # Symlink every direct child of skills/ into <target>/
  ln -sfn "$repo/skills/SKILL.md"      "$target/SKILL.md"
  ln -sfn "$repo/skills/shared"        "$target/shared"
  for dir in "$repo"/skills/[0-9][0-9]-*; do
    ln -sfn "$dir" "$target/$(basename "$dir")"
  done
  # And templates/ from the repo root, so `../templates/*.html` refs resolve
  ln -sfn "$repo/templates" "$target/templates"
}

install_html_effectiveness ~/.cursor/skills/html-effectiveness
install_html_effectiveness ~/.claude/skills/html-effectiveness

Verify the layout (you should see SKILL.md, the nine 01-… through 09-… directories, shared, and templates):

$ ls -la ~/.cursor/skills/html-effectiveness/
SKILL.md       -> /home/you/skills/html-effectiveness/skills/SKILL.md
01-explore     -> /home/you/skills/html-effectiveness/skills/01-explore
02-review      -> /home/you/skills/html-effectiveness/skills/02-review
03-design      -> /home/you/skills/html-effectiveness/skills/03-design
04-proto       -> /home/you/skills/html-effectiveness/skills/04-proto
05-diagram     -> /home/you/skills/html-effectiveness/skills/05-diagram
06-slides      -> /home/you/skills/html-effectiveness/skills/06-slides
07-research    -> /home/you/skills/html-effectiveness/skills/07-research
08-report      -> /home/you/skills/html-effectiveness/skills/08-report
09-editor      -> /home/you/skills/html-effectiveness/skills/09-editor
shared         -> /home/you/skills/html-effectiveness/skills/shared
templates      -> /home/you/skills/html-effectiveness/templates

After this, git -C ~/skills/html-effectiveness pull updates both Cursor and Claude in one go.

Don't symlink ~/skills/html-effectiveness/skills directly to ~/.cursor/skills/html-effectiveness — that misses the templates/ directory and writing the second symlink ends up creating it inside the source repo, polluting your clone.

Repository layout

html-effectiveness/
├── package.json              ← name, bin → install.js, version
├── install.js                ← npx entry; copies to target dirs
├── README.md
├── LICENSE
│
├── skills/                   ← the actual Skill (what gets installed)
│   ├── SKILL.md              ← main router: decision framework + 9-category routing
│   ├── shared/
│   │   ├── base.css          ← design tokens + shared component CSS
│   │   └── components.html   ← reusable HTML snippet library
│   ├── 01-explore/SKILL.md   ← exploration & planning
│   ├── 02-review/SKILL.md    ← code review & understanding
│   ├── 03-design/SKILL.md    ← design system & components
│   ├── 04-proto/SKILL.md     ← animation & clickable flows
│   ├── 05-diagram/SKILL.md   ← SVG figures & flowcharts
│   ├── 06-slides/SKILL.md    ← keyboard slide decks
│   ├── 07-research/SKILL.md  ← feature & concept explainers
│   ├── 08-report/SKILL.md    ← status & postmortem
│   └── 09-editor/SKILL.md    ← drag/configure/prompt editors
│
└── templates/                ← 12 single-file ready-to-fork templates
    ├── compare.html          ← 3-column approach comparison
    ├── plan.html             ← implementation plan / RFC
    ├── pr.html               ← PR writeup (author side)
    ├── diff.html             ← PR review (reviewer side, annotated diff)
    ├── design-tokens.html    ← design system reference (palette/type/spacing)
    ├── animation.html        ← transition tuner (duration/easing slider, Copy CSS)
    ├── flowchart.html        ← annotated SVG flowchart with click-to-detail
    ├── concept.html          ← interactive concept explainer (working ring viz)
    ├── slides.html           ← 6-slide keyboard deck
    ├── status.html           ← weekly engineering status
    ├── postmortem.html       ← incident report / RCA
    └── prompt.html           ← prompt tuner with live preview

Versioning

Current: v0.2.2.

• v0.1 (deprecated) — single-file SKILL.md monolith.
• v0.2.0 — npm package + 9 sub-skills + 9 templates + shared/.
• v0.2.1 — adds 3 templates (design-tokens.html, animation.html, flowchart.html) so all 9 sub-skills have at least one starter template; switches install.js to fs.cpSync and pins engines.node ≥ 16.7.0; documents npx github:Azhi-ss/html-effectiveness install path; rewrites the manual symlink instructions to avoid clobbering the source clone.
• v0.2.2 — output-location convention: all agent-produced HTML now stays inside the workspace. Default ephemeral path is <ws>/.agent-html/; long-lived output (plans / reports / postmortems / explainers / etc.) gets proposed to the matching standard directory (rfcs/, reports/, postmortems/, docs/…) and reused if already present. No more ~/Downloads/ writes.

Future versions will be backwards-compatible at the SKILL.md level so existing references keep working.

Acknowledgements

This skill systematizes the 20 patterns from Thariq Shihipar's The unreasonable effectiveness of HTML into a reusable agent decision framework, shared design tokens, and forkable templates. Credit and thanks to the original.

License

MIT — see LICENSE.

Issues & contributions

Bug reports and pattern suggestions: https://github.com/Azhi-ss/html-effectiveness/issues