What a skill actually is
A skill is a directory the model can load on demand. It has a SKILL.md with frontmatter — a name and a description. That description is what the model sees when deciding whether to open the skill. The body of SKILL.md is only read if the model invokes the skill.
This is progressive disclosure: a short elevator pitch for selection, a full body for execution. Treating it like one big prompt misses the point.
Mistake one: vague descriptions
description: Helps with database work
This never fires. "Database work" overlaps with the model's default behavior. No signal to open the skill specifically.
description: Use when the user wants to write or review a PostgreSQL migration — handles reversibility, lock-holding DDL, and column-drop safety for 50M+ row tables.
This fires. It names specific triggers (write/review migration), specific tooling (PostgreSQL), and specific concerns (reversibility, locks, big tables). The model has something to match.
Mistake two: putting everything in SKILL.md
I kept piling instructions into the body. It grew to 1500 lines. Two problems: token bloat on every invocation, and competing guidance. The model does better with a focused SKILL.md and supporting files it can read selectively:
my-skill/
SKILL.md # core instructions, ~200 lines
examples/
add-column.md
drop-column.md
templates/
reversible.sql
references/
lock-levels.md
SKILL.md tells the model when to read each file. The model loads only what the current task needs.
Mistake three: instructions without a trigger model
A skill is not documentation. It is behavior under specific conditions. I now write every SKILL.md starting with a "When to use this skill" section and a "When NOT to use this skill" section. The negative list matters more than people think — it prevents the skill from hijacking unrelated conversations.
The shape I use now
---
name: pg-migrations
description: [specific triggers + specific tools + specific concerns]
---
## When to use
- User asks to create, modify, or review a PostgreSQL migration
- User mentions column changes on large tables
## When NOT to use
- Read-only query tuning (use query-optimizer skill)
- Non-PostgreSQL databases
## Method
1. ...
2. ...
## References
- See references/lock-levels.md for DDL lock behavior
- See examples/ for worked cases
Short, directive, explicit about scope. The model can decide fast whether to open it, and once opened, the method section gives it a plan to execute.
The test for a good skill
Hand your SKILL.md description to a colleague who has never seen the codebase. Ask: "Given a message from a user, could you decide whether to invoke this?" If they cannot, neither can the model. Iterate on the description before touching the body.