---
# SKILL.md — agentskills.io skill definition
# Fill in all FILL IN: placeholders. Remove comment blocks that don't apply.

name: SKILL_NAME
# Required. Must exactly match the parent directory name.
# Valid characters: lowercase letters, numbers, hyphens.
# Invalid: uppercase, leading/trailing/consecutive hyphens.
# Max length: 64 characters.
# Examples: my-tool, data-analyzer, pdf-processor

description: >
  Use when FILL IN: trigger.
  FILL IN: at most ONE capability clause, stated specifically
  (e.g. "parses and validates OpenAPI specs", not "helps with APIs").
  Not FILL IN: near-miss case -> FILL IN: real sibling skill.
# Required. Preloaded into EVERY session whether or not the skill is invoked.
# Exactly three parts, in this order: trigger clause, at most one capability
# clause, boundary clause. Drop the boundary line if no near-miss skill exists.
# Trigger clause: when should an agent activate this skill? Describe the user's
# intent, not the skill's internal mechanics.
# Budget: 250 characters target, 400 hard ceiling (counting this value only,
# with YAML folding resolved). This scaffold sits at 214 — keep the fill-in
# under the target rather than growing past it.
# Boundary clauses may be plural: write one per genuine near-miss, and none
# where no sibling could steal activations.
# Never let a hyphenated skill name wrap across two lines of this folded block
# — folding turns the break into a space and the routing target stops resolving.
# Banned here: capability lists, output-format detail, composition notes,
# implementation detail, and restating one trigger twice in two registers.
# The boundary target must resolve to a real skill or agent — it is checked.
# Add "even if the user doesn't mention X explicitly" ONLY when the user's
# natural phrasing genuinely omits the domain word.

# disable-model-invocation: true
# Optional. Hand-invoked skills only (reached solely by the user typing
# /SKILL_NAME). With this set, replace the description above with ONE plain
# human-facing sentence — no trigger clause, no boundary clause.

# license: MIT
# Optional. License name (e.g. MIT, Apache-2.0) or relative path to a bundled
# license file. Include when distributing this skill. Omit for private/internal use.

# compatibility: Requires python3 >= 3.10 and uv
# Optional. 1–500 characters. State tool requirements, runtime versions,
# and network access needs. Omit for skills with no special environment requirements.

metadata:
  version: "0.1.0"
#   author: your-name
#   category: general
#   source_keys:
#     - source-slug-one
#     - source-slug-two
# `metadata.version` is REQUIRED on every skill (ADR-0022) and is enforced by the
# `skill-frontmatter` pre-commit hook. Three-component semver. A newly created
# skill starts at "0.1.0" — leave the seeded value as it is; "1.0.0" is the seed
# for a pre-existing skill retrofitted into the rule, not for a new one.
# The rest of the map is optional: author, category, source_keys.
# source_keys: populated when built from /research output. Lists slugs from references/sources.md.
# Also add source_keys to each references/*.md file that was informed by research.

# allowed-tools: Bash Read Write
# Optional (experimental — support varies by client).
# Space-separated list of pre-approved tools.
# Use when tool usage is known and bounded, to reduce permission prompts.
---

<!-- ============================================================
  SKILL BODY — decision procedure ONLY

  Keep here: ordered steps, decision branches, gates, and which reference
  file to load when.

  Move to references/: lookup tables, spec restatements, output schemas,
  templates, example blocks, rationale prose, and anything only one branch
  reaches. Wire each one with the literal conditional form
  "If <condition>, read `references/<file>.md`." — a generic
  "see references/ for details" is a lint error.

  Budget: 600 words target, 900 hard ceiling, counting THIS BODY ONLY
  (everything after the closing --- above). Separate from the whole-file
  spec backstop of 2,770 words / 500 lines — do not conflate them.

  Delete this comment block before shipping.
============================================================ -->

<!-- OPTIONAL but high-value: Gotchas. Place near the top — a gotcha read
     after the mistake is worthless.

     Each entry states a fact that CONTRADICTS a reasonable default:
     something the agent gets wrong by acting sensibly. Maximum 5 entries.
     An entry that paraphrases a step below it is a failure, not a gotcha.

## Gotchas

- FILL IN: fact that defies a reasonable assumption
- FILL IN: non-obvious naming discrepancy or hidden constraint
-->

<!-- DISPATCH — MANDATORY when this skill has two or more mutually exclusive
     flows. Keep only the dispatch table plus the gates common to every
     branch in this body; give each flow its own self-contained
     references/ file. Delete this block for a single-flow skill.

## Step 1 — Dispatch

| Condition | Flow | Reference |
|---|---|---|
| FILL IN: condition | FILL IN: flow | `references/FILL IN.md` |
| FILL IN: condition | FILL IN: flow | `references/FILL IN.md` |

Read only the reference matching the resolved flow — each is self-contained.
-->

<!-- OPTIONAL: single-flow workflow checklist. Delete if the skill dispatches.

## Workflow

- [ ] Step 1: FILL IN
- [ ] Step 2: FILL IN
- [ ] Step 3: FILL IN
-->

<!-- OPTIONAL: gates that apply to every branch — validation, versioning,
     closing checks. Keep these in the body even when flows are dispatched.

## Step N — Validate and close

FILL IN: the check that must pass before this skill reports done.
-->

## FILL IN: <section-name (e.g. Step 1, Workflow, Instructions)>

FILL IN: Add your skill instructions here. Replace this section header and body with your skill content.