When two Claude Code skills conflict, one of two things is happening: they have overlapping descriptions that compete on the same prompts, or one skill's description is so broad it claims territory that belongs to the other. Finding which description is the problem takes about ten minutes with the right approach.
TL;DR: To diagnose a skill conflict, ask Claude in the conflicting session: "Which description triggered for that prompt?" Then compare both descriptions for overlapping phrases. The problem description is the one with language that semantically matches prompts it shouldn't. Fix it by adding negative triggers that explicitly exclude the other skill's territory.
How Do You Ask Claude to Reveal the Conflict?
The fastest diagnostic is to reproduce the conflict and ask Claude to explain it.
- Run the prompt that causes the wrong skill to activate.
- In the same session, immediately ask: "Which skill description did you just match? What phrase in the description triggered it?"
- Claude will tell you. The answer will name the description and the matching phrase.
That phrase is your problem. It appears in (or closely matches) one description when it belongs exclusively to the other. A content-review skill that says "reviewing written content for quality" will match "check my email for SEO issues" because "reviewing written content" semantically includes emails, even if the intent is clearly SEO.
The fix is not to change the phrase in one skill. Add an explicit exclusion to the broader skill: "NOT for SEO analysis, keyword density, or search performance." That exclusion phrase tells Claude where the boundary is.
How Do You Identify Which Description Is the Broader One?
Lay both descriptions side by side. Ask: which one could reasonably match the prompt that caused the wrong activation?
Example:
Skill A: "Invoke when the user asks to review or critique written content, including blog posts, emails, and documents."
Skill B: "Use when the user wants an SEO audit or search performance analysis of written content."
The user asks: "Can you review this post and see if it'll rank well?"
Both descriptions match. "Review written content" matches Skill A. "SEO... written content" matches Skill B. Claude picks one. It won't be consistent.
The broader description is Skill A. "Review or critique written content" is wide enough to pull in requests that belong to Skill B. The fix goes on Skill A, not Skill B:
Skill A revised: "Invoke when the user asks to review or critique written content for quality, tone, or structure. NOT for SEO, search ranking, keyword density, or technical performance."
The exclusion is explicit. Now when "rank well" appears in the prompt, Claude sees that the SEO-adjacent intent doesn't match Skill A, and Skill B wins correctly.
What If Both Descriptions Look Reasonable?
If both descriptions look correctly scoped but the conflict persists, the problem is semantic overlap that isn't obvious from reading.
The technique: test each description independently. Create a temporary project with only Skill A installed. Run 10 prompts: 5 that should trigger Skill A and 5 that should trigger Skill B. Note how many Skill B prompts activate Skill A. Then repeat with only Skill B installed.
The skill that activates more of the other skill's prompts is the broader one. That's the description to fix.
We've seen this in commissions where both descriptions looked precise on paper. A "writing-reviewer" skill description included the phrase "writing quality," and a "grammar-checker" skill also described itself as checking "writing quality." Two different intents, one shared phrase. Adding specificity to both resolved it: "prose quality and structure (not grammar)" vs "grammar, spelling, and mechanics (not prose style)."
How Do You Fix a Description Conflict?
Three steps:
Step 1: Identify the overlapping phrase. It's the specific phrase that appears in or closely matches both descriptions. Once you know the phrase, you know what to differentiate.
Step 2: Add a negative trigger to the broader description. Don't change the positive trigger. Add an explicit exclusion. Format: "NOT for [what belongs to the other skill]." Negative triggers tell Claude where one skill's territory ends. For more on why negative triggers work, see What Are Negative Triggers and Why Should I Include Them in the Description?.
Step 3: Test with 10 prompts. Create a test set: 5 prompts for each skill. Run the full library with both skills installed. Every prompt should activate the correct skill. If any prompt still activates the wrong skill, the overlap isn't fully resolved.
"The single biggest predictor of whether an agent works reliably is whether the instructions are written as a closed spec, not an open suggestion." — Boris Cherny, TypeScript compiler team, Anthropic (2024)
What If the Fix Breaks the Other Skill?
If adding a negative trigger to Skill A stops Skill B from working correctly, the fix excluded something that Skill B needs to match.
Check the negative trigger you added. Is it excluding the right scope? "NOT for SEO" is precise. "NOT for technical analysis" is broad. It might exclude legitimate Skill A activations along with the ones you wanted to exclude.
Make the negative trigger more specific. Name the exact concepts that belong to Skill B: "NOT for SEO scores, keyword density, meta tag analysis, or Google ranking factors." That's more specific than "NOT for technical analysis" and avoids collateral exclusion.
For a deeper look at the root causes of skill interference, see What Causes Multiple Skills to Interfere with Each Other?.
Frequently Asked Questions
Can I use the same phrase in two different skill descriptions? You can, but you shouldn't if the phrase is semantically distinctive. Shared distinctive phrases are the primary cause of description conflicts. If two skills legitimately need the same phrase, differentiate by adding scope qualifiers: "reviewing code quality (not prose)" vs "reviewing writing quality (not code)."
Does changing the skill name fix a conflict? No. Claude matches descriptions, not names. Two skills named "analyzer" and "reviewer" with overlapping descriptions still conflict. Two skills with identical names but non-overlapping descriptions don't conflict.
My two conflicting skills are in different categories. Why do they still conflict? Categories are organizational metadata for humans, not for Claude's skill selection. Claude only reads the description field when deciding which skill to activate. Description overlap causes conflicts regardless of how the skills are categorized.
How many negative triggers can I include in one description? There's no hard limit, but a description loaded with negative triggers becomes harder for Claude to parse. Two to three negative trigger clauses are enough to differentiate overlapping skills. If you need more, the skills' scopes overlap fundamentally and a redesign is the right fix, not more exclusions.
Should I report skill conflicts to the skill author if I'm using community skills? Yes. If you're using a community skill and it conflicts with your custom skills, the conflict is worth reporting. The overlap affects other users too. Include the two conflicting descriptions, the prompts that cause the conflict, and which skill activates when it shouldn't.
Last updated: 2026-04-23