How to write a SKILL.md description that gets picked
A description has two jobs: say what the skill does, and name the situations that should reach for it. Write both in the words a person actually types, put the situations second, and mark the boundary against your other skills. Two or three sentences is enough. Everything below the frontmatter is read later, and only if the description won.
What goes in one, in order
1. A verb and an object, inside the first six words.
"Draft a statement of work from discovery notes" is a description. "Helper for SOW workflows" is a label. The selector is matching text, so the first thing it reads should be the thing the skill does, stated the way you would say it out loud.
2. A "use when" clause that lists real phrasings.
This is the part that does the work. List the ways the request actually arrives: "Use when the user asks for a statement of work, a SOW, a scope document, project scope, or wants discovery notes turned into deliverables and timelines." Five phrasings beat one clever one.
3. The sloppy words, not just the correct ones.
Nobody types "generate a statement of work document". They type "write up the scope for Henderson" or "turn these notes into a SOW". If the casual phrasing is missing, the skill loses to whichever file happens to contain it.
4. A boundary, stated in the description itself.
One clause saying where the skill stops keeps two files from claiming the same ground: "For pricing tables and rate cards, use the proposal skill instead." This is the cheapest fix available for overlapping skills, and it lives in the description because that is all the selector can see.
5. Two or three sentences, and stop.
A description that runs to a paragraph starts describing implementation, which no longer helps it get chosen. Put implementation in the body of the file.
Before and after
---
name: sow-draft
description: SOW generation utility.
------
name: sow-draft
description: Draft a statement of work from discovery notes, including
deliverables, timeline, and out-of-scope items. Use when the user asks
for a SOW, a statement of work, a scope document, project scope, or
wants discovery notes turned into a client-ready scope. For pricing
tables and rate cards, use the proposal skill instead.
---The file underneath is identical. The second version names four ways the request arrives and one place it does not apply, so it is reachable by an ordinary sentence rather than an exact one.
Two habits that keep it honest
Read your own last ten requests before you write the description, and make sure the nouns you type appear in it. Your vocabulary and your description's vocabulary drift apart over months, and the description is the half that never gets updated.
Then write it for a reader who has never seen the file. A description that only makes sense if you already know what the skill does is the most common failure, because you cannot un-know your own tool.
If the skill still sits unused after this, the cause is usually elsewhere in the setup, and the usual ones are listed in the guide on why a skill never fires. For the other fields in the block, see SKILL.md frontmatter, field by field.
Works with Claude Code.
Check your description now
Paste a skill file into the free checker. It reads the description the way a selector does, flags missing trigger language and overlap with your other skills, then runs the file against realistic prompts to see whether it would be picked. No account needed.
Check a skill file