title: "Why Your Claude Code Skill Isn't Triggering (and How to Fix It)" description: "Claude Code skills fail at three layers: discovery, loading, or execution. Diagnose which layer is breaking your skill and get tested fixes for each." pubDate: "2026-04-14" category: skills tags: ["claude-code-skills", "description-field", "troubleshooting", "anti-patterns"] cluster: 6 cluster_name: "The Description Field" difficulty: intermediate source_question: "Why isn't my Claude Code skill triggering?" source_ref: "Pillar.3" word_count: 3240 status: draft reviewed: false schema_types: ["Article", "FAQPage"]

Why Your Claude Code Skill Isn't Triggering (and How to Fix It)

Quick answer: A Claude Code skill that won't trigger has failed at one of three layers: discovery (Claude's classifier didn't match your description), loading (reference files didn't load correctly), or execution (instructions were followed partially). The description field is responsible for the majority of non-triggering cases. Start there, every time.

You built a skill. You wrote the steps carefully. You tested it once or twice and it seemed to work. Now Claude ignores it most of the time and you're not sure why.

The frustrating part: the file is valid YAML. The skill appears in /skills. The folder structure is correct. And yet the skill sits there, mostly unused, while Claude improvises.

The problem is specific and diagnosable. Every skill failure falls into one of three layers, and each layer has a distinct set of fixes. This guide works through all three.

What Are the Three Failure Layers?

Discovery, loading, and execution — the three sequential layers every Claude Code skill must pass through before it runs. A failure at Layer 1 makes Layers 2 and 3 irrelevant: if the classifier doesn't select your skill, the instructions and reference files are never read.

Layer 1, Discovery: Claude runs a meta-tool classifier over all available skill descriptions when it receives a prompt. The classifier compares the prompt's semantic intent against each description. If your description doesn't match the prompt precisely enough, the skill doesn't run. The steps, reference files, and output contract are never read.

Layer 2, Loading: The skill was selected by the classifier, but the content didn't load correctly. Wrong reference file paths, circular dependencies between files, or reference files too large to process cause this. Claude triggers the skill but executes with incomplete context:

  • missing domain knowledge
  • missing rules
  • missing examples

Layer 3, Execution: The skill loaded correctly, but Claude followed the instructions partially or inconsistently. Steps got skipped. Output format deviated from the contract. Rules stated explicitly in the file got ignored. This is an instruction quality problem.

Most non-triggering skills fail at Layer 1. Most incorrectly-executing skills fail at Layer 3. Loading failures (Layer 2) are less common but specific when they appear.

How Do I Know Which Layer Is Failing?

Run this three-step diagnostic before changing anything in your skill file. Each step isolates a different failure layer — visibility confirms Layer 1 pre-discovery, exact-match testing isolates description format, and fresh-session testing separates real failures from Claude A contamination. Changing files before diagnosing wastes time and breaks things that were working.

Step 1, Confirm visibility. Run /skills in your Claude Code session. Your skill should appear in the list with its description text visible. If it doesn't appear at all, the failure is pre-discovery: wrong file path, malformed YAML frontmatter, or the file sits outside the directory Claude scans. Fix the path or YAML first.

Step 2, Test explicit activation. Type a prompt that matches exactly what your skill description says it handles. Not a variation, the literal scenario the description names. If the skill activates on this exact prompt but fails on natural variations, the description is too narrow. If it doesn't activate on the exact match, the description format is wrong.

Step 3, Test output in a fresh session. Open a new Claude Code session with no prior context and let the skill run on a cold prompt. If it fails with a cold prompt but worked in your development session, you have a Claude A / Claude B contamination problem, covered below. If it fails in both, the instructions need work.

How Do I Fix a Description That Isn't Triggering?

The imperative format is the fix — rewrite your description to start with "Use this skill when" and explicitly include "Invoke automatically." This is not stylistic preference: it is a tested performance difference with a documented activation gap, measured across 650 trials comparing imperative and passive description formats on identical prompt sets.

AEM ran 650 activation trials comparing two description styles across the same set of matched prompts:

  • Imperative descriptions ("Use this skill when...") achieved 100% activation on matched prompts (AEM activation testing, 2026)
  • Passive descriptions ("This skill helps with...") achieved 77% activation on the same prompts

That 23% gap means a passive description fails roughly one in four times. The skill is present. The skill is relevant. Claude just doesn't select it.

Here is what the difference looks like:

# Passive — 77% activation rate
description: "A skill for writing technical documentation. Handles developer-facing content, API references, and tutorial articles."

# Imperative — 100% activation rate
description: "Use this skill when the user asks you to write, draft, or create technical documentation, API references, or developer tutorials. Invoke automatically for any content-writing request directed at a developer audience."

Two structural changes:

  1. Leads with "Use this skill when", directly addresses the classifier's matching pattern
  2. Includes "Invoke automatically", signals that auto-activation is intended, not just slash-command use

If your description doesn't begin with an explicit trigger condition, rewrite it. Keep it under 1,024 characters on a single line in the YAML frontmatter.

For the full mechanics of what the description field controls, see What Does the Description Field Do in a Claude Code Skill?.

Why Do Passive Descriptions Fail Silently?

Claude's classifier is calibrated to match prompts against trigger conditions, not capability catalogues. A capability description tells Claude what the skill can do. A trigger condition tells Claude when to run it. They look similar in English. They are not equivalent to the classifier.

"Handles developer-facing content" is a capability claim. "Use when the user asks you to write developer-facing content" is a trigger condition. The classifier recognizes the second pattern and acts on it. The first pattern gets catalogued as skill metadata but receives less weight in activation decisions.

The failure is silent because nothing errors out. The skill doesn't trigger, Claude handles the prompt some other way, and you see inconsistent output with no explanation. The first instinct is to fix the instructions. The problem is in the description.

"Probably the most important thing to get great results out of Claude Code: give Claude a way to verify its work. If Claude has that feedback loop, it will 2-3x the quality of the final result." — Boris Cherny, Creator of Claude Code, Anthropic (January 2026, https://x.com/bcherny/status/2007179861115511237)

This extends to negative triggers. A skill without negative trigger conditions activates on everything that resembles its positive trigger, including cases it shouldn't handle. When similar skills coexist in the same project, description precision determines which one wins. A skill with clear negative triggers wins that competition more reliably.

Add a negative trigger:

description: "Use this skill when the user asks you to write technical documentation or API references. Do NOT use for marketing copy, blog posts, or social media content — those have separate skills."

The classifier resolves conflicts between overlapping skills by selecting the one whose description most precisely matches the prompt's intent. Negative triggers narrow the match. Specificity wins.

What Happens When Code Formatters Break My Description?

Prettier, ESLint, and most YAML linters silently reformat long single-line descriptions onto multiple lines — and Claude Code's frontmatter parser breaks on multi-line values. The skill stops triggering after any formatting pass; because you didn't change content, you don't suspect format. The failure recurs silently until you add the skills directory to your linter's ignore list.

A multi-line YAML description looks syntactically valid:

---
description: "Use this skill when the user asks you to write technical documentation, API references,
  or developer tutorials. Invoke automatically for any content-writing request directed at a developer audience."
---

It isn't. Claude Code's frontmatter parser expects a single-line string value for the description field. A folded multi-line string in YAML is parsed differently, the continuation line is merged with unexpected whitespace or, in some parser configurations, discarded after the first newline. The classifier receives a broken trigger condition. Activation becomes inconsistent.

The skill worked before the formatting pass. It stopped working after. You didn't change the content, so you don't suspect the format. This is the most common root cause of "it was working and then it stopped" reports.

Fix: Add your skills directory to your formatter's ignore list.

For Prettier:

# .prettierignore
.claude/skills/**

After any formatting pass, run a quick check that your description fields are still single-line continuous strings. Five seconds of verification against hours of debugging.

What Anti-Patterns in Skill Structure Hurt Activation?

Five structural patterns degrade skill performance beyond the description field — and each one is specific enough to diagnose and fix. AEM's production audits across 12 skills in 2026 identified these consistently: prompts-in-a-trenchcoat, domain knowledge embedded in SKILL.md, budget exhaustion from too many descriptions, stray markdown files in the skill directory, and writing steps before the description.

Is your skill a prompt in a trenchcoat?

A prompt in a trenchcoat is a SKILL.md file that contains instructional text but is missing the structural components that make a skill work. It is a raw prompt saved with a .md extension. Missing components:

  • no structured sections
  • no output contract
  • no reference files
  • no description, or a placeholder description

These work inconsistently because Claude's classifier has no structural signal for how to weight the content. A production skill has four components:

  • description field — trigger condition for the classifier
  • process section — step-by-step instructions
  • output contract — scope boundaries and format constraints
  • reference files — domain knowledge

Missing any one reduces performance. Missing the description breaks auto-activation entirely.

Are you embedding domain knowledge in SKILL.md?

SKILL.md is a process file; reference files carry knowledge. Mixing them creates a file too long for reliable execution and too dense for the classifier to parse efficiently. Instructions buried deep in a bloated SKILL.md receive less attention than instructions stated early, and domain knowledge interleaved with steps degrades both classifier description-matching and the model's rule-following during execution.

A SKILL.md over 500 lines distributes Claude's attention unevenly across the file. The description, loaded first, receives appropriate weight. Instructions buried 400 lines deep receive less. Rules stated in the final third of a long file get ignored at a higher rate than rules stated early (AEM audit pattern, observed across 12 production skills in 2026).

Move domain knowledge to reference files. Load them conditionally during process execution, not at skill startup. For the correct distribution of content between SKILL.md and reference files, see What Goes in a SKILL.md File?.

Are your total descriptions exceeding the system prompt budget?

Claude Code reserves approximately 15,000 characters in the system prompt for skill description metadata. At a 200-character average description length, that budget covers roughly 75 skills. Exceed this and descriptions get silently truncated, not randomly, but in load order, which means your most recently installed skills get the worst truncation.

Check your total budget:

grep -h "^description:" .claude/skills/**/*.md | awk '{total += length($0)} END {print total " characters"}'

Target: under 12,000 characters. At 15,000+, trim descriptions or remove low-use skills.

Do you have README or CHANGELOG files in your skill folder?

In some Claude Code configurations, the skill directory scan includes all markdown files, not just SKILL.md. A README.md or CHANGELOG.md in your skill folder gets loaded as skill context. This adds tokens to the system prompt, dilutes the classifier's focus on the description, and occasionally introduces instructions that conflict with SKILL.md.

Keep skill directories clean: SKILL.md, a references/ subfolder, and an assets/ subfolder if needed.

Did you write the steps before the description?

Writing the steps first produces a description that summarizes what you built rather than a trigger condition the classifier can act on — these are different problems with different solutions. A description written after the fact describes capability. A description written first defines the trigger condition precisely. The classifier needs the second kind; most developers naturally produce the first.

Write the description first. If you cannot write a clear, specific trigger condition in under 150 characters, the skill's scope is not defined yet. The description is the proof-of-concept. Build it before the steps.

How Do I Fix Reference File Loading Problems?

Three specific patterns break reference file loading: wrong path format (absolute instead of relative), circular references between reference files, and oversized files over ~500 lines. Each pattern causes the skill to execute with incomplete context — and each has an exact fix. The failure is silent: the skill triggers, but runs without the domain knowledge it was supposed to have.

Wrong path format. Reference file paths in SKILL.md must be relative to the skill directory, not the project root. Use references/api-guide.md, not /.claude/skills/api-writer/references/api-guide.md. The absolute path fails silently, Claude cannot resolve it, skips the file, and executes without the domain knowledge it was supposed to have.

Circular references. The one-level-deep rule exists specifically to prevent this. SKILL.md can reference files in the references/ folder. Those reference files cannot reference other reference files. A chain from SKILL.md → ref-a.md → ref-b.md creates a circular dependency that Claude follows until it stalls. The skill runs with partial context and you don't know which knowledge is missing.

Oversized reference files. Reference files over roughly 500 lines cause attention degradation during execution. Claude loads the full file but distributes attention unevenly across a large content block. Specific rules and constraints stated in the dense parts of the file get lower effective weight than rules stated concisely. Prune reference files the way you prune SKILL.md: remove anything that can be looked up at runtime.

What If the Skill Triggers but Produces Wrong Output?

This is a Layer 3 execution problem: the description and loading are correct, but the instructions are not constraining Claude's output precisely enough. Two patterns account for the majority of Layer 3 failures — vague step language that Claude interprets differently each session, and Claude A contamination where your development context filled gaps that a fresh user session cannot.

Two patterns account for most Layer 3 failures.

Instructions are too vague. "Format the output appropriately" gives Claude latitude it will use differently each session. "Output a JSON object with exactly these fields: title (string), slug (lowercase hyphens only), tags (array of 2-5 strings), difficulty (one of: beginner, intermediate, expert)" is a constraint Claude follows consistently.

For a full framework for writing instructions that Claude follows reliably, see How Do I Write Step-by-Step Instructions for a Claude Code Skill?.

Claude A contamination. When you build and test a skill in your own session, your accumulated context fills in gaps the instructions don't cover. The skill appears to work because you're prompting it correctly, implicitly supplying what the instructions omit. A fresh user session (Claude B) has none of that context. The gaps become visible as inconsistent output, skipped steps, or ignored constraints.

Test every skill in a fresh session with the natural prompt a user would type. Not a prompt engineered to invoke the skill perfectly. If it fails cold, the instructions are not complete.

How Do I Test That My Fix Worked?

Three checks confirm the fix without introducing new problems: verify the description is visible and untruncated, test auto-activation with a cold natural prompt, and confirm output matches the contract in a fresh session. Run them in order — each check targets a different layer, and passing all three means the fix held at every level.

Check 1, Visibility. Run /skills and confirm your skill appears with the full, untruncated description. If the description looks cut off, the multi-line formatting problem has been reintroduced.

Check 2, Auto-activation. In a fresh session, type a natural prompt describing the task, not the slash command, not a prompt specifically designed to trigger the skill. It should activate automatically.

Check 3, Cold execution. In the same fresh session, let the skill complete without intervention. Verify the output matches the output contract. If it deviates, note the specific deviation and find the instruction that failed to constrain it.

One change at a time. One test cycle per change. If you changed the description format and trimmed reference files simultaneously and activation improved, you don't know which fix worked. The systematic approach also catches regressions, after fixing Layer 1, run the Layer 3 test anyway.

Frequently Asked Questions

Why does my skill work via /skill-name but not when Claude auto-triggers it?

Manual invocation with /skill-name bypasses the meta-tool classifier entirely, Claude runs the skill because you named it explicitly. Auto-triggering requires the classifier to match a natural-language prompt against your description. A skill that works via slash command but fails on auto-trigger has a description problem, not an instruction problem. Rewrite the description using the imperative format before looking anywhere else.

How do I stop my skill from triggering when it shouldn't?

Add explicit negative trigger conditions to your description. Without them, the classifier activates your skill on anything that resembles its positive trigger, including cases handled by other skills or by Claude's default behavior. Add a "Do NOT use for..." line that lists adjacent use cases clearly. The classifier gives explicit negative triggers significant weight in disambiguation between competing skills.

What happens if my SKILL.md description is longer than 1,024 characters?

The description gets silently truncated at the 1,024-character limit. Claude's classifier sees an incomplete trigger condition. Activation becomes inconsistent, sometimes the truncated text is sufficient to match a prompt, sometimes it isn't. Count your description's characters before committing. If you're approaching the limit, trim by removing redundant phrasing rather than cutting trigger conditions.

My skill worked until I added another skill: why did it break?

Two causes: description overlap or budget exhaustion. If the new skill has a description that overlaps yours, the classifier now has a split decision. The more specific, imperative description wins that competition. If your skill had a passive or generic description, the new skill likely out-competed it. The second cause is system prompt budget exhaustion, if your total description character count was near 15,000, the new skill pushed you over and your earlier skills got truncated.

How do I make my skill trigger reliably every time?

Use an imperative description that starts with "Use this skill when," includes specific trigger scenarios (not generic capabilities), and includes negative trigger conditions for adjacent use cases. Keep the description under 1,024 characters on a single line. Test in fresh sessions with cold prompts. Skills meeting all four criteria consistently achieve 100% activation on matched prompts in AEM testing.

Why does Claude skip steps even when my skill triggers correctly?

Three causes are common: step instructions are too vague (Claude interprets "complete the task" differently each time), important steps appear too late in a long SKILL.md file (attention thins in long files, and rules stated after line 300 receive lower weight than rules in the first 100 lines), or the testing context contaminated the result (Claude A contamination). Fix vague steps with specific constraints, move critical rules early in the file, and always test in fresh sessions.

Prettier keeps breaking my skill description onto multiple lines: how do I fix this?

Add .claude/skills/** to your .prettierignore file. This prevents Prettier from reformatting skill files on any formatting pass. The alternative, keeping descriptions short enough to avoid Prettier's line-length rules, works in the short term but breaks when descriptions grow. The ignore rule is the durable fix.

Last updated: 2026-04-14