SKILL.md Template
The shape of a reusable capability: when to fire, when not to, what it does, how it fails.
A template for a callable skill file. The two fields that decide whether it is ever used correctly are the trigger list and the explicit not-for list — without the second, a skill gets invoked for adjacent tasks it handles badly, and the failure looks like a capability problem rather than a routing one.
What it is
A template for one reusable capability that an agent can invoke by name.
---
name: [skill-name]
description: [One sentence: what it does.]
Trigger: [exact phrases that should fire this].
NOT FOR: [the adjacent thing it will be wrongly used for] (→ [correct route]).
---
# [SKILL NAME]
## When this fires
Concrete triggers. Phrases, file types, situations.
## When it does NOT fire
The nearest neighbours, each with where to go instead.
This section prevents more errors than the one above.
## Steps
1. ...
Numbered. Each independently checkable.
## Output
Format, location, naming. Where the result goes.
## Failure modes
What goes wrong, how it looks, what to do.
## Anti-patterns
What not to do with this skill, and why.How to use
Write the NOT FOR line before the steps. It is the field that decides whether a skill is used correctly, and it is the one everyone skips.
A skill without it gets invoked for adjacent tasks it handles poorly — and the resulting bad output reads as a capability problem rather than a routing one, so the wrong thing gets fixed.
Keep the body short. A skill file is loaded into context every time it is considered, so length is a running cost, not a one-time one. If it exceeds roughly 200 lines, split it or move detail into a reference the skill points at.
What to fill in
The trigger phrases should be the words actually used, not the words that would be logical. Collect them from real requests over a week rather than inventing them — invented triggers match nothing.
License
MIT.