A skill usually fails to trigger in Claude Code for one of three reasons: its description lacks the words you type, Claude Code cannot see the skill (wrong folder, refused name, or description cut from the listing), or it is set to run only on request. Of 1,948 public skills we read on November 9, 2026, 33 run only on request and 1,212 never say when to use them.
The quickest test is to type /skill-name. If the skill runs that way but never loads by itself, the description is the cause. If /skill-name is not recognized either, Claude Code is not loading the skill at all, and the folder, the name or a setting is the cause.
Which causes turn up in real skills?
We read the front matter of every skill in this directory's November 2 crawl that could still be opened on November 9, 2026: 1,948 SKILL.md files from 46 GitHub repositories. The table counts each cause that Claude Code's documentation lists, so you can see which ones are common and which are rare.
| Cause | Skills | Repositories | What Claude Code does |
|---|---|---|---|
disable-model-invocation: true |
33 | 5 | Removes the skill from Claude's context; it runs only when you type its name |
user-invocable: false |
1 | 1 | Hides it from the / menu; only Claude can invoke it |
| No trigger clause ("Use when", "when the user" and similar) in the description | 1,212 | 25 | Nothing to match unless the job itself names your words |
| Description under 60 characters | 20 | 4 | Rarely leaves room for trigger words |
| Same name as a skill in another repository | 131 (65 names) | 16 | Only one copy runs as /name if both are installed outside a plugin |
Description and when_to_use over 1,536 characters |
0 | 0 | Text past 1,536 characters is cut from the listing |
--- not on the first line, or YAML that does not parse |
0 | 0 | The skill loads with no description to match |
A field name misspelled (for example disable_model_invocation) |
0 | 0 | The field is ignored without an error |
| A name with characters Claude Code refuses | 0 | 0 | The skill is missing from the / menu |
name different from the folder name |
75 | 8 | Not a cause: both names invoke the skill |
Source: Use This Skill directory (data/skills.json, crawl of November 2, 2026), each repository cloned and every SKILL.md read by script on November 9, 2026. 112 skills could not be read: 100 in Shaisolaris/solaris-dev-shop, which asks for a sign-in, and 12 in stablyai/orca, whose folders have moved. The crawl only lists skills that have a name and a description, so skills with no description are not counted. 23 of the 33 run-on-request skills are in mattpocock/skills, which has 38 skills in the directory.
Two things stand out. Not one of the 1,948 had malformed front matter, so broken files are rare among published skills. The common cause is the quiet one: 1,212 descriptions say what the skill does but not when to use it. Outside ComposioHQ/awesome-claude-skills, where 864 skills share one template, 727 of 1,084 descriptions do have a trigger clause, and 633 of all 736 clauses start within the first 200 characters.
Can Claude Code see the skill at all?
Ask Claude "What skills are available?" and check that yours is in the list. If it is not, check these in order.
- The folder. Claude Code loads
~/.claude/skills/<name>/SKILL.mdfor all your projects and.claude/skills/<name>/SKILL.mdfor one project. Its documentation says project skills load from the directory where you start Claude Code and every parent up to the repository root. Skills in a.claude/skills/folder below where you started load only the first time Claude reads or edits a file in that subfolder, or sooner with/add-dir. - A new skills directory. Edits to skills are picked up during the session. A top-level skills directory that did not exist when the session started is not watched; run
/reload-skillsafter creating it and after each later change there. - The name. Claude Code refuses a skill's folder name or
namethat contains a zero-width space, a control character, an icon-font glyph, a character that changes text direction,<or>, or any blank other than one plain space between words. A refused folder name means the skill does not load. None of the 1,948 names in our count contains these characters. - Your settings. A
Skilldeny rule in/permissionsblocks all skills, andSkill(name)blocks one. TheskillOverridessetting can switch a skill to"off","name-only"or"user-invocable-only", which changes whether Claude sees it, without touching its SKILL.md.
If you install skills from several places, the same name can come from two of them. In our count, 65 names appear in two or more repositories (pdf, docx, skill-creator and canvas-design are in both anthropics/skills and ComposioHQ/awesome-claude-skills, for example). Claude Code's documentation says a personal skill wins over a project skill with the same name, so /pdf may run a different copy from the one you just edited. Skills inside a plugin avoid this, because they are namespaced as /plugin-name:skill-name.
Is the description the problem?
If /skill-name works but the skill never loads by itself, it almost always is. Claude decides from the name and description alone; the body of SKILL.md is read only after the skill is chosen. Claude Code's troubleshooting steps are to include the words people naturally say and to try rephrasing your request to match the description.
In practice, that means a second sentence that starts with the trigger, such as "Use when the user asks for release notes or a changelog entry," placed early in the description. Our guide on writing a SKILL.md description that triggers covers the wording in detail, with examples from the directory.
If the skill sets paths, it loads automatically only for matching files inside Claude's current working directory; a sibling git worktree does not match, even one added with /add-dir. None of the 1,948 skills we read uses paths.
Are descriptions being cut from the listing?
With many skills installed, they can be. Claude Code keeps every skill's name in the listing, but its documentation says the listing has a budget of 1% of the model's context window, and when it overflows, Claude Code drops descriptions, starting with the skills you invoke least. A skill you have never used is the first to lose its description, and with it the words Claude needs to match your request.
To check, run /doctor for the listing's estimated cost and largest entries, look at the Skills row in /context, or start Claude Code with --debug, which logs a warning when the listing exceeds its budget. To fix it, turn off skills you do not use (/skill-doctor suggests which), set low-priority skills to "name-only" in skillOverrides, or raise the budget with the skillListingBudgetFraction setting (0.02 is 2%) or the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable. How many skills Claude Code can load at once works out how many descriptions fit.
Each description and its when_to_use text is also capped at 1,536 characters in the listing. No skill in our count reaches that; the longest description we read, in anthropics/skills, is 1,068 characters.
How do I find a broken SKILL.md?
Claude Code reads front matter only when the opening --- is the very first line of the file. If the YAML between the markers does not parse, the skill still loads, with no fields set: /skill-name works, but there is no description for Claude to match. Field names must also match exactly; a field Claude Code does not recognize is ignored without an error.
To find these, run claude plugin validate .claude/skills for project skills or claude plugin validate ~/.claude/skills for personal skills (Claude Code v2.1.233 or later), or start with claude --debug and read the parse error. Among published skills this is rare; it is more likely in a file you have just edited by hand.
A checklist by symptom
| What you see | Likely cause | What to do |
|---|---|---|
/skill-name works, the skill never loads by itself |
Description lacks your words, or was dropped from the listing | Add a "Use when" sentence early; check /doctor and /context |
/skill-name works, Claude ignores the description entirely |
Front matter did not parse | claude plugin validate, or claude --debug |
/skill-name is not recognized |
Wrong folder, refused name, user-invocable: false, or a setting |
"What skills are available?"; check the folder, the name, /permissions and skillOverrides |
Only /skill-name ever runs it |
disable-model-invocation: true |
Intended for side-effect skills; remove the line if you want automatic use |
| A different version of the skill runs | Same name in two places | Remove the duplicate, or install one copy as a plugin |
| Works in one folder, not in another | Project or nested skill, or paths |
Start Claude Code in the folder that holds the skill, or use /add-dir |
For what disable-model-invocation does in each agent, and which public skills set it, see what disable-model-invocation does in a skill.
Does a skill that triggers actually help?
Triggering only tells you Claude found the skill. To see what a skill changes once it is loaded, the proven skills on this site run the same brief three times without the skill and three times with it, with every page published and tokens and time recorded. Before you install a skill from anywhere, paste its GitHub link into the live skill check to scan every file in its folder. For skills meant to work in Codex, Cursor or Gemini CLI as well, do agent skills work outside Claude Code? covers what carries over.
How we counted
A script cloned each repository in data/skills.json on November 9, 2026, opened the SKILL.md at each recorded path, checked that the first line is ---, parsed the front matter as YAML, compared every field name with the 20 fields in Claude Code's front matter reference (including near-misses in case or with underscores), measured the description plus any when_to_use text, and compared each name with its folder and with every other skill's name. The trigger clause pattern is the one in our description guide. Outside facts were checked on Claude Code's skills documentation the same day.