个人 Skill 库的卫生

它替你干掉什么 · 装法 · 第一条能跑的用法

它替你干掉的是「凭印象清理」：你记得哪些 skill 常用，但记不住每个占多少 token、上次什么时候被调用。

# ① 官方体检（Claude Code v2.1.252+，终端里跑）
/skill-doctor
# 交互会话里报告开在 /plugin 管理器的 Stats 页；-p 非交互模式直接打印文本

# ② 官方开关：高亮某个 skill，按 Space 循环状态，Esc 保存
/skills
# 写进 .claude/settings.local.json，效果等价于：
{ "skillOverrides": { "legacy-context": "name-only", "deploy": "off" } }

# ③ 插件的 skill 不归 skillOverrides 管，单独看
claude plugin details <name>   # Always-on 行 = 每个会话固定多出的 token

/skill-doctor 的报告按 skill 列出上下文成本和调用次数，标出从未被调用过的并告诉你去哪关；官方建议从成本最高的那批开始。它还会列出最近没用过的插件——/plugin 的 Installed 页也有一个 Not used recently 分组和每个插件的 Last used 行。

机制：skill 多了，到底坏在哪

① 清单预算：最少用的先「哑」

官方文档：清单的字符预算按模型上下文窗口的 1% 计；溢出时从你调用最少的 skill 开始丢描述。名字还在，但关键词没了，Claude 就很难自动匹配到它。/context 的 Skills 行显示的是预算裁剪后的大小，/doctor 会估算清单成本和最大贡献者。想放宽可设 skillListingBudgetFraction（如 0.02）——但这是把问题往后推，不是解决。

② 同名遮蔽：没有报错

同名 skill 的优先级是企业 > 个人 > 项目：~/.claude/skills/deploy 和仓库里的 .claude/skills/deploy 同时存在时，/deploy 跑的是你个人那份——队友改了项目版，你却一直用旧的，而且不会有任何提示。插件 skill 带命名空间 /插件名:skill名，所以不撞，但会出现两个功能相近的条目抢同一类请求。

③ 正文常驻：调过一次就一直在

skill 被调用后，正文作为一条消息留在对话里，后续轮次不重读文件。自动压缩时，每个 skill 只保留前 5,000 token，所有 skill 合计 25,000 token，按最近调用顺序填——一次会话里调了太多 skill，早的那些压缩后会整份丢掉。

真实用法与边界：命名、去重、废弃、合并回 prompt

命名一致：先让机器挑错

Agent Skills 规范规定 name 只许小写字母、数字和连字符，最长 64 字符，必须与父目录同名；用 skills-ref 的 skills-ref validate ./my-skill 校验。官方《Skill authoring best practices》建议用动名词（processing-pdfs）并点名要避免的：helper、utils、tools 这类含糊名，以及同一个库里风格不一致。

去重：两层检测

• MindiveLabs/skill-doctor（社区，MIT）——注意它和官方 /skill-doctor 同名但无关。它扫个人、项目目录里的 SKILL.md，报七类冲突：同名遮蔽、触发短语碰撞、语义重叠、主动建议互抢、状态文件冲突、子集包含等；默认只读，--fix 才会把冲突项挪进 ~/.skill-doctor/trash/。装法：/plugin marketplace add MindiveLabs/skill-doctor → /plugin install skill-doctor@skill-doctor。别装的时候：据 GitHub 仓库页（2026-10 读取）只有 4 星，会注册两个后台 hook——按 Skill 30 的清单先读一遍再装；别用 git clone 方式装，否则它会顶替官方的 /skill-doctor（见文末）。
• skill-creator 的 Description Optimization——两个 skill 抢同一类请求时，给留下的那个写 20 条触发评测，其中一半是「该不触发」的近邻请求；scripts.run_loop 按 60/40 切训练与留出集、每条跑 3 次、最多迭代 5 轮，按留出分选最佳描述。

废弃：用状态阶梯，不要直接删

skillOverrides 的四个状态天然就是废弃流程：on → name-only（只留名字，腾出描述预算）→ user-invocable-only（Claude 看不见，你还能 /name）→ off（全隐藏）→ 观察一阵没人想起它，再删目录。插件走 /plugin disable / /plugin uninstall。skill 内部过时的段落，官方建议挪进一个折叠的 「Old patterns」节，而不是混在正文里。

跨工具的库：一份源

同时用几个 agent 的人，最容易出现「三份副本、改了一份」。Vercel 的 skills CLI（据 GitHub 仓库页，2026-10 读取约 3.3 万星）默认用符号链接把各 agent 目录指向同一份拷贝：npx skills list 看装了什么、npx skills update 升级、npx skills remove <name> 卸载。别用的时候：只用 Claude Code 一个工具——内置的 /skills 和 /plugin 已经够了。

判据：一个 skill 该留、该降级、还是合并回 prompt

• 几乎每个会话都会调用、正文又很短 → 它其实是常驻事实，搬进 CLAUDE.md（这是我的经验线；官方的分界是 CLAUDE.md 放每轮都该在的上下文，skill 放具体任务）。
• 只有你会手动敲 /name → user-invocable-only，别让它的描述占清单。
• 和另一个 skill 触发重叠 → 合并成一个，留下的那个跑一遍触发评测。
• /skill-doctor 显示从未调用、成本又高 → off；一个月没想起来就删。
• 只剩一两句规则 → 写回你的 prompt 或 CLAUDE.md；必须每次成立的，写成 hook。

代价与替代品

① 「从未调用」不等于「没用」

有些 skill 一季度只用一次，但那一次很关键（比如发版检查清单）。/skill-doctor 只看调用次数，不看价值。这类 skill 降到 user-invocable-only 比直接删稳妥。

② 降级会改变行为

降到 name-only 后描述没了，原本靠关键词自动触发的场景会失效。改完要验：官方给的办法是挑几个真实提示，在新会话里分别开、关这个 skill 各跑一遍对比；插件 skill 用 claude plugin eval，它会自动带一个「不装插件」的基线。

③ 工具链本身也要卫生

社区去重工具、跨 agent 管理器都是新依赖：会注册 hook、会建自己的目录、会更新。为了清理 10 个 skill 再装 2 个工具，先算一下账。