If your AEM Claude Code skill produces excellent output when you invoke it with /skill-name but never fires automatically when you describe the task naturally, the problem is the description field. The skill logic is working. The skill auto-activation is not. Claude Code use for new feature implementation grew from 14.3% to 36.9% of transcripts between February and August 2025 (Anthropic, "How AI Is Transforming Work at Anthropic," 2025): skills that don't fire automatically are invisible to most of that volume.
TL;DR: Auto-activation failure has three causes: (1) the description has no trigger condition, only a capability statement; (2) the description is multi-line and the parser discards everything after the first line; or (3) the description trigger phrase doesn't match how real users phrase the request. Each one has a specific 2-minute fix. Cause 2 is the most common and the easiest to miss.
Why does the skill work via slash command but not automatically?
Slash commands bypass trigger matching entirely. When you type /reviewing-code, Claude loads the skill and executes it regardless of what's in the description. Auto-activation is different: Claude reads your message, compares it to every skill description in the registry, and decides which skill (if any) matches.
If the description doesn't contain a clear, natural-language trigger condition, Claude has nothing to match against. The skill stays dormant, the user types the task naturally, and nothing fires. Community testing across 650 trials found a baseline auto-activation rate of roughly 50% for skills with unoptimized descriptions, essentially a coin flip (Ivan Seleznov, Medium, 2025).
This is not a bug. It's a description that was written for documentation purposes rather than trigger matching.
What are the three causes of auto-activation failure?
Why does a missing trigger condition prevent skill auto-activation?
The description explains what the skill produces ("Analyzes code for quality issues and returns a structured review") but doesn't say when to use it. Claude reads this as a capability, not a trigger. The skill never fires automatically because there's no signal telling Claude when it should.
The fix: add a WHEN clause to the description. "Triggers when the user asks to review code, check a function for issues, analyze code quality, or critique an implementation. Does not trigger for general coding questions."
That WHEN clause is what Claude pattern-matches against. Without it, the skill is invisible to the automatic trigger system. The same 650-trial study found that directive-style descriptions with explicit trigger conditions achieved a 20x higher activation likelihood compared to capability-only descriptions (Seleznov, 2025).
Why does a multi-line description break skill auto-activation?
A multi-line description using a block scalar strips the trigger condition silently: Claude's runtime parses only the first line and discards the rest. In our builds, this is the single most common cause of skill auto-activation failure, responsible for roughly 40% of cases where the slash command works but automatic triggering does not.
SKILL.md frontmatter is parsed at startup as a single metadata string. A multi-line description:
description: |
Analyzes code for quality issues.
Triggers when the user asks for a code review.
Does not trigger for general questions.
produces a single stored string: "Analyzes code for quality issues." The second and third lines, including the trigger condition, are silently discarded.
The fix: one line, always. Use the literal block scalar (|) or folded block scalar (>) only for the body sections of SKILL.md, never for the description field.
description: "Triggers when user asks to review code or check a function for issues. Analyzes code quality and returns a structured review with specific issues and fixes."
Single line: trigger condition, scope limitation, and output type, all under 1,024 characters.
It's invisible until you know to look for it.
Why does trigger phrase mismatch cause auto-activation failure?
Trigger phrase mismatch means the skill's description uses formal phrasing that real users never type. The description says "Triggers when the user asks to conduct a formal code review." Real users say "can you check this," "take a look at this function," "what's wrong with this," "clean up this code." The skill sits dormant.
The mismatch means the skill activates on formal phrasing and misses the informal phrasing that real users produce. This is the conservative description problem: the trigger condition is technically present but too narrow to be useful. A diagnostic scan of 200+ skill files found that overly generic or formally-phrased descriptions were the most common structural issue, with one ambiguous description triggering correctly only 30% of the time (thestack_ai, DEV Community, March 2026).
The fix: test 10 natural phrasings of the request, then update the trigger condition to include the ones the skill should match. "Triggers when the user asks to review, check, analyze, critique, or look over code or a function." Scott Spence tested 200+ prompts and found that optimizing descriptions for natural phrasing lifted activation from 20% to 84% (Scott Spence, scottspence.com, 2025).
For the full trigger phrase mechanics, see How Do I Write Trigger Phrases That Make My Skill Activate Reliably.
How do I diagnose which cause is responsible?
Run three checks in order, stopping at the first failure. Check 1 catches multi-line descriptions, which account for roughly 40% of auto-activation failures. Check 2 catches missing trigger conditions. Check 3 catches trigger phrases that are too narrow to match real user phrasing. Each check takes under two minutes.
- Check 1: Is the description a single line? Open SKILL.md. Look at the description field. Is it a single string on one line? If it uses a block scalar (
|or>), it's multi-line and the parser is discarding everything after the first line. Fix this first. - Check 2: Does the description contain a WHEN condition? Read the description. Does it say anything like "triggers when," "activates on," or "use when"? If the description only describes output ("returns a structured review"), it has no trigger condition. Add one before checking anything else.
- Check 3: Does the trigger phrase match how users actually phrase the request? Open a fresh Claude Code session. Type the task naturally, as a user who doesn't know the skill exists. Does the skill fire? If not, the trigger phrase is too narrow. Test 5 more phrasings. For each miss, add that phrasing to the trigger condition.
"The failure mode isn't that the model is bad at the task. It's that the task wasn't specified tightly enough. Almost every production failure traces back to an ambiguous instruction." — Simon Willison, creator of Datasette and llm CLI (2024)
The same principle applies to trigger conditions. An ambiguous or absent trigger is an instruction failure, not a model failure.
What does a working description look like?
A working Claude Code skill description fits on one line and contains three elements: a trigger condition, a scope exclusion, and an output type. Descriptions using the YAML block scalar (|) silently truncate to the first line (Anthropic, Claude Code docs, 2025), so all three elements must fit within a single quoted string.
- The trigger condition: when does this skill activate?
- The scope exclusion: when should it NOT activate?
- The output type: what does it produce?
Example of a broken description (capability only):
"Analyzes code for quality issues, bugs, and style violations."
Example of a working description (trigger + exclusion + output):
"Triggers when user asks to review, analyze, check, or critique code or a function. Does not trigger for general coding questions. Returns a markdown list of specific issues with suggested fixes."
The second description is longer. It fires automatically. That's the trade. Claude Code serves 115,000 developers processing 195 million lines of code per week (ppc.land, July 2025): the cost of a poorly-triggered skill scales with that volume.
For a deeper look at what makes descriptions work, see The SKILL.md Description Field: The One Line That Makes or Breaks Your Skill and Why Your Claude Code Skill Isn't Triggering (and How to Fix It).
What are the most common questions about skill auto-activation failures?
Most skill auto-activation failures trace back to three fixable description problems: missing trigger conditions, multi-line block scalars that silently strip the trigger text after the first line, and formal phrasing that real users never produce. Getting the description right resolves all three. The edge cases below cover less common scenarios that remain after those fixes are applied.
How long should the trigger condition be in the description?
Long enough to cover the 5 to 8 most common natural phrasings of the request, and short enough to fit in a single line under 1,024 characters. A trigger condition with 4 to 6 verb synonyms ("review, check, analyze, critique, look over, inspect") covers the range without approaching the character limit.
Can I test auto-activation without a real user?
Yes. Open a fresh session with no prior conversation. Type the task using 5 different phrasings, starting with the most informal ("can you look at this?") and moving toward more formal ("please review this function"). Record which phrasings trigger the skill and which don't. Any miss is a trigger phrase gap to fix.
My description is one line with a trigger condition, but the skill still doesn't fire. What else could be wrong?
Two less common causes: (1) the skill name conflicts with a built-in Claude Code command, which takes precedence; or (2) another skill in the project has a description that matches the same trigger and is "winning" the match. Check both. For the second, temporarily disable other skills and test again.
Does the order of elements in the description matter?
Yes. Put the trigger condition first. Claude reads the description sequentially and weights the start more heavily during matching. A description that leads with output type and buries the trigger condition at the end activates less reliably than one that leads with the trigger.
Should I use "triggers when" or "use when" in the description?
Either works. "Triggers when" is more explicit and produces slightly higher activation rates in our testing. "Use when" is more natural. "Activates when" also works. What matters is that a clear condition is present, not the specific phrasing of that condition.
My skill is for an internal workflow. Does auto-activation even matter?
For workflows you always invoke intentionally with a slash command, auto-activation is optional. But for skills that should fire naturally during conversation (a writing style checker, a code quality gate, an output formatter), auto-activation is the skill's core delivery mechanism. Without it, you've built a tool that only works when the user remembers to invoke it manually.
Last updated: 2026-04-18