A skill's description is not a summary for humans. It is an instruction to Claude that says when to reach for the skill. If it is vague, Claude never matches a request to it, the skill sits unused, and you are left wondering why nothing happens. A good description says plainly what the skill does, and names the situations and phrases that should set it off. It leans a little pushy on purpose, so it fires when it should.
To write a skill description Claude uses, say what the skill does in one plain clause, list the moments and phrases that should trigger it, tell Claude to use it even when unnamed, name what it does not cover, then test it from a fresh chat.
Write it in five steps
- Say what it does in one plain clause. Open with the job, not the backstory. "Reformats messy notes into clean bullet points" tells Claude the shape of the work. A description that starts with how clever the skill is tells Claude nothing it can match against.
- List the moments and the phrases. Write the things a person would actually type when they need it: "tidy these notes", "clean this up", "sort out this mess". Claude matches requests to those phrases, so the closer they are to real wording, the more often the skill fires.
- Be a little pushy. Add a line like "use this whenever the user pastes rough notes, even if they do not say the skill's name". A description that waits to be named politely will wait forever. You want it to reach out and grab the right request.
- Name what it does not cover. Say where the skill stops: "not for writing new content from scratch". This keeps it from firing on the wrong things, which is just as annoying as it never firing, because now it interrupts work it cannot help.
- Test it from a fresh chat. Start a new chat, type one of your trigger phrases, and see if the skill fires. If it does not, the phrases are too far from real wording. If it fires when it should not, tighten the "not for" line. Adjust, do not guess.
The skill description template
Paste this into the description field of your SKILL.md and fill in the brackets. The weak and strong examples below show the difference, so read both before you write your own. The brackets are the file, so do not leave them as they are.
TEMPLATE [WHAT IT DOES IN ONE PLAIN CLAUSE. For example: reformats messy notes into clean, structured bullet points.] Use this whenever the user [THE MAIN TRIGGER. For example: pastes rough or unstructured notes and wants them tidied], even if they do not name the skill. Trigger on phrases like "[REAL PHRASE ONE]", "[REAL PHRASE TWO]", "[REAL PHRASE THREE]". Do not use this for [WHAT IT DOES NOT COVER. For example: writing new content from scratch, or summarising long documents]. WEAK EXAMPLE (Claude will not fire this) A helpful skill for working with notes and making them better. STRONG EXAMPLE (Claude will fire this) Reformats messy, unstructured notes into clean bullet points and short headings. Use this whenever the user pastes rough notes, meeting scribbles, or a wall of text and wants it tidied, even if they do not name the skill. Trigger on phrases like "tidy these notes", "clean this up", "sort out this mess", "format this properly". Do not use this for writing new content from scratch or for summarising, since it only restructures what is already there.
Where the line is
- Too broad and it fires on the wrong things. A description that reaches for every mention of "notes" will interrupt work it cannot help. When that happens, add or sharpen the "do not use this for" line.
- Too narrow and it never fires. A description that only matches one exact phrase will miss the ten other ways people ask for the same thing. You find the right width by testing from fresh chats, not by guessing at your desk.
Rewrite one description today
Pick the skill you built that never seems to trigger. Open its description, rewrite it with the template, add three real trigger phrases, then start a fresh chat and try one. Watch it fire, and if it does not, tighten and try again.
Ready to build something bigger than one step? Read how to build a multi-step skill.