# SKILLS — the expertise layer

Skills are the kit's **fifth layer**, and the one this kit was missing. A skill is a folder with a `SKILL.md` (YAML frontmatter — `name` + `description` — plus a markdown body and optional scripts/reference files) that Claude loads **on demand**: only the name + description (~100 tokens) sit in context until a task matches the description, then the body loads, then any reference files it points to. That progressive disclosure is why a project can carry dozens of skills cheaply, and why **deep procedural expertise belongs in a skill, not in `CLAUDE.md` (which is always loaded) or baked into a fat subagent prompt.** Skills are model-invoked and portable (an open standard other agent tools also read).

> **Specialization:** like the rest of the kit, project skills are **generic and bound from `CLAUDE.md`** at read time (stack, design-system prefix, naming grammar, domain compliance). See `SPECIALIZE.md`.

## The five layers (use the right one)

| Layer | What it is | When to reach for it |
|---|---|---|
| `CLAUDE.md` | Always-loaded project rules + the binding source | The few project specifics every session needs. Keep it lean. |
| **Skills** | On-demand **how-to / expertise** (this file) | A repeatable procedure or body of knowledge used across tasks/agents (reconstruction traps, the design-system contract, schema design). |
| Subagents (`.claude/agents/`) | A **role** with its own context window + tools | Delegating a scoped piece of work whose logs shouldn't pollute the main thread (build a slice, review, migrate). |
| Command (`.claude/commands/`) | A **workflow** you invoke explicitly | Orchestration you trigger (`/build-workflow`). |
| Hooks (`.claude/settings.json`) | Lifecycle/safety automation | Gates and checks around tool/stop events. |
| (MCP servers) | **Access** to external systems | Reading/writing real systems (repos, trackers, integrations). A **code-discovery graph MCP** (e.g. `codebase-memory-mcp`) is the recommended optional one: it gives the audit/spec/build agents cheap **read** structural discovery (who calls X, the cross-module contract surface, UI→handler matching) — see `CLAUDE.md §0` + `SPECIALIZE.md` for the wiring; absent it, agents fall back to Grep/Glob. |

Rule of thumb: **Skill = how to do it · Subagent = who does it · Command = when it runs · MCP = what it can reach · `CLAUDE.md` = the project's facts.**

## Skills + subagents compose
Two directions, both supported: a subagent can **use skills as reference material** (the subagent is the role; the skill supplies the expertise — this is how this kit uses them), and a skill can **fork** a task into an agent type. So the heavy procedural content currently inside the kit's subagents is better expressed as **project skills the subagents reference** — the subagent prompt shrinks to its role + report contract, the expertise loads on demand, and every agent (and any plain Claude session) shares the same source of truth.

---

## Recommended public skills (install these)

Anthropic publishes these in the `anthropics/skills` repo; paid Claude.ai plans already have them, and Claude Code reads them from `.claude/skills/` (project) or `~/.claude/skills/` (global). Install the ones that match this project's work:

| Public skill | What it gives | Serves (agent / phase) | Note |
|---|---|---|---|
| **skill-creator** | Scaffolds, iterates, and **evaluates** skills (description-tuning + benchmarking) | You — to author every project skill below | Install first. |
| **frontend-design** | Modern frontend patterns, accessibility, visual quality | Phase 1 design; `screen-reconstructor`, `module-wirer` (quality bar) | React/Tailwind-oriented — most direct in the **Claude Design** prototype; the Blazor reconstruction specifics are a *project* skill (below). |
| **webapp-testing** | Playwright UI verification + debugging (reconnaissance → screenshot → assert) | `test-engineer`; the reconstructor's fidelity gate | Maps directly onto the kit's screenshot/computed-style gate. |
| **artifacts-builder** / **theme-factory** / **brand-guidelines** | High-quality self-contained HTML/React artifacts; themes; brand consistency | Phase 1 prototype; the docs/reference site | Use for the design phase + the brand. |
| **mcp-builder** | Build high-quality MCP servers | Integration work (e.g. wrapping external systems/standards as MCP) | When you expose external systems to the agents. |
| **claude-api** | Build LLM features against the API/SDK | The AI-governed features in the product | Pairs with the kit's AI-governance rules. |
| **docx · pdf · pptx · xlsx** | Create/edit Word, PDF, PowerPoint, Excel | Deliverables — PRDs, stakeholder decks, a schema/registry as a spreadsheet, filled PDFs | Use when an output must be an Office/PDF file, not markdown. |
| **doc-coauthoring · internal-comms** | Structured document collaboration; status notes/FAQs | PRD authoring; team comms | Optional, useful for the writing around the build. |

---

## Project skills to author (extract the kit's expertise)

These don't exist publicly — author them with **skill-creator**, generic and bound from `CLAUDE.md`. Each captures expertise currently spread across the subagents/Constitution so it loads on demand and is shared. Start with the first two (highest leverage). One exception ships ready-made: **`spec-hardening`** (below) is included in the kit at `.claude/skills/spec-hardening/` and installed by bootstrap — a pre-build spec-quality gate adapted natively from GitHub spec-kit's clarify / checklist / analyze discipline (it installs nothing from spec-kit and defines no second constitution; if your team runs spec-kit for non-visual side-projects, keep that as a separate track).

| Project skill | `description` (the trigger) | Contains | Referenced by |
|---|---|---|---|
| **screen-reconstruction** | "Reconstruct a prototype screen 1:1 in the project's UI stack." | The reconstruction workflow + the target-framework traps + the fidelity gate (the transferable core of `screen-reconstructor`) | `screen-reconstructor` (role shrinks to claim + report) |
| **design-system** | "Build or wire UI using the project's design system." | The `<ds-prefix>` vocabulary, page scaffolds, voice, hard prohibitions, reuse-first rules | `screen-reconstructor`, `module-wirer` |
| **module-architecture** | "Build or review a module's domain/application layer." | Vertical-slice + boundary rules: contracts-only, self-registration (`Add<Module>()`), `[Permission]` fail-closed, per-module EF, events via the wrapper | `backend-builder`, `crosscutting-weaver`, `migration-engineer`, `reviewer` |
| **spec-authoring** | "Author or reconcile a module/workflow spec." | The naming grammar; `<X>_MODULE.md` / `<X>_WORKFLOW.md` / `<X>_DB_SCHEMA.md` / `<screen>_UIMAP.md` conventions; provenance headers; JIT reconciliation | `spec-architect`, `backend-builder` |
| **spec-hardening** _(ships with the kit)_ | "Stress-test a module/workflow spec for completeness, clarity, and consistency before building." | Clarify / checklist / analyze passes mapped to the kit's continuity invariants, naming grammar, `<X>_DB_SCHEMA.md`, and compliance | `spec-architect` (pre-build gate) |
| **graduation** _(ships with the kit)_ | "Consolidate duplicated UI markup into a verified-fidelity reusable primitive." | Easy vs. hard case distinction; proof-first scoping; golden-by-construction fidelity; two-layer proof (unit emission + region golden); false-green avoidance; 1:1-outranks-cleanup rule; go/no-go evidence report | `screen-reconstructor`, `module-wirer` (post-build DRY sweep) |
| **design-prompt-authoring** _(ships with the kit)_ | "Turn a design-backlog row (no prototype source) into a ready-to-send design brief." | The §J field-mapping; the design-prompts companion board (Global preamble once + per-row blocks, sidecar in the output contract); one brief serves both lanes (in-repo `design-builder` and the console); inbound-seam + primary-CTA-destination requirement; single-writer append; the drift-vs-net-new boundary (never fold into `design-sync`) | `/design-help`, `/design-build`, `/build-workflow` + `/build-wave` (Checkpoint 1) |
| **contract-sidecar** _(ships with the kit)_ | "Author or consume a screen's contract sidecar — the machine-readable UIMAP twin emitted at design time." | The `<screen-file>.uimap.json` schema (entities, CTAs+guards/effects, states, role gates, list params, born-provenance); producer duties (design-builder, the console lane's preamble, spec-architect backfill); consumer duties (validate-don't-re-derive: spec-architect lifts, reconstructor checklists, design-sync diffs) | `design-builder`, `spec-architect`, `screen-reconstructor`, `design-sync`, `/promote-design` |
| **journey-continuity-audit** _(ships with the kit)_ | "Audit the prototype's screens as end-to-end journeys — the gaps between screens." | The 5-phase method (mechanical route/edge ledgers → role×journey trace → gap patterns → report-then-STOP → additive fill); the GAP-row + severity contract; the continuity ledger; the fix-routing table (backlog / micro-edit / design-sync / forward-only); `CONSOLE_PROMPT.md` — the full fillable design-tool prompt (single source for both venues) | `journey-auditor`, `/journey-audit`, the phase-1 exit gate, any Claude Design session |
| **dead-edge-audit** _(ships with the kit)_ | "Find every prototype element that promises an action it doesn't perform." | The mechanical tells; the two-axis taxonomy (disposition × remediation class) + the taxonomy-completeness law (declare exclusions; re-runs inherit them); the additive fix grammar; the § Accepted toasts exceptions ledger; prevention-at-birth (handler honesty in design-builder + the Global preamble); `CONSOLE_PROMPT.md` for the design-tool venue | `edge-auditor`, `/edge-audit`, `interaction-auditor` (built side, shared taxonomy), any Claude Design session |
| **completeness-sweep** _(ships with the kit)_ | "Prove what is ACTUALLY built against what the boards claim." | Part A — eleven board-integrity checks that independently re-derive every number a tracker asserts (arithmetic · corpus-vs-registry incl. route-less surfaces · **branch coverage** · marker census · staleness · backlog charter · **measured tests** · **corpus ground truth** · **graph freshness** · **metrics written** · **kit + contracts drift**, the last three degrading to `n/a` when unbound); Part B — the four-class taxonomy (reconstruction gap / wiring gap / data-seam / design gap) + the **prototype-anchor entry test** that routes each finding to the board that owns it; the two honesty defects that outrank severity (silent data loss · a real write over unmarked fixture data); write-findings-never-fix; the Law-6 gate-amendment loop | `/construct-help` §0 (every run), every phase-exit gate, `/design-full-sweep`, `/construct-run` |
| **progress-reporting** _(ships with the kit)_ | "File a dated, immutable progress snapshot that survives its session." | The depth × kind contract (incl. the `session` kind — the end-of-session story the session ledger's Stop gate demands, filed to the journal); the 11-section structure (coverage honesty · Part A table · classification · systemic classes · hard defects · board-correcting verdicts · fan-out-ranked blocking graph · task pack · the Law-6 gate-amendment table); the 10 discipline invariants, each with its rationale; the proposes-never-files boundary that keeps it single-writer | `/progress-report`, every phase-exit gate, `completeness-sweep` (Part B findings are filed through it), the session-ledger Stop gate |
| **db-schema** | "Design or migrate a module's database schema." | The `<X>_DB_SCHEMA.md` design-of-record format; placement (SQL vs document store), keys, indexes, constraints, encryption-at-rest, retention; migration-matching | `backend-builder`, `migration-engineer`, `reviewer` |
| **compliance** | "Apply the project's audit / RBAC / safety rules." | The domain's audit, RBAC, break-the-glass, config-gating, AI-governance, identity-safety, irreversible-action rules (from `CLAUDE.md §7`) | `crosscutting-weaver`, `module-wirer`, `reviewer` |

Keep each `SKILL.md` body small (a screenful); push long detail into `reference/*.md` files the body points to, so progressive disclosure keeps context cheap. Use `templates/SKILL.template.md` as the starting point.

## Agent → skills map (quick reference)

- `screen-reconstructor` → **screen-reconstruction**, **design-system** (+ frontend-design, webapp-testing)
- `module-wirer` → **design-system**, **compliance**
- `spec-architect` → **spec-authoring**, **db-schema**, **spec-hardening**
- `backend-builder` → **module-architecture**, **spec-authoring**, **db-schema**
- `migration-engineer` → **db-schema**, **module-architecture**
- `crosscutting-weaver` → **module-architecture**, **compliance**
- `reviewer` → **module-architecture**, **compliance**, **db-schema**
- `test-engineer` → webapp-testing (+ **module-architecture**)
- `spec-researcher` → (research; no project skill needed)
- `/design-help` · `/build-workflow` · `/build-wave` (Checkpoint 1) → **design-prompt-authoring** (emit each filed design-backlog row's brief into the design-prompts companion board)

---

## Install & wire

- **Claude Code** — drop a skill folder into `.claude/skills/<skill-name>/SKILL.md` (project, version-controlled) or `~/.claude/skills/` (global). Claude Code discovers it automatically; no restart. For Anthropic's set you can also `/plugin install document-skills@anthropic-agent-skills` and `/plugin install example-skills@anthropic-agent-skills`.
- **Claude.ai** — prebuilt skills are already active; upload custom skills as a zip under Settings → Features.
- **API** — reference a prebuilt skill by `skill_id` (e.g. `pptx`, `xlsx`) or upload custom skills via the Skills endpoints (skills run in the code-execution container).

`bootstrap` creates `.claude/skills/` for you; the directory is where your authored + installed skills live.

## Author with skill-creator
1. Install **skill-creator** and ask it to scaffold a skill from the relevant row above.
2. Write the body generic; bind specifics from `CLAUDE.md` (per `SPECIALIZE.md`). Move long detail into `reference/` files.
3. Tune the `description` for **trigger precision** — it's the only thing always in context, and it decides when the skill fires. skill-creator's eval loop measures with-skill vs baseline; iterate the description until it triggers on the right tasks and not others.
4. Have the owning subagent reference the skill (the subagent keeps its role + report contract; the skill carries the how-to).