How to write a description that triggers your skill
If a skill doesn't trigger when it should, the problem is almost always the description. It's the line Claude reads to decide whether your skill fits what's being asked. Master it and your skills will work first time.
Why the description is (almost) everything
Claude doesn't read the full content of all your skills in every message — it would be too much. Instead it reads the name and the description of each one and, from that, decides which to use. So the description isn't a pretty summary: it's the trigger. If it's vague, your skill stays asleep even if it's perfect inside.
The formula for a good description
A description that works usually has three ingredients:
- The trigger moment: start with «Use this skill when…». Make it clear in which situations it should kick in.
- The specific task: include the action verb (write, analyze, review, summarize, translate…).
- The distinguishing detail: the topic, language, format or document type. This prevents it triggering when it shouldn't.
Examples: from weak to excellent
❌ Weak
description: Helps with emails.
Too short and ambiguous. Help read them, write them, translate them? Claude won't know when to use it.
⚠️ Can improve
description: Writes professional emails.
It mentions the task, but it's missing the trigger moment and the context.
✅ Excellent
description: Use this skill when the user asks to write, review or improve professional emails in English: requests, complaints, follow-ups or formal replies.
It has the moment («when the user asks»), the task («write, review, improve»), the context («professional emails in English») and example cases. It triggers exactly when it should.
Common mistakes to avoid
- Being too generic: «helps with text» overlaps with almost everything.
- Being too narrow: if you only mention «invoices», it won't trigger on «receipts» or «quotes».
- Describing how instead of when: the description is for the trigger; the «how» goes in the instructions.
- Repeating the name: if the skill is called
translator, «translates things» isn't enough; add languages and context.
Check it in real time
The SkillCreator wizard includes a unique quality meter: as you write your description, it scores it from 0 to 100 and tells you exactly what's missing (the moment, the task or the detail). It's the fastest way to get it right without being an expert. See also our best-practices guide.