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