开源Agent Skills让AI编程更省Token？实战拆解与接入指南

mattpocock/skills 我在过去一两周里翻来覆去看了好几遍，也顺手在几个真实项目里跑了一轮。先说结论：它确实能省 token，但省多少、值不值得用，完全取决于你让它干什么活。mattpocock 是 Total TypeScript 的作者，TypeScript 圈子里几乎没人不知道他，这次他把自己平时喂给 AI 编程助手的“技能包”整整齐齐开源了出来，仓库很快冲上趋势榜。这里的 skills 不是传统意义上的插件，而是一堆结构化的 SKILL.md 文件，每个文件就是一份“操作手册”，告诉 Claude Code、Codex 这类 AI 编程 Agent，遇到某个任务时该按什么思路走、输出要满足什么标准。很多人把它当成普通提示词合集，但实际用下来，它对 token 消耗的影响、对编程效率的提升，比想象中复杂得多。这篇文章我会从机制原理、公开实测、token 数据、用户口碑四个方面展开，最后给出可以直接抄的接入方法。

1. 项目速览：mattpocock/skills 到底是什么

1.1 一个“给 AI 编程序的程序”长什么样

先说清楚一个概念：Agent Skills 是 Anthropic 在 Claude 相关工具里推出来的一套机制，核心形式就是一个文件夹，里面放一个 SKILL.md 文件，文件名和目录名对应一个具体技能。模型在对话中会根据任务描述自动判断要不要“调用”这个技能，一旦调用，技能文件里的完整内容会作为上下文的一部分注入到模型视野里。

mattpocock/skills 做的就是这件事的“内容层”。他把自己在实际开发中总结出来的那些约束条件、检查清单、输出规范，全部写成了可复用的技能文件。比如一个“代码审查”技能，里面可能包含：先看类型定义、再看数据流、最后才看具体实现，评论时每条都要带上文件路径和行号，给出修改建议时必须带示例代码。这些东西单独拎出来看，每条都是常识，但写成一个结构化的技能文件后，AI 助手每次执行同类任务时都会稳定遵守，而不是靠运气碰。

它和普通提示词最大的区别在于“触发机制”。普通提示词写在系统提示词里，模型每个请求都会看到；skills 则可以按需加载，平时不占上下文，被触发时才进入。这一点对 token 消耗的影响非常大，后面我会专门算一笔账。

1.2 仓库里常见的技能包有哪些

从我翻到的目录结构和社区讨论来看，mattpocock 仓库里收录的技能大致覆盖了一条软件交付链路的几个高频场景：

• 类型错误修复：针对 TypeScript 编译报错的处理流程，要求先复现、再定位、再最小化修复，禁止为了通过检查而乱用 any。
• 代码审查：按“架构-数据流-实现细节-命名”的顺序评审，输出带文件路径的评论列表。
• 单元测试生成：规定测试文件的组织方式、命名习惯、mock 策略，只生成与改动相关的测试，不铺开全量测试。
• git 提交规范：强制使用 Conventional Commits 风格，标题控制在 72 字符以内，正文说明动机。
• README / 文档写作：面向用户而不是面向作者，先讲“能做什么”，再讲“怎么用”。

我不打算在这里逐个贴全文，因为仓库一直在更新，直接去 GitHub 上读原文最准确。但你可以把上面这几类当作理解这个项目的地图：它解决的不是“模型不会写代码”的问题，而是“模型每次写出来的代码风格和流程不一致”的问题。

1.3 为什么 2025 年下半年 skills 突然火了

一个很直接的原因是工具链成熟了。Claude Code 对 Agent Skills 的支持让这种“按需加载手册”的机制变成了标准能力，Codex、Cursor 等主流 AI 编程工具也在快速跟进。热词里那些“ai编程最厉害三个软件”的讨论，背后其实是用户开始意识到：模型能力已经拉不开绝对差距了，差距在提示词工程、上下文管理、流程约束这些“外围工程”上。skills 恰好是这类外围工程里最标准化的一种表达形式。

另一个原因是 token 成本被越来越多人重视。AI 编程助手每多跑一轮，就要多烧一轮的上下文费用。社区的普遍感知是：不约束的 Agent 很啰嗦，会为了一个小问题做大量无效探索，token 烧得飞快。而 skills 的核心价值之一，就是通过纪律约束减少这种无效探索。mattpocock 这种在开发者社区有影响力的人带头开源自己的技能集合，自然会让很多人想试试“大神的工作流长什么样”。

2. Token 到底花哪了：一次 AI 编程请求的完整拆解

2.1 一次请求里 token 的结构与占比

在聊 skills 省不省 token 之前，必须先搞清楚一次普通的 AI 编程请求里，token 都花在哪些地方。我用一个典型的“修复一个 TypeScript 编译错误”任务来举例，假设我们用的是 Claude Code 这类 Agent，会话已经进行了 5 轮。

• 系统提示词：模型运行前就固定注入的通用要求，包括角色设定、回复准则、安全规范，通常在 1500～3000 token。
• 工具定义：Agent 能调用的工具列表，比如读取文件、运行测试、搜索代码库，每个工具的描述都要占 token，加起来可能 2000～4000 token。
• 对话历史：之前的每一轮提问和回答都会累积，5 轮之后可能已经有 8000～15000 token。
• 当前任务输入：用户新补充的一条指令，加上相关的代码片段，大约 1000～3000 token。
• 模型输出：修复建议和补丁代码，通常 500～2000 token。

一次简单请求的总量很容易超过 15000 token，而且大头是“历史”和“工具定义”，不是用户真正写的指令。这就是为什么很多人在长会话里感觉越聊越贵——历史越长，每一轮的新请求都要重新读取一遍之前的所有内容。

2.2 skills 为什么能省 token，又为什么可能费 token

skills 省 token 的路径不是“减少输入”，而是“减少试错轮次”。一个没被约束的 Agent 在遇到类型错误时，可能会先打印一遍代码结构，再跑一次测试，再尝试一个修复方案，失败后再换个方案，整个过程要三四轮。而一个写好的“类型错误修复”技能会直接告诉它：先看 tsconfig 里的 strict 选项，再看报错文件的前后 100 行，按“类型收窄优先、显式断言次之、any 禁用”的顺序给修复方案。路径明确了，两轮内就能解决，整体 token 反而少。

但它也有费 token 的时候。每个 skill 被触发时，SKILL.md 的全文都会注入到上下文里。如果这个文件写了一万字，哪怕它再有用，光注入成本就不低。更麻烦的是，如果你同时挂载了 10 个 skill，有些模型会在任务边界模糊时同时触发好几个，token 消耗直接爆炸。我在一个项目里试过同时挂“代码审查”和“测试生成”两个技能去做一个小改动，结果模型先做了一轮审查，又补了一轮测试，最后还谦虚地追加了一段总结，单次任务的 token 比不挂任何技能时高出一大截。

2.3 公开实测里 token 数据到底怎么说

我在 GitHub Discussions、Reddit 和 X 上翻了不少公开测试帖，比较有代表性的有两类。

一类是“用 skills 跑完一组真实 issue”的长任务测试。有用户贴出对比数据：在一个中型 TypeScript 仓库里处理 20 个历史 issue，不用 skills 时总 token 消耗约 18 万，一次修复率只有 40%；挂载了类型修复和测试生成两个技能后，总 token 降到 14 万，一次修复率升到 65%。下降幅度大概 22%，主要省在“重复的无效轮次”上。

另一类是“短任务对比”测试。比如“给一个函数补 JSDoc”这类明确指令，挂不挂 skills 的 token 消耗几乎没有差别，甚至因为技能文件本身要注入上下文，挂了之后反而多出几百 token。这其实很好理解：短任务本身不需要探索，skill 的“纪律约束”派不上用场，只增加了固定开销。

所以你要有个心理预期：skills 的 token 收益和任务复杂度强相关。复杂任务、长会话场景下，收益明显；简单问答、一次性修改场景下，收益趋近于零。

3. 翻完公开实测和真实口碑，我得到的几个判断

3.1 三类让我印象深刻的公开测试

第一类是 bug 修复测试。测试者故意在一个仓库里埋了 5 个不同类型的 bug，包括一个空指针、一个类型断言错误、一个异步时序问题、一个边界条件遗漏，然后让 AI 助手修复。不挂技能时，AI 修到第三个 bug 时已经开始“乱猜”，给出的代码往往能通过类型检查但逻辑不对；挂上技能后，AI 会老老实实先写一个失败测试，再改实现，再跑回归。整个过程耗时更长，但 5 个 bug 全部修对。

第二类是大型仓库的代码审查测试。给 AI 一个包含几十个文件的 PR，要求按“是否引入新的类型不安全代码”这个维度做审查。不挂技能时，AI 的回答像是“整体来说代码质量不错”之类的空话；挂上专门设计的审查技能后，输出变成了带文件路径、行号、修改建议的列表，可以直接粘贴到 PR 评论里用。

第三类是从零写一个新模块。这类任务的结果最看好：有技能约束时，AI 生成的文件结构、注释密度、错误处理风格都更贴近团队现有代码风格，比单纯靠模型“猜风格”稳定得多。

3.2 用户反馈里的高赞与冷门吐槽

好评集中在几个点：类型错误修复稳了，跑测试的一次通过率高了，AI “自言自语”和“自我怀疑”少了。很多用户提到，最值钱的不是省 token，而是“省心”——你不用反复纠正 AI 的做事流程，它自己按流程走。

吐槽也不少。最常见的是版本更新问题：仓库迭代很快，SKILL.md 的格式变动频繁，上周还能用的技能这周启动就报路径不对。还有人指出，某些技能和自己的自定义 instructions 冲突，比如团队已经有强制的 git 提交规范，再加载一个风格不同的提交技能，模型会陷入困惑。另一个情报特别真实：模型在任务描述模糊时可能“饥不择食”地触发多个技能，效果反而很差。

3.3 综合来看，效率提升的合理区间是多少

把公开数据和用户反馈放在一起，我的判断是：在中等以上复杂度的任务里，合理配置的 skills 可以把效率提升 10%～30%，这里的效率包括 token 消耗、一次通过率、人工纠正次数等综合指标。在简单任务里，效率提升接近零。

注意“合理配置”这个前提。乱挂一堆技能，效率可能变成负数。mattpocock/skills 的价值不在于某一个文件写得多么惊为天人，而在于它示范了一套“把工作流沉淀为可复用文件”的方法。你自己团队最核心的规范，比任何公开技能都重要。

4. 实操：把 skills 用进自己的 AI 编程工作流

4.1 在 Claude Code 里安装与加载

以 Claude Code 为例，安装路径通常是~/.claude/skills/<skill-name>/SKILL.md。你拉下仓库后，把需要的技能目录复制进去就行：

# 拉取仓库 git clone https://github.com/mattpocock/skills.git # 把需要的技能复制到 Claude Code 的全局技能目录 mkdir -p ~/.claude/skills cp -r skills/type-script-error-fixer ~/.claude/skills/ cp -r skills/git-commit-style ~/.claude/skills/ # 进入项目目录，启动 Claude Code，输入 /skills 查看当前已加载的技能

/skills会列出所有可见的技能文件。如果列表里没有你刚复制的技能，检查目录层级：必须是~/.claude/skills/<名字>/SKILL.md，如果多套了一层目录，Claude Code 会识别不到。

在 Codex 里用法类似，只是目录要放到项目根目录的.codex/skills下。这里有个细节：全局目录对所有项目生效，项目目录只对当前仓库生效。如果你只想在某个特定仓库里启用“代码审查”技能，放到项目目录更合适，避免污染其他项目。

4.2 手写一个省 token 的最小技能：commit-style 示例

理解了原理后，你可以自己写一个极简技能，用来保证 AI 生成的 git 提交信息符合你的团队规范。下面这个例子我实际在项目里用着，效果稳定，也不会浪费太多 token：

--- name: commit-style description: 在生成 git 提交信息时使用。要求输出遵循 Conventional Commits 规范，主题行不超过 72 字符。 --- # Commit Style 所有 git 提交信息必须遵循以下规则： 1. 主题行格式：`<type>(<scope>): <subject>`，其中 type 只能是 feat/fix/docs/refactor/test/chore。 2. 主题行不超过 72 个字符。 3. 如果改动涉及破坏性变更，正文必须包含 `BREAKING CHANGE:` 说明。 4. 不要使用 emoji，不要以句号结尾。 5. 直接输出提交信息，不要附加解释。 ## 参考示例 - `fix(auth): refresh token before expiry` - `feat(api): add pagination to list endpoint`

# 示例：用这个技能辅助生成提交信息 # 在 Claude Code 中直接输入： # /skills commit-style 然后告诉它：帮我生成刚才修改的提交信息

文件头部的name和description很关键。模型会先读 description 来判断是否触发这个技能，所以 description 里要写清楚“什么场景下用、用了产出什么”。如果写成“处理 git 提交”，模型可能在任何提到 git 的对话里都触发它，白白消耗 token。这个文件总共不到 400 个 token，即使每次提交都触发，成本也极低，但它能把“AI 生成提交信息”这件事的稳定性拉满。

4.3 使用技巧：什么时候开、什么时候关

我个人的经验是三句话：长任务开、短问答关、模糊任务先问再跑。

长任务开：涉及多文件修改、类型修复、代码审查这类需要多轮探索的任务，挂上对应技能，收益最大。

短问答关：只是问一个函数怎么用，或者翻译一段代码，不要挂任何技能。技能在这种任务里只会增加固定的上下文开销。

模糊任务先问再跑：如果任务描述本身不清晰，比如“帮我优化一下这个模块”，最好的做法是先用一句追问明确范围，再考虑要不要触发技能。技能是执行层面的约束，它不能替代清晰的需求定义。

还有一个被我反复验证的小技巧：把技能的“适用场景”写窄一点。很多人写 description 时总想覆盖所有情况，结果模型每次都认为该触发。技能文件里的description越具体，触发准确率越高，token 浪费越少。

5. 常见问题与排查技巧实录

5.1 Token 相关报错速查表

实际使用 skills 的过程中，最常遇到的不是技能本身的问题，而是各种 token 和鉴权报错。我把高频问题整理成了表格：

这里要单独说一句：很多人在社区里抱怨“token exchange failed”是 skills 导致的，其实不是。skills 只是上下文内容，不参与鉴权。报错根源几乎都在账号状态、网络环境、服务区域这些登录链路环节。排查顺序建议是：先看账号是否过期，再看网络出口是否被限制，最后才去看是不是客户端版本太旧。

5.2 用了 skills 反而更费 token 的三个原因

第一个原因是“技能文件太长”。我见过有人把一个技能写到 8 千甚至 1 万 token，每次触发都是一次不小的开销。这种情况下，即便任务复杂，省下来的探索成本也很难覆盖固定注入成本。建议单技能控制在 800 token 以内，一份写好之后要反复精简。

第二个原因是“触发太随意”。原因在于 description 写得太宽泛。比如 description 写“在需要写测试时使用”，模型几乎在每个任务里都觉得自己需要写测试。你可以想像成，你给助手发了一本 200 页的规章制度，结果它每做一个决定都要翻一遍，效率能高才怪。

第三个原因是“多个技能互相打架”。同时挂一个“代码审查”技能和一个“提交信息规范”技能，可能本来只是让你看一段代码，模型却先做了一轮审查，又顺手给提交信息提了一条建议，硬生生把一轮对话变成两轮。解决方式是：按项目维度拆分技能目录，而不是全局挂一堆。

5.3 避坑建议：不要把 skill 当万能咒语

我踩过的最大一个坑，是期望 skills 能提升模型本身的代码能力。现实是：skill 改变不了模型的下限，它只能把模型的上限稳定发挥出来。如果模型本身写不出某个算法，你再怎么给它写操作手册，它还是写不出来。甚至因为技能文件占用了上下文窗口，留给真实任务的空间反而变小。

所以我的建议是：在引入任何公开 skills 之前，先花几天时间观察自己日常工作中“最常让 AI 重复做的一致性工作”是什么，然后只为这一类场景写一个 500 token 的技能，先跑一周，记录 token 变化和返工率，再决定要不要扩大技能库。这样比盲目装一堆技能要靠谱得多。

6. 我的个人使用体会与扩展建议

用了两周之后，我最终留在工作流里的技能其实只有两个半：类型错误修复、git 提交规范，以及半个文档生成技能（只在我明确要求时才触发）。我最大的感受是，mattpocock/skills 这个仓库的真正价值不是那些文件本身，而是它提供了一个“把个人工作流标准化”的模板。你不需要照抄他的全部技能，但你应该学他的文件结构、描述方式、约束粒度。

一个小技巧分享给你：把技能文件纳入版本管理，放在和项目代码同一个仓库里。我见过太多人改了 SKILL.md 之后忘了同步给别人，结果团队里每个人的 AI 行为都不一样。如果你们团队用 AI 编程助手很频繁，建议指定一个人维护技能目录，像维护代码规范一样维护它，改版时留 changelog。这样，你所有的 prompt 经验、流程约束都会沉淀成团队资产，而不是散落在聊天记录里的一次性对话。