---
name: <skill-name>
# description: routing-only field — loaded at startup for every skill scan to decide whether
# to activate this skill. Write in imperative phrasing ("Use when X", not "This skill does X").
# Must cover: (1) what the skill does, (2) when to invoke it, (3) negative triggers — what
# adjacent tasks must NOT activate it. No behavioral or role framing; that belongs in the body.
# Max 1024 characters. The `when:` detail that lived here previously now lives in META.md.
# Example: "Use when the user wants to create a new SKILL.md file or convert a placeholder to
# canonical format. Do NOT use when updating an existing well-formed skill — use upgrade-skill."
description: <trigger description>
metadata:
  category: <category — see CATEGORIES.md>
# allowed-tools: <add only when the skill has a narrow, well-defined tool surface; omit otherwise>
# model: sonnet | opus | haiku — Claude Code extension; overrides session model for this skill's turn.
# Omit to inherit the active session model. Factory §9 routing: haiku=formatting/classification,
# sonnet=most coding/review, opus=adversarial/complex reasoning.
---

<requirements>

## Required inputs

<!-- List each required input as a bullet: name, what it is, how the agent obtains it.
     Negative trigger cases are NOT listed here — the agent proposes them during trigger testing.
     Example:
     - **Skill name** — kebab-case slug; inferred from user description if not stated explicitly, ask if ambiguous
     - **Existing SKILL.md path** — for placeholder conversions only; read before writing -->

- **<Input name>** — <description; how obtained>

## Constraints

<!-- One rule per bullet. State the boundary condition inline. Plain English, no jargon.
     Do not include a constraint about body section structure — the template enforces that.
     Example:
     - Frontmatter has three fields only: `name`, `description`, and `metadata.category` — add `allowed-tools` only when the skill has a narrow, well-defined tool surface
     - Body ≤500 lines — content that explains rather than directs belongs in sub-files, not the body
     - Sub-files use three spec-defined optional directories: `scripts/` (executable code), `references/` (on-demand docs), `assets/` (templates, data files, lookup tables). File references must be one level deep. Wire each sub-file with an explicit step instruction (e.g. "See references/lookup.md for error codes") — without wiring, the file is never loaded -->

- <constraint>

</requirements>

<steps>

## Process

<!-- Numbered steps with a bold action label. Short, direct sentences — state what to do and
     what happens as a result. Call out hard gates explicitly (steps that block all progress
     until satisfied). No preamble, no meta-commentary about the steps themselves.
     Example:
     1. **Scan for overlap.** Check `.agents/skills/` for skills with similar purpose or trigger phrases. If overlap is found, surface it and wait for explicit direction — do not continue.
     2. **Grill.** Run a focused grill to reach shared understanding of: skill name, category, purpose, and use cases. One question at a time, with a recommendation for each. -->

1. **<Step name>.** <what to do and what happens as a result>

## Output format

<!-- Describe the files or artifacts produced. Include paths and how they are created
     (copy-fill from template, generated, etc.). State the template used for structured file output.
     Example:
     Two files produced for every skill, plus optional sub-files if the skill requires them:
     - `SKILL.md` — copy-filled from `SKILL-TEMPLATE.md` at `.agents/skills/<name>/SKILL.md`
     - `META.md` — copy-filled from `META-TEMPLATE.md` at `.agents/skills/<name>/META.md`
     - `scripts/`, `references/`, or `assets/` — created only when needed; each file wired with an explicit step instruction -->

<description of output>

</steps>

<checks>

## Failure handling

<!-- One bullet per failure mode. Lean — no overlap with constraints or process.
     Format: condition — action.
     Example:
     - Template file missing — stop, report the path searched, do not write from memory
     - `write-eval` fails or is unavailable — flag, do not mark the skill complete -->

- <failure condition> — <what to do>

## Self-check

<!-- Verifiable checklist the agent runs before declaring the skill complete.
     Each item must be checkable, not aspirational.
     Example:
     - [ ] Overlap check completed before any content was written
     - [ ] Trigger description tested against all three cases — all passed before body content was written -->

- [ ] <check>

</checks>