Writing a Description That Actually Triggers
The one-line description is the only thing evaluated before a skill's full instructions load, so vague ones quietly never get used.
The line that decides everything
Go back to the anatomy from the last chapter: before a skill's body is ever read, its description gets compared against the current task. That one line either earns the skill a chance to be used, or doesn't. Everything a skill can do is irrelevant if that line doesn't clearly say what kind of task it's for.
This could apply to almost anything, which in practice means it applies to nothing reliably. It never clearly wins a match against a more specific competing skill, and it can misfire on tasks that only loosely resemble "code stuff."
States the exact situation ("reviewing a pull request") and the exact value provided ("this team's standard review checklist"). A task that matches this description almost certainly should use this skill, and a task that doesn't match clearly shouldn't.
Say what it's for, and sometimes say what it isn't
Most descriptions only need to say what a skill covers. But when two kinds of tasks could easily be confused for each other, a good description sometimes earns its keep by also saying what's out of scope, the same way a sign that says "staff only" is more useful than one that just says "door."
Write it last, not first
It's tempting to write the description before the instructions, since it comes first in the file. In practice, it's easier to write well after the instructions exist: once you know exactly what the skill actually does, summarizing it precisely is far easier than guessing at a summary in advance and hoping the instructions grow to match it.
Picture a task you've explained to Claude more than once, in slightly different words each time. Write a one-line description for it as if it were a skill's frontmatter. Then ask: would a stranger, reading only that line, know exactly when to reach for it? If not, that's the sentence to fix before anything else.