Detailed content
🧩 The “Do + When” formula
Every strong description has two inseparable halves: what the skill does e when it should be used. Descriptions that only describe a capability (“generates reports”) leave Claude without the most important signal—the trigger. It’s like having a brilliant résumé but never saying which job you’re applying for.
✓ Has "Do + When"
- ✓"Troubleshoots frontend layout issues by testing live in the browser. Use when the user wants to fix cut-off elements or adjust layouts visually."
- ✓Claude knows what it receives AND which request it applies to.
✗ Just the “Do it”
- ✗"A frontend troubleshooting skill."
- ✗Describes the capability, but doesn't say when to apply it — triggering is left to chance.
💡 Practical tip
Write the description and mentally underline the two parts. If you can't point to where the "when" is, it's not ready yet. The phrase "use when" is almost required.
🔫 Concrete Triggers
One concrete trigger is an actual phrase or word the user would say when they need the skill. The closer it is to the user’s language, the better the matching. Well-crafted skills list several triggers— including slash commands and synonyms—to cover the different ways of asking for the same thing.
# Gerador de itinerários
"plan a trip", "create an itinerary", "travel planner", /travel
# Correção de frontend ao vivo
"fix CSS/HTML changes", "fix cut-off elements", "adjust layouts visually"
# Padrão: linguagem do usuário + sinônimos + comando de barra📊 Three trigger sources
- Action verbs: "create", "fix", "review", "generate"—what the user wants to do.
- Concrete objects: "itinerary", "invoice", "workflow", "report"—what they want to get.
- Slash commands:
/travel,/review— the explicit shortcut.
💡 Practical tip
Before writing the triggers, imagine five different people asking for the same thing, each in their own words. The common ground among those five sentences gives you your best triggers.
💡 Examples in the description
For skills with broad or ambiguous scope, embed short usage examples in the description itself gives Claude semantic anchors that abstract prose doesn't. "Show, don't just tell" applies both to the user and to the model: a concrete case carries more signal than a generic definition.
🎯 Abstract vs. grounded
"Helps with data analysis tasks."
"Analyzes a CSV and returns top trends. Use when the user says 'what's in this data?', 'find outliers', or 'summarize this spreadsheet'."
📐 When it’s worth it
- Broad scope: the skill does many things — examples set boundaries.
- Generic term: words like "helper" or "analysis" need an anchor.
- Confusion with neighboring skills: examples distinguish it from similar skills.
🚫 Anti-patterns that kill the launch
The fastest way to fix a skill that doesn’t activate is to recognize the anti-pattern in your description. Almost every broken description falls into one of these four gaps — and each has a straightforward fix.
Too many openings
"Helps with various tasks."
Fix: name the specific task and triggers. “Various” never matches anything and everything at the same time.
Just "what it does," without "when"
"Generates HTML pages."
Fix: add the “when” half. Without a trigger, Claude has no way to know that the current request applies.
Jargon without context
"Runs the v2 pipeline orchestrator."
Fix: translate into the user's language. Nobody asks "run orchestrator v2" — they ask for the result it delivers.
Overlaid with another skill
Two skills with nearly identical descriptions.
Fix: differentiate by scope and add "don't use for X" (next topic). Overlapping descriptions cause random triggers.
🛑 When NOT to launch
This is the part almost everyone forgets — and it's what separates a good description from an excellent one. Define the negative scope ("don't use for X") prevents false positives: the skill firing on similar but incorrect requests. A false positive is just as frustrating as a false negative because it delivers the wrong result with confidence.
🛑 The power of the explicit limit
Compare a “live frontend fix” skill. It handles layout and CSS—but NOT architecture. Making that explicit prevents it from triggering on requests like “add a database.”
"...Use for visual/layout bugs. Not for backend changes, new architecture, or database work — use a standard plan for those."
✓ Trigger when
- ✓The request clearly matches the core capability
- ✓A concrete trigger appears in the request
- ✓It's exactly the problem the skill solves
✗ Do NOT trigger when
- ✗The request only seems related, but it’s something else
- ✗Falls into a case the skill lists as out of scope
- ✗Another skill is clearly a better fit
💡 Practical tip
For each skill, write a sentence starting with "Don't use this skill to...". If you can't complete it, the skill's scope is probably too vague—and it will trigger when it shouldn't.
🧪 Testing the trigger
A description is a hypothesis about when the skill should activate. Only testing confirms it. The loop is simple: run real, varied prompts, see whether the skill activates when it should and stays quiet when it shouldn't, and adjust the description. It's iteration, not a one-shot guess.
Build test cases
List requests that should trigger (positive examples) and similar requests that should not (negatives). Good negatives are adjacent requests, not absurd ones.
Run it in natural language
Request each case without naming the skill. You are testing the description, not explicit invocation.
Count the errors and adjust
False negative (didn’t trigger but should have)? Add triggers. False positive (triggered but shouldn’t have)? Tighten the negative scope. Repeat.
⚠️ Attention
Don’t optimize the description for positives alone. A description that triggers on everything has 100% accuracy on positives and is useless — because it also triggers on every negative. The goal is to balance the two.
💡 Practical tip
Save your test cases in a file. Every time you change the description, run the suite again. It’s the cheapest way to prevent regressions — tweaking for one case often breaks another.
🧰 Copyable prompts
Use these prompts to write and test sharp descriptions with Claude.
Minha skill faz: <descreva>. Escreva uma description no padrão
"Faz + Quando", com: (1) o que produz, (2) 3 a 5 gatilhos concretos
na linguagem do usuário, e (3) uma frase de escopo negativo
("não use para...").Avalie esta description: "<cole>". Ela cai em algum anti-padrão
(vaga, sem "quando", jargão, sobreposta)? Aponte qual e reescreva
corrigindo o problema.Para esta description: "<cole>", gere 5 pedidos de usuário que
DEVEM disparar a skill e 5 que NÃO devem (mas são parecidos).
Depois diga, para cada um, se a description atual acertaria.📤 Sample Output
A complete description, with the four elements from this module: does + when, concrete triggers, examples, and negative scope.
---
name: meeting-notes
description: Turns a raw meeting transcript into clean notes with
decisions and action items. Use when the user says "summarize
this meeting", "what did we decide?", "pull the action items",
or pastes a transcript and asks for notes. Not for live
transcription or scheduling — only for processing text that
already exists.
---✏️ Practical exercises
1. Diagnose and fix
Choose five vague descriptions (make them up or collect them) and classify each by the anti-pattern it uses. Then rewrite them all in the "Does + When" format.
2. Write the negative scope
For three of your skills, write the phrase "Don't use this skill for...". If you get stuck on any of them, make a note—that's a sign the scope isn't well defined.
3. Create a runnable SKILL.md and test the trigger ⭐
Write a SKILL.md complete whose description have all four elements: what it does + when, at least 3 concrete triggers, an embedded example, and a negative-scope sentence. Then create 5 positive prompts and 5 negative prompts and ask Claude to judge—which ones would trigger, based only on the description. Adjust the description until it gets them all right.
🎯 Module summary
Next module:
You already understand the anatomy, structure, and trigger. In Module 1.4, you'll bring it all together with Anthropic's current rules, a copyable checklist, and a validator to audit your skills.