#AI创造营# Addy Osmani 是 Google 的工程师，目前担任 Google Cloud AI director。
他刚写了一篇博客《Agent Skills》来提醒开发者：AI 编码智能体虽然能快速生成代码，但默认会跳过高级工程师重视的“隐形工作”，比如写规格、拆任务、先测试、做评审、控制改动范围、留下验证证据。
本文中Addy Osmani 试图把多年在 Google 级工程体系中沉淀出的工程纪律，迁移到 AI agent 时代，让模型不只是更快地产出代码，而是在规格、测试、评审、验证和发布约束下产出更可信的软件。
文章配套有开源项目 addyosmani/agent-skills ，把里面这些高级工程实践封装成了 skills 。
下面是全文翻译，makedown排版，适合web端阅读，原文在：addyosmani.com/blog/agent-skills/
# Agent Skills
**2026 年 5 月 3 日**
高级工程师的工作，大多是那些不会出现在 diff 里的部分：规格说明、测试、评审、范围控制、拒绝发布无法验证的东西。AI 编码智能体默认会跳过这些部分。**Agent Skills** 是我试图让这些环节不再变成“可选项”的尝试。
任何 AI 编码智能体的默认行为，都是走向“完成”的最短路径。你要求它做一个功能，它就写这个功能。它不会问你是否有规格说明，不会在实现前先写测试，不会考虑这个改动是否跨越了信任边界，也不会检查这个 PR 在评审者眼中会是什么样子。它产出代码，宣布胜利，然后继续往前。
这正是每个高级工程师在职业生涯中都在学习避免的失败模式。任何任务的高级版本，都包含那些不会出现在 diff 里的工作：揭示假设、撰写规格、把工作拆成可评审的小块、选择朴素可靠的设计、留下结果正确的证据、控制改动大小，让人类真的能够评审它。这些步骤，正是能在规模化场景下交付可靠软件的工程师，与那些提交会破坏系统的代码的人之间的主要区别。
智能体跳过这些步骤，原因和初级工程师一样：这些步骤是不可见的。奖励信号指向的是“任务完成”，而不是“任务完成，并且设计文档也存在”。所以我们必须把高级工程师的脚手架重新加回去。
**Agent Skills** 就是我对这种脚手架的尝试。它刚刚超过了 2.6 万颗星，所以显然不只我一个人想要这个东西。这篇文章讲的是 README 没有完全覆盖的部分：为什么每个设计选择存在，它如何映射到标准 SDLC 和 Google 公开的工程实践，以及即使你永远不安装任何一个 skill，也应该从这个项目里借鉴什么。
---
## “Skill”到底是什么
在 Claude Code / Anthropic 的语境里，“skill”这个词承载了很多含义，所以有必要说精确一点。一个 skill 是一个带 frontmatter 的 markdown 文件，会在情况需要时注入到智能体的上下文中。它介于系统提示片段和运行手册之间。
skill 不是参考文档。它不是“关于测试你应该知道的一切”。它是一个工作流：一系列智能体要遵循的步骤，带有能产出证据的检查点，并以明确的退出标准结束。
这个区别就是整个问题的关键。如果你把一篇 2000 字的测试最佳实践文章放进智能体上下文里，智能体会读它，生成看起来合理的文本，然后跳过真正的测试。如果你把一个工作流放进去——先写失败的测试，运行它，确认它失败，写最小代码让它通过，确认它通过，再重构——智能体就有事可做，而你也有东西可验证。
**流程优先于散文。工作流优先于参考资料。有退出标准的步骤，优先于没有退出标准的长篇文章。** 仅仅这一个区别，就能区分有用的 skill 和漂亮的 markdown 文件。它也解释了为什么很多“AI rules”仓库在实践中最终什么都没做到：那些规则只是文章。
---
## Skills 编码的 SDLC
这个仓库里的 20 个 skills 围绕 6 个生命周期阶段组织，上面还有 7 个 slash commands：
| 阶段 | 命令 | 作用 |
|---|---|---|
| Define | `/spec` | 决定你到底要构建什么 |
| Plan | `/plan` | 拆解工作 |
| Build | `/build` | 以垂直切片实现 |
| Verify | `/test` | 证明它能工作 |
| Review | `/review` | 捕捉漏掉的问题 |
| Ship | `/ship` | 把它安全地交到用户手中 |
| Cross-cutting | `/code-simplify` | 横跨整个流程的代码简化能力 |
这不是巧合。这就是每个正常运转的工程组织都会运行的 SDLC，只是词汇不同。Google 称之为：
> 设计文档 → 评审 → 实现 → 可读性评审 → 发布清单
Amazon 称之为 working-backwards memo 和 bar raiser。每个健康的团队都有某种版本的这个循环。
AI 编码智能体带来的新问题是，大多数智能体默认会跳过这些阶段里的大部分。你要求一个功能，你得到一个实现，而规格、计划、测试、评审和发布清单全都没有发生。Skills 会推动智能体经过同样的阶段，这些阶段也是高级工程师强迫自己走完的流程，因为没有这些环节就发布代码，正是事故产生的方式。
一个复杂功能可能会按顺序激活 11 个 skills。一个小 bug 修复可能只用 3 个。路由器 `using-agent-skills` 会决定哪些适用。重点是，这个工作流会根据实际范围伸缩，而不是根据假定范围伸缩。
---
## 真正起作用的五个原则
这个项目里有五个设计决策是承重结构。系统的其余部分都由它们推导而来。
### 1. 流程优先于散文
前面已经讲过。工作流可以被智能体执行；文章不行。
人类团队也是如此。如果你的团队手册有 200 页，人在压力下没人会读。如果它是一小组带检查点的工作流，人们真的会运行它们。
---
### 2. 反合理化表格
这是这个项目里最有辨识度的设计决策，也是我最希望其他团队偷走的一个。
每个 skill 都包含一张表，列出智能体，或者疲惫的工程师，可能用来跳过工作流的常见借口，并配上预先写好的反驳。
| 常见借口 | 反驳 |
|---|---|
| “这个任务太简单，不需要规格说明。” | 验收标准仍然适用。五行可以。零行不行。 |
| “我稍后再写测试。” | “稍后”是最危险的关键词。没有稍后。先写失败的测试。 |
| “测试通过了，发布吧。” | 通过的测试是证据，不是证明。你检查运行时了吗？你验证了用户可见行为了吗？有人类读过 diff 吗？ |
它之所以有效，是因为 LLM 极其擅长合理化。它们会生成一段听起来很合理的文字，解释为什么这个特定任务不需要规格，或者为什么这个特定改动可以不经评审就合并。反合理化表格，是对智能体还没来得及说出口的谎言提前写好的反驳。
这个模式对人类团队同样有用。大多数工程退化，并不是因为有人选择做坏工作，而是因为人们接受了听起来合理的理由，跳过了他们不想做的部分。一个会写下自己反合理化清单的团队，会少很多这样的借口。
---
### 3. 验证不可协商
每个 skill 都以具体证据结束：
- 测试通过。
- 构建输出干净。
- 运行时 trace 展示了预期行为。
- 评审者签字确认。
“看起来对”永远不够。
这也是让 Anthropic 的 harness 能够从失败中恢复的同一个原则，是让 Cursor 的 planner / worker / judge 拆分真正能抓住 bug 的原则，也是任何长期运行智能体可恢复的基础。智能体是生成器。你需要一个单独的信号来确认工作已经完成。Skills 把这个信号内置进了每个工作流。
---
### 4. 渐进式披露
不要在会话开始时把全部 20 个 skills 都加载进上下文。应该根据阶段激活它们。一个小的 meta-skill，也就是 `using-agent-skills`，充当路由器，决定当前任务适用哪个 skill。
这是把 harness engineering 的经验应用到 skill 粒度上。每一个加载进上下文的 token，都会在某个地方降低性能，所以你只加载相关内容，把其余内容留在磁盘上。渐进式披露就是你如何把一个 20 个 skills 的库塞进 5000-token 的槽位，同时不污染整个上下文。
---
### 5. 范围纪律
meta-skill 编码了一个我愿意钉到每个智能体上的不可协商原则：
> 只碰你被要求碰的东西。
不要重构相邻系统。不要删除你没有完全理解的代码。不要看到一个 TODO 就决定重写整个文件。
这听起来显而易见，直到你看到一个智能体决定，为了修一个 bug，必须现代化三个无关文件。范围纪律是智能体 PR 能否被合并，还是必须被撤回的最大决定因素。它也是最直接映射到 Google 代码评审规范的原则之一，因为评审者会因为一个 PR 做了不止一件事而阻止它合并。
---
## Google 的基因
这些 skills 充满了来自《Software Engineering at Google》和 Google 公开工程文化的实践。这是有意为之。让 Google 规模的软件能运转起来的大部分东西都是公开记录下来的，而它们恰好也是智能体最可能跳过的部分。
下面是部分 skill 与实践之间的对应关系：
| Skill | 对应实践 |
|---|---|
| `api-and-interface-design` | Hyrum’s Law：你的 API 的每一个可观察行为，最终都会被某个人依赖，所以设计时必须考虑这一点。 |
| `test-driven-development` | 测试金字塔（约 80/15/5）和 Beyoncé Rule：“If you liked it, you should have put a test on it.” 基础设施改动不会抓 bug，测试才会。 |
| `test-driven-development` | 测试中 DAMP 优先于 DRY。测试代码应该像规格说明一样可读，即使代价是一些重复。过度抽象的测试是已知反模式。 |
| `code-review-and-quality` | 约 100 行 PR 大小，以及 Critical / Nit / Optional / FYI 严重性标签。大的 PR 不会被认真评审，只会被橡皮图章式通过。 |
| `code-simplification` | Chesterton’s Fence：在理解一个东西为什么被放在那里之前，不要移除它。 |
| `git-workflow-and-versioning` | trunk-based development 和 atomic commits。 |
| `ci-cd-and-automation` | Shift Left 和 feature flags：尽早捕捉问题，把部署和发布解耦。 |
| `deprecation-and-migration` | code-as-liability：你保留的每一行代码，都是你必须永远维护的一行，所以应该偏好更小的表面积。 |
这些都不是新想法。重点是，它们默认并不存在于智能体里。一个前沿模型在训练数据里读过“Hyrum’s Law”这个短语，但它不会在凌晨 3 点为你设计 API 时自动应用 Hyrum’s Law。Skills 就是确保它会这样做的方法。
---
## 如何实际使用它
有三种模式，承诺程度大致递增。
### 模式 1：通过 marketplace 安装
如果你使用 Claude Code：
```text
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills
```
你会得到这些 slash commands：
- `/spec`
- `/plan`
- `/build`
- `/test`
- `/review`
- `/ship`
- `/code-simplify`
智能体会根据上下文自动激活相关 skills。这是我建议大多数人开始尝试的路径。
---
### 模式 2：把 markdown 放进你选择的工具里
这些 skills 是带 frontmatter 的纯 markdown。
Cursor 用户可以把它们放进：
```text
.cursor/rules/
```
Gemini CLI 有自己的安装路径。Codex、Aider、Windsurf、OpenCode，或者任何接受 system prompt 的工具，都能读取它们。
工具本身不如底层工作流重要。
---
### 模式 3：把它们当成规格来读
即使你什么都不安装，这些 skills 也是一份关于“如何用 AI 智能体做好工程工作”的文档化描述。
你可以这样做：
- 阅读 `code-review-and-quality.md`，把五轴框架应用到你团队的评审流程里。
- 阅读 `test-driven-development.md`，下次和初级工程师争论“我们是否需要先写测试”时，用它来定论。
- 阅读 meta-skill，把五条不可协商原则偷到你自己的 `AGENTS.md` 里。
我实际上会从第三种模式开始。挑出最接近你当前痛点的四五个 skills。决定你想强制执行哪些工作流。然后再安装运行时，或者自己做一个，来执行这些流程。
---
## 即使你永远不安装，也应该偷走的东西
不管你是否使用 AI 编码智能体，这个项目里有几个模式都值得借鉴。
### 把反合理化变成团队实践
写下你的团队经常对自己说的谎言：
- “我们上线后再修测试。”
- “这个改动太小，不需要设计文档。”
- “没事，我们有监控。”
给每个借口配上反驳。把它放进你的 `AGENTS.md` 或工程 wiki。它会帮你省掉争论，也会抓住下一个疲惫的周五下午捷径。
---
### 内部文档要流程优先于散文
如果你发现自己正在写一篇 2000 字的文档，标题是“我们如何处理 X”，那你写的是参考材料。
把它转换成带检查点的工作流。文档会缩短到 400 字，而且人们真的会运行它。
这不仅适用于 agent skills，也同样适用于 onboarding 指南和 runbooks。
---
### 把验证作为硬性退出标准
让“产出证据”成为每个任务的退出步骤。对智能体如此，对工程师如此，对你自己也如此。
证据就是任何能证明工作完成的东西：
- 一次绿色测试运行
- 一张截图
- 一段日志
- 一个评审批准
没有证据，任务就没完成。“看起来对”永远不能闭环。
---
### 为任何规则手册采用渐进式披露
不要写一本 50 页的手册。
写一个小路由器，让它根据情况指向正确的小章节。这对 `AGENTS.md`、runbooks、事故 playbooks，以及任何人在压力下需要阅读的东西都成立。
---
### 五条不可协商原则
下面五条不可协商原则来自 meta-skill，我明天就会把它们放进任何 `AGENTS.md`：
1. **构建之前先揭示假设。**
沉默持有的错误假设，是最常见的失败模式。
2. **需求冲突时停下来并提问。**
不要猜。
3. **有必要时要反驳。**
智能体，或者工程师，不是只会说“是”的机器。
4. **偏好朴素、明显的解决方案。**
聪明技巧很昂贵。
5. **只碰你被要求碰的东西。**
不要扩大范围。
这五行就是一种值得拥有的工程文化，而且你不需要安装任何东西就能采用它。
---
## 它在 harness 中的位置
从更大的图景看，skills 是 agent harness engineering 的一层。harness 是模型加上你围绕它构建的一切；skills 是可复用的工作流片段，会被渐进式披露到 system prompt 中。
它们与以下层并列存在：
| 层 | 作用 |
|---|---|
| `AGENTS.md` | 滚动规则手册 |
| hooks | 确定性的执行层 |
| tools | 智能体可以采取的动作 |
| session log | 持久记忆 |
| skills | 高级工程师流程 |
每一层都有具体职责。Skills 负责高级工程师流程这部分工作。
对于长期运行的智能体而言，skills 比对聊天式智能体更重要，因为长时间运行会放大每一个捷径。
一个在 10 分钟会话中跳过测试的智能体，会制造一个 bug。一个在 30 小时会话中跳过测试的智能体，会在运行结束时制造一场调试考古项目，那时已经没人记得最初意图是什么了。运行时间越长，高级工程师的脚手架就越必须被强制执行，而不是被建议执行。
skills 格式的可移植性也很重要。同一个 `SKILL.md` 文件可以用于：
- Claude Code
- Cursor（通过 rules）
- Gemini CLI
- Codex
- 任何接受 system prompt 内容的 harness
工作流写一次，运行时负责执行。这就是 markdown-with-frontmatter 格式能带来的东西，而定制化 prompt engineering 做不到这一点。
---
## 结语
比起 skills 本身，我最希望人们从这个项目中带走的是这个框架。
AI 编码智能体是能力极强的初级工程师，但它们对那些不会出现在 diff 里的工作没有本能。高级工程工作——揭示假设、控制改动大小、撰写规格、留下证据、拒绝合并无法评审的东西——正是智能体会跳过的内容，除非你让它无法跳过。越来越多时候，我们的工作是在把这种纪律编码成智能体无法自我说服而绕过的东西。
Skills 是这种做法的一种形态：
- 反合理化表格
- 渐进式披露
- 流程优先于散文
- 把验证作为承重的退出标准
- 已经证明有效的 Google 实践，被做成可移植的形式
你可以安装我的版本。也可以自己做一套。不管怎样，这个教训都成立：
> 高级工程师职责中的那些部分已经不再是可选项，即使这个工程师是一个模型。
