Claude Skill Not Triggering? Fix It in 6 Checks

You installed a skill, you asked Claude to do the thing the skill is for, and Claude carried on as if the skill doesn’t exist. No error, no warning, nothing to grep. Just silence.

We see this constantly. SkillProof installs and tests every skill in our catalog on a clean machine, and failure to trigger is the single most common defect we find. It’s also the most fixable: nearly every “skill not working” report in our test logs traces back to one of six causes, and five of them take under a minute to rule out.

Run the checklist first. The rest of the article expands each check with the symptom, the cause, and the fix.

The 30-second checklist

1. Right folder? The file must be at ~/.claude/skills/<skill-name>/SKILL.md, one folder per skill, filename exactly SKILL.md.
2. Restarted? Claude scans skills at session start. Changes made mid-session are invisible until you restart.
3. Name collision? Two skills with the same name shadow each other. Only one survives.
4. Description too vague? If the description doesn’t mention what users literally ask for, Claude never matches it. This is the number one cause.
5. Frontmatter valid? One broken YAML character makes the entire skill invisible, silently.
6. Conflicting skill? Another installed skill with an overlapping description may be winning the match.

If all six pass and the skill activates but the output doesn’t change, that’s a different failure. Skip to when it triggers but does nothing.

Check 1: the skill is in the wrong folder

Symptom. The skill never appears when you ask Claude “what skills do you have installed?” It’s as if you never copied it.

Cause. Claude only looks in specific places: ~/.claude/skills/ for personal skills and .claude/skills/ inside a project for project skills. Within those, the layout is strict: one folder per skill, containing a file named exactly SKILL.md. The mistakes we see most often when we install community skills for testing: copying the whole cloned repo (so the path becomes skills/some-repo/skills/pdf-helper/SKILL.md, one level too deep), dropping SKILL.md directly into ~/.claude/skills/ without its own folder, and lowercase skill.md, which some filesystems forgive and others don’t.

Fix. Verify from the terminal:

ls ~/.claude/skills/*/SKILL.md

Every skill you expect should print exactly one line. If a skill is missing or its path has extra nesting, move the folder so SKILL.md sits one level below skills/. Our install guide walks through the correct layout for each platform.

Check 2: you didn’t restart

Symptom. The folder structure is correct, you fixed it two minutes ago, and Claude still can’t see the skill in the same conversation.

Cause. Skill discovery happens once, at startup. Claude reads the frontmatter of every SKILL.md it can find and holds that index for the session. A skill you add, rename, or edit mid-session doesn’t exist as far as the running session is concerned.

Fix. In Claude Code, exit and start a new session. In the desktop app, quit fully with Cmd+Q on macOS (closing the window doesn’t count) and reopen. This one is so cheap to rule out that we do it before any deeper debugging, the way you’d power-cycle a router before calling your ISP.

Check 3: a name collision is shadowing your skill

Symptom. You installed the skill, the folder is right, you restarted, and the skill list shows either nothing new or a different skill answering to the same name.

Cause. Skill names must be unique. If a personal skill and a project skill share a name, or two installed packs both ship a skill called seo-audit, one shadows the other with no warning. We hit this in our own catalog work: two marketing packs installed side by side produced a silent duplicate, and the one we wanted never loaded.

Fix. Search for duplicates:

grep -h "^name:" ~/.claude/skills/*/SKILL.md .claude/skills/*/SKILL.md 2>/dev/null | sort | uniq -d

Any output means a collision. Rename the folder and the name field of the copy you control, restart, and check the list again.

Check 4: the description never says when to fire

Symptom. The skill shows up in the installed list. Ask for it by name and it works fine. Ask for the task in your own words and nothing happens.

Cause. This is the big one, and it deserves its own section, so here’s the short version: Claude decides whether to load a skill by reading only its description field and comparing it against your request. If the description says what the skill is instead of when to use it, the match never happens. The skill isn’t broken. It’s unadvertised.

Fix. Rewrite the description around the phrases users actually type. The deep dive below shows three real failure patterns and their rewrites.

Check 5: the frontmatter is invalid

Symptom. Folder correct, restart done, no name collision, and the skill still doesn’t appear in the list at all. This looks like check 1 but the path is fine.

Cause. The YAML block at the top of SKILL.md failed to parse, and a skill with unparseable frontmatter is simply skipped. The usual culprits from our test notes: a missing closing ---, an unquoted colon inside the description (“Use for: reports” breaks the parser), curly quotes pasted from a blog post or a Google Doc, tab characters used for indentation, and a name that violates the format rules (lowercase letters, digits, and hyphens only, 64 characters max; descriptions cap at 1024).

Fix. Open the file and eyeball the block, or skip the eyeballing: paste it into our skill validator and it flags parse errors, format violations, and smart-quote contamination immediately. If the frontmatter parses and the skill still hides, go back to check 1, because at that point it’s almost always the path.

Check 6: another skill is winning the match

Symptom. You ask for the task and a skill does activate, just not yours. Or behavior changes in a way that matches a different skill’s instructions.

Cause. When several descriptions plausibly cover a request, Claude picks the one that reads as the best fit, and a broader, more confident description tends to beat a narrower one. Install a general “writing assistant” skill next to your “release notes formatter” and the generalist can swallow every writing request, including release notes.

Fix. Sharpen both descriptions so their territories don’t overlap, and add explicit exclusions. A line like “Do NOT use for release notes or changelogs” in the generalist’s description is crude and works. If you don’t control the offending skill, disable it while testing yours, then decide whether you actually need both.

Why descriptions fail: the deep dive

We test every skill we list, and trigger problems are the number one reason skills score low in our reviews. Not broken scripts, not bad instructions. Descriptions that never get matched.

The mechanics explain why. At startup Claude loads only each skill’s name and description, roughly a hundred tokens. The body, however brilliant, stays on disk until the description wins a match against your request. The description is a sales pitch delivered to a model, and most authors write it like a museum label instead.

Here are the three patterns we mark down most often, with rewrites that fixed them in our retests.

Pattern 1: the modest label.

description: Helps with documents.

Nothing here connects to anything a user would type. Compare Anthropic’s DOCX skill, which passed our trigger tests on the first run. Its description names the file format, the actions, and the phrasings that should activate it. The rewrite that follows the same logic:

description: Create, edit, and format Word documents (.docx).
  Use when the user mentions a Word doc, .docx file, memo,
  letter, or asks for a deliverable "as a document."

Pattern 2: the internal name.

description: Runs the acme-formatter pipeline with corporate config.

This describes the implementation. No user asks Claude to “run the acme-formatter pipeline”; they ask to “clean up this report before I send it to a client.” The rewrite translates the skill into the user’s vocabulary:

description: Reformat rough drafts into client-ready reports using
  Acme's corporate style. Use when the user wants to clean up,
  polish, or "make presentable" a document for external sharing.

Pattern 3: the greedy blanket.

description: Use for any writing task.

The opposite failure. This matches everything, which means it collides with every other writing-adjacent skill and fires when it shouldn’t, and users disable it within a week. The rewrite narrows the claim and fences the edges:

description: Write and edit marketing copy: landing pages, ads,
  and email campaigns. Do NOT use for technical docs, code
  comments, or internal memos.

The test we apply when reviewing: read only the description and ask, “if a user typed their request naturally, would these words match it?” Write in third person, state what the skill does and when it applies, and include the actual nouns people use. If you’re writing a skill from scratch, our authoring guide covers this in more depth, and Anthropic’s Skill Creator scaffolds descriptions that pass this test by default.

How to test triggering properly

Most people test a skill by naming it: “use the invoice skill on this.” That proves nothing, because naming a skill bypasses the description match entirely. It’s like testing a smoke detector by pressing the test button and concluding your house is fireproof.

Test the way a user would ask, in a fresh session each time. For an invoice-extraction skill, three phrasings that should fire:

• “Pull the totals out of these invoice PDFs.”
• “I’ve got 30 invoices from vendors, get the amounts and dates into a table.”
• “Extract the line items from this bill.”

And two that should not:

• “Summarize this PDF for me.” (Generic PDF work; a different skill’s territory.)
• “Write an invoice email to this client.” (Composing, not extracting.)

If a should-fire phrasing does nothing, ask Claude directly: “Which of your installed skills would you use for this request, and why?” The answer shows you the match reasoning, and it usually points straight at the weak spot in the description. If the should-not-fire phrasings activate the skill anyway, you have a greedy blanket and need exclusions. This is exactly the protocol we run in catalog testing, and it’s the same discipline the Systematic Debugging skill teaches: reproduce first, one variable at a time, believe the evidence.

When it triggers but does nothing

Suppose the skill does activate. You can confirm this by asking Claude mid-conversation whether a skill loaded for the request, and it will tell you. But the output looks the same as it did before you installed anything.

That’s not a trigger problem, and nothing above will fix it. It’s a body problem: the instructions inside the skill are too vague to change behavior, or the skill references bundled files that don’t exist at the paths it expects, or it calls a script whose dependencies were never declared. The description got the skill through the door and the contents fell over inside.

In our testing this is the other large bucket of failures, roughly the mirror image of trigger defects, and it’s the main reason about half of community skills fail our tests. The quick discriminator: if behavior didn’t change at all, suspect triggering; if behavior changed but badly or partially, suspect the body. Debug accordingly, because the fixes don’t overlap.

Platform gotchas

The skill format is identical everywhere, but discovery isn’t, and a skill that works in one place can look dead in another.

Claude Code reads folders on disk: ~/.claude/skills/ for personal, .claude/skills/ per project. Both load; name collisions between the two scopes resolve to one winner (check 3). Restart the session after any change.

Claude Desktop doesn’t read your skills folders. Skills are uploaded as a zip through Settings, under Capabilities, and the zip must contain the skill’s folder at the top level, not the bare SKILL.md and not a wrapper directory. A skill that triggers fine in Claude Code will be simply absent on Desktop until you upload it there separately.

claude.ai takes the same upload path as Desktop, with two extra ways to lose: skills need the code execution feature enabled on your plan, and workspace admins can disable skills org-wide, in which case nothing you upload will ever fire and no error will say so. Ask your admin before you spend an evening rewriting descriptions.

One more cross-platform trap: a skill body written for Claude Code that shells out to git or reads local project files will trigger correctly on claude.ai and then fail inside the sandbox. That’s a body problem wearing a platform costume.

When to stop debugging

If it’s your own skill, keep going, because every fix above is permanent and the validator plus the five-phrasing test will get you there. If it’s a third-party skill and you’ve burned more than twenty minutes on someone else’s description field, it’s fair to swap it for one that’s already been through this checklist: every skill on our best-of lists passed trigger testing on a clean machine before we listed it.

FAQ

How do I confirm a skill is installed at all?

Ask Claude “what skills do you have installed?” in a fresh session. If your skill isn’t in the answer, the problem is discovery (checks 1, 3, and 5: folder, collision, frontmatter), not triggering. If it’s listed but never activates, the problem is the description (checks 4 and 6).

Can I just force the skill to trigger by naming it?

Yes. “Use the docx skill to write this memo” loads the skill directly, and it’s a fine workaround while you debug. It’s not a fix, though: a skill you have to summon by name every time is a skill with a broken description, and you’ll forget to summon it exactly when it matters.

Why does my skill work in Claude Code but not on Desktop or claude.ai?

Different discovery paths. Claude Code reads folders on disk; Desktop and claude.ai only see skills uploaded through Settings as a zip with the skill folder at the top level. On claude.ai, also confirm code execution is enabled and your workspace admin hasn’t disabled skills entirely.

Does installing too many skills break triggering?

Not directly. Fifty skills cost a few thousand tokens of metadata, which is cheap. The real risk is overlap: the more descriptions you install, the more likely two of them claim the same territory, and then the wrong one wins sometimes (check 6). Install by need, and prune skills that never fire.

My skill triggered yesterday and not today. Is that normal?

Occasionally, yes. Matching is model-driven, not a regex, so a borderline description will fire on one phrasing and miss a near-identical one. If a skill is flaky rather than dead, treat it as a weak description: add the exact phrases that missed to the description field, restart, and retest. Reliable skills trigger on every reasonable phrasing, which is why we test with five, not one.

For more, see how Claude actually decides which skill to load.