Agent Skills 完全解读：Addy Osmani 给 AI 编码 Agent 的「高级工程师」脚手架
发布日期: 2026-05-05 • 阅读时间: 10 分钟 • 标签: Agent Skills, Addy Osmani, AI Coding Agent, Claude Code, Agent Workflow高级工程师的大部分工作不在 diff 里。写 spec、写测试、做代码审查、拒绝上线不可验证的变更——这些看不见的步骤才是专业软件工程的本质。而 AI 编码 Agent 的默认行为是跳过这些步骤，直接写代码。
Agent Skills 是 Google Chrome 工程总监 Addy Osmani 为解决这个问题而设计的开源项目，发布仅数日在 Hacker News 上引发热议（49 点 / 2 小时），GitHub 已飙升至 26K+ stars。它提供了一套标准化的 AI Agent 技能系统——不是参考文档，而是可执行的工作流——迫使 Agent 像高级工程师一样思考。
本文深度解读这个项目的核心设计理念、20 个技能的架构、5 个支撑性设计决策，以及如何在日常开发中落地。
目录
背景：AI Agent 跳过了什么
任何 AI 编码 Agent 的默认行为都是走最短路径到「完成」。你让它加一个功能，它就写这个功能的代码。它不会问：你有 spec 吗？测试写了吗？这个变更是否跨过信任边界？PR 在 reviewer 眼里是什么样子的？
它产出了代码，宣布胜利，然后进入下一个任务。
这正是每个高级工程师用职业生涯学会避免的失败模式。高级版本的任务包含不显示在 diff 里的工作：暴露假设、写 spec、把工作分解成可审查的块、选择无聊但可靠的设计、留下证据证明结果是正确的——限制变更规模让人可以真正审查。Addy Osmani 称之为「看不见的工程脚手架」（invisible scaffolding）。
Agent 跳过这些步骤的原因和 junior 工程师一样：它们不可见。奖励信号指向「任务完成」，而不是「任务完成并且设计文档存在」。所以我们必须把这些脚手架重新装回到 AI 身上。
什么是 Skill？流程不是散文
在 Agent Skills 项目中，「skill」是一个带有 frontmatter 的 markdown 文件，当场景触发时被注入到 Agent 上下文中。它介于系统提示片段和 runbook 之间。
一个 skill 不是参考文档。它不是你关于测试应该了解的一切。它是一个工作流：Agent 按照一定顺序执行的步骤序列，每个步骤有检查点产出证据，最后以明确的退出标准结束。
流程优于散文。工作流优于参考。带有退出标准的步骤优于没有退出标准的论文。这个区别就是一个有用的 skill 和一个漂亮的 markdown 文件的区别。它也解释了为什么那么多「AI rules」仓库在实践中毫无作用——那些 rules 都是论文。
—— Addy Osmani
如果你把一个 2000 字的测试最佳实践论文放入 Agent 上下文，Agent 会读它，生成看起来合理的文本，然后跳到实际测试步骤。但如果你放入一个工作流（先写会失败的测试、运行它、观察失败、写最少代码通过、运行通过、重构），Agent 有事情可做，你也有东西可以验证。
六阶段 SDLC 设计
仓库里的 20 个 skill 围绕 6 个生命周期阶段组织，上面覆盖 7 个 slash 命令：
| 阶段 | Slash 命令 | Skill 数量 | 核心目标 |
|---|---|---|---|
| Define / 定义 | /spec |
3 | 决定你在构建什么。产出明确的验收标准 |
| Plan / 计划 | /plan |
3 | 把工作分解成可审查的块 |
| Build / 构建 | /build |
4 | 垂直切片方式实现功能 |
| Verify / 验证 | /test |
4 | 证明功能正确运行 |
| Review / 审查 | /review |
3 | 捕捉遗漏的问题 |
| Ship / 发布 | /ship |
3 | 安全地把变更带给用户 |
另外还有一个 /code-simplify 命令横跨所有阶段底部。这其实就是每个正常运行的工程组织都在使用的 SDLC，只是叫法不同。Google 叫它 design doc → review → implementation → readability review → launch checklist。Amazon 叫它 working-backwards memo 和 bar raiser。每个健康的团队都有这个循环的某种变体。
AI 编码 Agent 的新问题在于：大多数 Agent 默认跳过了这些阶段中的大多数。你要求一个功能，得到一个实现，然后 spec、plan、test、review 和 launch checklist 全都不存在。Skills 推动 Agent 经历高级工程师强迫自己经历的那些阶段，因为只发布代码而不执行它们，就是事故的根源。
一个复杂的功能可能需要按顺序激活 11 个 skill。一个小 bug 修复可能只需要 3 个。路由机制（using-agent-skills）决定哪些适用。关键点是工作流的规模与实际范围匹配，而不是与假设的范围匹配。
五个核心设计原则
以下是支撑整个系统的五个设计决策，理解了它们才算真正理解了 Agent Skills：
1. 流程优于散文 (Process over Prose)
已经讲了很多。工作流对 Agent 可执行；论文则不然。对人类团队也是如此。如果你的团队手册有 200 页，在时间压力下没人会读。如果它是一小套带检查点的工作流，人们实际上会执行它们。
2. 反合理化表 (Anti-rationalization Tables)
这是项目中最具区分度的设计决策，也是 Addy Osmani 最希望其他团队借鉴的模式。
每个 skill 包含一个表格，列出 Agent（或疲倦的工程师）可能用来跳过工作流的常见借口，以及对应的书面反驳：
"这个任务太简单了，不需要写 spec。" → 验收标准仍然适用。五行也好。零行绝对不行。"
"我以后再写测试。" → "以后"是起支撑作用的词。没有"以后"。先写会失败的测试。"
"测试通过了，发布。" → 测试通过是证据而不是证明。检查运行时了？验证用户可见的行为了？人看过 diff 了？
为什么这有效？LLM 极其擅长合理化。它们会生成一段听起来合情合理的段落，解释为什么这个特定任务不需要 spec，或者为什么这个特定变更不需要审查就能合并。反合理化表是预写好的反驳——反驳那些 Agent 还没说出来的谎言。
这个模式对人类团队同样有效。大多数工程退化不是有人选择做坏的工作。是人们接受了听起来合理的借口，跳过他们不想做的部分。一个写下自己反合理化的团队，是反合理化更少的团队。
3. 验证不可协商
每个 skill 都以具体的证据终止。测试通过。构建输出干净。运行时跟踪显示预期行为。审查人签收。"看起来对"永远不够。
这和 Anthropic harness 从失败中恢复的原理相同，和 Cursor 的 planner/worker/judge 分离机制实际上能捕获 bug 的原理相同，和任何长运行 Agent可恢复性的原理相同。Agent 是一个生成器。你需要一个独立的信号表明工作已经完成。Skills 把这个信号烘焙进了每个工作流。
4. 渐进式激活
不要在会话启动时把所有 20 个 skill 加载到上下文里。根据阶段激活它们。一个元 skill（using-agent-skills）作为路由器，决定哪个 skill 适用于当前任务。
这是harness 工程在 skill 粒度上的应用。每加载一个 token 到上下文都会在某个地方降低性能，所以加载得越少越好。元 skill 只加载那些绝对必要的指令，按需拼接更大的工作流。
5. 证据终止条件
每个 skill 的输出必须是具体的、可验证的证据文件。Agent 不能只在内存中说"我完成了"，它必须生成一个文件证明它完成了。spec skill 产出 spec 文档。test skill 产出测试报告。review skill 产出审查评论。ship skill 产出发布检查清单。
这些证据构成了可审计的 paper trail。如果后续出了问题，你可以回到证据链查找哪里出了岔子。
如何在 Claude Code 中使用 Agent Skills
项目地址：github.com/addyosmani/agent-skills
使用方法很简单：
- Clone 仓库：
git clone https://github.com/addyosmani/agent-skills.git - 复制或 symlink skills 目录到你项目的
CLAUDE.md同级目录（对于 Claude Code） - 配置 agent 加载入口 skill：在聊天中通过
/spec、/plan、/build等 slash 命令触发对应 skill - 按流程走：Agent 会自动按阶段激活相关 skill，生成 spec → 制定计划 → 实现 → 验证 → review → ship
对于其他 Agent（如 Cursor、Codex），需要根据各自的 custom rules / agent hints 机制做适配。目前核心设计是为 Claude Code 打造的，但工作流模式是通用可移植的。
你能从 Agent Skills 学到什么
即使你从未打算安装一个 skill，Agent Skills 项目中蕴含的工程哲学也值得深刻思考：
- 写反合理化表给你的团队。记录下你们最常见的偷懒借口和准备好的反驳。这是最便宜的流程改进。
- 把工作流写进 agent 配置，而不是规则列表。Agent 可以执行步骤序列，但它不知道哪些步骤组成一个完整的工程流程——你需要告诉它。
- 验证必须独立于生成。让 Agent 同时担任程序员和 QA 不是不行，但你需要外部检查点。独立的 review skill 和 verify skill 就是这个作用。
- 证据是可审计的。在 AI 生成代码的时代，谁做了什么是不可追溯的。建立一个 paper trail，明确记录每个决策的上下文。
就像 Addy Osmani 自己说的："Agent Skills 是我把这些脚手架重新装回 AI 编码 Agent 的尝试。26K stars 说明我不是唯一一个需要它的人。"
在 2026 年，AI 写代码的能力已经毋庸置疑。但写出可维护、可审查、可部署的代码，仍然需要那些看不见的工程步骤。Agent Skills 提供了一个框架，把这些步骤重新带回到开发流程中——无论是对 AI 还是对人。