Claude Skills Not Firing When Expected

You expected a Skill to trigger and it didn't — Claude answered in plain prose instead. Usually the trigger description is too vague, the Skill isn't enabled in this surface, or it conflicts with another.

Published: May 23, 2026 Author: AI Productivity Guide Team 🌐 查看中文版本

You installed or built a Claude Skill that should run on “summarize PDF” or “review my PR” or “log to my CRM.” You type the trigger phrase, hit send — Claude just answers in plain prose. No Skill ran. No mention of the Skill in the response. The trigger description was too vague for Claude to recognize as a match, the Skill is not enabled on this surface (web vs Code vs API), or another Skill with a stronger description claimed the turn. Diagnose by inspecting the trigger text, the surface, and competing Skills.

Common causes

Ordered by hit rate, highest first.

1. Skill trigger description is too generic

Claude picks Skills by matching your prompt against each Skill’s “when to use” description. A description like “helps with documents” is too generic — every chat is plausibly “documents.” Skills with sharper trigger language win.

How to judge: Read the Skill’s trigger description out loud. If it could plausibly apply to half your prompts, it is too generic.

2. Skill is not enabled on the surface you are using

Skills can be scoped to claude.ai, Claude Code, or the API independently. A Skill installed for claude.ai will not run inside Claude Code, and vice versa.

How to judge: Skills settings in the surface you are actually using. Confirm the Skill shows as enabled there, not just installed.

3. A different Skill claimed the turn

If two Skills have overlapping triggers (“review documents” and “summarize documents”), Claude picks one. The one with the more specific match to your phrasing wins; the other stays silent.

How to judge: Check Claude’s response — does it mention any Skill name? If a different Skill ran, that is your competition.

4. Trigger phrase is too implicit

“Look at this PR” is not as strong a trigger as “review this PR using my code-review Skill.” Skills generally need the verb / topic to be clear; vague openings often miss.

How to judge: Did you mention any keyword that appears in the Skill description? If not, Claude has weak signal to fire it.

5. Skill input requirements not met

Some Skills require an attachment, a file path, or specific structured input. Without it, Claude falls back to plain answer rather than failing loudly.

How to judge: Read the Skill’s required inputs. Missing required attachment / argument = no fire.

6. Skill is broken / install failed

Less common, but: the Skill’s executable code may have errored on install, or its handler URL is unreachable. Claude silently skips.

How to judge: Skills settings → look for a red “error” badge or last-run-failed indicator on this Skill.

Before you start

Note the exact prompt that should have triggered the Skill (word for word).
Note the surface: claude.ai web, Claude Code, mobile app, API.
List all Skills currently enabled — competing triggers are the most common silent cause.
If this is a custom Skill, have the Skill definition file or the dashboard config handy.

Information to collect

Skill name (or names if you have multiple candidates).
Skill trigger description, verbatim.
The user prompt that should have fired it.
Other Skills enabled on the same surface.
Whether the Skill was installed via Marketplace, dashboard, or local file.
Surface name and version (claude.ai date, Claude Code version, API SDK version).

Step-by-step fix

Step 1: Invoke the Skill by name explicitly

The fastest diagnosis: tell Claude to use the Skill by name.

Use my code-review Skill on this PR.

If it fires: the Skill is functional, the original trigger was just too weak. If it still does not fire: the Skill is broken or not enabled on this surface — skip to step 4.

Step 2: Tighten the trigger description

If implicit invocation failed but explicit worked, rewrite the Skill’s “when to use” description with sharper verb + noun matches:

Weak	Sharp
Helps with documents	Triggered when the user asks to “summarize”, “extract from”, or “compare” a PDF or doc
For code review	Triggered when user shares a PR URL, a diff, or asks to “review this code”
Logging tool	Triggered when user says “log to CRM”, “save lead”, or “track this conversation”

The sharper version overlaps with real user phrasings.

Step 3: Check Skill enablement on this surface

Skills settings on the exact surface you are testing:

claude.ai → Settings → Skills → enabled list
Claude Code → /skills → enabled list
Anthropic dashboard → Skills → scope: which surfaces?

If a Skill is installed but not toggled on for this surface, it will not fire.

Step 4: List competing Skills

Run a sanity prompt likely to trigger several Skills:

What Skills do you have available, and which would you fire for the prompt:
"Review this PR and log a summary to my CRM"?

Claude will list candidates. If two Skills could fire, the one with the sharper description wins. Disable the loser temporarily, retest the original prompt.

Step 5: Verify required inputs are supplied

For Skills requiring a file or attachment, confirm you actually attached it. A Skill that expects a PDF attached to the turn cannot fire from a prompt with only text.

Skill: "Summarize PDF"
Required input: file attachment with extension .pdf
Your prompt had: only text → fall back to plain answer

Step 6: For custom Skills, check the handler

If you authored the Skill: open the Skill repo or dashboard config. Confirm:

Handler returns successfully on a manual test (curl or local run)
The name, description, and inputs fields parse correctly
No syntax error in the trigger description (broken YAML / JSON silently drops the Skill)

Step 7: Reinstall or reload the Skill

For Marketplace Skills, disable and re-enable. For Claude Code Skills, restart the editor. For custom dashboard Skills, push a fresh version (even a no-op bump) to force re-load.

Verify

Run the original trigger prompt again, no explicit naming. Skill should fire.
Run a near-miss prompt (similar but should not trigger). Skill should not fire — confirms the description is sharp without being over-broad.
Test the Skill across at least two surfaces if it is enabled on multiple (web + Code).
For shared Skills, ask a teammate to try the same prompt in their account; consistency confirms it is not a per-account state issue.

Long-term prevention

Write Skill descriptions in the form “Triggered when the user asks to X, Y, or Z” — verb-led, noun-precise.
Limit total enabled Skills per surface to ~10. Beyond that, competition becomes a real problem.
For custom Skills, write a TEST.md alongside the Skill listing 5 prompts that should fire and 5 that should not. Re-run these whenever you change the description.
For Skill authors: log every invocation server-side so silent skips show up in your data.
Group related Skills under a single multi-mode Skill rather than 4 narrow ones with overlapping triggers.

Common pitfalls

Editing the Skill description but forgetting to push / reload — Claude still sees the old text.
Two Skills with near-identical descriptions, then wondering why one never fires.
Assuming a Skill enabled on claude.ai also works in Claude Code. It does not — scopes are independent.
Writing trigger descriptions in user voice (“I want to …”) instead of system voice (“Triggered when user asks…”).
Forgetting that built-in tools (web search, code execution) can also intercept a turn — they look like Skills but are separate.

FAQ

How does Claude decide which Skill to fire? It matches your prompt against each Skill’s description and picks the best match. Sharper descriptions win.
Can I force a Skill to fire? Yes — name it explicitly: “Use my X Skill to do Y.”
Will Skills be cited in the response? Usually Claude mentions which Skill it used. If no mention, no Skill ran.
Is there a debug mode that shows what Skill Claude considered? On Claude Code yes (verbose logging). On claude.ai, ask Claude to “list the Skills you considered for that turn.”
Do Skills carry context across chats like Projects? No — each Skill invocation is its own thing. Persistent state needs to live in the Skill’s handler.

Tags: #Claude #Troubleshooting #Skills