How Claude Discovers and Loads Skills Automatically
Claude scans Skill descriptions to match incoming tasks and load matching instructions on demand.
This is the mechanism that lets you build a library of Skills without having to name one every time you want it used.
Understanding how the matching actually works is the fastest way to fix a Skill that isn't firing, or to write a new one that will.
Summary
- Core Idea: Claude checks the description of every available Skill against the current task, and loads the full instructions only for the Skill that matches.
- Why It Matters: It's what makes Skills feel automatic - you describe the task, not the tool, and the right instructions show up.
- Key Concepts: description index, on-demand loading, trigger wording, description specificity, overlapping descriptions.
- When to Use: Relevant any time you're deciding how to phrase a Skill's description, or debugging why a Skill did or didn't fire.
- Limitations / Trade-offs: Matching depends entirely on wording - a well-built Skill with a vague description behaves as if it doesn't exist.
- Related Topics: SKILL.md anatomy, Agent Skills basics, signs a Skill isn't discovered, writing an effective description.
Foundations
Every Skill you make available to Claude has two parts that matter for discovery: its name and, far more importantly, its description.
Claude doesn't read every Skill's full instructions on every message - that would add unnecessary length to every single conversation, most of which don't need any Skill at all.
Instead, it keeps something closer to a table of contents: each Skill's name and description, kept lightweight enough to check quickly against whatever you just asked for.
When your message arrives, Claude compares it against that table of contents, looking for a description that matches the shape of the task.
If one matches, Claude loads that Skill's complete SKILL.md body - the actual steps, format, or rules - into its working context before it starts on your request.
If nothing matches, Claude just answers normally, with no Skill involved at all.
This two-step process - a cheap check against short descriptions, then a full load only on a match - is why you can have many Skills available without every conversation slowing down or getting cluttered with irrelevant instructions.
Mechanics & Interactions
The description field is doing the actual work of discovery, and it's worth being precise about what makes one effective.
A good description states two things: what the Skill does, and when it should be used - ideally using the kind of words a person would naturally type when asking for that task.
description: >-
Generates the weekly team status report in our standard format.
Use when asked for a weekly update, status report, or team summary.Notice this description doesn't just say "handles reports" - it names the specific task and lists three phrasings someone might actually use to request it.
That specificity matters because Claude is matching against real task language, not against a category label you had in mind when you wrote it.
A description that's too broad risks firing on tasks it wasn't meant for; a description that's too narrow or abstract risks never firing at all, even on exactly the task it was built for.
When more than one Skill's description could plausibly cover the same request, Claude has to pick - which is why keeping descriptions distinct from each other matters as your Skill library grows, not just keeping each one individually clear.
The instructions body, by contrast, doesn't need to be optimized for matching at all - it only gets read after a Skill has already been selected, so it can be as long and detailed as the task genuinely requires.
Advanced Considerations & Applications
As a team's Skill library grows past a handful of entries, discovery reliability becomes a design problem, not just a wording tweak.
| Situation | What Happens | Fix |
|---|---|---|
| Description too vague ("handles reports") | Rarely or never matches real requests | Add concrete trigger phrases someone would actually type |
| Two Skills with overlapping descriptions | Claude may pick the wrong one, inconsistently | Narrow each description to its distinct trigger |
| Description accurate but instructions thin | Skill fires correctly but output doesn't match expectations | This isn't a discovery problem - revise the body, not the description |
| Skill covers too many unrelated tasks | Description becomes broad and unfocused, hurting matching | Split into two or more single-purpose Skills |
A useful habit is treating the description like a search query you're pre-writing on behalf of every future version of yourself who might ask for this task in slightly different words.
That means testing a new Skill with the actual phrasing you expect to use day to day, not a generic test message, and revising the description after watching a real result rather than guessing in advance.
This is also why discovery problems and instruction problems get confused: a Skill that never fires and a Skill that fires but produces the wrong output look similar from the outside, but the fix lives in a different part of the file each time.
Common Misconceptions
- "Claude reads every Skill's instructions on every message." - It checks lightweight descriptions first; full instructions only load for a matched Skill, keeping unrelated conversations unaffected.
- "A longer description matches more reliably." - Specificity, not length, drives matching - a short description with the right trigger words beats a long, vague one.
- "If my Skill isn't firing, the instructions must be wrong." - The instructions never even get evaluated until a description match happens first; check the description before touching the body.
- "Having many Skills slows Claude down." - Unmatched Skills add negligible overhead since only their short descriptions are checked, not their full content.
- "You need to name the Skill in your message for it to work." - Discovery is designed to work from natural task language alone; naming a Skill directly is optional, not required.
FAQs
What actually gets checked when I send a message?
- Claude compares your task against the descriptions of your currently available Skills, not their full instructions.
- Only a matched Skill's complete body gets loaded into the conversation.
Why didn't my Skill fire even though I described the right task?
- The most common cause is a description that doesn't use language close enough to how you actually phrased the request.
- Revising the description to include the exact trigger words you use in practice is the usual fix.
Can two Skills match the same message?
- It's possible if their descriptions overlap; Claude has to choose, which can produce inconsistent results.
- Narrowing each Skill's description to a distinct trigger reduces this risk.
Does having lots of Skills installed slow things down?
- No, not meaningfully - only short descriptions are checked against each task; full instructions load only for a match.
Do I need to say the Skill's name to use it?
- No - discovery is built to work from ordinary task phrasing. Naming a Skill directly is an option, not a requirement.
What's the difference between a discovery problem and an instructions problem?
- A discovery problem means the Skill never loads at all - fix the description.
- An instructions problem means the Skill loads but produces the wrong result - fix the body.
Should I make one broad Skill or several narrow ones?
- Several narrow Skills with distinct descriptions generally match more reliably than one broad Skill trying to cover many unrelated tasks.
How specific should a description really be?
- Specific enough to name both what the Skill does and two or three real phrasings someone would use to ask for it - not just an abstract category label.
Is matching based on exact keywords or something looser?
- It's based on the description's meaning and phrasing matching the task's meaning and phrasing - close, natural wording works better than trying to game exact keywords.
Can I test whether a Skill is being discovered correctly?
- Yes - send the kind of message you'd naturally use for that task and check whether the output follows the Skill's instructions, or ask directly which Skill was used.
Related
- What Are Agent Skills? - the basic building blocks a description belongs to
- Anatomy of a SKILL.md File - where the description field sits in the file's structure
- Signs Your Skill Isn't Being Discovered by Claude - a diagnostic list for discovery failures
- Writing an Effective Skill Description That Claude Will Trigger On - a deeper walkthrough of description writing
Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5. Model names, pricing, and product features move quickly - verify current specifics at platform.claude.com/docs before relying on them.