Skill Triggers: Making Claude Load the Right Skill
Claude decides which skill to load by comparing your task against the description field in every installed skill's frontmatter, so a skill that never triggers almost always has a description problem, not a content problem. Fix the description and the same skill body usually starts firing correctly.
This is the second post in a series on authoring skills. The first post covers building a skill end to end; this one goes deep on the single field that determines whether anyone ever sees the rest of your work.
TL;DR: Skill descriptions are the trigger surface: Claude reads them (not the full body) to decide relevance before loading anything else. A description that fires reliably names what the skill does and when to use it, is written in the third person, and lists concrete words a real user would actually type, not abstract categories. The most common failure is a description that reads like a slogan ("helps you write better docs") instead of an index entry ("writes API reference docs from OpenAPI specs, trigger on API docs, endpoint reference, swagger"). Test triggers the same way you would test search: try the phrasing a real user would use, try edge cases that should NOT trigger the skill, and check for collisions where two skills both plausibly match one task. This post covers how matching works, how to write descriptions that hold up under real phrasing, a table of common failures and fixes, and when to build one broad "hub" skill instead of several narrow ones.
How does Claude decide which skill to load?
Every installed skill contributes its name and description to a lightweight index Claude can see without loading the full skill body. When a task comes in, Claude matches the task against that index and loads the SKILL.md body (and only the body, not references/ or scripts/) for whichever skills look relevant. This is why the description carries so much weight: it is the only part of an unloaded skill that gets a vote.
That also means two skills with overlapping descriptions can both load for the same task, and a skill with a description that is too narrow can fail to load for a task it was clearly built for. Both problems live entirely in the frontmatter, not the body.
What makes a description trigger reliably?
A reliable description does three things: states what the skill does, states when to use it, and does both using words a real user would actually type.
Write in the third person, not as an instruction to yourself
# Weak
description: I help with writing changelogs.
# Better
description: Writes a structured changelog entry from a diff or
commit list. Use when the user asks to summarise changes, write
release notes, or draft a changelog entry.
The second form reads like a catalog entry Claude can match against a task, not a note to the skill's author.
Name concrete triggers, not categories
"Helps with documentation" could mean almost anything. "Trigger on: API docs, endpoint reference, OpenAPI spec, swagger.json" tells Claude exactly which tasks qualify.
description: Generates API reference documentation from an OpenAPI
or Swagger spec file. Trigger on: API docs, endpoint reference,
OpenAPI spec, swagger.json, generate API documentation.
Include boundary cases when a skill is easy to confuse with another
If you maintain both a "blog post" skill and a "technical documentation" skill, say so in each description, so Claude has a basis to pick one:
description: Writes long-form technical how-to guides for
developers (setup steps, code examples, troubleshooting).
Not for marketing blog posts or social copy -- use the
content-marketing skill for those.
How do you test triggers?
Test triggers the way you would test a search index: with real queries, not the ones you happen to remember writing the skill for.
Cold session testing
Open a brand new session with no prior context. Type the task the way an actual user would phrase it on a normal day, not the way you would phrase it as the skill's author. If it does not load, the description is the first thing to fix, not the body.
Phrase variation testing
Run the same underlying task through three or four different phrasings. A skill that only triggers on one exact phrase is fragile. If your changelog skill loads for "write a changelog" but not for "summarise what changed in this release," broaden the description's trigger list.
Collision testing
If you have two skills that could plausibly both match a task, run that exact task and see which one loads, or whether both do. Two skills loading for one task is not automatically wrong, but it should be a decision you made on purpose, documented in each skill's description, not something you discover by accident in production.
Common trigger failures and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| Skill never loads | Description too abstract or too short | Add concrete trigger words and a "use when" clause |
| Skill loads for unrelated tasks | Description too broad | Narrow the trigger list, add explicit exclusions |
| Two skills both load | Overlapping trigger words | Add boundary language to each description, or merge the skills |
| Skill loads inconsistently | Trigger words only cover one phrasing | Test 3-4 phrasings, add the missing variants |
| Skill loads but wrong companion skill also loads | No routing logic between related skills | Use a hub-and-companion pattern, covered in the chaining guide |
Broad hub skills versus narrow single-purpose skills
Some skills are meant to trigger on almost everything, like a session-bootstrap skill that should load on the first message of any session. Those need deliberately broad descriptions, the kind used in the Cowork navigator skill, which lists a long, generic set of trigger verbs (building, fixing, writing, researching, deploying) specifically so it catches nearly every task. Most other skills should stay narrow: a precise description that only matches its actual job is easier to reason about and far less likely to collide with something else you install later.
Frequently asked questions
Why does my skill sometimes not load even with a good description?
Check for a second skill with an overlapping description that is winning the match, or a description that covers the concept but omits the specific words the user actually typed. Testing with real phrasing, not your own phrasing, catches most of these.
Should I list every possible trigger phrase in the description?
No. List the concrete, high-frequency ones plus the category they fall under. An exhaustive list is hard to maintain and the marginal phrases rarely matter as much as getting the core three or four right.
Can I force a skill to load regardless of the task?
Broaden the description deliberately, the way a session-bootstrap skill does, or invoke it explicitly if your environment supports direct skill or command invocation. Relying on an accidentally broad description is fragile; write the breadth on purpose.
About the author
Yanni Papoutsis builds AI products, automation pipelines, and technical documentation with Claude, and publishes free tooling and guides at yanni.uk.
Next step: See how multiple skills work together in one task in the skill chaining guide, or explore 1,000+ AI tools at yanni.uk/ai-tools.
Sources
- Claude documentation (agent skills): https://docs.claude.com
- Anthropic (agent and context design): https://www.anthropic.com