How Claude Discovers and Loads Skills Automatically
Claude scans Skill descriptions to match incoming tasks and load matching instructions on demand.
//
Search across all documentation pages
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.
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.
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.
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.
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.
Reviewed by Chris St. John·Last updated Jul 16, 2026