Why Isn't My Claude Code Skill Triggering? (And How to Fix It)

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 character budget that’s quietly dropping your skill’s description.

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: Make sure Claude Code can see the folder

Older advice says to restart the session. You rarely need to now: Claude Code watches ~/.claude/skills/ and your project’s .claude/skills/ and picks up a new or edited SKILL.md within the session. The exception catches people out. If you created a skills folder that didn’t exist when the session started, Claude Code isn’t watching it yet, so run /reload-skills, and run it again after each later change there. Type / and look for your skill’s name in the list: if it’s there, Claude Code has found it and the problem is further down this page.

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 the file and check two things. It has to be called exactly SKILL.md. And it should start with a front-matter block between two --- lines that holds a description (the name is optional: without one, the folder name becomes the skill’s name). If the description is missing, Claude Code falls back to the first line of your instructions, which is rarely a good trigger. And if the header doesn’t parse, or the opening --- isn’t the file’s very first line, the skill still loads but with no description at all, so Claude has nothing to match (start Claude Code with --debug to see the error). 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 puts a listing of your skills into every conversation, and that listing has a character budget: by default 1% of the model’s context window. Every skill name always makes the list, but when the descriptions don’t all fit, Claude Code drops some of them, starting with the skills you use least. A skill with no description has nothing for Claude to match, so it just stops firing. Nothing appears on screen; the only warning goes to the debug log, which you see if you start Claude Code with --debug.

Run /doctor for an estimate of what the listing costs and which skills take the most room. Then either raise the budget, with the skillListingBudgetFraction setting (0.02 means 2%) or the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable set to a fixed number of characters, or make room: /skill-doctor shows the skills you never use, so you can turn them off. Also keep each description tight and put the main use case first, because each one is cut at 1,536 characters whatever the budget. Before Anthropic documented all this, it was a known 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: check it’s found → 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 is still listed, it just quietly stops firing.

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

GuidesWhat Is an AI Agent? (Plain English, No Jargon)A chatbot answers your questions; an AI agent goes and does things for you. The difference in plain words, with an example you've probably heard of.GuidesBest AI Coding Tool 2026: An Honest, No-Hype ComparisonThere's no single winner. Here's a fair look at Claude Code, Cursor, Devin Desktop, Copilot, Cline and Aider: what each is genuinely best at, and who it's for.GuidesWhat Is Vibe Coding? (And Is It Safe for Beginners)Building software by describing what you want in plain language and letting AI write the code. What it's genuinely good at, plus the honest catch.