html-workbench
Diffs, call-graphs, comparisons, timelines, and tunable parameters are spatial information. Markdown flattens them. HTML lets the user see, compare, and act.
The eight-category taxonomy and the export-loop discipline below are adapted from Thariq's HTML Effectiveness essay. This skill operationalizes that framework with explicit triggers, anti-triggers, pattern templates, and a UI/UX quality floor.
1. What this skill does
html-workbench helps an agent decide when an HTML artifact will materially improve a response, then build a self-contained .html file that earns its weight.
The artifact is a working surface for the user — a thinking surface, review surface, explanation surface, comparison surface, prototype surface, report surface, presentation surface, or editing surface. It is not a decorative webpage and not a portfolio piece. It exists to help a busy person understand, decide, review, tune, compare, or act faster than Markdown would let them.
Treat the file the way you'd treat a well-structured document: clear purpose, tight information architecture, restrained visual design, real interactions only where they pay for themselves.
2. When to use this skill
Reach for HTML when the answer is one of:
- Implementation plans, technical specs, RFCs
- Architecture explainers, system diagrams, data-flow diagrams, module maps
- PR / code reviews, annotated diffs, codebase tours
- Design explorations, design-system token sheets, component variant sheets
- Animation sandboxes, clickable prototypes, SVG figure sheets
- Research explainers, technical learning pages
- Weekly / status reports, incident timelines, postmortems
- Slide-like presentations
- One-off custom editors, prompt tuners, ticket triage boards, feature-flag editors, dataset curation tools, configuration editors
- Decision matrices, tradeoff comparisons
Trigger even if the user did not say "HTML" — these tasks almost always benefit from spatial layout, comparison, interactivity, or export.
3. When NOT to use this skill
Markdown wins for:
- Short answers, definitions, quick yes/no questions
- Plain prose, single paragraphs, summaries under ~200 words
- Simple lists or small Markdown tables (≤ ~6 rows × 3 columns)
- Code-only responses where the file is the answer
- Quick calculations, single command invocations
- Tasks where HTML would be decorative rather than load-bearing
- Cases where the user explicitly asked for Markdown / plain text / a code block
Be willing to say plainly: "Markdown is the better output here." HTML that adds friction without adding clarity is worse than no artifact at all.
4. HTML capability taxonomy
These eight categories form the trigger checklist. If the task benefits from at least two, prefer an HTML artifact. If only one applies weakly, prefer Markdown.
| # | Category | What it means | Why HTML beats Markdown | Artifacts that need it |
|---|---|---|---|---|
| 1 | Tables | Real <table> rows/columns, sortable, sticky headers | Dense comparison without ASCII alignment, scrollable, sortable | Decision matrix, status reports, token sheets |
| 2 | Design | Color, typography, spacing, tokens, hierarchy, states | Real CSS rather than imagined formatting | Design sheets, component states, leadership reports |
| 3 | Illustrations | Inline SVG diagrams, visual metaphors, figure sheets | Vector, scalable, labelable, themeable | Architecture, data flow, state machines |
| 4 | Code | Highlighted snippets, annotated diffs, callouts, file tours | Side-by-side panels, inline annotations, syntax color | PR reviews, code explainers, lifecycle traces |
| 5 | Interaction | Sliders, toggles, tabs, accordions, filters, buttons | The user can try it, not just read about it | Prototypes, tuners, sandboxes, editors |
| 6 | Workflows | Boxes, arrows, flows, timelines, state machines, pipelines | Spatial flow, not linear text | Plans, runbooks, incident timelines |
| 7 | Spatial layouts | Canvases, grids, side-by-side panels, module maps | Cognitive parallelism — see options at once | Design exploration, comparison, diagram sheets |
| 8 | Images | Embedded figures, screenshots, mockups, thumbnails | Inline visual evidence with captions | Reports, postmortems, design references |
If you find yourself using only one category and weakly (e.g. a small comparison with three rows), Markdown is probably better. Use the table above as a sanity check, not a permission slip.
5. Pattern selection heuristic
| User need | Pattern | Capability mix |
|---|---|---|
| Compare options | Card grid, comparison table, tradeoff matrix, side-by-side panels | Tables + Spatial |
| Explain code | Annotated snippets, call graph, request lifecycle, data-flow diagram | Code + Illustrations |
| Review a PR | Annotated diff, severity tags, reviewer checklist, changed-files map | Code + Tables + Spatial |
| Plan implementation | Timeline, milestones, architecture diagram, risks, code touchpoints | Workflows + Illustrations |
| Understand a system | Module map, request lifecycle, glossary, key invariants, dependency diagram | Illustrations + Spatial |
| Tune behavior | Sandbox with sliders / toggles / copyable parameters | Interaction + Code |
| Triage / reorder | Drag-drop board with export | Interaction + Spatial |
| Present to others | Slide-like sections with keyboard nav | Spatial + Design |
| Report status | Executive summary, timeline, shipped/slipped/blocked, follow-ups | Tables + Workflows + Design |
| Explain an incident | Timeline, impact panel, root-cause chain, logs, follow-ups | Workflows + Code + Tables |
| Show design | Component contact sheet, token table, state matrix, responsive mockups | Design + Spatial |
| Edit structured data | Form-based editor, validation, dependency warnings, copy/export output | Interaction + Code |
| Brainstorm visually | Multiple rendered directions with labeled tradeoffs | Design + Spatial |
For full templates per pattern, read references/html_artifact_patterns.md.
6. Output principles
By default, the agent should:
- Produce one self-contained
.htmlfile. - Inline all CSS and JavaScript unless the user explicitly allows external assets.
- Avoid network dependencies (no remote scripts, no remote fonts, no analytics).
- Make the file open directly in any modern browser by double-clicking.
- Use semantic HTML (
<header>,<nav>,<main>,<section>,<article>,<table>,<details>). - Use a responsive layout that works at desktop and mobile widths.
- Use accessible contrast and visible focus states.
- Use SVG for diagrams (inline, themeable, labelable).
- Use
<table>for dense comparisons. Use<details>/ tabs / accordions for long material. - Include copy / export buttons for any artifact that captures user decisions.
- Include a short "How to use this artifact" line when interactions are non-obvious.
- Keep the document understandable if JavaScript fails (graceful degradation).
- Prefer clarity over cleverness.
7. UI/UX quality floor
Every artifact must meet this baseline:
- Clear title and one-line purpose at the top.
- Executive summary or TL;DR when the artifact is long or decision-oriented.
- Strong visual hierarchy (one obvious place to start reading).
- Readable typography: 16px minimum body text, line-height ≥ 1.5, max content width ≤ 75ch for prose.
- Adequate contrast (WCAG AA: 4.5:1 for body text, 3:1 for large text and UI).
- Responsive layout, no horizontal scrolling on mobile (unless the artifact is intentionally spatial like a board).
- Visible keyboard focus states on every interactive element.
- Touch-friendly hit targets (≥ 40px) on interactive controls.
- Semantic labels on every form input.
- Clear error / warning / success / disabled states (color and icon and text).
- Charts and diagrams labeled with legends, axes, and units.
- Color used for meaning, ne