Home / Extending: skills, MCP, subagents, hooks, plugins
Skill routing fails silently
Claude decides whether to invoke a skill by comparing the request's vocabulary against that skill's description field alone, and a mismatch of language or jargon between the two causes automatic invocation to fail with no visible signal in the response.
Nothing signals, at the moment of a request, that an installed skill covers the subject exactly: Claude decides whether to invoke it by comparing the request's vocabulary against that skill's description field, and a skill that shares no word with the request stays silent (source code.claude.com/docs/en/skills, accessed on 2026-09-02).
A single field decides
The documentation is explicit on this point: description states what the skill does and when to use it, it is the only text Claude reads to decide whether to invoke it automatically. When this field is absent, Claude falls back on the first paragraph of the SKILL.md file. This text is also truncated to one thousand five hundred and thirty-six characters in the listing presented to the model, to limit token cost: a long description whose main use case comes at the end of the text loses exactly the sentence that would have triggered the invocation.
The vocabulary mismatch warns no one
A skill described in English for a use case named chart or dataviz may not trigger on a request in French that uses the word graphique, even when the need is identical. A skill described for summarising a ticket may not trigger on a request that talks about synthesising an incident. The answer still arrives, written by Claude directly, and nothing in its form distinguishes a response that drew on the installed skill from one that ignored it.
---
description: Crée des graphiques et des tableaux de bord à partir de données
---Two direct workarounds
The first is to phrase your request using the very vocabulary of the installed description, which assumes you have read it at least once. The second is to invoke the skill directly by its name, with the slash, rather than relying on automatic matching: the same skill is then invoked regardless of the word chosen in the phrase that follows.
This risk of non-triggering connects directly to what is taught in skills, teaching Claude a workflow: a correctly written skill that is never invoked is no better than a skill that does not exist.
The truncation limit of the description field
Same installed skill, same need, different vocabulary
| A skill described in English with the words chart and dataviz, facing two phrasings of the same request | Words used in the request | Overlap with the installed description | Skill invoked automatically |
|---|---|---|---|
| Request aligned with the description | chart, dataviz | strong | yes |
| Request rephrased in different vocabulary | graphique, tableau de bord | weak | no |
The description of the skill installed for this use case uses the words chart, dataviz and visualization in its SKILL.md file. A user asks Claude, in French, to build a graphique (the French word for a chart) from a table of figures they have just pasted into the conversation. Claude responds by writing the requested chart's code directly in the body of its reply.
Write, in one sentence, what this situation establishes, and in one sentence what it does not establish.
What this establishes: In this exchange, Claude produced the chart without going through the skill installed for this use case, even though the request's vocabulary did not overlap with that of its description.
What this does not establish: That the same skill would also fail to trigger on a request that used the exact words from its description, chart or dataviz for instance.
The three most common miscalibrations
- Too broad This exchange proves that this skill never triggers, regardless of the vocabulary used in a future request.
- Too narrow This exchange proves nothing, since only a single request was made against a single installed skill.
- Off the mark This exchange shows that this skill's description exceeds the limit of one thousand five hundred and thirty-six characters applied to the listing presented to the model.
- Claude decides whether to invoke a skill by comparing the request's vocabulary against that skill's description field alone.
- A skill's combined description is truncated to one thousand five hundred and thirty-six characters in the listing presented to the model, to limit token cost.
- A mismatch of language or jargon between the request and the installed description causes automatic invocation to fail with no visible signal in the response.
- Phrasing the request with the vocabulary of the installed description, or invoking the skill directly by its name, works around this risk.
Open the SKILL.md file of a skill you use regularly, note down three exact words from its description field, then rephrase a recent request using these words to check that it does indeed trigger this skill.
These points depend on an interface or a rule that may have changed since this was written. Check them on your own screen before relying on them.
- The truncation threshold of one thousand five hundred and thirty-six characters is a harness implementation detail, liable to change with a future version, to be rechecked at https://code.claude.com/docs/en/skills before citing it as a fixed limit.
Every datable claim in this lesson links here to the public text behind it. A source that does not open proves nothing.
- Anthropic, Claude Code, skills reference consultée le 2026-09-02