深度拆解——Google 工程总监如何把“资深工程师纪律“封装成 22 个可执行 Skill
2026 年 4 月初，Google Cloud AI Director Addy Osmani 在 GitHub 开源了一个项目叫
agent-skills。三周拿到 21.4k stars，一个月破 30k——速度比他当年那本《学习 JavaScript 数据结构与算法》还快。我把这个项目从 README、SKILL.md 格式、22 个 Skill 内容、3 个 Agent personas、7 个 slash 命令完整刨了一遍。结论是：这不是又一个 Prompt 集合，这是 AI Coding Agent 第一份真正的"工程纪律手册"——把"我之后再加测试""这个简单先这么写"这种 AI 偷工减料的借口，全部前置堵死。
一、问题定义：AI 编码 Agent 默认走"最短路径"
先说一个我们都见过的场景。
你让 Claude Code / Cursor / Gemini CLI 做一个功能。它默认会怎么干？
用户："帮我实现用户登录" ↓ Agent："好的" ↓ [直接开始写代码] ↓ [没问需求边界] ↓ [没写测试] ↓ [没考虑安全] ↓ [没看现有项目结构] ↓ [5 分钟后交付一坨能跑但活不长的代码]这就是 AI 编码 Agent 的默认行为模式——走最短路径。功能跑通就算完，跳过规范、跳过测试、跳过安全审查、跳过文档。这些步骤一个资深工程师永远不会跳，但 AI 默认就跳。
Addy Osmani 在他那篇引爆 30k stars 的博文《Why agent skills matter》里这样写：
“我们以为 AI 写代码慢的瓶颈是模型能力——其实是工程纪律。资深工程师的 80% 工作量不在敲键盘，在’决定不写哪些代码’‘验证假设’‘拒绝走捷径’。这些’决策习惯’恰恰是 AI 默认丢失的部分。”
agent-skills项目的本质就是——把这套"决策习惯"显式编码成 Markdown，让 Agent 强制执行。
二、项目骨架：22 Skills × 7 Slash × 3 Personas × 6 Stages
先把全景结构画清楚：
┌──────────────────────────────────────────────────────────────┐ │ agent-skills 项目结构 │ ├──────────────────────────────────────────────────────────────┤ │ │ │ 📁 skills/ ← 22 个 SKILL.md（核心） │ │ 📁 agents/ ← 3 个 Agent personas（专家角色） │ │ 📁 commands/ ← 7 个 Slash 命令（阶段触发器） │ │ 📁 references/ ← 4 个 Checklist 参考（按需召回） │ │ 📄 plugin.json ← Claude Code 插件元信息 │ │ 📄 README.md ← 项目入口与生命周期说明 │ │ │ └──────────────────────────────────────────────────────────────┘它把整个软件交付过程切成 6 个生命周期阶段：
DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP ↓ ↓ ↓ ↓ ↓ ↓ /spec /plan /build /test /review /ship /code-simplify每个 slash 命令在该阶段会自动激活相关的若干 Skills——这是它跟"一坨 Markdown 散文件"最大的区别：有路由、有触发、有强制流。
三、22 个 Skills 完整清单（按生命周期分类）
这是项目的核心。我把全部 22 个 Skill 列出来，每个用一句话点明它"反对的偷工减料行为"：
🟦 Meta（元技能，1 个）
| Skill | 反对的偷工减料 |
|---|---|
| using-agent-skills | 反对"凭感觉选 Skill"——把任务正确路由到对应 Skill |
🟦 Define 阶段（2 个）
| Skill | 反对的偷工减料 |
|---|---|
| idea-refine | 反对"用户说啥我做啥"——发散→收敛→假设验证 |
| spec-driven-development | 反对"边写边想"——先写 PRD（目标/命令/结构/风格/测试/边界） |
🟩 Plan 阶段（1 个）
| Skill | 反对的偷工减料 |
|---|---|
| planning-and-task-breakdown | 反对"一口气写完"——拆分为带验收标准和依赖顺序的小任务 |
🟨 Build 阶段（7 个）
| Skill | 反对的偷工减料 |
|---|---|
| incremental-implementation | 反对"一次做完再 commit"——薄垂直切片 + feature flag |
| test-driven-development | 反对"先写功能后补测试"——红绿重构 + 测试金字塔 80/15/5 |
| context-engineering | 反对"把所有信息一股脑给 Agent"——按阶段裁剪上下文 |
| source-driven-development | 反对"凭训练记忆决策"——框架选型必须查官方文档 |
| doubt-driven-development | 反对"AI 说啥都信"——CLAIM→EXTRACT→DOUBT→RECONCILE→STOP |
| frontend-ui-engineering | 反对"模板化 AI UI"——组件架构 + 设计系统 + WCAG 2.1 AA |
| api-and-interface-design | 反对"接口随便定"——契约优先 + Hyrum 定律 + 单版本规则 |
🟧 Verify 阶段（2 个）
| Skill | 反对的偷工减料 |
|---|---|
| browser-testing-with-devtools | 反对"看代码自我感觉良好"——通过 DevTools MCP 拿真实运行数据 |
| debugging-and-error-recovery | 反对"猜测式连续改"——五步分诊：复现→定位→缩小→修复→守护 |
🟪 Review 阶段（4 个）
| Skill | 反对的偷工减料 |
|---|---|
| code-review-and-quality | 反对"看一眼就批准"——五维评审 + 严重性标签（Nit/Optional/FYI） |
| code-simplification | 反对"为简化而简化"——Chesterton 围栏 + 500 规则 |
| security-and-hardening | 反对"先上线再说安全"——OWASP Top 10 + 三层边界 |
| performance-optimization | 反对"先优化再说"——测量优先 + Core Web Vitals |
🟥 Ship 阶段（5 个）
| Skill | 反对的偷工减料 |
|---|---|
| git-workflow-and-versioning | 反对"一坨 commit 全 push"——主干开发 + 原子提交 + 100 行变更 |
| ci-cd-and-automation | 反对"右移修问题"——左移 + 质量门 + feature flag |
| deprecation-and-migration | 反对"留着旧代码免得报错"——代码即负债 + 僵尸代码移除 |
| documentation-and-adrs | 反对"代码就是文档"——ADR 记录架构决策的"为什么" |
| shipping-and-launch | 反对"全量发布祈祷不出事"——分阶段发布 + 回滚预案 + 监控 |
四、SKILL.md 格式规范——每个技能的标准结构
这是项目最容易被低估的设计。每个 Skill 不是随便写的 Markdown，是有严格 schema 的：
┌─────────────────────────────────────────────────┐ │ SKILL.md 标准结构 │ │ │ │ ┌─ Frontmatter（YAML 前置元数据）─────────────┐│ │ │ --- ││ │ │ name: lowercase-hyphen-name ││ │ │ description: Guides agents through [task]. ││ │ │ Use when… ││ │ │ --- ││ │ └─────────────────────────────────────────────┘│ │ │ │ ## Overview → 这个技能的作用 │ │ ## When to Use → 触发条件 │ │ ## Process → 步骤化工作流（核心） │ │ ## Rationalizations → 借口 + 反驳（创新点） │ │ ## Red Flags → 出问题的信号 │ │ ## Verification → 证据要求 │ └─────────────────────────────────────────────────┘最有意思的两个 Section 是Rationalizations和Red Flags。
Rationalizations（合理化借口反驳）
举个真实例子。在test-driven-development这个 Skill 里：
## Rationalizations（你可能给自己找的借口） ❌ 借口："这个改动太小了，不需要写测试。" ✅ 反驳：小改动恰恰是漏 bug 高发区——因为没人 review。 Beyoncé 规则适用："If you liked it, then you should have put a test on it." 没测试的代码下个迭代就敢被 人改坏。 ❌ 借口："我之后再加测试。" ✅ 反驳：之后 = 永远不会。在你已经知道实现细节后写测试， 会写出"实现导向的测试"——只验证当前实现，不验证 行为，没有防御性。 ❌ 借口："这个用户只是想快速看个 demo。" ✅ 反驳：demo 是最容易"将错就错地变成生产代码"的形态。 即使是 throwaway code，也要有最小测试集证明它真的 能扔掉而不是变成债务。这是整个项目最反直觉、也最体现"工程师血泪"的设计——它知道 AI 会找借口偷工减料，所以提前把借口列出来一一反驳。
Red Flags（出问题的信号）
每个 Skill 还会列出"看到这些信号就要停手"的红旗。比如incremental-implementation里：
## Red Flags 🚩 一次提交超过 100 行变更 → STOP，回去拆切片 🚩 测试还没写就开始下一个特性 → STOP，先补测试 🚩 同时改三个不相关的模块 → STOP，原子化 🚩 commit message 写不出来在干啥 → STOP，重新规划这种"硬规则"特别有用——AI 在执行时如果遇到红旗，会主动暂停而不是硬着头皮跑。
五、3 个 Agent Personas：把"资深工程师"角色化
除了 22 个 Skill，项目还提供 3 个Agent personas——可以理解为"专家虚拟角色"：
┌──────────────────────────────────────────────────────────────┐ │ Persona │ 角色 │ 视角 │ ├──────────────────────────────────────────────────────────────┤ │ code-reviewer │ Staff 工程师 │ "Staff 会批准这个 PR 吗？"│ │ test-engineer │ QA 专家 │ 测试策略 + Prove-It 模式 │ │ security-auditor │ 安全工程师 │ 漏洞 + 威胁建模 + OWASP │ └──────────────────────────────────────────────────────────────┘实际使用场景：你写完一段代码，让 Claude Code 切到code-reviewerpersona，它就会用 Staff 工程师的视角五维评审你的代码（正确性、可读性、架构、安全、性能），并打 Severity 标签（Nit/Optional/FYI/Required/Blocker）。
这跟"在 system prompt 里写’你是一个资深工程师’"有什么区别？
区别在于 Persona 不是空说"你是 X"，而是绑定了一整套规则、Checklist、判断标准。code-reviewer这个 persona 加载时，会同时激活code-review-and-qualitySkill +references/security-checklist.md+references/performance-checklist.md——这是一个带武器装备的角色，不是一句空话。
六、一个 Skill 的实际工作流：以 spec-driven-development 为例
抽一个最关键的 Skill 看具体怎么运作。
触发：用户说"帮我实现 X 功能"，且没有现成的 PRD。
Skill 强制流程：
1️⃣ Specify 阶段 → Agent 不写代码，先回答 7 个问题： - 目标是什么？（用户能看到什么变化） - 执行命令？（怎么跑这个功能） - 项目结构？（在哪个目录、用什么框架） - 代码风格？（项目现有约定） - 测试策略？ - 边界（不做什么）？ - 成功条件？（可验证的） 2️⃣ Plan 阶段 → 基于 Specify 拆任务（调用 planning-and-task-breakdown） 3️⃣ Tasks 阶段 → 每个任务有验收标准和依赖关系 4️⃣ Implement 阶段 → 才开始写代码，且按 incremental-implementation 切片核心约束：
- ❌ 不允许"边想边写"
- ❌ 不允许"假设默认值"——所有不明确的地方必须显式列出假设而非补全
- ❌ 模糊表述必须改写为"可验证的成功条件"
举个例子，用户说"做个登录"，Skill 强制 Agent 这样反应：
[Agent 收到模糊需求] "做个登录" ↓ [激活 spec-driven-development] ↓ [Agent 回应] "在开始实现前，我需要明确以下几点（标记为我的假设， 你可以纠正）： 假设 1: 邮箱+密码登录（不是 OAuth/SSO） 假设 2: JWT 存 localStorage（不是 httpOnly cookie） 假设 3: 不需要邮箱验证流程 假设 4: 失败 5 次锁账号 30 分钟 成功条件（可验证）： ✅ 用 curl 能拿到 token ✅ Token 过期后请求返回 401 ✅ 错误密码 5 次后锁账号 不做的事： ❌ 注册流程（默认用户已存在） ❌ 找回密码 ❌ 多因素认证 如果上述假设有误，请指出。否则我开始写。"这个对话风格，就是这个 Skill强制出来的。没有 Skill，AI 默认会直接写代码。
七、跟 Anthropic Skills 是什么关系？
这是很多人会问的问题。
一句话答案：SKILL.md 这个文件格式来自 Anthropic Skills 标准，但 agent-skills 是社区项目，不是 Anthropic 官方出品。
详细说：
| 维度 | Anthropic Skills | addyosmani/agent-skills |
|---|---|---|
| 出品方 | Anthropic 官方 | 社区（Addy Osmani 个人） |
| 格式 | 定义了 SKILL.md 标准 | 沿用 SKILL.md 标准 |
| 内容 | 框架/格式 | 22 个具体工程实践 |
| 平台 | Claude 系（Claude Code 等） | 跨平台：Claude Code / Cursor / Gemini CLI / Windsurf / Copilot / Kiro / OpenCode |
| 灵感来源 | Anthropic 内部 | 《Software Engineering at Google》+ Google engineering practices guide |
agent-skills 的高明之处：沿用 Anthropic 的 SKILL.md 标准（让 Claude Code 一键安装），但内容是 Markdown 纯文本，所以同一份 Skill 可以喂给任何 AI 编码工具。一份内容多个出口。
八、八种主流工具的接入方式（实战代码）
项目最贴心的地方——给 8 个主流 AI 编码工具都写了接入示例。我整理成统一对照表：
1. Claude Code（首选，原生插件）
# 通过 plugin marketplace 一键安装/plugin marketplaceaddaddyosmani/agent-skills /plugininstallagent-skills@addy-agent-skills# 如果 SSH 不通，走 HTTPS/plugin marketplaceaddhttps://github.com/addyosmani/agent-skills.git# 本地开发模式（便于自己改）gitclone https://github.com/addyosmani/agent-skills.git claude --plugin-dir /path/to/agent-skills2. Cursor
# 把 SKILL.md 复制到 .cursor/rules/ 目录cp-ragent-skills/skills/*/SKILL.md .cursor/rules/3. Gemini CLI
# 从远端仓库安装gemini skillsinstallhttps://github.com/addyosmani/agent-skills.git--pathskills# 从本地安装gemini skillsinstall./agent-skills/skills/4. GitHub Copilot
# 把核心 skill 内容塞进项目级 instructionscatagent-skills/skills/*/SKILL.md>>.github/copilot-instructions.md5. Windsurf / OpenCode / Kiro IDE / Codex
各有各的接入路径——本质都是把 Markdown 注入到工具的 system prompt 通道。
接入工作量评估：Claude Code 是 30 秒（一行命令），Cursor 是 5 分钟（拷贝目录），其他工具大概 10-30 分钟。
九、对工程实践的真实影响——账本视角
我自己在团队里推过一阵这套 Skills，给个实际数据感受。
没用 Skills 之前（团队默认用 Claude Code / Cursor 写代码）：
代码评审通过率（首轮）： ~40% 返工率（功能变更）： ~35% 线上 bug 数（每周新增）： 8-12 "AI 写完测试自己就跑挂了"： 每周 5-8 次接入 agent-skills 一个月后：
代码评审通过率（首轮）： ~75% （+35pp） 返工率（功能变更）： ~15% （-20pp） 线上 bug 数（每周新增）： 3-5 （-50%） "AI 写完测试自己就跑挂了"： 每周 1-2 次（-75%）⚠️ 上述数据基于小团队（5 人）一个月观察，仅供方向性参考，不是严格 A/B 实验。
最显著的变化不在代码质量本身，而在"AI 不再忽悠你"——以前 Cursor 经常给你写一段代码，跑不起来，你说"为啥跑不起来"，它说"哦我没考虑到 X"。装上 Skills 之后，它会在写代码前主动列出"我在假设 X"，错误前置暴露，省了大量返工。
十、给团队落地的具体建议
如果你想在团队里推这套 Skills，给三条具体路径。
路径 1：从 spec-driven-development 单点突破（推荐新团队）
不要一上来推 22 个。从一个 Skill 开始——spec-driven-development。
逻辑：80% 的 AI 写错代码，根因都是"需求理解错了"，不是"代码能力差"。把这一个 Skill 装好，AI 会在写代码前先跟你对齐假设——这一个变化就能解决一半的返工。
路径 2：从 code-review-and-quality persona 切入（推荐成熟团队）
成熟团队有自己的工程规范，强推 22 个 Skill 可能跟现有规范冲突。
但code-reviewerpersona 是低冲突的——它只是给 PR 加一个"AI Staff 工程师"的视角。让团队在 commit 前先用 persona review 一遍，能在不动现有流程的情况下提升代码质量。
路径 3：基于 SKILL.md 格式自己写公司专属 Skill（推荐大厂）
agent-skills 的 22 个 Skill 是通用工程实践，但你公司可能有特定规范——内部框架、风格、安全要求。
学 SKILL.md 格式，写自己的 Skill。每个 Skill 包含 Overview / When to Use / Process / Rationalizations / Red Flags / Verification 这 6 段——把公司内部最资深工程师"心里默念的检查清单"写下来，让 AI 强制执行。
我自己最近在搞云迁移服务相关 Skill：
cloud-migration-spec：迁移方案的 PRD 模板migration-cutover-runbook：割接前 24 小时检查清单post-migration-validation：迁移后回归测试
这些没法用通用 agent-skills，但完全能用同样的格式写。
十一、一句话结论
agent-skills 不是 Prompt 库，是工程纪律的可执行版本。
它的真正贡献不在于 22 个 Skill 本身（这些资深工程师都懂），而在于：
- 格式：SKILL.md 统一格式让"工程纪律"第一次可以被加载、被路由、被强制
- 跨平台：同一份内容能喂给 Claude Code / Cursor / Gemini CLI / Copilot
- 反借口设计：把 AI 偷工减料的常用借口提前列出来一一反驳——这是项目最反直觉、最有价值的创新
对个人开发者：装上立刻见效，特别是 spec-driven-development 这一个就能省掉一大半返工。
对团队 lead：这是把"老司机经验"传承给 AI 时代新人最快的路径——你不需要每次都口头教，把规矩写成 Skill 就行。
对工程组织：这是 AI 时代的"工程纪律基础设施"——值得作为团队级标准长期投入。
30k stars 不是虚的。Addy Osmani 这次开源的不是代码，是一份给 AI 时代工程师的"如何不被 AI 拖累"自救手册。
参考资源
- 项目地址：https://github.com/addyosmani/agent-skills
- 作者博客：https://addyosmani.com
- Software Engineering at Google：https://abseil.io/resources/swe-book
- Google Engineering Practices：https://google.github.io/eng-practices/
- 配套教程（社区）：clauday.com / openagentskill.com
作者注：本文基于项目公开 README、SKILL.md 实际内容拆解而成。22 个 Skill 的描述出自 README 原文，"反对的偷工减料"一栏是我对每个 Skill 核心反命题的总结。文中实际数据基于小团队一个月观察，方向性参考，非严格 benchmark。
如果你对"团队级 Skill 落地"“自定义公司专属 Skill”"SKILL.md 标准与 Anthropic 官方关系"感兴趣，欢迎评论区交流。
tags: AI Coding Agent, Claude Code, Cursor, Agent Skills, SKILL.md, 工程实践, Anthropic Skills