Writing a description it will pick
A skill that is never chosen is the same as no skill at all, and the description is what does the choosing.
Claude reads the description of every available skill and decides which one applies to what you just asked. It is a matching problem, and the documentation is blunt about it: the description determines when the skill is invoked, so it should say what the skill does and when to use it. It has 200 characters to do that in.
Three descriptions for the same skill
| Description | What happens |
|---|---|
| "Sales helper" | Never chosen. Nothing in it matches anything anyone would ask |
| "Cleans up sales data" | Chosen sometimes, and also chosen for jobs it should not touch |
| "Combine monthly sales CSV exports into one spreadsheet with consistent columns and regions. Use when asked to prepare, clean or combine the monthly sales data." | Chosen when it should be |
The third one works because it contains the words a person would actually use. Combine, clean, prepare, monthly, sales. You are not writing a title, you are writing the sentence that has to match a request nobody has typed yet.
The shape that works
Two halves. What it does, then when to use it.
<what it does, in one clause>. Use when <the situations, in the
words somebody would say them>.The second half is the one people leave out, and it is the half that does the matching. Without it Claude has to infer the trigger from a description of the mechanism, which is how a good skill sits unused for a month.
Names matter less than you think
The name is a label, capped at 64 characters, and it is what you see in a list. It is not what routing depends on. Spend your effort on the description.
- Write three versions of your description and try each with the same request.
- Ask a colleague how they would phrase the request. Put their words in the description.
You understood something today that you didn't yesterday.