技能包装得越多越快?我装了二十个之后反而变慢了
技能包装得越多越快?我装了二十个之后反而变慢了
Agent Skills 的宣传语很好懂:把你的经验写进一个文件夹,模型按需读取,装得越多本事越大。于是我把一个 macOS 开发技能包整套装了进去——BAMA 这个仓库里正好有 21 个技能,从调研、克隆、脚手架到设计、性能、测试、发版,一条流水线配齐。
装完的第一周感觉是“专业了”。第二周开始感觉不对:回答变啰嗦,动不动就先读三份文档再动手,明明只是改一个 padding,它却把工具栏规范、菜单规范、设置页规范全翻了一遍。
这不是玄学。把仓库摊开数一遍,成本在哪儿一目了然。
先厘清一件不能编的事:我没有测出“慢了 37%”
市面上讲这个题的文章喜欢给一条漂亮的折线图:装 5 个技能响应 1.2 秒,装 20 个变成 4.8 秒。这类数字我没法复现,也不打算编。
原因是模型侧的时间不是一个稳定可观测量:同样的输入,服务端排队、缓存命中、思考长度都会让耗时抖动几倍,你测到的差异大概率来自噪声。而“准确率”更麻烦,它需要一套固定的评测集和人工判分,随手跑十个 prompt 得出的结论没有统计意义。
所以本文只做两件能站住脚的事:
- 把上下文成本算清楚(这部分是确定性的,字节数、字符数可数);
- 把结构性问题指出来(哪些描述在互相抢触发词,哪些链条会导致级联加载)。
至于“感觉变慢”,它对应的机制我会在下面解释:慢的不是模型,是你的会话被塞进了它这一刻并不需要的东西。
21 个技能,常驻的只有 6.4 KB
先看 Anthropic 那篇讲 Skills 的工程文章给出的机制:技能启动时,agent 会把每个已安装技能的 name 和 description 预加载进系统提示,这是渐进式披露的第一层;只有当模型判断相关时,才会去读完整的 SKILL.md,这是第二层;SKILL.md 里再用链接指向同级文件,是第三层。
换句话说,常驻成本 = 所有 description 之和,正文成本 = 被触发的那几次读取。
拿 .claude-plugin/plugin.json 的清单对着数:
| 指标 | 实测值 |
|---|---|
| 登记技能数 | 21 |
21 个 SKILL.md 正文合计 |
117,124 字节 |
skills/ 下全部 Markdown(42 个文件) |
270,231 字节 |
21 条 description 合计 |
6,463 字符(约 1.6k tokens) |
单条 description 区间 |
76 ~ 438 字符 |
description 超过 300 字符的技能 |
12 / 21 |
design/ 阶段占全部 Markdown 的比例 |
153,361 / 270,231 ≈ 56.8% |
第一层的 1.6k tokens,放进 200k 窗口不到 1%。所以“装了二十个技能所以变慢”这个说法,在元数据层面是不成立的。
真正的问题在第二层。
成本不在路标多,在路标指向的路太长
skills/design/mac-design/ 是这套技能里最重的一个目录,74,012 字节:
| 文件 | 字节 | 什么时候会被读 |
|---|---|---|
SKILL.md |
9,922 | 涉及任何窗口、侧边栏、工具栏、菜单、设置页的改动 |
design-rules.md |
17,585 | 做设计评审时 |
patterns.md |
21,291 | 需要可直接抄的 SwiftUI 代码时 |
toolbars.md |
10,652 | 动工具栏时 |
menus.md |
4,952 | 动菜单时 |
settings.md |
4,268 | 动设置页时 |
这个拆分本身是正确示范——AGENTS.md 里写得很清楚:“Inline what every branch needs. Push what only some branches need into a sibling file behind a link.” 把每次都要的东西内联,把只有某些分支要的东西推到同级文件后面。
问题出在调用频率上。skills/ship/improve-loop/SKILL.md 是一个自动循环,一轮跑一个 story:
pick story -> plan -> code -> ./build.sh -> snapshot -> compare -> fix -> commit -> update STORIES.md
它的第 2 步说:story 新增界面或文案,先调 ux-design;第 3 步说:遵循 swift-swiftui 和 mac-design;第 4 步说:遵循 build-and-verify,有逻辑就加测试(test-mac-app)。
于是一个 story 的真实上下文账单是:
| 被拉入的文件 | 字节 |
|---|---|
design/ux-design/SKILL.md |
7,348 |
code/swift-swiftui/SKILL.md |
7,558 |
design/mac-design/SKILL.md |
9,922 |
design/mac-design/design-rules.md |
17,585 |
ship/build-and-verify/SKILL.md |
6,354 |
ship/test-mac-app/SKILL.md |
7,733 |
| 合计 | 56,500 字节(约 14k tokens) |
这 14k 不是每轮都重复付,但它在整个会话余下的每一轮里都在占位。一个里程碑跑十个 story,你的窗口里有 7% 永久被“工具栏按钮该放在哪一列”占着,而这些规则中真正与当前 story 相关的可能只有三行。
这就是“变慢”的第一层体感来源:能用来思考当前问题的空间被历史规范挤走了。模型不是变笨,是每轮都要在一堆无关约束里找相关的那条。
三个隐形损耗
一、选择成本:21 个描述在抢同一个动词
description 不是简介,它是触发器。AGENTS.md 的写作规则第一条就是:
The description is a context pointer: one short sentence on what it is, then "Use when" and one trigger per branch. Front-load the leading word.
按这个标准检查,21 条描述里有 12 条超过 300 字符,而字符越多的描述,“Use when”列出的分支就越多,被误命中的概率就越高。比如 skills/design/design-system/SKILL.md 的 438 字符里塞了四个触发场景:想要品牌色、想让人选颜色、应用超过几个页面、界面开始飘、动画不一致、想要主题或设计 token。
再看路由表本身。skills/start/bama/SKILL.md 的 Design 段落里,design-system 出现了两次:
| An accent or brand color, a color picker, tokens | `design-system` |
| Their own parts and feel, not Apple's: buttons, rows, sidebar, icons | `design-kit` |
| The look of an app they name, or screenshots of one | `design-from-app` |
| One set of colors, radii, motion, and controls for the whole app | `design-system` |
两行不同的用户意图,映射到同一个技能。这不是笔误,而是边界没想清楚的症状:一个技能同时负责“选主色”和“整套 token 体系”,它在描述层面就无法被精确路由。
社区里其实早有共识。掘金那篇 2.7 万阅读的《前端开发必装 Skill 清单》结尾的建议是“不用一次性装太多 Skill,从最常用的 2-3 个开始”;另一篇讲 ask-matt 路由器的长文则把整个体系的入口收敛成一个“我现在处在哪个阶段”的判断,而不是让用户背技能名。方向是一致的:技能数量的增长必须由路由能力的增长来消化,否则就是纯粹的干扰项。
二、误触发:一句“每次构建之后”就是一条级联
三条描述放在一起看,问题很清楚:
layout-grid:Use when building or reviewing a custom page, card, row, form, or sheet, **after every build that touched layout**build-and-verify:Use **after any UI code change**, when a build fails...improve-loop:...building, snapshotting, comparing against reference screenshots, fixing, and committing
“每次碰了布局的构建之后” + “任何 UI 改动之后” + 自动循环,三个时间条件在同一个动作上叠加。改一个 padding,理论上三个技能都该进来。
而实际上,网格检查本来就已经在构建路径里了。skills/start/new-mac-app/template/CLAUDE.md 把这件事写在“Build and check”里:
- Then check the grid: `tools/grid-lint.sh` and `swift tools/check-layout.swift /tmp/__APP_NAME__-shots/*-layout.json`. Both print PASS.
- A change is done when the build has no errors, the grid checks pass, and you looked at the light and dark snapshots.
既然 build-and-verify 的“完成定义”里已经包含了网格检查,layout-grid 就不该再用“每次构建之后”作为自动触发条件。 它需要的是被人显式点名——第一次搭页面时、或者用户说“这儿看着歪了”时。
这就是误触发的代价:多读一份 5 KB 的 SKILL,加上它内部再指向 UI/Grid.swift、tools/check-layout.swift,一次误命中就能多花几 KB 和几次工具调用。注意,工具调用是串行的,多一次读取就多一次往返,这才是“响应变慢”里唯一真实的时钟时间成本。
三、上下文挤占:设计文档吃掉了 57%
design/ 一个阶段 153,361 字节,占全部 Markdown 的 56.8%。这不是设计写得不好——恰恰相反,skills/design/mac-design/design-rules.md 有 17 KB 的检查清单,skills/design/design-kit/parts.md 有 15 KB 的部件规范,都是硬货。
但硬货的布局会决定它是否会被滥用。看一眼 mac-design 的 SKILL.md 开头,7 个链接指向 7 个文件,然后正文里还有 3 处 call the Skill tool with:
- App-wide tokens (colors, radii, motion): call the Skill tool with `design-system`.
- How a feature works and what it says: call the Skill tool with `ux-design`.
- Spacing, alignment, and the checks that catch misalignment: call the Skill tool with `layout-grid`.
一个技能里嵌三个技能调用,加上 7 个同级文件链接,构成了一张扇出很宽的图。扇出宽本身没错,但它要求调用方有很强的自律;而 agent 的自律来自描述里的触发条件,恰恰是前面两条说的最薄弱环节。
更隐蔽的一处:跨阶段引用。skills/code/swift-swiftui/SKILL.md 里写着 <a href="https://link.gitcode.com/i/74264242bc55873bfc5366f334bc93b7" target="_blank">../../design/mac-design/patterns.md</a>,skills/ship/test-mac-app/SKILL.md 里写着 <a href="https://link.gitcode.com/i/dded87f4c1803391a84328f7c125dd97" target="_blank">../../code/os-integrations/recipes.md</a>。这类路径穿越在文件系统上完全合法,代价是代码技能会把设计技能一起拖进来:本来只想知道 Sendable 怎么修,顺手把 21 KB 的 SwiftUI 代码合集也读了。
我的收敛原则:常驻不超过五个
清理之后我留下的是这五个,理由是它们正好构成 improve-loop 每一轮都会碰的最小闭环:
| 常驻技能 | 为什么它在热路径上 |
|---|---|
ux-design |
每个新增界面或文案的 story 都要先定名字、流程、打开方式 |
swift-swiftui |
每个 story 都要写 Swift |
mac-design |
每个 story 都要落到窗口、工具栏、设置页 |
build-and-verify |
每个 story 都要构建、截图、看一眼 |
test-mac-app |
有逻辑的 story 都要加测试或自检 |
对照一下 skills/ship/improve-loop/SKILL.md 第 2~4 步点名的技能,正好就是这五个。热路径上的技能数量,应该由工作流的形状决定,而不是由你能写出多少文档决定。
剩下的 16 个不是删掉,而是降级为显式调用。它们在生命周期的某个时刻一定会用上,只是不该参与“这句话该触发哪个技能”的竞争:
- 阶段入口:
research、clone、app-brief、user-stories、new-mac-app - 专项开关:
os-integrations、performance、agent-cli、improve-architecture - 设计分支:
design-kit、design-from-app、app-icon、design-system、layout-grid - 驱动器:
improve-loop
把冷技能变成“显式调用”,仓库里已经有现成开关
这一步不需要发明新东西。BAMA 自己就在用正确的写法——skills/start/bama/SKILL.md 的 frontmatter:
---
name: bama
description: Build any Mac app. Start here to pick the next skill for a native macOS app.
disable-model-invocation: true
---
配套的 skills/start/bama/agents/openai.yaml:
policy:
allow_implicit_invocation: false
两行配置,就把这个路由器从“模型自动判断要不要用”变成“用户输入 /bama 才用”。21 个技能里唯一不该被自动触发的那个,恰好被正确禁用了。把这个模式推广到上面 16 个冷技能,常驻触发面就从 20 降到 5。
具体可以按这个顺序做:
- 收缩描述。 每条压到 200 字符内,只留一个
Use when分支。design-system的四类场景合并成一句“需要一套贯穿全应用的颜色、圆角、动效 token 时”。 - 删掉重复的路由行。
bama表里design-system出现两次,合并成一条,让一个意图只对一个技能。 - 把时间条件从“之后”改成“当……时”。
layout-grid的描述从after every build that touched layout改为when the user says something looks misaligned, or when setting up a page's grid for the first time。构建后的检查留在build-and-verify的完成定义里。 - 拆掉跨阶段的直接链接。
swift-swiftui里那个../../design/mac-design/patterns.md改成“需要 SwiftUI 代码时调mac-design”,让跳转发生在技能层,而不是文件层——至少路由过一次。 - 一次只装一条路。 README 的 Install 章节自己就警告过:“Pick one route per agent. Two routes install every skill twice.” 手动安装脚本 scripts/link-skills.sh 会把每个技能同时软链到
~/.claude/skills和~/.agents/skills;如果你在同一台机器上又用/plugin install装了一遍,同一份 description 就会进两次提示。支持--skill的安装方式也给了收敛的余地:
npx skills@latest add daveebbelaar/bama --skill=clone
一个反例:specs/ 为什么值得学
仓库里有个东西完全不在技能体系内,却是最省的做法:specs/ 下的 12 份建站计划。README 的说法是“复制一份到空文件夹,然后告诉 agent:用 BAMA 构建 window-snapper.md 里的应用”。
这 12 份文档(window-snapper.md、launcher.md、clipboard-history.md……)常驻成本为零,因为它们不是技能,不会被预加载,只在被复制进项目后才成为上下文。想做一个窗口吸附工具,你付的就是那一份文档的钱,而不是 12 份。
这正是判断“该做成技能还是该做成文件”的分界线:
- 需要模型自己判断何时使用的流程 → 技能,付常驻元数据的钱;
- 只是某次任务要读的资料 → 文件,零常驻;
- 两者都想要的 → 技能里放一个链接指向它,让读取发生在第二层或第三层。
社区里那些“200+ 技能一键接入”的合集之所以让人上头,是因为它们把第三类也做成了第一类。装上之后你的系统提示里会多出两百条描述,而其中真正属于“模型该自己判断”的可能不到十条。
结语:把技能当缓存,而不是当收藏
回头看那个 6.4 KB 的常驻成本,它真的不贵。贵的是它指向的 270 KB 里,有多少会被无差别地拉进每一次会话。
所以“装二十个反而变慢”的准确表述是:装二十个不会让模型变慢,但会让判断变慢——因为触发条件重叠、扇出过宽、时间条件互相级联,每一轮都在为“可能相关”付钱。
收敛到五个不是审美选择,是把热路径压到工作流真实需要的最小闭环,把其余全部转成显式调用或纯文件。判断标准很简单:把技能的 description 全部打印出来,如果其中有两条在回答同一个“什么时候用我”,那就该合并;如果有一条的触发条件里出现了“之后”,那就该改成“当……时”。
技能是缓存,不是收藏。缓存的价值只在于命中率,不在于条目数。