custom-skills-tool-overlap-analyzer

ツール重複分析

エージェント、スキル、コマンド、フック、ワークフローなど、プロジェクトのツールを分析し、重複や最適化の機会を特定します。各ツールタイプは、同じカテゴリ内でのみ比較します。

ワークフロー

┌──────────────────────────────────────────────────────────────────┐
│                      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. プラットフォーム間で同じ名前のファイルを比較する：

   • 内容が同一（またはほぼ同一）の場合 → 単一のツールとして扱う
   • 分析用に代表を 1 つ選ぶ（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：検出

各ツールタイプについて、プロジェクトをスキャンします：

タイプ	検索場所
エージェント	.claude/agents/、agents/、skills/agents/
スキル	.claude/skills/、skills/、.agent/skills/
コマンド	.claude/commands/、commands/
フック	.claude/settings*.json（hooks セクション）
ワークフロー	skills/workflows/、.agent/workflows/、**/*.workflow.yaml

検出したツールごとに、次の情報を記録します：

• ファイルパス
• 名前（ファイル名またはフロントマターから取得）
• 先頭 20 行（大まかなスキャン用）

ステップ 2：大まかなスキャン（同じタイプ内のみ）

各ツールタイプを個別に、次の項目で比較します：

1. 名前の類似性 - 名前が似ている場合、重複の可能性があります（例：git-commit と commit-standards）
2. キーワード抽出 - 先頭 20 行から主要な用語を抽出
3. 目的の推定 - 説明やフロントマターから主な目的を推定

次の場合、ペアに「重複の可能性あり」のフラグを付けます：

• 名前の類似性が 60% を超える（レーベンシュタイン距離または意味的な類似性）
• 共通するキーワードが 3 個を超える
• 推定される目的が似ている

ステップ 3：詳細分析

フラグを付けたペアについて、全内容を読み込み、分析します：

重複カテゴリ

カテゴリ	説明	例
重複	機能がほぼ同一	2 つのコミットメッセージ生成ツール
サブセット	一方が他方の一部にあたる	基本的な 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/ で確認します