Documentation > Tutorials > Detecting Conflicts

Guide ID	T-6
Audience	Developers, Professionals
Prerequisites	T-1: Creating Your First Skill, 2+ skills created
Time	10 minutes
Difficulty	Intermediate

Detecting Conflicts

When you have multiple skills, their descriptions may overlap semantically. Two skills with similar descriptions can cause activation confusion — Claude may activate the wrong skill or activate multiple skills when only one is appropriate. Conflict detection uses embedding-based semantic analysis to find these overlaps and suggest description rewrites that differentiate the skills.

Why Conflicts Matter

Consider two skills: git-commit-helper with description “Helps with git commits” and git-workflow with description “Guides git workflow and commits.” These descriptions overlap significantly. When you type “commit my changes,” both skills score high, and the activation system may pick the wrong one or load both, wasting token budget.

Conflict detection catches these issues before they affect your workflow.

Step 1: Scan for Conflicts

Run the conflict detection command to scan all your skills:

skill-creator detect-conflicts

You can also check a specific skill against all others:

skill-creator detect-conflicts my-commit-helper

The command uses embedding-based semantic analysis to compute similarity scores between all skill description pairs.

Step 2: Understanding Results

Conflicts are reported at two severity levels:

Severity	Similarity	Meaning	Action
HIGH	>90%	Very likely activation conflict	Review and rewrite immediately
MEDIUM	85-90%	Possible overlap	Worth reviewing, may not need changes

HIGH severity conflicts almost always cause problems in practice. MEDIUM severity conflicts are worth reviewing but may be acceptable if the skills serve genuinely related purposes.

Step 3: Review Rewrite Suggestions

For each detected conflict, the command generates rewrite suggestions to differentiate the overlapping skills. When ANTHROPIC_API_KEY is available, Claude generates context-aware suggestions. Otherwise, heuristic suggestions are provided.

Review each suggestion carefully. A good rewrite makes each skill’s scope more specific by adding unique trigger phrases and clarifying the boundary between the two skills. For example:

# Before (conflicting):
git-commit-helper: "Helps with git commits"
git-workflow:      "Guides git workflow and commits"

# After (differentiated):
git-commit-helper: "Formats commit messages with conventional commit syntax. Use when writing or reviewing commit messages."
git-workflow:      "Manages branch strategy and PR workflow. Use when creating branches, opening PRs, or managing merge strategy."

Step 4: Apply Rewrites

After reviewing the suggestions, update your skill descriptions. You can edit the SKILL.md files directly or use the CLI to update descriptions. After making changes, re-run conflict detection to verify the conflict is resolved:

# Re-run after updating descriptions
skill-creator detect-conflicts

The conflict should now be resolved, with similarity dropping below the threshold.

Threshold Tuning

The default conflict threshold is 0.85 (85% similarity). You can adjust this for stricter or looser detection:

# Stricter: only flag very high similarity (fewer results)
skill-creator detect-conflicts --threshold=0.90

# Looser: catch more potential conflicts (more results)
skill-creator detect-conflicts --threshold=0.80

Use a stricter threshold when you have many skills and want to focus only on the most problematic overlaps. Use a looser threshold when doing a thorough quality review.

CI Integration

Conflict detection integrates with CI pipelines using JSON output and exit codes:

# JSON output for CI pipelines
skill-creator detect-conflicts --json

# Exit code 0: no HIGH severity conflicts
# Exit code 1: HIGH severity conflicts detected (>90% similarity)

Add this to your CI workflow to prevent conflicting skills from being merged. The exit code 1 on HIGH severity means your pipeline will fail when a potentially problematic skill overlap is introduced.

Quiet Mode

For scripting, use quiet mode to get one-line-per-conflict output:

# Count total conflicts
skill-creator detect-conflicts --quiet | wc -l

What’s Next

• Calibrating Thresholds — Optimize activation thresholds after resolving conflicts for best accuracy
• Command Reference — Full documentation for detect-conflicts, score-activation, and related commands