Skill-Doctor
诊断技能库。找出描述竞争相同提示的技能，然后修复路由问题。
何时运行
- 你安装了很多技能，并且“总是触发错误的那个”
- 在发布技能包之前（捕捉审核者会遇到的重叠问题）
- 添加技能后（它是否与现有技能冲突？）
- 对不断增长的库进行定期健康检查
输入
将引擎指向以下任一位置：
- 技能目录（
<root>/<name>/SKILL.md），或 - Claude Code manifest.json（
skills-plugin/.../manifest.json）
如何运行
引擎位于此文件旁边的 scripts/ 目录中。零依赖（Python 3.8+ 标准库）。
# 从包含此 SKILL.md 的目录运行：
python3 -m scripts <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 | 🔴 | 两个技能同名 |
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 行 |
评分如何运作（一句话）
collision = 0.50·cosine(描述的TF-IDF)
+ 0.35·jaccard(触发短语)
+ 0.15·jaccard(领域关键词)
区间：<0.22 低 · 0.22 中 · 0.38 高 · 0.55 严重。
完整原理请参见 references/scoring.md。
代理工作流程
- 运行引擎对用户的技能路径 → 读取 Markdown 报告。
- 总结健康评分、最严重的集群和重复触发词。
- 针对每条重要建议，提出具体修改：
MERGE→ 草拟一份合并后的描述，建议保留的名称。ABSORB→ 指出要删除的技能及其触发词转移到哪里。DISAMBIGUATE→ 写两条镜像分界线（“如需 X，请见 Y。”）。
- 提供应用描述重写（编辑每个 SKILL.md 的 frontmatter）。
- 重新运行以确认健康评分有所改善。
输出
- Markdown 报告：健康评分、最严重重叠、易混淆集群、 重复触发词表格、建议、完整问题列表、ASCII 热力图。
- 可选 JSON（
--format json）用于 CI 门控或其他工具。
规则
- 引擎只读——它从不编辑技能。重写由代理（你）仅在用户批准后应用。
- 未经明确确认，不得删除任何技能。
- 重写描述时，保留用户依赖的每个真实触发短语； 只能移动/消歧——不能丢弃它们。
算法请参见 references/methodology.md，每种问题类型的修复方法请参见 references/issue-catalog.md。