diff --git a/skills/INDEX.json b/skills/INDEX.json
index 05bd0d28..03b36a67 100644
--- a/skills/INDEX.json
+++ b/skills/INDEX.json
@@ -1,6 +1,6 @@
{
"version": "2.0",
- "generated": "2026-05-06T18:04:11Z",
+ "generated": "2026-05-08T22:32:26Z",
"generated_by": "scripts/generate-skill-index.py",
"skills": {
"csuite": {
@@ -1494,6 +1494,26 @@
"codebase-overview"
]
},
+ "html-artifact": {
+ "file": "skills/meta/html-artifact/SKILL.md",
+ "description": "Generate rich self-contained HTML artifacts instead of markdown.",
+ "triggers": [
+ "HTML artifact",
+ "make HTML",
+ "as HTML",
+ "rich visualization",
+ "interactive document",
+ "HTML file",
+ "self-contained HTML"
+ ],
+ "category": "meta",
+ "user_invocable": false,
+ "pairs_with": [
+ "pr-workflow",
+ "research-pipeline",
+ "planning"
+ ]
+ },
"install": {
"file": "skills/meta/install/SKILL.md",
"description": "Verify VexJoy Agent installation, diagnose issues, and guide first-time setup.",
diff --git a/skills/meta/html-artifact/EVAL.md b/skills/meta/html-artifact/EVAL.md
new file mode 100644
index 00000000..b666bba8
--- /dev/null
+++ b/skills/meta/html-artifact/EVAL.md
@@ -0,0 +1,134 @@
+# html-artifact Evaluation Cases
+
+Repeatable evaluation cases for the html-artifact skill. Used by `skill-eval` to measure shape detection accuracy, generation quality, and routing correctness.
+
+---
+
+## Should-Trigger Prompts
+
+Requests that MUST activate html-artifact and produce the expected shape.
+
+| # | Prompt | Expected Shape | Key Assertion |
+|---|---|---|---|
+| 1 | "Explore 3 different approaches to implement rate limiting" | spec | Comparison grid with 3 columns, pro/con per option, recommendation section |
+| 2 | "Help me review PR #42, annotate the diff" | code-review | Diff with line numbers, severity-colored annotations, file jump links |
+| 3 | "Prototype a checkout button animation with sliders to tune it" | prototype | Interactive sliders, live preview, export/copy button |
+| 4 | "Write a weekly status report for the team" | report | TL;DR box at top, collapsible sections, metric callouts if applicable |
+| 5 | "I need to reprioritize these 30 tickets across Now/Next/Later/Cut" | editor | Drag-drop or form controls, state persistence, export buttons (Markdown + JSON + Prompt) |
+| 6 | "Show me test coverage trends over the last 6 months" | data-viz | SVG chart, legend, tooltips, filter controls |
+| 7 | "Make an HTML artifact explaining how our auth flow works" | report | Explicit trigger via "HTML artifact"; report shape for explanatory content |
+| 8 | "Create an interactive feature flag editor" | editor | Form-based editing, toggle switches, export buttons |
+
+---
+
+## Should-NOT-Trigger Prompts
+
+Requests that must NOT activate html-artifact.
+
+| # | Prompt | Why Not | Correct Route |
+|---|---|---|---|
+| 1 | "Fix the bug in auth.ts" | Code fix, not visualization | typescript-frontend-engineer |
+| 2 | "Run the tests" | Test execution, not output generation | test runner / quick |
+| 3 | "Write this as markdown" | Explicit markdown request | Standard markdown output |
+| 4 | "Create an interactive essay about caching" | Full Vite+React project | interactive-essay skill |
+| 5 | "Make a slide deck for the conference" | Presentation deck | frontend-slides skill |
+| 6 | "Build a React component for the login page" | Framework component | typescript-frontend-engineer |
+
+---
+
+## Behavioral Expectations Per Shape
+
+### spec
+
+| Must Have | Must NOT Have |
+|---|---|
+| N-column comparison grid (2-5 columns) | External dependencies or build steps |
+| Pro/Con section per option | Generic "Option A / Option B" without substance |
+| Metadata badges (complexity, risk, timeline) | Hardcoded colors or spacing |
+| Recommendation section at bottom | Missing mobile layout (stacked columns) |
+
+### code-review
+
+| Must Have | Must NOT Have |
+|---|---|
+| Diff with line numbers | Broken syntax highlighting |
+| Severity-colored annotations (critical/warning/info) | External CDN for highlight.js or similar |
+| File navigation / jump links | Missing line number alignment |
+| Risk map overview | Diff without context lines |
+
+### prototype
+
+| Must Have | Must NOT Have |
+|---|---|
+| Interactive controls (sliders, selectors, toggles) | Missing export/copy button |
+| Live preview that updates with controls | Controls that do not update preview |
+| Export/Copy button | Framework imports |
+| Responsive layout | Hardcoded animation values without control |
+
+### report
+
+| Must Have | Must NOT Have |
+|---|---|
+| TL;DR box visible without scrolling | Wall of unstyled text |
+| Collapsible sections (default collapsed) | All sections expanded by default |
+| Metric callouts for key numbers (if applicable) | Numbers buried in paragraphs |
+| Table of contents with jump links | Missing section structure |
+
+### editor
+
+| Must Have | Must NOT Have |
+|---|---|
+| Drag-drop or form-based editing | No export mechanism |
+| State persistence (survives re-ordering) | State loss on interaction |
+| Export buttons: Markdown + JSON + Prompt (min 2 formats) | Single export format only |
+| Visual feedback on state changes | Silent state changes |
+
+### data-viz
+
+| Must Have | Must NOT Have |
+|---|---|
+| SVG charts (unless >1000 data points) | Canvas for simple datasets |
+| Legend with labels | External charting libraries (Chart.js, D3 CDN) |
+| Tooltips on data points | Charts without axis labels |
+| Filter controls (if multiple series) | Static image with no interactivity |
+
+---
+
+## Quality Checks (All Shapes)
+
+These checks apply to every generated artifact regardless of shape.
+
+| Check | Method | Pass Criterion |
+|---|---|---|
+| Structural validity | `validate-artifact.py` | Exit code 0 |
+| File size | `validate-artifact.py` | < 500KB |
+| No external deps | `validate-artifact.py` | No `src=` or `href=` to external URLs |
+| Has `` | `validate-artifact.py` | Non-empty, descriptive title |
+| Has charset meta | `validate-artifact.py` | `<meta charset="utf-8">` present |
+| Has viewport meta | `validate-artifact.py` | `<meta name="viewport">` present |
+| Responsive | Manual / browser test | Renders at 375px and 1440px without horizontal scroll |
+| Keyboard accessible | Manual / browser test | Tab through all interactive elements |
+| No console errors | Browser DevTools | Zero errors on load and interaction |
+| Design tokens used | Grep source | CSS custom properties, not hardcoded values |
+| Reduced motion | Grep source | `prefers-reduced-motion` media query present |
+
+---
+
+## Shape Detection Accuracy
+
+Test `detect-shape.py` independently with these inputs:
+
+| Input | Expected | Notes |
+|---|---|---|
+| "explore 3 auth approaches" | spec | Primary signal: "explore", "approaches" |
+| "compare rate limiting strategies" | spec | Primary signal: "compare" |
+| "review the diff for PR 42" | code-review | Primary signal: "review", "diff", "PR" |
+| "annotate this code change" | code-review | Primary signal: "annotate", "code" |
+| "prototype a button hover effect" | prototype | Primary signal: "prototype" |
+| "tune the animation timing" | prototype | Primary signal: "tune" |
+| "weekly team status update" | report | Primary signal: "status", "report" |
+| "explain how the auth flow works" | report | Primary signal: "explain" |
+| "triage these 20 bugs by priority" | editor | Primary signal: "triage", "priority" |
+| "reorder the feature backlog" | editor | Primary signal: "reorder" |
+| "chart our deploy frequency" | data-viz | Primary signal: "chart" |
+| "show error rate trends" | data-viz | Primary signal: "trends" |
diff --git a/skills/meta/html-artifact/SKILL.md b/skills/meta/html-artifact/SKILL.md
new file mode 100644
index 00000000..fc605b97
--- /dev/null
+++ b/skills/meta/html-artifact/SKILL.md
@@ -0,0 +1,258 @@
+---
+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) 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
+ pairs_with:
+ - pr-workflow
+ - research-pipeline
+ - planning
+ 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 6 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 1: DETECT SHAPE
+
+Classify the user's request into one of 6 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 |
+
+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.
+
+---
+
+### Phase 2: LOAD CONTEXT
+
+Load the design system and shape-specific reference files.
+
+**Always load (every invocation):**
+1. `references/design-system.md` -- Birchline CSS tokens, 4 theme presets, typography scale, color system
+2. `references/interaction-patterns.md` -- Shared JS patterns: tabs, collapsibles, drag-drop, copy buttons, keyboard nav
+
+**Load per detected shape:**
+
+| Shape | Reference File | Key Content |
+|---|---|---|
+| spec | `references/shape-spec-exploration.md` | Grid layouts, comparison cards, SVG flow diagrams |
+| code-review | `references/shape-code-review.md` | Diff rendering, severity system, annotations |
+| prototype | `references/shape-design-prototype.md` | Sliders, live preview, animation sandbox |
+| report | `references/shape-report-research.md` | TL;DR boxes, collapsibles, timelines, metrics |
+| editor | `references/shape-custom-editor.md` | Drag-drop, forms, export buttons, live re-render |
+| data-viz | `references/shape-data-visualization.md` | SVG charts, canvas, tooltips, filters |
+
+Gate: All required references loaded (design-system + interaction-patterns + shape-specific).
+-- because generating without the design system produces inconsistent visual output, and generating without shape patterns produces generic HTML that defeats the purpose.
+
+---
+
+### Phase 3: GENERATE
+
+Dispatch the html-builder subagent to produce the artifact.
+
+1. Read `agents/html-builder.md` for the subagent prompt
+2. Dispatch with: detected shape, design system tokens, interaction patterns, shape-specific patterns, user request
+3. Agent writes a single `.html` file to the project directory (or `/tmp/html-artifacts/` if no project context)
+
+**Self-contained file constraints (inline here because they govern generation):**
+
+| Constraint | Reason |
+|---|---|
+| All CSS in `<style>` tag | No external stylesheets -- file must work offline |
+| All JS in `<script>` tag | No CDN imports -- no React, Vue, Tailwind CDN, Bootstrap CDN |
+| Vanilla JS only | Single file, no build step, no transpilation |
+| Must include `<title>` | Browser tab identification, validation requirement |
+| Must include `<meta charset="utf-8">` | Consistent rendering across platforms |
+| Must include `<meta name="viewport">` | Responsive on mobile/tablet |
+| Semantic HTML sections | `<header>`, `<main>`, `<section>`, `<footer>` for structure |
+| SVG inline, not `<img src>` | No external file references |
+| Max 500KB file size | Keeps generation time reasonable, prevents bloated inline assets |
+
+Constraint: No framework boilerplate.
+-- because React/Vue/Svelte require build steps and external imports that violate the single-file self-contained requirement. Vanilla JS handles all 6 shapes adequately.
+
+Constraint: Generate HTML directly, never generate markdown then convert.
+-- because markdown-to-HTML conversion loses the shape-specific layout, interactivity, and visual structure that justifies using HTML in the first place.
+
+Gate: `.html` file exists on disk.
+-- because Phase 4 validation reads the file; a missing file means generation failed silently.
+
+---
+
+### Phase 4: VALIDATE
+
+Run deterministic validation on the generated file.
+
+Run: `python3 skills/meta/html-artifact/scripts/validate-artifact.py {html_file_path}`
+
+The script checks:
+
+| Check | Fails When |
+|---|---|
+| Valid HTML structure | Missing `<html>`, `<head>`, or `<body>` |
+| No external dependencies | Any `src=` or `href=` pointing to external URLs |
+| Has `<title>` | Missing or empty `<title>` tag |
+| Has charset meta | Missing `<meta charset>` |
+| Has viewport meta | Missing viewport meta tag |
+| File size under 500KB | Excessive inline assets or animation keyframes |
+| No broken internal refs | `href="#id"` pointing to nonexistent `id` attributes |
+
+Gate: All validation checks pass.
+-- because an HTML file with external dependencies fails offline, missing meta tags render inconsistently across browsers, and missing structure breaks accessibility.
+
+**If validation fails:** Read the specific failures from script output, fix the identified issues in the HTML file, re-run validation. Maximum 3 fix attempts before showing the user the remaining issues and asking for guidance.
+
+---
+
+### Phase 5: DELIVER
+
+1. Print the absolute file path
+2. Print a 1-line summary of what was generated (shape + key features)
+3. Ask user: "Open in browser?"
+4. If yes: run `open {file}` (macOS) or `xdg-open {file}` (Linux)
+
+Constraint: Detect headless/SSH environments before offering browser open.
+-- because `xdg-open` fails without a display server, producing confusing errors. Check `$DISPLAY` on Linux or `$SSH_TTY` presence. If headless, print path only and skip the open offer.
+
+---
+
+## Error Handling
+
+| Error | Cause | Solution |
+|---|---|---|
+| detect-shape.py returns low confidence | Ambiguous request mapping to multiple shapes | Fall back to "report" shape -- safest general-purpose format |
+| Generated HTML has external dependencies | Builder included CDN links or external `src` refs | Regenerate with explicit constraint: "no external deps, all CSS/JS inline" |
+| File exceeds 500KB | Excessive inline SVGs or animation keyframes | Simplify SVG paths, reduce keyframe count, compress data |
+| Browser won't open | No display server (headless, SSH, WSL without WSLg) | Print path only, suggest `scp` or `python3 -m http.server` |
+| Validation fails repeatedly (3+ attempts) | Structural issue the builder cannot self-correct | Show validation output to user, ask for guidance |
+| Shape misclassified | Auto-detection picked wrong shape for request | User overrides with `/html --shape=<name> <request>` |
+
+---
+
+## Preferred Patterns
+
+### Pattern 1: CDN and Framework Imports
+
+**What it looks like:** `<link href="https://cdn.jsdelivr.net/...">` or `<script src="https://unpkg.com/react@18/...">` in the generated HTML.
+
+**Why wrong:** Breaks the self-contained contract. File fails offline, introduces version drift, adds weight the user didn't ask for.
+
+**Do instead:** Inline all CSS in `<style>`. Write vanilla JS in `<script>`. The Birchline design system in `references/design-system.md` provides the full token set.
+
+### Pattern 2: Markdown-to-HTML Conversion
+
+**What it looks like:** Generating a markdown document first, then running it through a converter or wrapping it in `<pre>` tags.
+
+**Why wrong:** Loses shape-specific layout, interactivity, SVG diagrams, and responsive grid structures. Produces "markdown in a browser" instead of a native HTML artifact.
+
+**Do instead:** Generate HTML directly using shape-specific patterns from references. The HTML structure IS the output format, not a rendering layer on top of text.
+
+### Pattern 3: Monolithic Unstructured HTML
+
+**What it looks like:** One giant `<div>` with inline styles on every element, no semantic structure, no comments.
+
+**Why wrong:** Unreadable source, hard to debug, impossible for the user to modify. Accessibility tools cannot navigate it.
+
+**Do instead:** Use semantic HTML (`<header>`, `<main>`, `<section>`, `<footer>`). Define CSS classes in `<style>`. Add section comments. Group related elements logically.
+
+### Pattern 4: Over-Engineering Simple Requests
+
+**What it looks like:** Generating a full interactive dashboard when the user asked for a simple comparison table.
+
+**Why wrong:** 2-4x generation time for features the user didn't request. Complexity without value.
+
+**Do instead:** Match artifact complexity to request complexity. A comparison of 3 options needs a grid with cards, not a filterable dashboard with animations.
+
+---
+
+## Anti-Rationalization
+
+| Rationalization | Why Wrong | Required Action |
+|---|---|---|
+| "Markdown is fine for this" | If shape detection triggered, the request has visual/interactive needs markdown can't serve | Generate HTML; user opts out with "as markdown" |
+| "I'll add Tailwind CDN for faster styling" | Breaks self-contained requirement, fails offline | Use Birchline tokens from design-system.md |
+| "The HTML looks right, skip validation" | Visual inspection misses missing meta tags, broken internal links, external deps | Run validate-artifact.py every time |
+| "Report shape works for everything" | Each shape has distinct layout and interaction patterns; report is a fallback, not a default | Use the detected shape; report only when confidence is genuinely low |
+
+---
+
+## Reference Loading Table
+
+| Signal | Load These Files | Why |
+|---|---|---|
+| Any html-artifact invocation | `references/design-system.md` | CSS tokens, themes, typography, color system |
+| Any html-artifact invocation | `references/interaction-patterns.md` | Shared JS: tabs, drag-drop, copy buttons, keyboard nav |
+| Shape = spec | `references/shape-spec-exploration.md` | Grid layouts, comparison patterns, SVG flows |
+| Shape = code-review | `references/shape-code-review.md` | Diff rendering, severity system, annotations |
+| Shape = prototype | `references/shape-design-prototype.md` | Sliders, live preview, animation sandbox |
+| Shape = report | `references/shape-report-research.md` | TL;DR boxes, collapsibles, timelines, metrics |
+| Shape = editor | `references/shape-custom-editor.md` | Drag-drop, forms, export buttons, live re-render |
+| Shape = data-viz | `references/shape-data-visualization.md` | SVG charts, canvas, tooltips, filters |
+
+---
+
+## Shared Patterns
+
+This skill uses:
+- [Anti-Rationalization](../../shared-patterns/anti-rationalization-core.md) -- Prevents shortcut rationalizations
+- [Verification Checklist](../../shared-patterns/verification-checklist.md) -- Pre-completion checks
+- [Gate Enforcement](../../shared-patterns/gate-enforcement.md) -- Phase transitions
+
+---
+
+## Reference Files
+
+- `references/design-system.md`: Birchline CSS tokens, 4 theme presets, typography scale, color palette
+- `references/interaction-patterns.md`: Shared JS patterns across all shapes (tabs, collapsibles, drag-drop, copy, keyboard)
+- `references/shape-spec-exploration.md`: Spec shape -- grids, comparison cards, SVG flow diagrams, risk tables
+- `references/shape-code-review.md`: Code review shape -- diff rendering, severity colors, annotations, jump links
+- `references/shape-design-prototype.md`: Prototype shape -- sliders, CSS var live update, animation sandbox
+- `references/shape-report-research.md`: Report shape -- TL;DR boxes, collapsible sections, timelines, metric callouts
+- `references/shape-custom-editor.md`: Editor shape -- drag-drop, kanban, toggle switches, export buttons
+- `references/shape-data-visualization.md`: Data viz shape -- SVG charts, canvas rendering, tooltips, filter controls
+- `agents/html-builder.md`: Subagent prompt for HTML generation
+- `scripts/detect-shape.py`: Deterministic shape classification from user request
+- `scripts/validate-artifact.py`: HTML structure and self-containment validation
diff --git a/skills/meta/html-artifact/SPEC.md b/skills/meta/html-artifact/SPEC.md
new file mode 100644
index 00000000..e97f571f
--- /dev/null
+++ b/skills/meta/html-artifact/SPEC.md
@@ -0,0 +1,105 @@
+# html-artifact Specification
+
+## Purpose
+
+Generate rich self-contained HTML artifacts instead of markdown when output benefits from visual structure, interactivity, or information density.
+
+## Scope
+
+**IN:**
+- Single self-contained `.html` files for 6 shapes: spec, code-review, prototype, report, editor, data-viz
+- Auto-detection of artifact shape from user request
+- Birchline design system with 4 theme presets
+- Interactive elements: tabs, collapsibles, drag-drop, sliders, copy buttons
+- SVG diagrams and charts (inline, no external deps)
+
+**OUT:**
+- Multi-page sites, framework apps, deployment artifacts
+- Anything requiring npm, build steps, or external dependencies
+- Full Vite+React projects (use `interactive-essay` skill)
+- Presentation decks (use `frontend-slides` skill)
+- Application UIs with backend integration
+
+## Non-Goals
+
+- Not a web app builder — no npm, no build steps, no server-side logic
+- Not a replacement for `interactive-essay` (full Vite+React projects with scroll animations)
+- Not a replacement for `frontend-slides` (presentation decks)
+- Not forced — user opts out with "as markdown" or "in markdown"
+- Not a charting library — SVG generation is inline, not a reusable API
+
+## Invariants
+
+1. Every artifact is a SINGLE `.html` file with no external dependencies
+2. All CSS inline in `<style>`, all JS inline in `<script>`
+3. `detect-shape.py` classification is deterministic (same input produces same shape)
+4. `validate-artifact.py` checks run before delivery
+5. Editor and prototype shapes MUST include export/copy buttons
+6. All artifacts use Birchline design tokens (not hardcoded values)
+7. File size under 500KB
+8. Semantic HTML structure with accessibility support
+
+## Pipeline
+
+```
+Phase 1: DETECT SHAPE → scripts/detect-shape.py (deterministic)
+Phase 2: LOAD CONTEXT → design-system.md + interaction-patterns.md + shape-*.md
+Phase 3: GENERATE → agents/html-builder.md subagent
+Phase 4: VALIDATE → scripts/validate-artifact.py (deterministic)
+Phase 5: DELIVER → file path + browser open offer
+```
+
+## Dependencies
+
+| Dependency | Required | Purpose |
+|---|---|---|
+| Python 3.10+ | Yes | Shape detection, artifact validation |
+| External Python packages | No | Scripts use stdlib only |
+| Node.js / npm | No | Not used |
+| `xdg-open` / `open` | Optional | Browser preview |
+
+## Success Criteria
+
+| Criterion | Measurement |
+|---|---|
+| Renders correctly | Chrome, Firefox, Safari — no console errors |
+| Self-contained | No network requests on load (validate-artifact.py check) |
+| Interactive | All controls respond to user input without external deps |
+| File size | < 500KB (validate-artifact.py check) |
+| Validation | `validate-artifact.py` exits 0 |
+| Shareable | User can email/share the `.html` file directly — no build required |
+| Accessible | Keyboard navigation works; ARIA labels present; reduced-motion respected |
+| Responsive | Works at 375px (mobile) and 1440px (desktop) |
+
+## Router Integration
+
+| Mechanism | Details |
+|---|---|
+| Auto-detect | `/do` Phase 3 ENHANCE injects when output benefits from HTML |
+| Explicit | User types `/html [description]` |
+| Opt-out | User says "as markdown" or "in markdown" |
+| Shape override | `/html --shape=<name> <description>` |
+
+## File Layout
+
+```
+skills/meta/html-artifact/
+├── SKILL.md # Orchestrator (5-phase pipeline)
+├── SPEC.md # This file
+├── EVAL.md # Evaluation cases
+├── agents/
+│ └── html-builder.md # Subagent: generates the HTML
+├── references/
+│ ├── design-system.md # Birchline CSS tokens, themes
+│ ├── interaction-patterns.md # Shared JS patterns
+│ ├── shape-spec-exploration.md # Spec shape patterns
+│ ├── shape-code-review.md # Code review shape patterns
+│ ├── shape-design-prototype.md # Prototype shape patterns
+│ ├── shape-report-research.md # Report shape patterns
+│ ├── shape-custom-editor.md # Editor shape patterns
+│ └── shape-data-visualization.md # Data viz shape patterns
+├── scripts/
+│ ├── detect-shape.py # Deterministic shape classifier
+│ └── validate-artifact.py # Post-generation validator
+└── assets/ # (reserved for templates)
+```
diff --git a/skills/meta/html-artifact/agents/html-builder.md b/skills/meta/html-artifact/agents/html-builder.md
new file mode 100644
index 00000000..86eef8cc
--- /dev/null
+++ b/skills/meta/html-artifact/agents/html-builder.md
@@ -0,0 +1,91 @@
+# html-builder
+
+You generate self-contained HTML artifacts. Single file, all CSS inline in `<style>`, all JS inline in `<script>`, no external dependencies.
+
+## Inputs
+
+You receive from the orchestrator:
+- **shape**: One of `spec`, `code-review`, `prototype`, `report`, `editor`, `data-viz`
+- **user_request**: The original request text
+- **design_system**: Birchline CSS tokens from `references/design-system.md`
+- **shape_patterns**: Shape-specific HTML/CSS/JS patterns from `references/shape-*.md`
+- **interaction_patterns**: Shared JS patterns (tabs, collapsibles, drag-drop, copy buttons, keyboard nav)
+
+## Generation Rules
+
+### Structure
+
+Every artifact follows this skeleton:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="utf-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <title>[descriptive title]
+
+
+
+
+
+
+
+
+