jburlison/analyze-agent-overlap

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