Skip to main content
Guide11 min read·Updated July 16, 2026
🧩

Claude Code Skill Not Triggering? Run This 3-Step Ladder

B

A. Frans

Published July 16, 2026

Claude CodeAgent SkillsTroubleshootingSKILL.mdDeveloper Tools

I wrote a skill that formats our release notes. Then I asked Claude to format the release notes. It wrote them by hand in its own style, the exact style the skill existed to replace. The file was sitting right there at ~/.claude/skills/release-notes/SKILL.md. Claude never reached for it.

No error, no warning. Nothing in the output saying "skipped your skill because X." That silence is the whole problem. It's why most people debug this by guessing: rewrite the SKILL.md, restart, try again, rewrite it a third way, give up.

Skill matching is model-driven. Claude reads a list of skill descriptions and decides which one fits your request. There's no deterministic dispatcher and no "why didn't it fire" log to read afterward. Guessing is expensive when the feedback is silent, so work down a ladder instead: is the skill discovered, is it matching, is it being obeyed. Each rung has one check, and each check rules out everything above it.

If your skill has never worked because you're still building it, how to write your first Claude Code skill covers the build. This article assumes the skill exists and won't fire.

Match your symptom first

SymptomLikely causeThe check that confirms it
Name missing when you type /Wrong directory, or the session started before the folder existedCompare your path to the location table below, then restart Claude Code
/skill-name works, but Claude never fires it itselfDescription doesn't match how you phrase requestsReread the description as the matcher, not as a reader
/skill-name works, description looks fine, still never auto-firesdisable-model-invocation: trueOpen the frontmatter and look for that field
Fires in some folders but not otherspaths: is setLook for paths in the frontmatter
A different skill fires insteadOverlapping descriptions, or a same-name skill at a higher levelCompare both descriptions; check for a personal skill shadowing the project one
Skill loads, Claude does it its own way anywayInstructions too weak to change behaviorRung 3 below
Worked at turn 3, gone by turn 40Compaction dropped itRe-invoke the skill

Rung 1: Is it discovered?

Type / and look for your skill in the menu. If it's there, it's discovered, and you can skip to rung 2. If it isn't, you have a file placement problem, and no amount of description rewriting will help.

Where the file lives decides who can use it:

LocationPath
Personal~/.claude/skills/<skill-name>/SKILL.md
Project.claude/skills/<skill-name>/SKILL.md
Plugin<plugin>/skills/<skill-name>/SKILL.md
The entry point is a SKILL.md inside a folder named for the skill. A loose file at .claude/skills/my-skill.md is not a skill and won't load. This is the single most common placement error I've seen, and it looks correct at a glance.

Two caveats worth knowing before you trust the / menu:

The menu isn't a perfect discovery test. Setting user-invocable: false hides a skill from the / menu on purpose while leaving Claude able to load it automatically. So "missing from the menu" means "not discovered, or deliberately hidden."

Claude Code watches skill directories and picks up edits within the session, so you don't need to restart after changing a SKILL.md. But creating a top-level skills directory that didn't exist when the session started requires a restart so the new directory can be watched. If you just made ~/.claude/skills/ for the first time, that's your bug. Restart and it appears.

One more placement trap: --add-dir and /add-dir do load .claude/skills/ from the added directory. The permissions.additionalDirectories setting in settings.json grants file access only and does not load skills. They look interchangeable. They aren't.

Rung 2: Is it matching?

Invoke the skill by name: /release-notes. This is the highest-value move in the whole process, because it splits the problem cleanly in two.

If it runs fine when you name it but never fires on its own, that's a matching problem, and the description is your culprit. If you get "Unknown skill" or nothing at all, go back to rung 1, because it was never discovered.

The description is the trigger surface, and Anthropic's docs are blunt about it. The description field is "What the skill does and when to use it. Claude uses this to decide when to apply the skill." In a normal session, skill descriptions sit in context so Claude knows what's available, and the full skill body loads only after it gets picked.

That ordering is the whole ballgame. Claude never reads your instructions when deciding whether to use them. A 400-line SKILL.md with a lazy one-line description is a skill that will never run.

The before and after that fixed my release-notes skill:

Bad:

name: release-notes
description: A powerful toolkit for release documentation.

That's written for a human browsing a README. "Powerful toolkit" matches nothing anybody types into a terminal. It advertises. It doesn't trigger.

Good:

name: release-notes
description: Formats release notes in our house style from a git log or changelog. Use when the user asks to write release notes, draft a changelog, or summarize what shipped this release.

Two parts, both load-bearing: what it does, then when to use it, phrased in the words you'd actually say out loud. The second sentence is the one doing the work.

There's a balance point, and both ends fail quietly. Too vague ("helps with data") matches nothing. Too narrow ("reviews Flask endpoints for SQL injection in PostgreSQL queries") won't fire when you ask it to "review my code for security bugs," which is how you'll really ask 90% of the time. Be specific about the task, general about the context.

Two mechanical details that bite:

If you omit description entirely, Claude Code falls back to the first paragraph of your markdown content. So a skill that opens with "This document explains the conventions our team uses..." is being matched on that sentence. It'll match nothing useful.

The combined description and when_to_use text is truncated at 1,536 characters in the skill listing. Put the key use case first, not last. If you have trigger phrases and example requests to add, when_to_use is the field built for them, and it counts toward the same cap.

Rung 3: Loaded but ignored

This rung surprises people, because loaded and obeyed aren't the same thing. The skill fired, its content is in context, and Claude went and did the task its own way regardless.

The docs name this directly: "If a skill seems to stop influencing behavior after the first response, the content is usually still present and the model is choosing other tools or approaches." The fix is to strengthen the description and the instructions so the model keeps preferring the skill, or to use hooks when you need behavior enforced deterministically rather than suggested.

Two mechanics explain most of rung 3. When a skill is invoked, the rendered SKILL.md enters the conversation as a single message and stays. Claude Code does not re-read the file on later turns, so guidance meant to apply throughout a task has to be written as standing instructions, not as one-time steps that read like they've already happened.

Then there's compaction. When the conversation is summarized to free context, Claude Code re-attaches the most recent invocation of each skill, keeping the first 5,000 tokens of each, with all re-attached skills sharing a combined 25,000-token budget filled from the most recently invoked. Invoke six skills in a long session and the early ones can be dropped entirely. That's the "it worked at turn 3 and vanished by turn 40" case, and re-invoking is the fix.

The myth that wastes the most time

Somewhere along the way people picked up the idea that your frontmatter name must match the directory name or the skill won't load. It's wrong, and it sends people renaming folders for an hour while the real bug sits in the description.

All frontmatter fields are optional. Only description is recommended. The name field sets the display label shown in skill listings and defaults to the directory name. The command you type comes from where the file lives, not from name: .claude/skills/deploy-staging/SKILL.md gives you /deploy-staging no matter what the frontmatter says.

The one exception is a plugin-root SKILL.md, where name does set the command name, because there's no skill directory to take it from.

A mismatched name makes your skill listing confusing. It doesn't stop the skill from loading. If yours isn't firing, the description is a much better suspect.

Two fields that switch off triggering on purpose

Both of these are working as designed, which is exactly why they're maddening to debug.

disable-model-invocation: true means only you can invoke the skill. The description isn't loaded into context at all, so Claude can't consider it even in principle. It's the right setting for /deploy or /commit, where you don't want Claude deciding the timing. It gets copied out of example frontmatter and forgotten constantly.

paths: takes glob patterns that limit when the skill activates. With it set, Claude loads the skill automatically only when working with files matching those patterns. If your skill fires in one folder and stays silent in another, open the frontmatter and look here first.

When the wrong skill wins

Same-name skills resolve by precedence: enterprise overrides personal, and personal overrides project. That middle one catches teams off guard. Your own ~/.claude/skills/code-review/ quietly shadows the project's .claude/skills/code-review/ that your team checked in, and the repo's version never runs. A skill at any of those levels also overrides a bundled skill of the same name. Plugin skills are namespaced as plugin-name:skill-name, so they can't collide with yours.

When two of your own skills have overlapping descriptions, there's no precedence rule to save you. The model picks, and it'll pick inconsistently across sessions. The fix is boring and effective: make the descriptions disjoint, and say what each skill is not for. "Use for unit tests only; for end-to-end tests use e2e-runner instead" costs you eight words and removes the ambiguity. If you're running several skills together on one task, how to chain multiple agent skills in Claude Code covers making the handoffs deliberate.

Before you install someone else's skill

A skill runs with your permissions, and allowed-tools in its frontmatter pre-approves tools so Claude uses them without prompting you. Anthropic's own docs put the warning plainly: review project skills before trusting a repository, since a skill can grant itself broad tool access. For a project's .claude/skills/, those grants take effect once you accept the workspace trust dialog.

So read three things before installing: the SKILL.md, any scripts in the folder, and the allowed-tools line. If a formatting skill wants shell access, that's your signal to stop.

Verified sources for the tools mentioned here:

For packaging, testing, and the mistakes that show up while you're still building, debugging a custom Claude skill is the companion field guide. And if you're assembling a working setup from scratch, see our full list for developers.

FAQ

Why doesn't Claude Code tell me why a skill didn't trigger? Because nothing decided not to trigger it in a way that could be logged. Claude reads the available descriptions and picks what fits, the same way it picks any other approach. There's no rule engine with a rejection reason, which is why narrowing beats reading output.

My skill shows in the / menu but never fires on its own. What now? That's a matching problem, so the description is the fix. Check for disable-model-invocation: true first, since that blocks auto-firing by design. If it's absent, rewrite the description to name the trigger situation in the words you actually use.

Does the name in my frontmatter have to match the folder name? No. name is a display label and defaults to the directory name. Your command comes from the directory. The exception is a plugin-root SKILL.md, where name does set the command.

Do I have to restart Claude Code after editing a skill? Usually not. Claude Code watches the skill directories and picks up edits to SKILL.md within the session. You do need a restart if you created a top-level skills directory that didn't exist when the session started.

Can two skills conflict? Yes, in two ways. Same-name skills across levels resolve by precedence, where enterprise beats personal and personal beats project. Two skills with overlapping descriptions at the same level just compete, and the model picks one.

The description is the product

Most skill authors spend hours on the body and about nine seconds on the description. That's backwards, and it's why so many good skills sit unused. The body is what your skill does once it's chosen. The description is the entire reason it ever gets chosen. One is a loaded gun and the other is the trigger.

Write the description first, before you write a line of the body. Phrase it the way you'd ask a colleague for the thing. Then go use the skill on real work for a week, and every time it fails to fire, note the exact words you used and put those words in the description. That loop fixes more skills than any amount of rewriting instructions ever will.

Share this article

📬

Get More AI Tool Guides

New comparisons and guides every week. Join thousands of professionals staying ahead of the AI curve.