/html-artifact

name: html-artifact
description: |
  Generate rich self-contained HTML artifacts instead of markdown. Auto-detects
  artifact shape (spec, code-review, prototype, report, editor, data-viz,
  diagram, deck) and loads shape-specific patterns. Bundles Birchline design system with 4 theme
  presets. Use for "make HTML", "as HTML", "HTML artifact", or auto-injected
  by router when output benefits from rich visualization.
user_invocable: true  # justification: users type "/html" directly for explicit
                      # HTML output; also auto-injected by /do router enhancement
command: /html
argument-hint: "[description of what to generate]"
routing:
  triggers:
    - HTML artifact
    - make HTML
    - as HTML
    - rich visualization
    - interactive document
    - HTML file
    - self-contained HTML
    - visual companion
    - pptx
    - powerpoint
    - editable deck
    - pitch deck
    - slide deck
    - make a deck
  pairs_with:
    - pr-workflow
    - research-pipeline
    - planning
    - publish
  complexity: Medium
  category: meta

/html - Self-Contained HTML Artifacts

Generate single self-contained `.html` files that replace markdown when the output needs color, interactivity, layout, or visualization. Auto-detect artifact shape from the request, load shape-specific patterns, generate, validate, deliver.

**Core constraint:** Every artifact is ONE `.html` file. All CSS in `<style>`, all JS in `<script>`. No CDN links, no frameworks, no build steps, no external dependencies. Works offline, opens in any browser.

---

Instructions

Overview

5-phase pipeline: DETECT SHAPE, LOAD CONTEXT, GENERATE, VALIDATE, DELIVER. Phase 1 classifies the request into one of 8 shapes via deterministic script. Phase 2 loads the Birchline design system plus shape-specific reference. Phase 3 dispatches a subagent to generate the HTML. Phase 4 validates structure. Phase 5 delivers the file path and offers browser preview. Phase 6 EXPORT (optional) renders to PDF when the user asks for one.

---

Phase 0: CHECK SAVED TEMPLATE (clone-first)

Before detecting a shape, check whether the request names or matches a saved template. A saved template is a frozen, human-authored layout; cloning it beats regenerating structure because the layout cannot drift.

Run: `python3 skills/meta/html-artifact/scripts/fill-template.py --list`

If the request names a listed template (e.g. "project kickoff", "business review", "system design") or clearly matches one:

1. Read `templates/saved/<name>.slots.json` to learn the slots. 2. Generate ONLY the slot content — never the layout, CSS, or chrome. 3. Write the slot values to a JSON file and run `fill-template.py --template <name> --slots <file> --out <artifact>`. 4. Skip Phases 1–3 (shape detection, assembly, generation). Go to Phase 4 VALIDATE.

The fill script fails loud on a missing required slot, an undeclared slot name, or a leftover marker. Fix the slot JSON; do not edit the template.

If no saved template matches, continue to Phase 1.

**See "Fidelity & Authority" below for the content-vs-layout rule that governs clone mode.**

---

Phase 1: DETECT SHAPE

Classify the user's request into one of 8 artifact shapes.

Run: `python3 skills/meta/html-artifact/scripts/detect-shape.py --request "{user_request}"`

The script outputs a shape name and confidence score.

| Shape | Trigger Signals | What It Produces | |---|---|---| | spec | plan, explore options, compare N approaches, brainstorm | Side-by-side grids, Pro/Con badges, SVG data-flow diagrams, risk tables | | code-review | review PR, explain diff, annotate code, understand module | Diff rendering, severity colors, margin annotations, jump links | | prototype | prototype, animation, tune, try options, component variants | Sliders, CSS var live update, animation sandbox, contact sheets | | report | report, summarize, status update, explain how X works, incident | TL;DR box, collapsible sections, timeline, metric callouts, SVG diagrams | | editor | reorder, triage, edit config, tune prompt, pick values | Drag-drop, kanban, toggle switches, split-pane, export buttons | | data-viz | visualize, chart, dashboard, show data, trends | SVG charts, canvas, interactive tooltips, filter controls | | diagram | diagram, flowchart, architecture, sequence, SVG, illustrate, figure | Inline SVG diagrams, annotated flowcharts, figure sheets, interactive node details | | deck | slides, presentation, deck, talk, pitch | Arrow-key navigable slide deck, 16:9 aspect ratio, slide types, progress bar |

Gate: Shape detected with medium+ confidence. -- because low-confidence classification produces artifacts that mix concerns and satisfy no shape well. Fallback to "report" (safest general-purpose shape) if confidence is low or ambiguous.

---

Hybrid Shapes

Real content often combines two shapes — a report with embedded diagrams, a spec with data-viz charts. When `detect-shape.py` returns a primary shape with medium/high confidence but the request also contains signals for a secondary shape, use the hybrid pattern:

| Primary Shape | + Secondary | Result | |---|---|---| | report | + diagram | Report layout (TL;DR, collapsibles, TOC) with inline SVG diagrams between sections | | report | + data-viz | Report layout with embedded SVG charts illustrating key metrics | | spec | + diagram | Comparison grid with SVG flow diagrams showing each option's architecture | | spec | + data-viz | Comparison grid with charts showing performance/cost per option | | diagram | + report | Figure sheet with explanatory text sections between diagram groups |

**Detection:** After running `detect-shape.py`, check if the `secondary_shape` field is non-null. If so, load BOTH shape references in Phase 2.

**Generation rule:** Primary shape controls page layout (outer structure). Secondary shape provides embedded components (inner elements). The html-builder agent receives both shape patterns and uses primary for structure, secondary fo