Original skill document
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
Tool Overlap Analyzer
Analyze project tooling (agents, skills, commands, hooks, workflows) for overlap and optimization opportunities. Each tool type is compared only within its own category.
Workflow
┌──────────────────────────────────────────────────────────────────┐
│ Analysis Pipeline │
├──────────────────────────────────────────────────────────────────┤
│ │
│ 0. Dedup 1. Discovery 2. Coarse Scan │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Remove │───▶│ Find all│────▶│ Read 20 │ │
│ │platform │ │ tools │ │ lines │ │
│ │ copies │ └─────────┘ └─────────┘ │
│ └─────────┘ │ │
│ ▼ │
│ Similar? ──No──▶ Skip │
│ │ │
│ Yes │
│ │ │
│ ▼ │
│ 3. Deep Analysis 3.5. Cross-Reference 4. Report │
│ ┌─────────────┐ ┌─────────────────┐ ┌──────────┐ │
│ │Full semantic│───────▶│ Check if tool │────▶│ Generate │ │
│ │ comparison │ │ is referenced │ │ report │ │
│ └─────────────┘ │ by other files │ └──────────┘ │
│ └─────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘Step 0: Deduplication (Cross-Platform Copies)
Many projects distribute identical tools to multiple platform directories (e.g., agents/claude/, agents/opencode/, skills/agents/). These are intentional copies for distribution, not redundancy issues.
Before analysis, deduplicate by:
- Identify platform directories:
*/claude/,*/opencode/,*/gemini/→ platform-specificskills/agents/→ may mirroragents/*/
- Compare files with same name across platforms:
- If content is identical (or near-identical) → treat as single tool
- Keep one representative for analysis (prefer
claude/or first found)
- Record deduplication:
Deduplicated: code-architect.md
- agents/claude/code-architect.md (analyzed)
- agents/opencode/code-architect.md (skipped - identical)
- skills/agents/code-architect.md (skipped - identical)Important: Cross-platform copies are NOT overlap issues. Only compare unique tools within each type.
Step 1: Discovery
Scan the project for each tool type:
| Type | Search Locations |
|---|---|
| Agents | .claude/agents/, agents/, skills/agents/ |
| Skills | .claude/skills/, skills/, .agent/skills/ |
| Commands | .claude/commands/, commands/ |
| Hooks | .claude/settings*.json (hooks section) |
| Workflows | skills/workflows/, .agent/workflows/, **/*.workflow.yaml |
For each discovered tool, record:
- File path
- Name (from filename or frontmatter)
- First 20 lines (for coarse scan)
Step 2: Coarse Scan (Within Same Type Only)
For each tool type separately, compare tools using:
- Name similarity - Similar names suggest overlap (e.g.,
git-commitvscommit-standards) - Keyword extraction - Extract key terms from first 20 lines
- Purpose inference - Infer primary purpose from description/frontmatter
Flag pairs as "potentially overlapping" if:
- Name similarity > 60% (Levenshtein or semantic)
- Shared keywords > 3
- Similar inferred purpose
Step 3: Deep Analysis
For flagged pairs, read full content and analyze:
Overlap Categories
| Category | Description | Example |
|---|---|---|
| Duplicate | Nearly identical functionality | Two commit message generators |
| Subset | One is subset of another | Basic TDD vs full TDD workflow |
| Complementary | Different aspects of same domain | BDD scenarios vs BDD runner |
| Naming Conflict | Same name, different purpose | Rare, flag for rename |
Comparison Dimensions
┌────────────────────────────────────────────────────────────┐
│ Comparison Matrix │
├────────────────────────────────────────────────────────────┤
│ │
│ Dimension Weight How to Compare │
│ ─────────────────────────────────────────────────────── │
│ Purpose 40% What problem does it solve? │
│ Trigger Context 20% When is it invoked? │
│ Output/Action 25% What does it produce? │
│ Dependencies 15% What does it rely on? │
│ │
└────────────────────────────────────────────────────────────┘Overlap Score Calculation
Overlap Score = (Purpose × 0.4) + (Trigger × 0.2) + (Output × 0.25) + (Deps × 0.15)
Score Interpretation:
90-100% → Duplicate (recommend: merge or remove)
70-89% → High overlap (recommend: consolidate)
50-69% → Moderate overlap (recommend: clarify boundaries)
30-49% → Low overlap (recommend: document relationship)
0-29% → Distinct (no action needed)Step 3.5: Cross-Reference Analysis (Before Optimization)
Before recommending merges or removals, check if tools are referenced by other files:
Why This Matters
Tools often have inter-dependencies:
- Commands may reference Skills (e.g.,
see: skill-name) - README files may list available tools
- Documentation may link to specific commands
- Other tools may call or reference the tool
How to Check
For each tool flagged for potential merge/removal, search for references:
bash
# Search for tool name in entire project
grep -r "tool-name" --include="*.md" --include="*.yaml" --include="*.json"
# Common reference patterns to find:
# - Direct links: [link](./tool-name.md)
# - Command references: /tool-name
# - Skill references: skill: tool-name
# - Import/see-also: see: tool-nameReference Categories
| Category | Impact | Action Required |
|---|---|---|
| Documentation | README, guides | Update docs to reflect change |
| Tool References | Other skills/commands | Update calling tools |
| Configuration | mapping.yaml, overlaps.yaml | Update config files |
| Archive/History | Old proposals, reports | No action (historical) |
Include in Report
For each optimization recommendation, add:
markdown
**Cross-References Found:**
- `README.md:466` - Lists /tool-name in command table
- `commands/claude/README.md:91` - Command list entry
- `skills/other-skill/SKILL.md:15` - References as related
**Required Updates:** 3 files need updating before removalStep 4: Report Generation
Generate report at docs/report/tool-overlap-analysis-{YYYY-MM-DD}.md
Report Structure
markdown
# Tool Overlap Analysis Report
Generated: {date}
Project: {project-name}
## Executive Summary
- Total tools analyzed: {count}
- Overlap issues found: {count}
- Optimization opportunities: {count}
## Analysis by Tool Type
### Agents ({count} analyzed)
[Per-type analysis with findings]
### Skills ({count} analyzed)
[Per-type analysis with findings]
### Commands ({count} analyzed)
[Per-type analysis with findings]
### Hooks ({count} analyzed)
[Per-type analysis with findings]
### Workflows ({count} analyzed)
[Per-type analysis with findings]
## Detailed Findings
### High Priority (Score >= 70%)
[Detailed comparison for each high-overlap pair]
### Medium Priority (Score 50-69%)
[Detailed comparison for each moderate-overlap pair]
### Low Priority (Score 30-49%)
[Brief notes on low-overlap pairs]
## Optimization Recommendations
### Merge Candidates
[Tools that should be combined]
### Deprecation Candidates
[Tools that could be removed]
### Boundary Clarification Needed
[Tools that need clearer scope definition]
### Documentation Improvements
[Tools that need better relationship documentation]
## Appendix: Tool Inventory
[Complete list of all discovered tools by type]Writing Style for Report
The report should be written in natural, readable prose:
- Use clear headings and subheadings
- Explain findings in context, not just list data
- Provide actionable recommendations
- Include reasoning for each suggestion
- Use tables for comparisons, prose for analysis
- Maintain professional but accessible tone
Example Analysis Output
markdown
### Skills: custom-skills-git-commit vs commit-standards
**Overlap Score: 78% (High)**
| Dimension | custom-skills-git-commit | commit-standards | Similarity |
|-----------|-------------------|------------------|------------|
| Purpose | Generate commits with custom workflow | Format commit messages | 85% |
| Trigger | "git commit", "commit changes" | "commit message", "format commit" | 70% |
| Output | Git commit executed | Commit message text | 75% |
| Dependencies | Git CLI | None | 60% |
**Analysis:**
Both skills address commit message generation, but `custom-skills-git-commit` includes
the full workflow (staging, committing, pushing) while `commit-standards` focuses
solely on message formatting according to Conventional Commits.
**Recommendation:**
Consider merging `commit-standards` into `custom-skills-git-commit` as the message
formatting module, or clearly document that `commit-standards` is the lightweight
option for users who only need message formatting.Invocation
To run this analysis:
- Ensure you're in the project root
- Invoke: "Analyze tool overlap" or "Run tooling audit"
- Review generated report at
docs/report/
