skill-doctor は何をしますか？
スキルライブラリを診断します。同じプロンプトを奪い合う説明文を持つスキルを見つけ、ルーティングを修正します。
実行するタイミング
- 多くのスキルをインストールしたが「間違ったスキルがよく発動する」場合
- スキルパックを公開する前（レビュアーが遭遇する衝突を事前にキャッチ）
- 新しいスキルを追加した後（既存のスキルと衝突しないか確認）
- 増え続けるライブラリの定期的な健全性チェック
入力
エンジンに以下のいずれかを指定します：
- スキルディレクトリ（
<root>/<name>/SKILL.md形式） - Claude Code の manifest.json（
skills-plugin/.../manifest.json形式）
実行方法
エンジンはこのファイルの隣にある scripts/ に配置されています。依存関係ゼロ（Python 3.8+ 標準ライブラリのみ）。
# この SKILL.md が置かれているディレクトリから実行：
python3 -m scripts <path-to-skills-or-manifest> # Markdownレポート
python3 -m scripts <path> --format json --out report.json # 機械出力
python3 -m scripts <path> --fail-on critical # CIゲート（終了コード1）
よく使うオプション：
--merge-at 0.55— MERGE（統合）推奨となる衝突スコア--disambig-at 0.30— DISAMBIGUATE（明確化）推奨となるスコア--vague-threshold 0.5— この値よりあいまいな説明をフラグ--top 12— 上位の衝突数の表示--format md|json|both
検出する問題（問題コード）
| コード | 重大度 | 意味 |
|---|---|---|
DUPLICATE_TRIGGER | 🔴 | 同じトリガーフレーズが2つ以上のスキルで使われている（誤ルーティングの最大の原因） |
DUPLICATE_NAME | 🔴 | 2つのスキルが同じ名前を持つ |
MISSING_DESCRIPTION | 🔴 | スキルが確実にトリガーされない |
HIGH_OVERLAP | 🔴/🟠 | 2つの説明文が意味的に近すぎる |
VAGUE_DESCRIPTION | 🟠 | 抽象的な表現が多く、「use when」やトリガーがない |
NAME_DIR_MISMATCH | 🟠 | 名前とディレクトリ名が一致しない（仕様違反） |
BAD_NAME_FORMAT | 🟠 | 名前が小文字・ハイフンのルールに違反している |
DESC_TOO_SHORT / DESC_TOO_LONG | 🟠/🟡 | 文字数が40〜1024の範囲外 |
NO_BOUNDARY | 🟡 | 「Xについては、<他のスキル>を参照」という相互参照がない |
BODY_TOO_LONG | 🔵 | SKILL.md本文が500行を超えている |
スコアリングの仕組み（一行で）
衝突 = 0.50・コサイン類似度(TF-IDF(説明文))
+ 0.35・Jaccard係数(トリガーフレーズ)
+ 0.15・Jaccard係数(ドメインキーワード)
バンド：<0.22 LOW · 0.22 MEDIUM · 0.38 HIGH · 0.55 CRITICAL。
詳細は references/scoring.md を参照。
エージェント向けワークフロー
- 実行：ユーザーのスキルパスに対してエンジンを実行 → Markdownレポートを読む。
- サマリー：健全性スコア、最悪のクラスタ、重複トリガーを要約する。
- 各上位推奨に対して、具体的な修正案を提示する：
MERGE→ 統合後の説明文のドラフトと、残す名前を提案。ABSORB→ 削除するスキル名と、そのトリガーの移動先を指定。DISAMBIGUATE→ 2つの境界線（「XについてはYを参照」）を記述。
- 適用を提案：説明文の書き換えを申し出る（各SKILL.mdのフロントマターを編集）。
- 再実行：健全性スコアが改善したことを確認する。
出力
- Markdownレポート：健全性スコア、上位衝突、混同しやすいクラスタ、重複トリガー表、推奨事項、全問題リスト、ASCIIヒートマップ。
- オプションでJSON（
--format json）：CIゲートや他のツール向け。
ルール
- エンジンは読み取り専用です — スキルを編集することはありません。書き換えはユーザーの承認後にエージェント（あなた）が適用します。
- 明示的な確認なしにスキルを削除しないでください。
- 説明文を書き換える際は、ユーザーが依存している実際のトリガーフレーズはすべて保持し、移動や明確化のみ行い、削除はしないでください。
詳細なアルゴリズムについては references/methodology.md を、各問題タイプの修正方法については references/issue-catalog.md を参照してください。