custom-skills-tool-overlap-analyzer

工具重叠分析器

分析项目工具（Agent、技能、命令、钩子、工作流）的重叠情况和优化机会。每种工具类型只与自身类别中的工具进行比较。

工作流

┌──────────────────────────────────────────────────────────────────┐
│                      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  │     └──────────┘   │
│                         └─────────────────┘                     │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

步骤 0：去重（跨平台副本）

许多项目会将相同的工具分发到多个平台目录中（例如 agents/claude/、agents/opencode/、skills/agents/）。这些是有意分发的副本，不属于冗余问题。

分析前，按以下方式去重：

1. 识别平台目录：

   • */claude/、*/opencode/、*/gemini/ → 特定平台目录
   • skills/agents/ → 可能是 agents/*/ 的镜像

2. 比较各平台上同名文件：

   • 如果内容相同（或几乎相同）→ 视为单个工具
   • 分析时保留一个代表文件（优先选择 claude/ 中的文件，或最先找到的文件）

3. 记录去重情况：

   Deduplicated: code-architect.md
   - agents/claude/code-architect.md (analyzed)
   - agents/opencode/code-architect.md (skipped - identical)
   - skills/agents/code-architect.md (skipped - identical)
   

重要：跨平台副本不属于重叠问题。只比较每种类型中唯一的工具。

步骤 1：发现

扫描项目中的每种工具类型：

类型	搜索位置
Agent	.claude/agents/、agents/、skills/agents/
技能	.claude/skills/、skills/、.agent/skills/
命令	.claude/commands/、commands/
钩子	.claude/settings*.json（hooks 部分）
工作流	skills/workflows/、.agent/workflows/、**/*.workflow.yaml

对于发现的每个工具，记录：

• 文件路径
• 名称（取自文件名或 frontmatter）
• 前 20 行（用于粗略扫描）

步骤 2：粗略扫描（仅在同一类型内进行）

分别针对每种工具类型，使用以下方法比较工具：

1. 名称相似度——名称相似可能表示存在重叠（例如 git-commit 与 commit-standards）
2. 关键词提取——从前 20 行提取关键词
3. 用途推断——根据描述/frontmatter 推断主要用途

满足以下条件时，将工具对标记为“可能重叠”：

• 名称相似度 > 60%（Levenshtein 距离或语义相似度）
• 共享关键词 > 3 个
• 推断出的用途相似

步骤 3：深入分析

对于已标记的工具对，阅读完整内容并进行分析：

重叠类别

类别	描述	示例
重复	功能几乎相同	两个提交消息生成器
子集	一个是另一个的子集	基础 TDD 与完整 TDD 工作流
互补	同一领域中的不同方面	BDD 场景与 BDD 运行器
命名冲突	名称相同，用途不同	少见，标记以供重命名

比较维度

┌────────────────────────────────────────────────────────────┐
│                  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 = (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)

步骤 3.5：交叉引用分析（优化前）

建议合并或删除工具之前，检查其他文件是否引用了这些工具：

为什么这很重要

工具之间通常存在相互依赖：

• 命令可能会引用技能（例如 see: skill-name）
• README 文件可能会列出可用工具
• 文档可能会链接到特定命令
• 其他工具可能会调用或引用该工具

如何检查

对于每个被标记为可能合并/删除的工具，搜索其引用：

# 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-name

引用类别

类别	影响	所需操作
文档	README、指南	更新文档以反映变更
工具引用	其他技能/命令	更新调用该工具的工具
配置	mapping.yaml、overlaps.yaml	更新配置文件
归档/历史记录	旧提案、报告	无需操作（历史记录）

在报告中包含

对于每项优化建议，添加：

**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 removal

步骤 4：生成报告

在 docs/report/tool-overlap-analysis-{YYYY-MM-DD}.md 生成报告

报告结构

# 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]

报告写作风格

报告应使用自然、易读的文字撰写：

• 使用清晰的标题和子标题
• 结合上下文解释发现，而不只是罗列数据
• 提供可执行的建议
• 说明每条建议的理由
• 使用表格进行比较，使用文字进行分析
• 保持专业且平易近人的语气

分析输出示例

### 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.

调用

运行此分析：

1. 确保当前位于项目根目录
2. 调用：“Analyze tool overlap”或“Run tooling audit”
3. 查看生成的报告：docs/report/