Activation problems fall into three types. Knowing which type you're dealing with tells you exactly which part of the description to fix. This guide covers Claude Code skill activation debugging for SKILL.md description fields, using AEM's tested methodology for identifying and resolving all three failure types.

TL;DR: Before debugging the description, confirm the skill loads correctly. Then build a 10-prompt test set (5 should-trigger, 5 should-not-trigger), run it in a fresh session, and map failures to description properties. Under-triggering means the trigger phrases don't match your real use cases. False positives mean the trigger phrases are too broad.

What are the three types of description activation problems?

Skill description activation fails in one of three ways: the skill never fires when it should (under-triggering), fires on requests it should ignore (false positives), or fires inconsistently on identical prompts. Each type maps to a different property of the description, so identifying the type first saves you from applying the wrong fix.

  • Type 1: Under-triggering: The skill never fires automatically. You have to invoke it with /skill-name explicitly. The description's trigger condition doesn't match the phrases your real prompts use.
  • Type 2: False positives (over-triggering): The skill activates on requests it shouldn't handle. The trigger condition is too broad and matches adjacent use cases.
  • Type 3: Inconsistent triggering: The skill fires sometimes but not others on identical prompts. Usually caused by session context accumulation or competing skills.

Each type needs different attention. Running the same generic fix across all three wastes time and often makes things worse.

"When you give a model an explicit output format with examples, consistency goes from around 60% to over 95% in our benchmarks." — Addy Osmani, Engineering Director, Google Chrome (2024)

The same principle applies to trigger conditions. An explicit, unambiguous trigger specification — not a vague one — gets consistent activation.

How do I confirm the skill is actually loaded?

Activation debugging is pointless if the skill is not loaded. Run /skills and verify your skill appears in the list with its full description intact. If it does not appear, or appears with a truncated description, the loading problem takes priority over any description changes.

The most common loading failures are wrong file path, misnamed SKILL.md, and malformed frontmatter (usually an unescaped colon or multi-line description). Claude Code loads skill descriptions dynamically, scaling to 1% of the context window with a fallback cap of 8,000 characters across all loaded skill descriptions (Anthropic, Claude Code Docs, 2026). See Why Does Claude Say 'No Skills Found' When I Run /skills for the file-loading diagnostic.

If the skill loads but the description appears shorter than you wrote it, the 1,024-character limit has been hit. Count the characters in your description: field. At 1,024 characters, Claude truncates the value, cutting off any trigger phrases at the end.

How do I build a test set before editing the description?

Write 10 prompts before touching the description: 5 that represent real use cases that should trigger the skill, and 5 adjacent requests that should not. Run them in a fresh Claude Code session with no prior skill-building context. Record whether the skill activated for each prompt. This baseline tells you which failure type you are dealing with before any edits.

Writing prompts before looking at the description forces you to use natural vocabulary instead of the vocabulary you already embedded in the description. This is the only way to catch the vocabulary gap before it reaches production. Write these prompts from memory:

Should-trigger prompts (5 prompts): How would you naturally ask for this skill? Write five prompts that represent real use cases. These are the phrases you actually type in practice.

Should-not-trigger prompts (5 prompts): What adjacent requests should the skill ignore? Write five prompts that are related but clearly outside the skill's scope.

Start a fresh Claude Code session. Run each prompt. Record whether the skill activated. Do this in a session with no prior skill-building context — the Claude A/Claude B distinction matters here. A session where you just designed the skill will activate it more readily than a fresh user session.

In our activation testing across 650 trials, skills tested in a fresh session with no design context activated at 87% of their design-context rate (AEM activation testing, 2025). A skill that scores 10/10 in the designer's session scores 8-9/10 in a neutral session. This gap is why "it works for me" doesn't mean the skill is production-ready. Real-world testing across 200+ prompts found that unoptimized descriptions activate at ~20%; adding examples and explicit trigger phrases raises that to ~90% (mellanon, GitHub, December 2025). For reliable activation baselines, skill evaluation methodology recommends 25-30 test inputs minimum; A/B testing description changes requires 40+ inputs for high confidence results (MindStudio, March 2026).

How do I diagnose the failure by pattern?

After running the test set, the failure pattern tells you which fix applies. Three distinct outcomes are possible: should-trigger prompts fail, should-not-trigger prompts activate the skill, or results are inconsistent across identical prompts. Each outcome maps directly to a different part of the description that needs attention.

  • If should-trigger prompts don't activate the skill: The trigger phrases in your description don't match how you actually phrase requests. Read your should-trigger prompts and compare their vocabulary to your description. If the prompts use words that don't appear in the description, those words are candidates for addition.

    Example: Description says "Invoke for content planning." Should-trigger prompt says "Help me map out a content calendar." The description doesn't mention "calendar," "map out," or "schedule." The trigger condition is too narrow for how the task is actually phrased.

  • If should-not-trigger prompts activate the skill: The trigger phrases are too generic. Identify the vocabulary shared between the false-positive prompts and your description. Add a negative trigger that excludes that vocabulary for the false-positive context. See How Do I Debug a Skill That Triggers on the Wrong Prompts for the full false-positive methodology.

  • If activation is inconsistent across identical prompts: Session context is interfering. Test the same prompt in five consecutive fresh sessions. If activation varies, you have a competing-skill conflict or a trigger phrase that's at the edge of the classifier's confidence threshold.

What is the minimum fix for each failure pattern?

The smallest change that resolves the failure pattern is the right change. Do not rewrite the description to fix a single issue. Each failure type has a specific one-line correction: adding targeted vocabulary for under-triggering, adding a negative constraint for false positives, or clarifying boundaries between overlapping skills for inconsistency.

  • For under-triggering: Add the specific vocabulary from your should-trigger prompts into the description. Add examples of how users actually phrase the request: "Invoke when the user asks to plan, outline, or schedule content."
  • For false positives: Add one negative trigger for the shared vocabulary causing the false positive. "Do NOT invoke for [specific pattern]."
  • For inconsistency: Check whether another skill's description overlaps with yours. If it does, the two skills are competing for the same triggers. Clarify the boundary in one or both descriptions. For borderline trigger confidence, add stronger signal: imperative phrasing ("INVOKE for..." rather than "Use when...") raises activation rates from 77% to 94% in testing (AEM activation research, 2025). A separate 650-trial controlled experiment found that directive-style descriptions ("ALWAYS invoke...") achieve 100% activation, compared to 77% for passive-style descriptions, with an odds ratio of 20.6 (Ivan Seleznov, reported in Marc Bara, Medium, March 2026).

How do I retest after applying a fix?

After making the minimum fix, start a fresh Claude Code session and run the full 10-prompt test set from scratch. Do not continue the session where you made the edit. The old description may still be loaded. Record results for both the should-trigger and should-not-trigger lists. A correct fix should:

  • Pass all 5 should-trigger prompts
  • Pass all 5 should-not-trigger prompts

If the fix improved one list but degraded the other, the change was too broad. Narrow it. If neither list changed, verify that the description file was actually saved and the session was actually fresh (not a continued session where the old description is still loaded).

Each iteration cycle takes about 10 minutes. Most description activation problems resolve in 2-3 cycles. Independent testing measured baseline skill activation at 55% without description optimization (Scott Spence, scottspence.com, February 2026), confirming that iteration is necessary, not optional. If you're past cycle 5 with no improvement, the issue is probably not in the description text — look at whether the trigger condition itself is achievable. Some use cases are genuinely hard to auto-activate because they share too much vocabulary with unrelated work.

What do I do when activation is always inconsistent, never stable?

Persistent inconsistency across fresh sessions means one of three things, and the fix differs for each. Start by ruling out the simplest cause: run /skills and read all active descriptions. If two descriptions could both match the same prompt, that is the source. If they do not overlap, the problem is trigger confidence or session contamination.

  • Multiple skills with overlapping descriptions: Run /skills and read all descriptions. If two descriptions could both plausibly apply to the same prompt, Claude will choose between them non-deterministically based on context. The fix: add mutually exclusive negative triggers to each skill.
  • Trigger phrases at the edge of classifier confidence: The classifier has a confidence threshold. Trigger phrases near that threshold activate sometimes and not others depending on surrounding prompt context. Raising the specificity of the trigger (adding more descriptive vocabulary and a concrete example) moves the trigger further above the threshold. This produces stable activation.
  • Session context accumulation: If you run many prompts in a single session before testing the skill, prior context shifts how the classifier interprets later prompts. Always test activation in a session that starts with the skill test prompt as the first message.

For the broader context of how descriptions control activation, see What Does the Description Field Do in a Claude Code Skill.

Frequently Asked Questions About Skill Description Activation

The most common point where systematic debugging still fails is the vocabulary gap between your test prompts and real user language. A test set written by the skill author will consistently outperform real-world activation because the author naturally uses the same vocabulary as the description. The questions below address this gap and other persistent edge cases.

Q: My skill activates perfectly in my tests but users report it doesn't activate for them. What's different? Your test prompts match your description's vocabulary because you wrote both. Users phrase things differently. Collect the actual user prompts that should have triggered the skill and run them as should-trigger tests. The gap between your test vocabulary and user vocabulary is the fix.

Q: How do I test activation without running through every use case manually? Build a batch of 20 test prompts (10 should-trigger, 10 should-not-trigger) once, save them to a file, and run them as your standard test suite. After any description change, run the full set. The upfront investment in building the test suite pays for itself on the second iteration.

Q: The skill activates on the first prompt in a session but not on subsequent identical prompts. What causes this? This is a known pattern with high-specificity triggers. The classifier partially anchors to the first trigger event in a session. If you want consistent activation across repeated prompts, add "INVOKE each time the user..." phrasing to your description to signal that the skill applies repeatedly, not just once.

Q: My activation rate is 80% — is that acceptable, or should I aim for 100%? For skills invoked via /skill-name, 80% is a UI problem, not a description problem. Explicit invocation should work 100% of the time regardless of description quality. For auto-triggered skills, 80% means 1 in 5 natural-language requests won't activate the skill. Whether that's acceptable depends on the use case. Production skills we ship at AEM target 90% or above on a standardized 10-prompt test set.

Q: I added explicit trigger examples to my description and activation went down. What happened? Examples that contain false-positive vocabulary can accidentally activate the skill for the wrong prompts, making the classifier less confident about the description overall. Use trigger examples that are unambiguous. "Invoke when the user shares a blog post draft" is unambiguous. "Invoke when the user shares text for editing" is not — "text" and "editing" match too many things.

Last updated: 2026-04-21