HTML Effectiveness

html-effectiveness

Based on Thariq Shihipar's html-effectiveness repo. He works on Claude Code at Anthropic; the philosophy: agents producing HTML files instead of markdown walls because HTML carries spatial information and interaction that markdown flattens.

Canonical source — vendored in-tree

The 20 canonical patterns ship with this plugin as standalone .html files under ${CLAUDE_PLUGIN_ROOT}/skills/html-effectiveness/references/patterns/ (one per pattern.file, e.g. 01-exploration-code-approaches.html … 20-editor-prompt-tuner.html). No clone, no network, no external setup — the plugin carries its own source of truth and works on any machine. They are the upstream reference (Apache-2.0, see references/patterns/UPSTREAM-LICENSE): read them to learn the pattern, then write a new file with the user's data into the user's project area (default: ~/<task>/<slug>.html or alongside related artifacts) — never edit the vendored references in place.

Decision protocol

1. Load the routing data. Read references/patterns.json from this skill folder. It contains 20 canonical patterns and a decision_tree mapping user-intent phrases (English + German + semantic) to use_pattern IDs. The triggering_principles block at the top tells you HOW to match (fuzzy, multilingual, typo-tolerant, intent-based — not literal).

2. Match user intent. Scan the user's request for semantic fit with any entry in decision_tree. Match on intent regardless of language, case, or typos. If multiple patterns fit, pick the one whose key_pattern field most closely describes the data structure the user has. If still ambiguous, prefer the more interactive pattern (editor > report > diagram).

3. Study the canonical source. Open ${CLAUDE_PLUGIN_ROOT}/skills/html-effectiveness/references/patterns/<pattern.file> and read it end-to-end. Don't paraphrase the pattern — internalize the HTML structure, CSS tokens, JS interaction code, and copy-button mechanism. Reuse the same eyebrow / h1 / sub / sticky-toolbar / column / card markup so the output feels like one family.

4. Replicate with the user's real data. Replace Thariq's example data (Acme tickets, Birchline comments, etc.) with the user's actual data. Keep the design tokens (#FAF9F5 ivory bg, #D97757 clay accent, ui-serif, Georgia, serif + system-ui + SF Mono), layout, and interaction code intact. If the user has no real data yet, ask once for a sample — do not invent fictional company data.

5. Honor the principles (see references/patterns.json:principles):

   • Self-contained: inline <style> and <script>, no external dependencies — fully offline, no Google Fonts.
   • Anthropic Coral DNA: design tokens in references/patterns.json:design_tokens.
   • Vanilla JS only. No React, no jQuery.
   • Editors end with a Copy as markdown (or Copy diff / Copy JSON / Copy gh commands) button that exports the UI state back into something the user can paste into the next prompt.
   • If the artifact contains private data (private repo names, customer info, internal URLs), save it under the user's home (e.g. ~/repo-audit/, ~/<task>/) — never commit to a public plugin repo.

6. Output and open. Write the .html at a sensible location (default: ~/<task>/output.html or alongside related artifacts). Open it in the user's browser via open <file> for immediate inspection. For interactive editors, mention the export-button location so the user knows how to round-trip the UI state.

Trigger principles — read these before matching

• Match on intent, not phrase. The trigger lists are EXAMPLES of intent, not a whitelist. If the user describes a deliverable that would render better with layout + interaction than as markdown prose, fire.
• Languages: English + German + mixed. Triggers are listed bilingually. Mixed-language input ("mach mir einen status report"), Austrian/Swiss German variants, and informal contractions all count. Match by semantic intent regardless of language.
• Typo tolerance. User typos ("reprot", "staus", "tirage", "flowshart", "implementierungsplan" misspelled) are expected. Match by stem / phonetic similarity.
• Case-insensitive. "HTML REPORT", "html report", "Html Report" are the same.
• Ambiguous user intent. If the user says "make me a thing for X", look at WHAT X is. A list of tickets → triage-board. A diff → code-review. A timeline → incident-report. Let the data shape decide the pattern.
• Be pushy. Default to firing when the output would otherwise be a long markdown table, several sections of prose with categories, or a list the user will sort/filter/diff. Markdown for a paragraph; HTML for anything you'll come back to.

Palette choice

patterns.json:palettes defines two:

• coral (default) — #FAF9F5/#D97757/#141413/#788C5D + ui-serif, Georgia, serif. Use for reports, plans, design docs, status updates, research explainers, editor UIs. Anything reading-room or knowledge-work.
• github_dark — #0d1117/#58a6ff/#3fb950/#f85149. Use for codebase audits, CI/CD dashboards, fan-out agent decks, terminal-adjacent tooling. Anything that lives next to a terminal session.

Pattern 21-agent-spawn-deck defaults to github_dark. All others default to coral. The user can override per request.

Composition (multi-pattern output)

If a task naturally splits across multiple deliverables (e.g., an implementation-plan AND a spawn-deck for executing the plan), write multiple linked .htmls and reference each other via <a href> at the bottom. Example: repo-cleanup-plan.html (pattern 16, plan) + repo-cleanup-spawn-deck.html (pattern 21, parallel scanners) + repo-cleanup-triage.html (pattern 18, result triage). Each links the next.

If a single pattern needs sub-work that parallelizes (audit 200 repos, scan 30 services), default to 21-agent-spawn-deck instead of one giant report — the deck carries N ready-to-paste prompts, the user fan-outs, the lead synthesizes.

When to skip this skill

• The user explicitly asked for markdown / a commit message / a code change in a .py / .cs / etc. file.
• The output is genuinely a single short paragraph or single code snippet.
• The user wants prose they will paste into another system that doesn't render HTML (e.g., a Slack message body, a commit body, a CHANGELOG entry).

Examples (intent → pattern)

Bundled asset

assets/otel-semconv-demo.html is a concrete proof-of-concept built on top of 01-exploration-code-approaches pattern, showing OTel semantic-convention YAML → generated C# diff with breaking-change filter. Open it to see the pattern applied to Alexander's actual problem domain.