Skill Doctor

Skill Doctor - 给 Skill 做体检的元技能

> 方法论出处：Matt Pocock《Building Great Agent Skills: The Missing Manual》。

🔒 两道同意门（最高铁律，任何情况不得跨越）

1. 门一 · 体检：确认要体检哪个 Skill 后，只读取、只出报告，绝不修改任何文件。
2. 门二 · 改造：出完报告后，必须等用户明确说"改造/优化/动手改"才能动手。用户没点头，就停在报告。

> 报告 ≠ 授权改动。哪怕问题很明显，也先给建议、等用户拍板。改造只碰目标 Skill 目录，绝不动用户其他内容/数据。

首次使用引导（Onboarding · 不知道体检哪个时）

用户第一次用、或问"哪些 skill 该体检"时：

1. 跑分诊扫描：bash scripts/scan-skills.sh [skills目录]（默认 ~/.claude/skills），得到按体检优先级排序的分诊表（行数/是否已拆分/近改天数）。
2. 挑出 🔴🟠 高优先项，结合用户确认的"实际最常用哪几个"（文件系统看不到真实使用频率，必须问用户），给出引导建议：

> "扫描发现你的 A（xxx 行）、B（xxx 行）主文件偏胖，最该体检。你日常最常用哪几个？我给它做一轮体检（只出报告、不改动），要吗？"

1. 用户选定后，进入下面的体检流程。始终止于门一，改造要等门二。

体检流程（Pocock 审稿顺序）

先用 Read 读完目标 Skill 的 SKILL.md（长文分段读完），再按三关顺序审：

关卡 1：谁触发（入口设计）

• 判断该 自动触发（高频、低风险、边界清楚）还是 手动触发（低频、影响大、需人判断时机）。
• 检查 description 触发语是否清楚、是否和 CLAUDE.md/记忆文件等其他地方的真实触发语一致——入口真相要收敛到一处。
• 记住：每个自动触发 Skill 的 description 都常驻上下文，是实打实的 token 成本。

关卡 2：结构（步骤 vs 参考材料）

• 一份 Skill 只该有两类内容：步骤（怎么走）和 参考材料（某步查什么）。
• 找混在主文件里的参考材料（模板/样例/glossary/长清单）——只在某一种情况用的，就该拆到旁边文件，主文件留一句指向。
• 主文件目标：十分钟读完。

关卡 3：删减（deletion test）

• 逐段做 deletion test：删掉这段，我的行为会不会变？不变就是 no-op，该删。
• 三类坏味道：重复（同内容散落多处）、沉积物（没人敢删的旧话）、no-op（看着有用实则不改变行为）。
• 反向保护：能压住一整套做法的 leading 短句/短词（Pocock 的例子如 vertical slice、read first、deletion test）务必留，别误删。

输出：体检报告

按 references/report-template.md 的格式出报告：三关逐项结论 + 优先级排序的建议。判定用词参考 references/checklist.md。

改造（仅在通过门二后）

用户明确同意改造后：先 cp SKILL.md SKILL.md.bak- 备份（尤其高频当红 Skill），再按 Pocock 顺序动手：拆参考材料 > 收敛入口/补触发语 > 合并重复句 > 删 no-op。改完对比主文件行数验证瘦身，并跑一次关键内容存活检查（grep 几个关键词确认没搬丢）。改动只碰目标 Skill 目录，不动任何用户内容/数据。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: isalicema
• Source: isalicema/skill-doctor
• License: MIT

Install and usage instructions live in the source repository linked above.