| name | write-a-skill |
| description | Create, revise, or retire a reusable agent skill with accurate routing, progressive disclosure, and verified resources. Use when authoring or materially changing a SKILL.md, its description, references, assets, scripts, or reusable workflow guidance. Do not use for one-off preferences, installing third-party skills, or a non-reusable task. |
| disable-model-invocation | true |
Write a Skill
Contract
- One coherent recurring job per skill. Ground it in real repeated work, corrections, failures, or durable domain knowledge.
- Keep activation guidance in frontmatter
description; the body loads after activation.
- Preserve behavior outside the evidence-backed change. Do not collect skills speculatively.
- Read
references/skill-quality-checklist.md before finalizing a new or material revision.
Routing first
- Record 2–3 realistic trigger requests: input, expected output, success criteria, constraints.
- Record 2–3 near misses. Name the adjacent skill or direct workflow that owns each instead.
- Draft description first: third-person capability, concrete triggers, and material non-triggers. Keep it compact.
- Do not describe tool mechanics in frontmatter unless they distinguish routing.
Progressive disclosure
Keep in SKILL.md:
- trigger-specific invariants and safety boundaries;
- the normal decision flow;
- mandatory resources and when to load or run them;
- verification and failure handling.
Move conditional detail deliberately:
| Resource | Use for |
|---|
references/ | long workflows, vendor/version details, schemas, examples, pitfalls |
assets/ | templates, starter artifacts, output shapes |
scripts/ | repeatable or fragile deterministic work |
Do not split merely to meet a line count. Split when the common case remains complete without the deferred material. References stay one level deep and every pointer names its read/use condition.
Build and validate
- Inspect target skill, nearby skills, runtime conventions, tools, and referenced resources.
- Write the smallest actionable contract. Prefer short headings, bullets, and explicit boundaries over prose.
- Add a script only when deterministic execution, error handling, or repeat reuse beats generated commands. Scripts need safe defaults,
--help, bounded output, clear exits, and confirmation/dry-run for destructive actions.
- Check every referenced path, command, example, and version-sensitive claim against the live environment.
- Test routing with the recorded triggers and near misses from description alone.
- Run one representative safe execution. Use an independent reviewer when proportionate; otherwise state the independence limit.
- Report changed files, checks run/skipped, routing cases, and remaining risk.
