| name | analyze-agent-overlap |
| description | Analyzes existing agents, skills, prompts, and instructions to identify overlaps, redundancies, and conflicts. Works with GitHub Copilot, Claude Code, Codex, OpenCode, and other providers. Use before creating new customization files to avoid duplication, when consolidating agents, or when troubleshooting conflicting behaviors. |
Analyze Agent Overlap
Detects redundancy, overlap, and potential conflicts between AI coding assistant customization files.
Provider Folder Reference
This skill works across multiple AI coding assistant providers:
| Provider | Base Folder |
|---|
| GitHub Copilot | .github/ |
| Claude Code | .claude/ |
| Codex | .codex/ |
| OpenCode | .config/opencode/ |
Throughout this document, <provider>/ represents your chosen provider's base folder.
When to Use
- Before creating a new agent, skill, prompt, or instruction
- When you suspect two agents are doing similar things
- To audit and consolidate your customization files
- When agent behaviors seem to conflict
Analysis Process
Step 1: Inventory Existing Items
Scan these locations (replace <provider>/ with actual folder):
<provider>/agents/*.md - All agent definitions (including .subagent.agent.md)<provider>/skills/*/SKILL.md - All skill definitions<provider>/prompts/*.prompt.md - All prompt templates<provider>/instructions/*.instructions.md - All instruction files
For each item, extract:
- Name: The identifier
- Purpose: What problem it solves (from description)
- Domain: What areas/topics it covers
- Triggers: Keywords or scenarios that activate it
- User-Invokable: Whether it's a user-facing agent or sub-agent
Step 2: Compare Against Proposed Item
When analyzing a proposed new item, compare:
Direct Overlap Indicators:
- Same or very similar name
- Same primary purpose statement
- Identical target domain
- Overlapping trigger keywords (>50% match)
Partial Overlap Indicators:
- Related but distinct purposes
- Some shared expertise areas
- Similar but different trigger scenarios
- Complementary functionality
No Overlap Indicators:
- Different domains entirely
- Non-overlapping use cases
- Distinct trigger keywords
Step 3: Detect Conflicts
Look for these conflict types:
Behavioral Conflicts:
- Two agents giving contradictory guidance for same scenario
- Instructions that override each other for same file patterns
- Skills that produce incompatible outputs
Scope Conflicts:
- Multiple agents claiming the same use cases
- Overlapping
applyTo patterns in instructions
- Ambiguous routing between similar agents
Naming Conflicts:
- Names too similar causing confusion
- Same name in different contexts
Overlap Severity Levels
🔴 Critical (Do Not Proceed)
- Exact duplicate of existing item
- Direct contradiction with existing guidance
- Name collision
-
80% purpose overlap
🟡 Warning (Needs Discussion)
- Significant overlap (50-80% shared purpose)
- Potential user confusion about which to use
- Overlapping triggers with different behaviors
- Partial scope conflict
🟢 Low Risk (Proceed with Awareness)
- Minor overlap (<50% shared concerns)
- Complementary purposes
- Clear differentiation possible
- Different trigger contexts
Resolution Strategies
When overlap is detected, consider:
Merge
Combine into single, more comprehensive item.
- Best when: Items serve nearly identical purpose
- Action: Create unified item, deprecate duplicates
Extend
Add new functionality to existing item.
- Best when: New need is subset of existing item's scope
- Action: Modify existing item, don't create new
Differentiate
Clarify boundaries between items.
- Best when: Items serve related but distinct needs
- Action: Update descriptions to make distinctions clear
Reference
Have one item delegate to another.
- Best when: Items have hierarchical relationship
- Action: Add handoff or reference in description
Supersede
Replace older item with improved version.
- Best when: New item is strictly better
- Action: Create new, mark old as deprecated
Output Format
## Overlap Analysis: [Proposed Item Name]
### Summary
**Proposed Type:** [Agent|Skill|Prompt|Instruction]
**Proposed Purpose:** [Brief description]
**Overlap Level:** None | Low | Medium | High | Critical
**Recommendation:** Proceed | Modify | Merge | Reconsider
### Comparison Matrix
| Existing Item | Type | Overlap | Shared Concerns |
|---------------|------|---------|-----------------|
| [name] | [type] | [level] | [what overlaps] |
### Detailed Findings
#### High/Critical Overlap Items
[For each significant overlap:]
**[Existing Item Name]**
- Type: [type]
- Purpose: [their purpose]
- Overlap Areas: [specific shared concerns]
- Key Distinction: [how proposed differs]
- Resolution: [recommended action]
#### Potential Conflicts
[List any behavioral or scope conflicts]
#### Complementary Items
[Items that could work well alongside proposed]
### Recommendations
1. [Primary recommendation with rationale]
2. [Secondary options if applicable]
### Questions to Resolve
- [Clarifying questions that would help decision]
Example Analysis
Proposed: database-helper agent for SQL query assistance
Findings:
dx12-terrain-engine-dev - No overlap (different domain)agent-builder - No overlap (different domain)
Result: ✅ Proceed - no conflicts detected
Proposed: code-reviewer agent for code review
Findings:
- Existing
dx12-terrain-engine-dev mentions code quality
- Partial overlap in "review code" scenarios
Result: ⚠️ Warning - clarify scope boundaries
- Recommendation:
code-reviewer for general review, dx12-terrain-engine-dev for DX12-specific review only
