posts/claude-code-skill-doctor-plugin-eval.md
装了 69 个 Skill,开场就吃掉一万 token
69 个。
这是我这台 Mac 上 ~/.claude/skills 里的 skill 数量。我把它们的 description 字段全拉出来数了一遍,16982 个字符,4346 个汉字加 12636 个别的字符,粗算下来 7500 个 token 左右(token 是模型读文本的最小计价单位,中文差不多一字一个,英文四个字符一个)。
这些字有个特点,不管我今天用不用它们,每开一个新会话它们都在上下文里躺着。模型得先知道自己身上挂了些什么,才知道该不该去拿。再加上 5 个启用状态的插件,常驻又叠了四千多。
也就是说我还没敲第一句话,上下文里已经先塞了一万多 token 的工具说明书。
这笔账我以前是算不清的,只能凭感觉,觉得「装多了是不是有点沉」。这两周不一样了,Claude Code 前后补了三条命令,把这件事变成了可以量的东西。我觉得这是它今年做得最不性感、但对老用户最实在的一次更新。
第一把尺子只回答一件事,谁在白吃
/skill-doctor,官方 changelog 里的原话是「show which loaded skills go unused and what they cost in context, so you can prune them」。
它报的东西很窄,就是本次会话里加载的那些 skill(内置和企业级的不算),谁的 context 成本多少,被调用过几次,从来没被调用过的会被单独标出来,并且直接告诉你去哪儿关。官方文档还补了一句很实用的排序建议,要关就从 context 成本最高的那批开始关。
版本要求是 2.1.252 以上。
顺着这个往下翻 skills 文档,我看到一句以前没注意的话,skill 清单里 description 和 when_to_use 合起来会被截断在 1536 个字符。好家伙,这就是说你写得再长也没用,后面那截压根进不了模型眼里。我顺手数了一下自己这 69 个里最长的那个,ui-ux-pro-max 的 description 是 916 字符,还没顶到上限,算是虚惊一场。
不过它有个前提得先知道,不然一跑就会被自己骗。它统计的是本次会话里的调用情况,你刚开一个新窗口马上跑,所有 skill 都是「从来没被调用过」,这时候按它的名单去关,关掉的全是无辜的。正确姿势是干完一阵活、会话跑到一半再跑,让数据先攒一会儿。
这套机制背后是渐进式披露(progressive disclosure,先只把目录给模型看,模型真要用了再把整篇内容塞进去)。description 是目录,常驻;SKILL.md 正文是内容,按需加载。所以你能砍的常驻成本,其实只有目录那一层,而这层恰好是大家最不上心的一层。
这一把尺子只解决「常驻」这一半的问题。另一半更容易被忽略。
装得多不一定贵,调用才贵
claude plugin details <插件名>,它给的是一份组件清单加一份预估 token 账单,而且账单是拆成两栏的,always-on 和 on-invoke。前者是每次开会话都要交的,后者是这个技能每被触发一次就要交一遍。
我把自己启用的三个插件各跑了一遍,真实回显是这样。
hive,1 个 skill 加 1 个 agent,常驻约 348 token。
understand-anything,9 个 skill 加 10 个 agent,常驻约 1146 token。
vercel,28 个 skill 加 1 个 MCP 服务,常驻约 2624 token。
看到第三行的时候我停下来算了一下。28 个 skill 常驻只要 2624,平均一个不到 100 token,这跟我原本的直觉是反的。我一直以为装一个 28 个技能的大插件会把上下文撑爆,结果它常驻部分便宜得不像话。

贵的地方在另一栏。同一份回显里,understand 这个技能一次触发预估 18.5k token,file-analyzer 13.3k,architecture-analyzer 8.9k,tour-builder 8.4k,vercel 那边的 ai-gateway 7.8k、shadcn 7.3k。

所以这两栏的关系,我自己是当成月租和打表来理解的。常驻是月租,装着就交,不用也交;on-invoke 是打表,上车才跳字。真正该清理的不是「装得多」的插件,而是那种常驻一直占着、可表从来不跳的。
而这批,正好就是 /skill-doctor 圈出来的那批。两条命令是配着用的。
最值钱的是那个无插件基线
第三条是 claude plugin eval,9 月 11 号才进的 changelog。
它的设计里有一个决定,我觉得比命令本身值钱,有点子牛逼。官方文档写得很直白,光凭高分不能告诉你插件是否有帮助,因为 Claude 可能在没有插件的情况下也能做得很好。
所以默认每个用例会跑两遍。一遍加载你的插件,叫 with-arm;一遍什么插件都不加载,叫 without-arm。你拿到两个分数,WITH 和 W/OUT,它们的差值 Δ 才是你这个插件真正贡献的东西。如果一个用例带插件 1.0、不带插件也 1.0,那让它通过的不是你的插件。
每个用例默认跑 3 次,两个 arm 就是 6 次运行,因为一次非确定性的 agent 运行基本说明不了什么。
评分器有 6 种。regex、tool_used、tool_order、file_exists 这四种是从运行记录和磁盘文件里算出来的,零成本;llm 和 baseline 要调评判模型,会进你的账单。套件不用手写,claude plugin eval init 会读你的插件、问你什么样的结果算好、提议用例和评分器、试跑一遍,然后把文件写出来。
文档里有一段值得单独拎出来。它说最常见的第一个发现是 Δ 接近零,同时用例里那个 tool_used: Skill 的评分器失败,说的是 Claude 在自然措辞上没有选择你的技能。
这句话我得替它翻译一下。不是你的技能不行,是用户按人话提问的时候,你的 description 根本没把它勾起来。这个结论对写 skill 的人来说有点扎,但极其有用,因为绝大多数人调的是 SKILL.md 正文,而真正决定它有没有机会上场的是 frontmatter 里那两行描述。以前这事儿只能靠瞎猜,现在它是一个能看见的数字。
进 CI 的写法官方也给了现成的。
claude plugin eval . \
--trust-plugin \
--json results.json \
--threshold 0.8 \
--model claude-sonnet-5 \
--judge-model claude-haiku-4-5 \
--no-publish \
--max-cost-usd 20
--threshold 默认是 1.0,任何用例低于它命令就退出 1,所以照自己的标准调。退出码分得挺细,0 是全过,1 是分数不达标或用例加载失败,2 是部分运行(撞了成本上限或者凭证被拒),130 是被中断,143 是被 CI 超时干掉。两个模型都要钉死,否则下次模型换代,分数一掉你会当成自己插件的回归,白查半天。
说个我自己踩到的版本坑。这个命令官方要求 2.1.269 以上,我这台还停在 2.1.263,--help 打得出来、参数列得挺全,真跑就一行回显。
`plugin eval` is currently in early access
--trust-plugin 这个参数它也还不认识,直接 unknown option。所以别像我一样看着 help 以为能用了,先 claude update。
今天就能做的三步
第一步,开个会话跑 /skill-doctor,只看两列,从来没被调用过的,和 context 成本最高的。交叉出来的那批就是第一波该关的。
第二步,对每个启用的插件跑一次 claude plugin details,把常驻高、可你回想一下这一个月压根没触发过的整个插件关掉。别一个个 skill 抠,插件级的开关更省事。
第三步,如果你自己或者团队在维护 skill,找一个最常用的场景,claude plugin eval init 起一个套件,先只挂免费的那四种评分器跑起来,把 Δ 看一眼。Δ 如果贴着零,去改 description,别改正文。
还有一种情况是不该删的,得说清楚。有些 skill 属于低频高价值,一年用两三次,用上的那次能救命,而它的常驻成本可能只有几十个 token。为这几十个 token 去折腾不划算,删完下次现找更费时间。真正值得动手的是那种常驻上千、又连着几个月一次都没触发过的整插件,它才是账单上那块肉。量出来的意义就在这儿,不是让你把工具箱清空,是让你知道哪几件东西压舱压得最狠。
几个坑提前说。--ablation none 只跑单臂,成本减半,但它的绝对分数跟双臂模式不可比,别混着看趋势。默认 3 次运行别省,单次运行噪声很大。长输出别交给 llm 评分器判,它读得越长判得越飘,官方建议用 regex 去评文件内容。有一条特别容易翻车,eval 的每次运行都是隔离的,你的用户设置、CLAUDE.md、个人 MCP 服务器、其他插件全都不加载,插件要什么配置得自己塞进去。还得记着,每次运行和每个评判评分器都是真实的模型调用,算你的额度和账单,不是白跑的。
写到这儿我想起来,做 agent 这两年,我们大部分精力都花在给它加能力上,加工具、加技能、加记忆。很少有人停下来问一句,它身上现在到底挂了多少东西,哪些是真在使劲,哪些只是压着舱底。船装得越满,不一定走得越远,有时候只是吃水更深。
所以想问问屏幕前的你,你那台机器上现在装了几个 skill?跑完 /skill-doctor 之后,从来没被调用过的有几个?