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— 觸發「合併」建議的碰撞分數--disambig-at 0.30— 觸發「消歧義」建議的分數--vague-threshold 0.5— 標記描述過於模糊的門檻--top 12— 列出多少個最高碰撞--format md|json|both
可檢測的問題（問題代碼）
| 代碼 | 嚴重程度 | 意義 |
|---|---|---|
DUPLICATE_TRIGGER | 🔴 | 相同觸發詞被 2 個以上技能聲明（路由錯誤的首要原因） |
DUPLICATE_NAME | 🔴 | 兩個技能名稱相同 |
MISSING_DESCRIPTION | 🔴 | 技能永遠無法可靠觸發 |
HIGH_OVERLAP | 🔴/🟠 | 兩個描述在語義上過於接近 |
VAGUE_DESCRIPTION | 🟠 | 充滿填充詞，缺乏「何時使用」及觸發詞 |
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·傑卡德係數(觸發詞)
+ 0.15·傑卡德係數(領域關鍵字)
閾值：<0.22 低 · 0.22 中 · 0.38 高 · 0.55 嚴重。
完整原理請參閱 references/scoring.md。
AI 代理的工作流程
- 執行引擎，導入使用者的技能路徑 → 讀取 Markdown 報告。
- 總結健康評分、最嚴重的問題群集以及重複的觸發詞。
- 針對每個最佳建議，提出具體的編輯方案：
MERGE（合併） → 草擬一個合併後的描述，建議保留的名稱。ABSORB（吸收） → 指定要刪除的技能，以及其觸發詞移至何處。DISAMBIGUATE（消歧義） → 寫出兩條對應的邊界線（「若要 X，請參閱 Y。」）。
- 提議套用描述改寫（編輯每個 SKILL.md 的前置資料）。
- 重新執行以確認健康評分已改善。
輸出
- 一份 Markdown 報告：健康評分、頂級碰撞、易混淆群集、 重複觸發詞表格、建議、完整問題清單、ASCII 熱力圖。
- 可選的 JSON（
--format json），供 CI 閘道或其他工具使用。
規則
- 引擎是唯讀的——它絕不會編輯技能。改寫操作必須由 AI 代理（你）在使用者同意後執行。
- 未經明確確認，絕不刪除任何技能。
- 在改寫描述時，保留使用者依賴的所有真實觸發詞； 僅移動或消歧義它們——切勿刪除。
更多資訊請參閱 references/methodology.md（演算法）及 references/issue-catalog.md（如何修正各類問題）。