Guides
Why Isn't My Claude Code Skill Triggering? (And How to Fix It)
Published:
A skill that won’t trigger is one of the most frustrating things in Claude Code: you wrote it, it’s clearly there, and Claude just… ignores it. The good news is that there are only a handful of causes, and they have a reliable order. Work through these five checks top to bottom and you’ll almost always find the culprit. Usually it’s a vague description, or a silent character budget that’s quietly dropping your skill.
First, understand how a skill gets chosen
Before the checklist, the one fact that explains most failures: Claude doesn’t read your whole skill to decide whether to use it. It reads only the name and description at the top of the SKILL.md file and matches those against what you ask. That short description isn’t documentation. It’s the entire trigger. Get it right and the skill fires; leave it vague and nothing happens. Keep that in mind as we go.
Check 1: Restart your session
The simplest and most common fix. Claude Code loads available skills when a session starts. If you added or edited a skill while a session was already open, it won’t be picked up. Quit and relaunch Claude Code, then try again. Do this first: it costs ten seconds and solves a surprising share of “my skill is broken” reports.
Check 2: Make the description specific
If a restart didn’t help, look hard at your description. “Helps with code” or “useful for tasks” gives Claude nothing to match. A good description names the situation that should trigger it:
- Weak:
description: Helps with commits - Strong:
description: Use when writing or reviewing a git commit message, so messages follow the project's conventional-commit style
Write the description as “use this when…” and include the words a person would actually say when they want it. This single change fixes more silent skills than anything else.
Check 3: Check the folder isn’t nested too deep
Claude Code expects a personal skill at ~/.claude/skills/<skill-name>/SKILL.md and a project skill at .claude/skills/<skill-name>/SKILL.md. The classic mistake is one extra folder, as in skills/my-skill/my-skill/SKILL.md, which puts the file out of reach. Confirm the path has exactly one folder named for your skill, with SKILL.md directly inside it.
Check 4: Confirm the file header is valid
Open SKILL.md and check it starts with a proper front-matter block containing both a name and a description. If that header is missing, malformed, or the file is named something other than SKILL.md, Claude Code can’t register the skill at all. The official skills docs show the exact format. Match it line for line.
Check 5: Raise the description budget
If everything above looks right and the skill still won’t fire, you’ve likely hit the cause almost nobody mentions. That goes double if you have a lot of skills installed. Claude Code reserves a limited number of characters for all skill descriptions combined. Once your skills exceed that budget, some are silently left out and simply never trigger, with no error to tell you why.
The fix is to raise the limit. Set the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable (for example to 30000) before launching Claude Code. This is the documented gotcha behind a lot of “it worked yesterday” mysteries: you added one more skill and pushed the total over the edge.
The order is the point
Run these in sequence and stop when the skill works: restart → fix the description → check the path → check the header → raise the budget. Most of the time you’ll be done by check 2. The character budget is the one that catches experienced users off guard, because nothing visibly breaks: the skill just quietly stops existing.
Building your coding setup
Skills are one piece of a good Claude Code setup; the bigger wins come from getting the whole thing configured for how you work. Our free AI for Coders tool helps you choose the right assistant, install it for your operating system, and generate a starter rules file that tells the AI your conventions up front, so you rely less on individual skills and more on a setup that just behaves the way you want.
Keep reading
Frequent questions
Why won't my Claude Code skill activate? +
The most common reasons, in order: the session was open before you added the skill (restart it), the description is too vague for Claude to match, the folder is nested one level too deep, the skill file is missing its name and description header, or you have enough skills that the description budget is silently dropping some. Work through them top to bottom.
How does Claude decide when to use a skill? +
Claude reads only the skill's name and description, not its full contents, and matches them against what you ask. That short description is load-bearing: it's the entire basis for whether the skill fires. A vague description like 'helps with code' rarely matches anything; a specific one like 'use when writing or reviewing git commit messages' matches reliably.
What is the skill description budget, and how do I raise it? +
Claude Code reserves a limited number of characters for all skill descriptions combined. Once your skills exceed it, some are silently left out and never trigger. You can raise the limit by setting the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable (for example to 30000) before launching Claude Code.
Where should a skill folder live? +
A personal skill goes in ~/.claude/skills/<skill-name>/SKILL.md, and a project skill goes in .claude/skills/<skill-name>/SKILL.md. A frequent mistake is nesting it one level too deep (putting SKILL.md inside an extra folder), so Claude Code never finds it.