addyosmani/agent-skills 完全教程：25 个技能、6 个阶段、9 个命令，哪一半跟你有关
它是目前同类里唯一一个按开发阶段编号、并且在仓库里自带考试的技能包。这两点让它和你看过的 Superpowers、Matt Pocock 那几套确实不一样——但第三点差异才是关键：它也是同类里最依赖你逐阶段点头的一个。这篇把它的六个阶段、九条命令、三层结构、四个评审人格全拆开，也把「它要求你点头」这件事说透。
📅 更新于 2026-09-16
本文校对于 addyosmani/agent-skills @ v0.6.9 · 官方源：https://github.com/addyosmani/agent-skills
0030 秒速览：三句话、起手动作、以及你手上必须有什么
如果只记三句话
① 它是「按开发阶段组织的技能包」，不是提示词合集。25 个技能被分进六个阶段——定义（DEFINE）、计划（PLAN）、构建（BUILD）、验证（VERIFY）、评审（REVIEW）、上线（SHIP）——九个斜杠命令（就是在对话框里打一个斜杠 / 开头的短命令，像 /learn 那样）一一对应。你敲 /spec，等于同时启动「写规格」（spec：动手之前先把「要做成什么样、什么算完成」写下来）这个阶段需要的那个技能。
② 它和另外几套最大的差别是「自带考试」。仓库里有一整套 evals/ 目录和 CI 脚本，专门检查「这个技能的说明写得对不对、会不会在该触发的时候触发」。同类里没有第二家这么干。它的原话是：如果一个技能没被正确触发，应该去改技能的说明，而不是改考题。
③ 25 个你大概只会用到 5 到 6 个，而且它要求你逐阶段点头。仓库自己写在入门文档里：「不要一次性把 25 个都装进上下文，按阶段加载」。而每一个阶段都是一个需要你说「可以」的检查点——这一点对你是好是坏，见 10。
起手动作：读完 60 秒内，你要做的第一件事
先别装。打开下面这个地址，往下滚到 Common Rationalizations（常见借口）那张表，读三分钟：
# 在浏览器里打开（这是一个纯文本网页，不用装任何东西）
https://github.com/addyosmani/agent-skills/blob/main/skills/test-driven-development/SKILL.md为什么是「先别装」？这不是我替你省事——是作者自己给的入门建议。他在官方博客里写的是：推荐先从「把技能当规格来读」入手，而不是先装运行时（「运行时」指真正在你机器上跑起来的那部分程序——这里是说，先别急着把插件装进 AI 助手）。理由很直接：这套东西的价值一半在那些文字里，装不装是第二步。
做这个动作之前，你手上必须有什么
这一栏比上面那一栏重要——它让你在花时间之前就知道这篇对你有没有用。
不用好，不用能跑，半途而废的正好。这篇的绝大部分内容，只有你手里有这样一个项目的时候才落得了地——因为它的每个阶段都在问「你这次改动的规格是什么」，而你手上没有正在改的东西时，这个问题是空的。
如果你手上没有这样的项目，这篇仍然可以读——但请把 08 怎么装 整节当成「先知道有这回事」，而不是「今天要照做」。没有可套的东西时，装了它只会多出一套没地方用的规则。
先给一组数字，后面才谈细节
idea-refine 178 行，最长的 security-and-hardening 524 行。01它是什么：先破三个错想
先说三个最容易先入为主的印象。这三个都错，而且错得很有代表性——把任何一个当成对的，后面整篇都会读歪。
错想一：它是一份「提示词合集」
提示词合集（网上常说的「prompt 库」）是被动的：你想用哪条，得先知道它存在、再手动复制粘贴过去。技能包不是。
一个技能文件里写的不是「一段好用的话」，而是一套带顺序的流程：什么时候该用它、按哪几步走、每一步的产出是什么、做完之后要拿什么证据证明真做完了。最后这一条是关键区别——每个技能文件都以一张验证清单结尾，里面每一条都要求能拿出证据（测试跑过的输出、构建的结果、运行时的数据）。
「Passing tests are evidence, not proof.」（测试通过是证据，不是证明。）以及贯穿整个包的一句：「'Seems right' is never sufficient.」（「看起来对」永远不算数。）
这句话决定了整个包的性质：它不承诺让 AI 变聪明，它要求 AI交作业。
错想二：装了它会变聪明
它不换模型，不加任何私有接口，不改你的 AI 助手本身。作者自己的说法是：
「The tooling matters less than the workflow underneath.」（工具不重要，底下那套流程才重要。）
他还补了一句更狠的：你可以用他的版本，也可以自己造一个——他真正想让人抄走的是那套流程，不是这 25 个文件。
所以它是装在你的 AI 助手外面的一层，不是装在里面的一层。类比一下：它像是给一个手脚很快但没规矩的人配了一份岗位手册。人没变，手上还是那双手，但他现在会先问清楚要做什么、做完会主动给你看证据。
这个类比到这里就不准了：岗位手册是人自己会读、会记、会遵守的；而 AI 读完就忘——所以这一整套东西的成败，全押在「它这一次有没有真的读到这一段」上。这正是后面 06 自带考试 那一节要解决的问题。
错想三：/ship 是一键上线
/ship 不部署任何东西。它做的是：同时叫三个不同专业的评审员来看这次改动，然后把三份报告合并成一个「能不能发」的决定，外加一份回滚方案。
它会给出 GO / NO-GO（发 / 不发）两种结论，并且明确规定：只要任何一位评审员报出「严重」级别的问题，默认结论就是 NO-GO——除非你本人明确说「我知道这个风险，还是要发」。
它的名字里带「发」，实际干的是「发之前的最后一道闸」。
那么，一句话版本是什么
它是一份用 Markdown 写成的开发流程手册，按六个阶段编号，装在你的 AI 编程助手外面，让它按资深工程师的顺序做事、并且在每一步交出证据。
它在磁盘上长什么样
下面这张表是 2026-09-16 实测的目录清单，不是从文档里抄的。行数是我自己数的，可以复核。
| 目录 / 文件 | 里面是什么 | 数字（实测）· 你什么时候会碰到它 |
|---|---|---|
skills/ | 25 个技能，每个一个文件夹，里面一个 SKILL.md | 25 个。你实际会读的就是这里。这是全包的核心，其他目录都是围着它转的。 |
agents/ | 4 个「评审人格」的说明书（见 04） | 4 个。你不会主动打开它，但 /ship 会替你调用它们。 |
references/ | 7 份共享清单：「做完的定义」、测试模式、安全检查表、性能清单等 | 7 份。技能流程走到某一步时会去引用它们。这也是单技能安装会踩的坑，见 08。 |
.claude/commands/ | Claude Code 用的 9 个斜杠命令 | 9 个。你敲的 /spec /build 就是从这儿来的。 |
evals/ | 「考试」：25 个用例 + 25 组夹具（先摆好的样板项目，让 AI 在上面做题）+ 判分脚本 | 25 个用例。它在持续集成（CI，指每次提交代码时服务器自动跑一遍检查）里跑，你一般看不到，但它是第 06 节的主角。 |
docs/ | 16 份文档：入门、各工具安装、对照、迁移手册 | 16 份。08 怎么装 全部内容都来自这里。 |
hooks/ | 会话开始时自动跑的小脚本 | 6 个。装了插件就会生效，你不用管它，但要知道它在。 |
02一个技能文件里写了什么（这是它能起作用的原因）
这一节是整篇最值得慢读的地方。因为你可以不装这个包，但这里面的结构是可以直接抄走的——作者本人也是这么希望的。
打开任意一个 SKILL.md，结构几乎都一样，长这样：
name：小写连字符的名字，必须和文件夹名一模一样。
description：先说这个技能「做什么」，再写「什么时候用」。这两行是 AI 唯一会自动看到的部分（见下面「渐进式披露」）。
一两句话。为什么这个技能存在、不照它做会出什么问题。
触发条件清单。而且通常会明确写出「什么时候不用」——这一栏比正面清单更值钱，因为它防止技能在不该用的时候抢戏。
编号的步骤。文档里对「具体」有一条硬标准：写「跑 npm test 并确认全部通过」是对的；写「确保测试是好的」是错的。
全包最值钱的一张表。下面单独讲。
「出现这些现象，说明这个技能正在被违反」。既是给 AI 自检用的，也是给你评审时对照用的。
出口条件。每条都要能拿得出证据。这是整个技能「什么时候算做完」的唯一定义。
「常见借口表」：这张表值一整篇文章
它解决的问题是：AI 想偷懒的时候不会说「我偷懒」，它会给你一个听起来很合理的理由。作者对这件事有一句原话，是整篇最值得抄走的一句：
「Anti-rationalization tables are pre-written rebuttals to lies the agent hasn't yet told.」
翻译过来：这些表是预先写好的反驳，用来对付 agent 还没说出口的谎。不是等它偷懒了再骂它，是在它还没偷懒之前，就把那个借口和对应的反驳一起摆在它眼前。
作者说这是他最希望别的团队抄走的一点。下面是从两个技能里逐字挑出来的真实条目——左栏是 AI 会说的话，右栏是官方给的反驳：
| AI 会说的借口（原文） | 官方给的反驳（原文） | 为什么这条对你的处境特别有用 |
|---|---|---|
| "It works, that's good enough." （能跑就行了） | "Working code that's unreadable, insecure, or architecturally wrong creates debt that compounds." （能跑的坏代码会产生会复利的债。） | 这是你最容易点头的一句。它听上去像务实，实际是把今天的判断赊到明天。 |
| "We'll clean it up later." （以后再清理） | "Later never comes. Require cleanup before merge, not after." （「以后」不会来。要求在合入之前清理。） | 你的那十几个项目，基本都死在这句话上。 |
| "AI-generated code is probably fine." （AI 写的应该没问题） | "AI code needs more scrutiny, not less. It's confident and plausible, even when wrong." （AI 写的代码需要更多审查。它错的时候也一样自信、一样像对的。） | 这句直接命名了你的处境——错的和对的在当下长得一模一样。 |
| "I'll commit when the feature is done." （功能做完再一起提交） | "One giant commit is impossible to review, debug, or revert. Commit each slice." （一个巨大的提交无法评审、无法调试、无法回退。每一小片就提交一次。） | 这条你已经会了（你说过 git 你用）。列在这里是为了让你看清：同一张表里的其他条目，你没会的还很多。 |
| "I'll squash it all later." （之后再压成一个提交） | "Squashing destroys the development narrative. Prefer clean incremental commits from the start." （压扁会毁掉开发过程的叙事。） | 解释为什么「先乱提交、最后整理」不是个省事的路。 |
| "The refactor makes it cleaner." （重构让它更干净了） | "Relocating complexity isn't reducing it. If the reader still holds the same number of concepts, the structure didn't improve." （把复杂度换个地方不是减少它。如果读者要装的概念个数没变，结构就没变好。） | 这条是「AI 说它优化了，我怎么验证」。判据很妙：数你要同时记住的概念有几个。 |
为什么 description 里不许写流程
这一点设计得很细，值得单独说。官方的规范文档里写着一条规则：技能说明里不要概括流程步骤。理由写得很直白：
「Do not summarize the workflow — if the description contains process steps, the agent may follow the summary instead of reading the full skill.」
意思是：如果简介里写了步骤，AI 可能照着简介做，而不去读后面的完整流程。简介变成了一份劣质的替代品。
这背后是整套包的一个机制，叫渐进式披露——字面意思就是「一点一点地给」：
- 会话开始时，AI 只看到 25 个技能的名字和那两行简介，看不到正文；
- 当它判断某个技能和当前任务相关时，才把那个技能全文读进来；
- 正文里引用的清单（比如安全检查表），只有走到那一步才去读。
这么做只有一个目的：省 token（token 是 AI 处理文字时的计量单位，你可以理解成「AI 的阅读量和算钱的单位」）。如果把 25 个技能全文一次性塞进去，那是 7,780 行——既贵，又会把真正相关的那几条淹掉。
如果简介是 AI 决定「要不要读这个技能」的唯一依据，那么简介写得不好 = 技能等于不存在。这就是为什么这个包要专门写一套程序来测简介（下一节 06）。
这条推论对你自己写技能同样成立——本站那篇《定制自己的 Skill》里也撞到过同一件事。
03六个阶段、九个命令：它的骨架
这是这个包最显眼的地方：它不按「技能类型」分类，而是按一次开发从左到右经过的阶段来编号。作者画的图是这样的：
九个命令，一张表看完
你实际动手时面对的是这九个命令。下表的第三列是我加的——它回答「这个命令交付的东西是什么」，因为那才是你能验收的对象。
| 命令 | 对应阶段与技能 | 它会给你留下什么可验收的东西 |
|---|---|---|
/spec | DEFINE · 规格驱动开发 | 一个 SPEC.md 文件，六个部分：目标、命令、项目结构、代码风格、测试策略、边界。作者的原则是「Spec before code」（先规格后代码）。 |
/constraints | DEFINE · 约束驱动开发 | 一个 CONSTRAINTS.md 文件，写着这个项目「好到可以发」的具体数字和检查命令。见 09。 |
/plan | PLAN · 任务拆解 | tasks/plan.md 和 tasks/todo.md：拆成小块的任务清单，每个带验收标准和依赖顺序。 |
/build | BUILD · 增量实现 + 测试驱动 | 一块代码 + 一个提交。原则是「One slice at a time」（一次只切一片），做完就停。 |
/build auto | BUILD · 同上，但跑完整个计划 | 同样的东西，只是中途不停。它去掉的是「你在任务之间手动敲回车」，不是验证——每个任务照样要过测试、照样单独提交。 |
/test | VERIFY · 测试驱动开发 | 先写一个会失败的测试，再写让它通过的代码。原则是「Tests are proof」（测试是证明）。 |
/review | REVIEW · 代码评审与质量 | 一份五轴评审报告（正确性、可读性、架构、安全、性能），每条发现带严重级别标签。 |
/code-simplify | REVIEW · 代码简化 | 把能读但过于复杂的代码改简单，行为完全不变。原则是「Clarity over cleverness」（清楚胜过聪明）。 |
/ship | SHIP · 上线与发布 | 一份 GO / NO-GO 决定 + 一份回滚方案（回滚方案 = 万一发出去发现问题，具体怎么退回到上一个版本）。三个评审人格并行跑，然后合并（见 04）。 |
/webperf | SHIP · 网页性能审计 | 一份 Core Web Vitals 报告（网页性能的核心指标：加载速度、视觉稳定性、交互响应）。只对网页项目有效。 |
/build auto：唯一一个「放手」模式，它的刹车在哪
这是全包唯一一个「批准一次、然后自己跑完全部任务」的命令，也是最需要看清细节的一个。它的官方说明里有六条硬性停止条件——遇到就必须停下来问你，不许自己往前冲：
它只会在三个固定位置找规格文件：仓库根目录的 SPEC.md、docs/SPEC.md、或 spec/ 目录下的文件。README 不算，随便一份文档也不算。找不到就停下，让你先跑 /spec——它的原话是「do not invent requirements」（不许自己发明需求）。
跑一次 git status --porcelain，如果有计划文件之外的未提交改动，必须停下问你。理由：自动模式的每个任务都要单独提交，如果混进无关的本地改动，「随时能干净回退」这个保证就破了。
它把完整计划摆出来，等你一个明确的肯定答复。而且规定了什么叫肯定：「approve」「go」「yes」算；「看着还行」「我觉得可以」不算——那被当成没批准。
转入调试流程，不再往下走。
不许自己拍板。
它列举的清单是：权限 / 认证改动、破坏性的数据迁移、支付、删除、部署、任何碰到密钥的操作——以及「任何你不能用 git revert 撤销的事」。
/build auto 不是「不用管了」，是把「批准」这个动作从每个任务之间，挪到了开始之前的一次。次数少了一次次点，但每一次判断的分量变重了——你要批准的是一整份计划，不是下一步。
04三层结构：技能、人格、命令，这三个最容易混
这个包里有三种听起来差不多的东西，而它们的职责完全不同。分不清它们，你在读文档时会一直觉得「这几份文件在说同一件事」。
| 层 | 它回答什么问题 | 举例 · 谁调用它 |
|---|---|---|
| 技能（Skill） | 这件事怎么做 | code-review-and-quality（五轴评审怎么做）。由人格或命令在内部调用。你不会直接叫它。 |
| 人格（Persona） | 这件事谁来看，以及他要交什么格式的报告 | code-reviewer（资深工程师视角）。由命令调用，也可以你直接点名。 |
| 命令（Command） | 这件事什么时候做，入口在哪 | /ship、/review。由你敲出来。 |
官方文档里把这三层压成一句口诀：技能是「怎么做」，人格是「谁」，命令是「什么时候」。而负责把这三样串起来的人，是你。
四个评审人格分别是谁
| 人格 | 扮演的角色 | 你什么时候会叫它 / 它替你看什么 |
|---|---|---|
code-reviewer | 资深主任工程师 | 合入前的五轴评审。它的标准是一句话自问：「一个主任工程师会批准这个吗？」 |
security-auditor | 安全工程师 | 查漏洞与威胁模型：常见的十大安全风险、密钥处理、权限、依赖库的已知漏洞。 |
test-engineer | 测试工程师 | 分析这次改动的测试覆盖，指出缺的是正常路径、边界情况、出错路径还是并发场景。 |
web-performance-auditor | 网页性能工程师 | 只看网页项目的性能指标。注意：它由 /webperf 单独调用，不在 /ship 的并行队伍里——见 14 的一处文档不一处。 |
为什么规定「人格不能调用人格」
官方文档里有一条明确的禁例，还把反面例子画了出来：不要造一个「调度人格」，专门负责决定该叫哪个别的人格。
你 → 调度人格 → 它判断「这次需要评审」→ 叫评审人格 → 评审人格返回结果 → 调度人格转述给你 → 你
官方给的三条理由：纯转发、没有专业价值；多加两个转述环节，信息会丢，成本还翻倍；你自己就知道要评审，直接敲 /review 就行。
/ship 同时叫三个人格，每人交一份只属于自己的报告，没有谁依赖谁，最后由主会话合并成一个决定。
官方说这是它唯一认可的编排模式。判据是「子任务之间真正互相独立」——有共享状态或有先后顺序的，就不能并行。
还有一条硬约束，在 Claude Code 上是平台强制的：子代理不能再生成子代理。所以「人格不能调用人格」在那边不只是规矩，是物理上做不到。
05它到底在堵哪个洞：AI 默认走最短路径
前面讲的都是「它长什么样」。这一节回答「为什么需要它」——也是全篇最能解释「为什么同类里它值得看」的一节。
作者的原话：它会交代码、宣布胜利、然后走开
「It produces code, declares victory, and moves on.」（它产出代码、宣布胜利、然后继续下一个。）
他认为 AI 这么做不是因为它笨，是因为它在按奖励信号做事：奖励指向「任务完成」，不指向「任务完成而且设计文档还在」。而那些没被奖励的部分——写规格、把改动切小、留下证据、拒绝合入无法验证的东西——正是资深工程师和初级工程师真正的分界线。他的说法是，这些是「the parts that don't show up in the diff」（不会出现在改动比对里的那部分工作）。
所以这个包的做法，他的原话是「把资深工程师的脚手架重新装回去」（bolt the senior-engineer scaffolding back on）。
为什么「写一份规则文件」不管用
你可能会想：这些道理写进 CLAUDE.md 不就行了？作者明确说这是行的，但有一句很准确的话形容了绝大多数规则文件的失败方式：
「The rules are essays.」（那些规则是散文。）
他的意思是：一份写满道理的规则文件，读起来像一篇文章。文章的问题是它没有出口条件——读完你不知道自己算不算做到了。
技能反过来：每一步都有产出，最后有一张「拿证据来」的清单。「不许跳过测试」是散文；「先贴出这个失败的测试的输出，再去改代码」是流程。
它藏了哪些「资深工程师的判断」
这个包还有一处值得单独看：它把一批有名字的工程原则，直接嵌进了 AI 要照着走的步骤里。不是当成知识介绍，是当成动作要求。下面这些名词你不需要记住，但值得知道它们各自在管什么：
| 原则（原名） | 一句话解释 | 它被放进哪个技能、管什么 |
|---|---|---|
| Hyrum 定律 | 只要你的接口有足够多的使用者，那么所有能被观察到的行为——包括 bug——都会有人依赖。 | 接口设计。所以改接口比你想的更危险。 |
| Beyoncé 规则 | 如果你喜欢某个行为喜欢到要依赖它，你就该给它写个测试。 | 测试。用来判断「这件事该不该有测试」。 |
| 测试金字塔 80/15/5 | 测试分三层，越底层的越多：单元测试（只测一小段代码）占约 80%，集成测试（测几块拼起来）约 15%，端到端（从用户点下去到结果出来整条链走一遍）约 5%。 | 测试。防止全写成一跑半小时的端到端测试。 |
| Chesterton 的栅栏 | 看到一堵不知道为什么要有的栅栏，先别拆——先搞清楚它为什么在那儿。 | 代码简化。这是「删代码」前的必答题。 |
| Shift Left（左移） | 把检查尽量往流程的早期挪——越早发现越便宜。 | CI/CD（持续集成，见下）。 |
| 主干开发 | 大家都在同一条主线上小步提交，而不是各自开长期分支。 | 版本控制。配套的要求是改动控制在约 100 行。 |
| 代码即负债 | 每一行留着的代码都是一笔要还的债，删代码和写代码同样重要。 | 废弃与迁移。整套包里专门有一个技能讲「怎么安全地删东西」。 |
一句值得单独抄下来的话
「Big PRs don't get reviewed; they get rubber-stamped.」
翻译：大的改动不会得到评审，只会得到盖章（PR = pull request，就是「我改好了，请求把这些改动合进主分支」的那个东西）。不是没人看，是看了也看不出来。这也是为什么这个包把「约 100 行」写成了硬性建议——它不是在追求整洁，是在保住「评审」这件事本身还有意义。
还有一句，解释为什么长任务比短任务更危险：
「The longer the run, the more the senior-engineer scaffolding has to be enforced rather than suggested.」
翻译：跑得越久，「资深工程师那套脚手架」就越必须被强制，而不是被建议。
06唯一一个自带「考试」的技能包：三层 eval
这是它和另外几套最实在的差别，也是第三方评测里被说错最多的一处（见 14）。
先解释这个词：eval 是 evaluation 的缩写，这里是「评估 / 考试」的意思——用一组预先写好的题目，去测「这个技能到底会不会在该触发的时候触发、会不会真的改变 AI 的行为」。它测的不是 AI 聪不聪明，是这些技能文件本身写得好不好。
三层，成本从零到花钱
| 层 | 它考什么 | 什么时候跑 · 花不花钱 |
|---|---|---|
| 第一层：结构 | 文件格式对不对——开头那两行有没有、名字和文件夹名是否一致、必填部分在不在、命令和技能是否一一对上。 | 每次提交都跑。不花钱。 |
| 第二层：触发与路由 | 「路由」在这里就是「分派」的意思——你说了句话，系统该把它分给哪个技能。它考两件事：① 用户真会说的话，能不能排到这个技能前面；② 两个技能的说明会不会长得太像、互相抢活。 | 每次提交都跑。不花钱。 |
| 第三层：行为 | 真的让一个 AI 按这个技能去做一件事，然后逐条对照它有没有做到技能承诺的那些动作。 | 手动触发。要花 token。 |
第二层考的是什么，为什么它最难写
第二层是这个包自己说「别人没有」的部分。它做两件很具体的事：
每个技能都配了一组「真实用户会打出来的话」。系统算一遍，看这个技能能不能排在最前面。而且明令不许作弊：写题目时必须模仿用户真实的说话方式，不许照抄技能自己的简介——文档原话是「that's gaming the eval」（那是在应付考试）。
每个技能还要配几条「不属于我」的话，并指名它应该归谁。系统会检查那个正确的技能确实排得比我高——这样反向题才真的在考路由，而不是随便找一个都不匹配的句子糊弄过去。
系统算两份技能简介的文本相似度。到 75% 就报错，到 50% 就警告。
它的诚实之处在于自己承认这一层只是近似：用的是词频统计（把每份简介拆成词、算权重、比谁更接近），它判不了语义——那是第三层的事。但官方说它抓得住真实世界里最常见的那两种触发故障：简介里缺了用户真正会说的词（该触发却没触发），以及简介写得太宽（不该它抢的它抢了）。
系统维护着一个分数，叫「排第一的比例」。CI 里的门槛设成 95（不是 100，留一点余量，免得改一个无关的说明就让 CI 红）。
而官方的规矩是：「Raise the floor as routing improves; never lower it to make a regression pass.」——分数只能往上抬，绝不许为了让一次退步过关而下调门槛。
另外有一句同样值得抄：「如果一个技能没被触发，去改那个技能的简介，不要改题目。」
第三层：它是怎么判分的
第三层会真的开一个一次性的仓库，把预先准备好的项目文件放进去、提交成基线，然后让 AI 按技能去做，最后用一个「判分器」逐条检查它的执行记录（包括它调用了哪些工具、改了哪些文件）。
里面有两个细节能看出作者想清楚了：
- AI 是用「允许改文件」的模式跑的，不是被拦住然后只会嘴上说「我改了」——否则考的就是它会不会说话，不是它会不会做事。
- 它的执行记录被当成「不可信数据」围起来，再喂给判分器。因为那些记录里可能藏有诱导判分器的话（AI 自己写的内容也算）。
另外，对那些「纪律类」的技能，题目里专门加了三种压力场景：时间紧张、已经投入了很多（沉没成本）、以及对方是权威——用来验证「当题面本身就在劝你跳过流程时，这套流程还站得住吗」。
诚实地补一句：第三层不进 CI
有评测说这个包「没有任何评估或遥测」（遥测 = 自动收集你在用它的过程中产生的数据，用来看它到底有没有被真用上）。这句话对了一半——它确实有一整套评估，但只有前两层是每次提交都自动跑的，第三层（真跑真判分的那层）要手动触发、要花 token。
所以准确的说法是：它对「结构」和「触发」有持续的自动检查，对「行为」有工具但没做到持续。两边各对一半，你按这个理解就行。详见表 14。
07和 Superpowers、Matt Pocock 差在哪（你手上可能已经装了别的）
这一节对你尤其重要：本站已经写过 Superpowers 和 Matt Pocock 各两篇。所以真正的问题是——你已经有前两套了，这套要不要？
先说来源：这个仓库自己写了一份对照文档（docs/comparison.md），态度难得地公道——它明说「三个都好，都值得学」，还主动声明不比较星标数，理由是「各个博客引用得乱七八糟、还每周都在变」。这一点我核实过，是真的乱，见 14。
三方对照（第三列是我补的）
| 维度 | agent-skills（本篇） | Superpowers ／ Matt Pocock | 对你的实际意义 |
|---|---|---|---|
| 组织原则 | 按开发阶段分：定义 → 计划 → 构建 → 验证 → 评审 → 上线 | Superpowers 是一条流水线（头脑风暴 → 计划 → 子代理执行 → 评审）；Matt Pocock 是按类别的工具箱 | 阶段式的好处是「不会漏掉某一环」；代价是每一步都要你确认。 |
| 覆盖面 | 最宽：从想点子一直到上线、监控、废弃旧系统 | Superpowers 深而窄（专攻构建内环）；Matt Pocock 偏「需求问清 + 写」 | 这是它最实在的优势。你缺的那几环（安全、上线、删旧代码）只有它覆盖。 |
| 自主程度 | 每个阶段一个检查点，默认全程要你点头 | Superpowers 刻意减少中途打断，让你交出去、回来看结果 | 这条对你最重要，见下面单独讲。 |
| 自带评估 | 有，三层（见 06） | Superpowers 有它自己的「压力测试」方法论，但评估套件已挪到另一个仓库；Matt Pocock 仓库里没有 | 如果你在意「装的技能到底会不会被用上」，这是它独有的。 |
| 工具覆盖 | 很广，且多一个通用的 npx skills 安装方式 | Superpowers 覆盖面同样很广；Matt Pocock 实际上以 Claude Code 为主 | 你用非 Claude Code 的助手时，这篇的安装最省事。 |
一个真实的对照实验（但它只是一个人、一个任务）
官方对照文档里引了一项第三方实测。要先把它的证据强度说清楚：同一个人、同一个模型、同一个仓库、同一句提示词，只换技能框架，做了一次。这是一个人的单任务实验，不是基准测试。
尽管如此，结论很有信息量：
更快到代码（约 8 分钟 vs 约 12 分钟），而且跑了更多验证轮次（7 次 vs 5 次，包含完整测试套件）。多出来的那几轮抓到了一个不在本次功能范围内的兼容性问题——是功能专用的测试漏掉的那种。作者给它在「验证深度」上判了胜。
在前期的架构推演上投入更多。那位开发者说自己日常仍然用 Superpowers，用于正在演化、还没有既定模式的生产系统。token 消耗两边几乎一样，两边都重新规划过一次。
他自己给的结论是最公道的那句：按手头这件事来挑工具。
最关键的一条：同类不能叠加
官方文档里明确写了：不要同时把两套当作「活动路由」。原因是——两套都有元技能（负责决定「该用哪个技能」的那一层），叠在一起会抢命令名（比如 /tdd 在两处都有定义）、抢路由判断、还会塞进两套不同的测试哲学。结果是行为不可预测，不是「取两家之长」。
可以做的是：挑一个当主框架，从别家单件借技能（它们是 Markdown 文件，不是运行时，单独拿一个出来用没问题）。不可以做的是：装两个路由器。
08怎么装、怎么确认它生效、以及三个已知的坑
先选一条路，别四条都走
官方给了四条主要路径。选一条就行——同一个助手装两遍不是「更保险」，是制造两套来源。
# 先只看不装：把这个仓库里的技能列出来
npx skills add addyosmani/agent-skills --list
# 装全部 25 个
npx skills add addyosmani/agent-skills
# 只装一个
npx skills add addyosmani/agent-skills --skill code-review-and-quality见下面「坑一」。
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills插件市场是用 SSH 方式拉仓库的。你没配过 GitHub 的 SSH 密钥就会失败。官方的解法是强制走 HTTPS：
/plugin marketplace add https://github.com/addyosmani/agent-skills.git
/plugin install agent-skills@addy-agent-skills如果还是报 Permission denied (publickey)，官方给的兜底做法是让 git 把 GitHub 的 SSH 地址全部改写成 HTTPS：
git config --global url."https://github.com/".insteadOf git@github.com:git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills装完怎么确认它真的生效了
三条，从最省事到最确凿：
敲一个斜杠、看列表里有没有 /spec、/review、/ship。在，说明插件挂上了。
在一个真实项目里敲 /spec。它应该开始问你要做什么、给谁用、有什么边界——而不是直接给你写一份规格。如果它不问就写，说明技能没被读到。
让它做一件小事，然后你主动说「这个太简单了，跳过测试吧」。一个真的读到技能文件的 AI，应该会引用那张常见借口表反驳你，而不是听话照做。
三个已知的坑
用 --skill 只装单个技能时，只会复制 skills/那个技能/ 这一个文件夹，仓库根目录的 references/（7 份共享清单）不会被带过去。技能本身还能用，但里面指向那些清单的链接会失效。
官方自己承认这个缺口，并且它有编号：issue #361，到 2026-09-16 仍未关闭。官方的三个绕法：① 整仓库安装（插件市场那种）；② 克隆整个仓库；③ 手动把需要的那份清单复制到技能文件夹里一个 references/ 目录下。
用 Claude Code 插件安装时，你可能会看到「默认的 commands/ 文件夹被忽略，因为清单里指定了 commands」。这是正常的、可以忽略的。原因：仓库根目录那个 commands/ 是给 Antigravity CLI 用的，Claude Code 的命令在 .claude/commands/，两者故意分开。官方文档明说这条警告是「cosmetic」（表面的）。
AGENTS.md / CLAUDE.md 抄进你的项目
这两个文件配置的是「给 agent-skills 这个仓库做贡献的人」，不是「用这个包的人」。官方入门文档里专门写了这一条。抄过去等于把你的项目配置成它的开发环境。你只需要装技能，再加你自己项目本来就会读的说明。
为什么仓库里有九个 commands 目录
这是第一次逛这个仓库最容易困惑的地方：它有好几个看起来重复的目录。答案是——那些不是它的品牌别名，是各个工具各自的原生「发现路径」。改了名字或合并，那些工具就扫不到了。
| 目录 / 文件 | 给谁用 | 你什么时候需要在意它 |
|---|---|---|
.claude-plugin/ + .claude/commands/ | Claude Code | 你走 路线 B 时，靠的就是它。 |
.gemini/commands/ | Gemini CLI | 用 Gemini CLI 时，命令是 TOML 格式（另一种配置文件写法）放在这儿。 |
.codex-plugin/ + .agents/plugins/ | Codex CLI | Codex 是直接读根目录的 skills/，这两个文件只是注册插件市场。 |
commands/ + 根目录 plugin.json | Antigravity CLI | 就是它让 Claude Code 报那条警告的。不要动它。 |
.opencode/ | OpenCode | 用 OpenCode 时才需要。 |
根目录 plugin.json | GitHub Copilot CLI | Copilot 按约定自己找 skills/，但不会注册斜杠命令。 |
没有为自己做适配目录的工具（Cursor、Windsurf、Kiro 等），就按各自文档把 skills/ 核心拷到自己的原生位置。
09最小例子：一次改动从 /spec 走到 /ship
这一节用一条真实的路径把它串起来。场景很简单：你的一个半途项目里，登录页在手机上会横向溢出。
第一步：先立约束（这是它最该被抄走的一个动作）
/constraints 对应的是「约束驱动开发」这个技能。它解决的是一个非常具体的问题——作者的原话：
「When you wrote the code, reading it told you whether it was any good. An agent writes more in an afternoon than you will read that week, so the judgement moves out of your head and into checks that run around the loop.」
翻译：你自己写代码的时候，读一遍就知道好不好。但 agent 一个下午写的，比你那一周读的还多——所以判断必须从你脑子里，搬进那些围着循环自动跑的检查里。
这句话精确地说出了「为什么你读不完，也就判断不了」。它的解法不是让你读得更快，是把判断换成一串你自己定过数字的检查。而这个动作只需要做一次。
它会先问你四个问题，每个问题都带一个默认答案——所以「我不知道」是一个完整的回答，照样能产出一份能用的文件。四问长这样：
# 它问的四个问题（每问都自带一个「不确定时的默认值」）
Q1 除了底线之外，你还想强制哪几项？(a) 新代码的测试覆盖 (b) 安全扫描 (c) 性能预算 (d) 无障碍 (e) 架构边界
→ 猜你选 a 和 b；不确定时的默认：也是 a 和 b。
Q2 某个检查失败时，应该拦住还是只警告？
→ 猜：拦住。默认：底线部分拦住，其余先警告两周。
Q3 你心里有目标数字吗，还是我测一下现在多少、就守住这条线？
→ 猜：测。默认：测出来、守住它，不许变差。
Q4 你能接受的最慢检查是多少秒？
→ 猜：约 90 秒。超过你就不会跑了。回答完，它会写出一个 CONSTRAINTS.md 文件，长这样（这是官方给的模板，我保留了结构）：
# CONSTRAINTS.md（放在项目根目录）
# Constraints
Last reviewed: 2026-09-16
## 底线（永远生效，不需要装任何工具）
- 不许新增「压制报错」的注释（比如让检查工具闭嘴的那种标记）
- 不许留没实现的空壳函数，不许用空 catch 把错误吞掉
- 不许跳过或删除测试（除非提交信息里写明理由）
- 不许把密钥写进源码
- 这个文件本身不许为了让某次改动过关而被放松
## 带数字的强制项
| 维度 | 规则 | 用哪个命令检查 | 什么时候跑 |
|----------|-------------------------|-----------------------------|-----------|
| 类型 | 零类型错误 | tsc --noEmit | 每次编辑 |
| 密钥 | 源码里没有密钥 | gitleaks detect --redact | 每次编辑 |
| 覆盖率 | 改动的那几行 ≥ 80% 有测试 | vitest run --coverage | 任务结束 |
| 无障碍 | 严重问题为零 | axe $PREVIEW_URL | 预览部署后 |这张表里有一条规矩，是整份文件最重要的设计：
「Every row names the command that produces the verdict. A dimension with a number and no command in this column is an aspiration, not a constraint.」
翻译：每一行都必须写出「用哪个命令来判定」。一个只有数字、却没有命令的维度，是一个愿望，不是一个约束。
还有一条对你特别友好，叫「棘轮」（ratchet，本意是只能往一个方向转的齿轮）：
如果你定 80% 覆盖率，而项目现在只有 62%，那你会永远看到一个红的构建，然后学会无视它。
棘轮换了个做法：记下今天是多少，然后只要求「不许变差」。这个动作不需要你做任何判断——你只要说「我不知道目标是多少」，它就自己去测一个现在值。数字变好了就更新记录；变差了，那就是这次发现的问题。
第二步：/spec，把「想改什么」写下来
/spec 登录页在手机上会横向溢出，我想修掉。只能动 styles/login.css 和 components/LoginForm.tsx 这两个文件。它会先问四个方向的问题（目标与用户、核心功能与验收标准、技术栈与限制、边界），然后生成 SPEC.md。「边界」那一栏是你写「什么绝对不许动」的地方——对半途项目来说，这一栏比目标栏还重要。
第三步：/build，一片一片来
# 只做计划里的下一个任务，做完就停
/build
# 或者：批准一次计划，然后跑完整个计划（中途遇险会停）
/build auto第四步：/ship，发之前的最后一道闸
/ship它同时开三个子代理：code-reviewer 跑五轴评审、security-auditor 跑安全检查、test-engineer 分析测试缺口。三份报告回来后，主会话把它们合并成一份决定。
它自己规定了一条「可以不跑这套」的条件——必须三条同时满足：改动不超过 2 个文件、差异不超过 50 行、而且不碰权限、支付、数据访问、配置或环境变量。否则默认就跑。原话：
「/ship is designed for production-bound changes — when the blast radius is non-trivial, run the parallel review even if the diff looks small.」
它的意思是：看爆炸半径，不看改动大小。改一行权限判定，比改三百行样式危险得多。
中途出问题的症状 → 该回哪一步
| 你看到的症状 | 先回到哪一步 | 为什么 |
|---|---|---|
| 它改的地方超出你允许的文件 | /spec | 「边界」那一栏没写死。这一栏空着，等于没有边界。 |
| 它说「完成了」，但你不知道完成在哪 | /constraints | 你没有可跑的检查，只能听它说。回去把至少一条「带命令的数字」定下来。 |
| 修一个 bug，冒出两个新 bug | 本站另一篇：《该停下来的信号》 | 这通常不是 bug，是结构问题——继续修只会更多。 |
| 它每一步都在问你，你答不上来 | 10 什么时候别用它 | 见下一节。这可能是这套东西现在不适合你的信号，不是你的问题。 |
10什么时候别用它（这一节请认真读）
前面九节都在讲它有什么。这一节讲它的代价——因为我核实过的所有第三方评测里，被提得最多的缺点正是这一条。
代价一：它把「点头」的次数变多了
这是它的设计本身：每个阶段一个检查点。官方的说法是「keeps a human checkpoint at each phase」（在每个阶段保留一个人工检查点）。这被写成优点是对的——对能判断的人，它是护栏。
但把它和另外两套放在一起看，差别就出来了：Superpowers 是刻意「减少中途打断」的，让你交出去、过一阵回来看结果。这个包相反，它更多的阶段会停下来等你。
这套东西的每个阶段都要求你在改动发生之前判断「这个方案对不对」——规格要你批、计划要你批、每片构建完要你确认、上线要你签字。
如果你能判断，这些检查点是在保护你。如果你判断不了，它们的作用就变成了让你在更多的地方点「同意」——而流程越精密，需要你盖章的地方越多。
这不是这个包的问题，是「事前批准」这类机制的共同前提。Superpowers、Matt Pocock 的 grill-me 都有同一个前提（后者更直接：它靠一连串问题逼你回答）。三个设计完全不同的工具撞在同一处，说明那是「位置」的问题，不是工具的问题。
如果你正处在这个位置上，这个包对你仍然有一半是可用的——就是那些不需要你做事前判断的部分：
| 可以先用这些（事后看结果） | 先别碰这些（事前批方案） |
|---|---|
/review、/ship——它们产出的是报告，你只需要看「有几条严重问题」，这是个能回答的问题。 | /spec、/plan——它们要你在动手之前批准一份方案，而你手上没有可判断的依据。 |
/constraints 的棘轮模式——你不需要定目标，只需要说「我不知道」，让它测一个现在值。 | /build auto——它的整个前提是「你批准一次计划，然后它跑完」。事前批准正是它的入口。 |
debugging-and-error-recovery——它给的是「复现 → 定位 → 缩小 → 修 → 加护栏」这套顺序，你照着念就行。 | doubt-driven-development——它叫来第二个 AI 对抗性地质疑第一个。它换掉的是「你的判断」，变成「另一个 AI 的判断」。这不一定比现在更好。 |
代价二：25 个太多，你实际会用的没几个
这个包自己也知道。它的入门文档里写得非常直接：
入门文档给了两个推荐档位，第二个尤其值得注意：
最小档（从这里开始）：只装三个——spec-driven-development（定要做什么）、test-driven-development（证明它真的能用）、code-review-and-quality（合入前验质量）。官方说这三个「覆盖了 AI 辅助开发里最关键的质量缺口」。
全流程档：开始项目时用规格 + 拆任务；开发中用增量实现 + 测试驱动；合入前用代码评审 + 安全加固；上线前用发布清单。
它同时明确禁止：「不要一次性把 25 个都装进上下文」——既浪费上下文，又会把真正相关的那几个冲淡。
第三方评测里被提得最多的一条抱怨也是这个：「二十个技能太多了」，而且「大概率只会用五六个」。
代价三：每一个被强制的步骤，都在花 token
规格、测试、五轴评审——每一样都要花 token（前面解释过，就是 AI 的阅读量和计费单位）。有一篇第三方评测提了一个很尖的观察：如果上下文被塞满了，那些「常见借口表」会被挤出窗口——被挤出去之后，它就不再起作用了。
这句话说得有道理，而且它解释了一件事：这个包的机制是「让 AI 在读得到的地方看到反驳」，不是「让 AI 记住」。读不到就等于没有。这也是为什么它拼命强调按需加载。
代价四：它带着很强的「Google 工程文化」底色
这一点官方自己也讲得很明白：Hyrum 定律、Beyoncé 规则、测试金字塔、Chesterton 的栅栏、主干开发、Shift Left、每千行约 100 行的改动——这些全部来自 Google 的工程实践。对习惯了另一套做法的团队，要么改自己，要么改它。
还有一条它自己也承认没解决的
对照文档的最后一段承认了一件事，我认为是整份文档里最诚实的一句：
「None of these has solved durable cross-session memory well yet: what an agent learned in one session rarely carries cleanly into the next.」
翻译：这三套都还没解决好「跨会话的持久记忆」——一个会话里 AI 学到的东西，很少能干净地带到下一个会话。三个项目都在往这个方向试（笔记文件、交接产物、用任务清单承载计划）。
「你新开一个会话，前面那些判断就没了」——这是三套共同的天花板，不是你用错了。
11五个一定会撞上的误解
实践上的对策是：先用斜杠命令——敲
/spec 是明确指名，不依赖它的自动判断。allowed-tools 是给技能「上锁」，限制它能干什么。列进去的工具在那个回合里免去权限询问，但没有任何东西被移出工具池。真正起限制作用的是另一个字段
disallowed-tools。顺带一个实用细节：这些字段不应该写进公开发布的
SKILL.md——它们属于「你这个本地的副本」，写进发布版会因为出现未预期的字段而打包失败。可以做的是：选一个当主框架，从别家单件借技能。
而且它对「证据」这个词本身有精确的标准——「Passing tests are evidence, not proof」（测试通过是证据，不是证明）。它还专门设计了一类检查，用来抓 AI 为了变绿（「变绿」= 检查全部通过，这类工具习惯用绿色表示通过、红色表示失败）而使的五种走捷径动作：把阈值改松、把测试改简单、把检查工具静音、留没做完的空壳、悄悄加一条例外。
12一页纸速查
按你现在的处境，该看哪一节
| 你的处境 | 直接看 | 一句话 |
|---|---|---|
| 完全不知道它是什么 | 01 → 03 | 先破三个错想，再看六个阶段。 |
| 想先判断值不值得装 | 07 → 10 | 对照另外两套，然后认真读它的代价。 |
| 已经装了，想确认它生效 | 08 的三步验证 | 第三步最确凿：故意说「跳过测试吧」，看它反不反驳你。 |
| 想知道它凭什么比别家靠谱 | 06 → 02 | 三层评估 + 常见借口表。 |
| 手上有一个半途项目想接着做 | 09 | 从 /constraints 的棘轮模式开始，不是从 /spec。 |
| 它每一步都在问我，我答不上来 | 10 第一段 | 用「事后看结果」的那半张表。 |
九条命令，一行一条
/spec 写规格（SPEC.md）：先规格后代码
/constraints 定质量底线（CONSTRAINTS.md）：数字 + 检查命令
/plan 拆任务（tasks/plan.md）：小块、可验、有依赖顺序
/build 做下一个任务，然后停
/build auto 批准一次，跑完整个计划（遇险会停）
/test 先写会失败的测试，再写让它通过的代码
/review 五轴评审：正确性 / 可读性 / 架构 / 安全 / 性能
/code-simplify 改简单，行为完全不变
/ship 三个人格并行评审 → GO / NO-GO + 回滚方案
/webperf 网页性能审计（只对网页项目）四条最值得抄走的东西（不装也能用）
| 抄什么 | 具体怎么写 | 它治的是什么 |
|---|---|---|
| 常见借口表 | 左边写 AI 会说的借口，右边写反驳。现在就写，表不怕它还没说。 | 你分不清「合理的省事」和「偷懒」——这张表把判断提前做完了。 |
| 有数字必须有命令 | 每一行质量要求都写出「用哪个命令判定」。写不出的那行删掉。 | 「要写测试」是愿望；「改动的那几行覆盖率 ≥ 80%，用 vitest run --coverage 判定」才是约束。 |
| 棘轮 | 不设目标，只记下今天多少，然后要求「不许变差」。 | 你不需要做「目标定多少」这个你答不了的判断。 |
| 看这五个动作 | 改动里出现这些就是有人在走捷径：阈值被改松、测试被改简单、检查被静音、留了空壳、多了一条没人讨论的例外。 | 只靠 git diff 就能抓，不需要装任何工具。 |
13术语表
| 术语 | 一句话定义 | 为什么重要 / 什么时候用 · 别当什么用 |
|---|---|---|
| 技能 / skill | 一个 Markdown 文件，写着「什么情况下按哪几步做、做完要交什么证据」。 | 整套东西的基本单位。别把它当提示词——提示词是被动的，技能带流程和出口条件。 |
| 元技能 / meta-skill | 负责回答「这次该用哪个技能」的那个技能。 | 这个包里是 using-agent-skills。同类包不能同时装两个，因为两个元技能会抢路由。 |
| 斜杠命令 / slash command | 你在对话里敲的 /spec 这种命令，是「用户能直接按的入口」。 | 它是最可靠的触发方式——不依赖 AI 自己判断该不该用某个技能。 |
| 人格 / persona | 一个扮演固定角色、交固定格式报告的 AI 子代理。 | 用来拿到「某个专业视角」的意见。别把它当技能：人格回答「谁来看」，技能回答「怎么做」。 |
| 渐进式披露 | 一点一点地给信息，而不是一次全塞进去。 | 这个包省 token 的核心机制。推论：简介写得不好 = 技能等于不存在。 |
| 常见借口表 | 把 AI 会用来偷懒的借口和对应的反驳，事先写在一起。 | 全包最值钱的一张表，也是作者最希望别人抄走的一点。不装这个包也能用。 |
| 红旗 / Red Flags | 「出现这些现象说明流程正在被违反」的清单。 | 给你评审和自查用的。别当检查脚本——它是给人看的迹象，不是自动判定。 |
| eval / 评估 | 用预先写好的题目测「技能会不会被正确触发、会不会真的改变行为」。 | 这个包独有的部分。别理解成「测 AI 聪不聪明」——它测的是技能文件写得好不好。 |
| CI / 持续集成 | 每次提交代码时，服务器自动跑一遍检查。 | 这个包的前两层评估在这里跑。注意第三层不在 CI 里，要手动跑、要花钱。 |
| 规格 / spec | 动手之前先写下来的「要做什么、验收标准是什么、边界在哪」。 | /spec 的产出。边界那一栏比目标栏重要——它写着你不会动什么。 |
| 约束 / constraints | 这个项目「好到可以发」的具体数字，以及判定它的命令。 | /constraints 的产出。别写成愿望清单：没有命令的那一行不算约束。 |
| 棘轮 / ratchet | 只往一个方向转的齿轮。这里是「只许变好，不许变差」。 | 用在「你还没有目标数字」的时候——它把「定多少」这个判断整个取消了。 |
| token | AI 处理文字时的计量单位，也是计费单位。 | 这个包反复权衡的东西。技能按需加载就是为了省它。 |
| 适配器 / adapter | 仓库里为每个不同工具单独放的那一份命令入口。 | 那不是重复文件，是各工具各自的原生发现路径。改名或合并不行，工具会扫不到。 |
14来源、证据边界，和两处对不上的地方
我实际核对了什么
下面这些数字不是从文章里抄的，是 2026-09-16 把仓库克隆到本地、逐项数出来的，可以复核：
| 断言 | 实测结果 | 怎么复核 |
|---|---|---|
| 技能总数 | skills/ 下 25 个目录，全仓库共 25 个 SKILL.md | ls skills | wc -l；find . -name SKILL.md | wc -l |
| 技能文件总行数 | 7,780 行；最短 idea-refine 178 行，最长 security-and-hardening 524 行 | cat skills/*/SKILL.md | wc -l；wc -l skills/*/SKILL.md | sort -n |
| 斜杠命令 | .claude/commands/ 下 9 个 | ls .claude/commands | wc -l |
| 评审人格 | agents/ 下 4 个 | ls agents | wc -l |
| 共享清单 | references/ 下 7 份 | ls references | wc -l |
| 提交次数 / 建仓日期 | 512 次提交；建仓 2026-02-15；最后提交 2026-09-11 | GitHub API：/repos/addyosmani/agent-skills 与 /commits |
| 版本号 | v0.6.9（plugin.json 与 .claude-plugin/plugin.json 一致） | cat plugin.json |
第一处对不上：一个技能违反了它自己定的规矩
仓库的规范文档里有一条明确要求：「Keep SKILL.md under 500 lines.」（技能文件保持在 500 行以内。）
而实测结果：security-and-hardening/SKILL.md 是 524 行，是 25 个里唯一超线的（第二长的 performance-optimization 496 行，刚好卡在线上）。
更值得注意的一点：我检查了 CI 里的校验脚本 validate-skills.js——它根本不检查行数。所以这条规则是靠人遵守的，违反了不会被拦。
这对你的意义不是「抓到了它的错」，而是：这个包的质量是靠「写下来的规矩 + 一张检查表 + 慢跑的人眼」维系的，不是靠自动化挡住的。它同样会有漏。
第二处对不上：/ship 到底叫了几个人
README 和对照文档都写「/ship 并行扇出到评审人格」，并把 四个人格名字一起列了出来（含 web-performance-auditor）。
但打开 .claude/commands/ship.md 看它实际做什么：Phase A 写的是「Spawn three subagents」（开三个子代理），列的是 code-reviewer、security-auditor、test-engineer——没有第四个。性能那个人格是走 /webperf 单独调用的。
这是个很小的文档不一致，但它是个好例子：读命令文件本身，比读 README 准。
第三方评测互相矛盾的地方（这一节请当成「怎么读二手文章」的样本）
我查到的第三方评测，在几个最基本的事实上互相打架：
| 说法 | 各来源报了哪些值 | 实测值 · 该怎么对待这类分歧 |
|---|---|---|
| 技能数量 | 20 个 / 21 个 / 22 个 / 24 个 / 48 个 SKILL.md | 25 个。 「48 个」是错的——全仓库确实只有 25 个 SKILL.md。这个数字大概是把别的文件也算进去了，或者根本是编的。 |
| 星标数 | 14k / 25k / 49.8k / 72.6k / 87.4k | 95,192（2026-09-16）。 这些差异大多是快照时间不同造成的，不全是错——但这个仓库七个月涨到这个数，说明只用「星标」当判断依据会严重滞后。 |
| 命令数量 | 7 个 / 9 个 | 9 个（/spec /plan /build /test /constraints /review /code-simplify /ship /webperf）。报 7 个的大概是早期的数字。 |
| 「没有任何评估」 | 有一篇评测明确说它「没有评估或遥测」，并说那些反借口表是「看起来合理的缓解措施，不是被评估过的干预」。 | 对了一半（逐条拆解见 06）。 补充一个时间点： evals/ 最早的相关提交在 2026-07-04——如果你读到的那篇评测更早，它说的可能就是当时的事实，不算错。 |
上表里每一行都是同一件事：二手文章会抄来抄去、会过期、会掺进没核过的数字。上面那个「48 个 SKILL.md」的说法流传得不窄——但只要你自己数一遍，十秒钟就推翻了。
这件事和你手上的项目是同一个道理：能自己数一遍的东西，别接受转述。
时效与来源边界
- 本文校对版本：
v0.6.9，对应提交 2026-09-11。这个仓库最后提交在 2026-09-12，处于活跃开发中——技能数量、命令、目录结构都可能变化。learn:shelf-life标为evolving。 - 我读的是仓库的
main分支快照，不是某个发布版。所以上面所有数字对应的是那一天的main。 - 星标与 fork 数是 2026-09-16 的实时值，会一直变。
- 那项对照实验是单次、单人、单任务，不能当基准测试读；我在 07 里已经标明了它的证据强度。
- 一处我核不到的：第三方评测里反复出现的「官方推荐某个具体版本组合」之类的说法，我没能在仓库里找到对应的一手来源，所以本篇没有引用。
一手来源
- 仓库：github.com/addyosmani/agent-skills（MIT 协议：一种很宽松的开源许可，基本等于「随便用、随便改、随便商用，出事别找我」）
- 作者原文：Agent Skills — AddyOsmani.com（2026-05-03）。本文引用的作者原话都出自这里与仓库文档。
- 仓库内的关键文档：
README.md、docs/getting-started.md、docs/adoption-guide.md、docs/comparison.md、docs/agents.md、docs/skill-anatomy.md、docs/advanced-per-agent-configuration.md、evals/README.md、references/definition-of-done.md - 已知未关闭问题：#361 单技能安装丢失共享清单
- 第三方对照实验：Superpowers vs Agent-Skills（Om Mishra）
99一句话总结
它是一份按开发阶段编号的流程手册，装在你的 AI 助手外面；它最实在的贡献不是那 25 个技能，是两件事——把 AI 的偷懒借口提前写成一张带反驳的表，以及把「代码好不好」从你脑子里搬进一串你自己定过数字的检查里。
它的代价也说清楚了：它是同类里最依赖你逐阶段批准的一个。你能判断时，那是护栏；你判断不了时，它只是让你在更多地方盖章。但它的另一半——评审、报告、棘轮——是不需要你事前判断的，那半可以先拿起来用。
留给你自己验的那一条
这篇文章里所有事实我都能替你验，除了这一条——它只能你来。
拿出你手边那个最小的半途项目，试着回答：
① 这个项目里，有没有一句话是你对 AI 说过的、听上去很像「以后再补」的？（比如「先这样，能跑就行」「这个先不测了」「回头统一整理」）
② 那句话当时是 你 说的，还是 AI 说的、你点头同意的？
然后想一想：如果当时有人在旁边替你把反驳念出来，你还会不会点那个头？
这就是这个包最值钱那部分——它甚至不要求你装它。