enmr10/skill-doctor

# skill-doctor 🩺 — 审计您的 Claude Skills 以排查冲突与碰撞 [](LICENSE) [](#requirements) [](#requirements) [](#requirements) 如果您已经安装了超过 20 个 Claude skills，并且发现 Claude 为提示词选错了 **skill**，这就是解决方案。skill-doctor 能够诊断 skills *为何* 会被错误路由，并为您提供准确的修改建议来解决此问题。 ## 问题所在：为什么总是触发了错误的 Claude skill 当某个 skill 的 `description` 与您的意图匹配时，它就会被触发。当两个描述表达了**重叠的**意图时，模型就只能去猜测——并且有时会猜错。由于每个新增的 skill 都会与现有的每个 skill 形成配对，潜在碰撞的数量呈**二次方**增长：20 个 skills = 190 对，67 个 skills = 2,211 对。任何人都无法通过手动来对此进行审计。 **真实示例（3 个 skills，1 个提示词）：** 提示词 *"analyze my competitors"* 可以匹配 `competitors`、`competitor-profiling` **以及** `customer-research` ——这三个 skill 都声称包含 "competitor"（竞争对手）一词。Claude 会从中选择一个，但经常选错，从而导致您得到较差的结果，且找不到明显的原因。 ## skill-doctor 的功能 | 功能 | 详情 | |---|---| | 🔍 **碰撞评分** | 使用 3 信号模型（TF-IDF + 触发器重叠 + 关键词重叠）对每对 skill 进行评分 | | ⚠️ **重复触发器检测** | 找出被 2 个及以上 skills 同时声明的完全相同的触发器短语——这是导致错误路由的头号原因 | | 🧩 **易混淆集群** | 将争夺相同提示词的整个 skill 家族进行分组 | | 🛠️ **可操作的修复建议** | 针对每对 skill 提供 MERGE / ABSORB / DISAMBIGUATE 建议，并附带置信度 | | 📊 **健康评分** | 提供单一的 0–100 分数值，方便您追踪随时间推移的改进情况 | | 🌡️ **热力图 + 报告** | 生成 Markdown 报告、ASCII 热力图以及 JSON 输出，适用于 CI 门控 | | 🚦 **CI 门控** | `--fail-on critical` 将会阻止引入碰撞的 PR | ## 快速开始 skill-doctor 既可以读取 **skills 目录**（`/SKILL.md`），也可以读取 Claude Code 的 **`manifest.json`**。 ``` # 输出 Markdown 报告到你的 console python3 -m scripts /path/to/skills # 保存报告 python3 -m scripts /path/to/skills --out report.md # 用于 CI 的机器可读输出 python3 -m scripts /path/to/skills --format json --fail-on critical ``` 无需安装，无需 pip，无需 API key。纯 Python 标准库实现。 ## 实际效果（对包含 67 个 skills 的库进行的审计） 我们在一个真实安装的包含 **67 个 skills** 的库上运行了 skill-doctor，随后应用了它的建议并重新运行： | 指标 | 调整前 | 调整后 | 变化 | |---|:--:|:--:|:--:| | 健康评分 | 43/100 | 51/100 | ▲ +8 | | 易混淆集群 | 3 | **0** | ✅ 已消除 | | HIGH 严重性重叠 | 5 | **0** | ✅ 已消除 | | HIGH 总问题数 | 9 | 4 | ▼ | 它甚至捕捉到了由于*合并*共享了模板化描述的 skills 而引入的碰撞——这正是大多数 skill-pack 作者最容易犯的错误。 ## 碰撞评分的工作原理 ``` collision = 0.50 · cosine(TF-IDF of descriptions) # semantic overlap + 0.35 · jaccard(trigger phrases) # explicit, deadliest + 0.15 · jaccard(domain keywords) # lexical backstop ``` | 分数 | 等级 | 含义 | |---|---|---| | < 0.22 | LOW | 安全 | | 0.22–0.38 | MEDIUM | 添加边界说明 | | 0.38–0.55 | HIGH | 有时会路由错误 | | ≥ 0.55 | CRITICAL | 需要合并或硬性消除歧义 | 三个独立的信号胜过单一信号：触发器短语重叠能够捕捉到纯 embedding 会平滑处理掉的复制粘贴的触发器列表，而 TF-IDF 余弦相似度则能捕捉到用不同措辞描述相同工作的 skills。完整原理说明见 [`methodology.md`](skills/skill-doctor/references/methodology.md)。 ## 安装 ### 选项 A — Claude Code 插件市场 ``` /plugin marketplace add /skill-doctor /plugin install skill-doctor ``` ### 选项 B — 手动安装 下载最新版本，并通过 **Add Skill** 上传 `skill-doctor.zip`，或者将 `skills/skill-doctor/` 复制到您的 skills 目录中。 ## 环境要求 - Python **3.8+**（仅使用标准库——**零第三方依赖**） - 完全**离线**运行；无需 API key，无需网络调用，无需遥测 - 跨平台（Windows / macOS / Linux）。即使在 Windows 控制台上也能安全输出 UTF-8 字符。 ## 常见问题 ### 为什么 Claude 会触发错误的 skill？ 因为两个或更多的 skill `description` 字段声明了重叠的意图，或者共享了完全相同的触发器短语。模型无法区分它们，所以只能猜测。 skill-doctor 会找出每一个此类重叠，并告诉您如何将它们区分开来。 ### 我该如何审计我的 Claude skills 是否存在冲突？ 将 skill-doctor 指向您的 skills 目录或 `manifest.json`： `python3 -m scripts /path/to/skills`。它会返回一个排好序的碰撞配对列表、重复触发器、易混淆集群以及具体的修复建议。 ### 出现多少个 skills 之后碰撞会成为问题？ 大约 20 个。在 20 个 skills 时会有 190 个潜在配对；碰撞呈二次方增长，因此包含 30 个以上 skills 的库几乎总是至少存在一个碰撞。 ### 它会自动修改我的 skills 吗？ 不会。该引擎是**只读**的。它生成报告和建议；由您（或您的 agent）在审查后应用修改，因此未经您的批准，任何内容都不会被更改。 ### 它支持 Agent Skills 标准 / 跨 agent 的 skills 吗？ 支持。任何带有标准 `SKILL.md` frontmatter（`name` + `description`）的 skill 都受支持，此外还支持 Claude Code 的 `manifest.json` 文件。 ### 我可以在 CI 中使用它吗？ 可以。`--fail-on critical` 会在存在严重问题时以非零状态退出，因此引入碰撞 skill 的 PR 将导致构建失败。 ## 使用场景 - **个人库** —— 阻止触发错误的 skill - **Skill-pack 作者** —— 发布内部零碰撞的 pack - **团队** —— 在共享的 skill 库不断扩大的同时保持其整洁 - **市场 / 审核人员** —— 审查提交内容以确保描述质量 ## 关键词 Claude Code skills · skill 冲突 · skill 碰撞检测器 · 错误的 skill 触发 · 审计 Claude skills · skill 描述重叠 · Agent Skills linter · skill 路由器 · Claude skill 质量 · skill 库健康度 · 触发器短语冲突 · skill 市场 QA ## 许可证 MIT — 详见 [LICENSE](LICENSE)。 *由 Claude 构建。最后更新：2026-06-16。*

标签：Claude, CVE检测, DLL 劫持, Python, 大语言模型, 开发辅助, 无后门, 逆向工具