Claude Skills Not Firing When Expected

You installed or built a Claude Skill that should run on “summarize this PDF” or “review my PR” or “log this to my CRM.” You type the trigger phrase, hit send, and Claude just answers in plain prose. No Skill ran.

Fastest fix: invoke it explicitly by command or name first. In Claude Code type /your-skill-name; on claude.ai say “Use my your-skill Skill to do X.” If that works, the Skill is healthy and the real problem is the trigger description or the skill budget (Steps 2 and 4). If even explicit invocation fails, the Skill isn’t enabled on this surface or is broken (Steps 3, 6, 7).

Skills match your prompt against each Skill’s description text, which is the only part loaded at startup. A vague description, the disable-model-invocation flag, the wrong surface, or Claude Code silently dropping the description to stay under its skill budget will all produce a silent miss. This guide walks the causes in hit-rate order and gives the exact menu paths, commands, and settings keys as of June 2026.

How Skill matching actually works

This is the mechanic that explains most silent misses. Every Skill is a SKILL.md file with YAML frontmatter. Anthropic’s progressive-disclosure design loads the Skill in stages:

Level	When loaded	Cost	Content
1. Metadata	Always, at startup	~100 tokens/Skill	name + description in the system prompt
2. Instructions	Only when the Skill triggers	under ~5k tokens	the SKILL.md body
3. Resources	On demand	effectively unlimited	bundled files/scripts read via bash

The matcher only ever sees Level 1. So if your description doesn’t clearly say when to use the Skill, Claude has nothing to match against and falls back to a plain answer. The combined description (plus optional when_to_use) is truncated at 1,536 characters in the listing, so front-load the trigger conditions.

Common causes

Ordered by hit rate, highest first.

1. SKILL.md description is too generic

Claude picks Skills by matching your prompt against each Skill’s description. “Helps with documents” is too generic, because almost every chat is plausibly “documents.” Anthropic’s own guidance: the description should state both what the Skill does and when Claude should use it.

How to judge: read the description aloud. If it could plausibly apply to half your prompts, it’s too generic, or too generic to beat a sharper competing Skill.

2. The Skill has disable-model-invocation: true

In Claude Code, a Skill (or merged custom command) with disable-model-invocation: true in its frontmatter will never auto-fire. It only runs when you type /skill-name yourself. This is the single most overlooked silent cause for skills authored as manual workflows (deploys, commits).

How to judge: open the SKILL.md frontmatter and look for disable-model-invocation: true. If present, the Skill is manual-only by design.

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

Skills do not sync across surfaces. A Skill uploaded to claude.ai is not available in the API or Claude Code, and vice versa. claude.ai skills are per-user; API skills are workspace-wide; Claude Code skills are filesystem-based.

How to judge: check the Skills list on the exact surface you’re testing. Confirm it shows there, not just somewhere else.

4. Claude Code dropped it from the skill budget

As of build 2.1.129 (May 2026), Claude Code caps total skill-listing metadata to skillListingBudgetFraction of the context window, default 0.01 (1%). If your installed Skills’ descriptions exceed that budget, Claude Code keeps the highest-priority ones (by usage/recency) and drops the descriptions for the rest, so they stop auto-firing. A startup warning names which Skills were truncated.

How to judge: run /context and read the Skills: line, or run /skills and check whether your Skill still shows a full description. If it was dropped, that’s why it stopped matching.

5. A different Skill claimed the turn

If two Skills have overlapping triggers (“review documents” and “summarize documents”), Claude picks the one whose description matches your phrasing best; the other stays silent.

How to judge: in Claude Code, after the turn, ask “Which Skill did you use and why?” On claude.ai, check whether the answer reflects a different Skill’s behavior.

6. Trigger phrase is too implicit

“Look at this PR” is a weaker signal than “review this PR.” Skills generally need the verb/topic to overlap with the description’s wording; vague openings often miss even with a good description.

How to judge: did your prompt contain any keyword from the Skill’s description? If not, the match signal is weak.

7. Required inputs not met, or paths restriction

Some Skills expect an attachment or file path. Without it, Claude falls back to a plain answer instead of failing loudly. In Claude Code, a Skill with a paths: glob only auto-loads when you’re working on a matching file.

How to judge: read the Skill’s required inputs and any paths: frontmatter. Missing attachment or non-matching file path means no auto-fire.

8. Skill is broken or the install failed

Less common: broken YAML frontmatter, a name over 64 chars, a description over 1,024 chars, or a handler that errored on install. Claude silently skips a Skill it can’t parse.

How to judge: validate the frontmatter (name: lowercase, hyphens, no “claude”/“anthropic”, max 64 chars; description non-empty, max 1,024 chars). On claude.ai, re-check the upload didn’t error. In Claude Code, look for the startup parse warning.

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, or API.
• List every Skill currently enabled on that surface. Competing triggers and budget pressure are the two most common silent causes.
• For a custom Skill, have the SKILL.md (or dashboard config) open.

Step-by-step fix

Step 1: Invoke the Skill explicitly

The fastest diagnosis is forcing the Skill to run.

In Claude Code:

/your-skill-name

On claude.ai or the API prompt:

Use my code-review Skill on this PR.

If it fires, the Skill is functional and the original trigger was just too weak (go to Step 2 / Step 4). If it still does not fire, it is broken or not enabled on this surface (jump to Step 3, 6, or 7).

Step 2: Tighten the description

If explicit worked but implicit didn’t, rewrite the description with sharper verb + noun matches. Put the key trigger first (only the first 1,536 chars are kept in the listing).

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

In Claude Code you can also add a when_to_use: field with explicit trigger phrases; it’s appended to the description in the listing. Research circulating in 2026 found directive phrasing (“Use this skill whenever the user asks about X”) activates far more reliably than passive descriptions, so name the trigger conditions plainly.

Step 3: Confirm the Skill is enabled on this surface

Check the exact surface you’re testing:

claude.ai     → Settings → Features → Skills (upload custom zip; Pro/Max/Team/Enterprise + code execution required)
Claude Code   → /skills  → toggle the Skill on
API           → skill must be uploaded via /v1/skills and referenced by skill_id in the container param

On claude.ai the pre-built skills (PowerPoint, Excel, Word, PDF) work automatically with no setup. Custom skills must be uploaded as a zip under Settings → Features and are individual to your account, not shared org-wide.

In Claude Code, custom skills live at ~/.claude/skills/<name>/SKILL.md (personal, all projects) or .claude/skills/<name>/SKILL.md (this project only). When names collide, enterprise overrides personal, and personal overrides project.

Step 4: Check the Claude Code skill budget

If you’re in Claude Code and a previously-working Skill stopped auto-firing after you installed more Skills, you’re likely over budget.

/context   → read the "Skills:" line for token usage and percent of context
/skills    → open the picker; a dropped Skill shows truncated/no description

Two fixes:

1. Disable Skills you don’t use in the /skills picker. Disabled Skills are removed from the listing entirely and stop counting against the budget. This is the zero-cost fix.
2. Raise the budget in settings.json (costs roughly 3k extra tokens per session):

{
  "skillListingBudgetFraction": 0.02,
  "skillListingMaxDescChars": 2048
}

skillListingBudgetFraction is a decimal between 0 and 1 (0.02 = 2%), not a percentage. skillListingMaxDescChars defaults to 1536.

Step 5: List and de-conflict competing Skills

In Claude Code, run a probe that several Skills could match, then ask which one Claude would choose:

Which Skill would you use for: "Review this PR and log a summary to my CRM"? Explain why.

If two Skills could fire, the sharper description wins. Temporarily disable the loser in /skills and retest the original prompt. On claude.ai, disable competing skills under Settings → Features.

Step 6: Verify required inputs and paths

For Skills that need a file, confirm you actually attached it. A “Summarize PDF” Skill cannot fire from a text-only prompt:

Skill: "Summarize PDF"
Required input: a .pdf attachment on the turn
Your prompt had: text only → falls back to a plain answer

In Claude Code, check for a paths: glob in frontmatter. A Skill scoped to paths: ["src/**/*.ts"] only auto-loads when you’re working on a matching file.

Step 7: Validate frontmatter and the handler

For custom Skills you authored, open SKILL.md and confirm:

• name: lowercase letters, numbers, hyphens only; max 64 chars; not “claude” or “anthropic”.
• description: non-empty; max 1,024 chars; trigger conditions first.
• No disable-model-invocation: true unless you intended manual-only.
• The YAML parses (a stray colon or unquoted : silently drops the Skill).
• For API/dashboard Skills with executable handlers, the handler returns successfully on a manual curl or local run.

Step 8: Reload the Skill

• Claude Code: edits to SKILL.md under a watched directory take effect within the session via live change detection. A brand-new top-level skills directory that didn’t exist at session start requires restarting Claude Code.
• claude.ai: re-upload the zip under Settings → Features; uploads don’t hot-reload.
• API: push a new version via the Skills API and reference the updated skill_id.

How to confirm it’s fixed

• Re-run the original trigger prompt with no explicit naming. The Skill should fire.
• Run a near-miss prompt (similar but should not trigger). The Skill should stay silent, which confirms the description is sharp without being over-broad.
• In Claude Code, run /context and confirm the Skill still has a full description in the Skills: budget (it didn’t get re-dropped).
• If the Skill is enabled on more than one surface, test each separately; they don’t sync.
• For a shared Claude Code project skill, have a teammate pull the repo and try the same prompt.

Long-term prevention

• Write descriptions as “Use when the user asks to X, Y, or Z.” Verb-led, noun-precise, trigger conditions first.
• Keep total enabled Skills per surface modest. In Claude Code, watch the /context Skills: line and prune with /skills before you hit the 1% budget cap.
• Reserve disable-model-invocation: true for genuinely manual workflows, and document that in the Skill so future-you isn’t confused when it won’t auto-fire.
• For custom Skills, keep a short test list of 5 prompts that should fire and 5 that should not. Re-run it whenever you change the description.
• Merge related narrow Skills into one multi-mode Skill rather than 4 with overlapping triggers.

Common pitfalls

• Editing the description but forgetting to re-upload (claude.ai) or restart for a new top-level dir (Claude Code), so Claude still sees the old text.
• Two Skills with near-identical descriptions, then wondering why one never fires.
• Assuming a claude.ai Skill works in Claude Code. It does not; surfaces don’t sync.
• Leaving disable-model-invocation: true on a Skill you expected to auto-fire.
• Installing many Skills and silently blowing the Claude Code skill budget, so older Skills lose their descriptions.
• Writing the description in user voice (“I want to…”) instead of trigger voice (“Use when the user asks…”).

FAQ

• How does Claude decide which Skill to fire? It matches your prompt against each Skill’s description (the only text loaded at startup) and reads the SKILL.md body via bash for the best match. Sharper, trigger-first descriptions win.
• Why did a Skill that used to work stop firing in Claude Code? Most often you installed more Skills and went over skillListingBudgetFraction (default 1%), so Claude Code dropped its description. Run /context and /skills; disable unused Skills or raise the budget.
• Can I force a Skill to fire? Yes. In Claude Code type /skill-name; on claude.ai say “Use my X Skill to do Y.”
• My Skill only runs when I type the slash command, never automatically. Why? It probably has disable-model-invocation: true in its frontmatter, which blocks auto-loading by design.
• Where do I enable a custom Skill on claude.ai? Settings → Features, uploaded as a zip. It requires a Pro, Max, Team, or Enterprise plan with code execution enabled, and is private to your account.
• Do Skills carry context across chats like Projects? No. Each invocation is independent; persistent state must live in the Skill’s own files or handler.

Related

• Claude tool call stuck on pending
• Claude Projects context pollution across chats
• Claude Chrome connector issue
• Claude connector no permission
• Claude beginner guide

External references: Agent Skills overview (Anthropic docs) and Use Skills in Claude Code.

Tags: #Claude #Troubleshooting #Skills

Related Articles

Troubleshooting

Claude Artifact React Component Fails Silently on Prop Errors

Your Claude React artifact renders a blank Preview with no error banner. The fastest fix: open DevTools console (or click 'Try fixing with Claude') to read the swallowed exception. Full cause-by-cause debug guide.

May 24, 2026 #Troubleshooting #Claude

Troubleshooting

Claude Artifact Reverts to an Old Version After a Follow-up

You hand-edit an artifact, send one more message, and it snaps back to a version from three turns ago. The fix: your in-panel edits never reached Claude's memory. Recover them from the versions dropdown and stop it recurring.

May 24, 2026 #Claude #Troubleshooting

Troubleshooting

Claude Attachment Preview Not Rendering: Fix the Blank Thumbnail

Claude shows the attachment tile but no preview thumbnail. Usually a render lag, an unsupported format (HEIC/TIFF), or a stale cache. Fastest fix and full diagnosis here.

May 24, 2026 #Claude #Troubleshooting

Troubleshooting

Claude Web Search Citations Return 404 or Wrong Page

A Claude citation link 404s or lands on the wrong article. Usually URL reshaping, an expired snapshot, or a paywall — how to rescue the real source and verify the fact.

May 24, 2026 #Claude #Troubleshooting

Troubleshooting

Claude Computer Use Stuck Clicking the Same Button in a Loop

Claude Computer Use keeps clicking the same button or field without progressing — almost always a screenshot-timing, coordinate-scaling, or hidden-state problem. Here is the fastest fix plus the full diagnosis.

May 24, 2026 #Troubleshooting #Claude

Troubleshooting

Claude Conversation Export Broken: PDF or Data Dump Fails

Print to PDF gives a blank page, or your Settings > Privacy data export never emails a link. Usually a long thread, a failing artifact, or a stuck export job — here is the exact fix for each.

May 24, 2026 #Claude #Troubleshooting