深度拆解——Google 工程总监如何把“资深工程师纪律“封装成 22 个可执行 Skill

Google Cloud AI总监Addy Osmani开源的agent-skills项目三周斩获21.4k星，为AI编码Agent制定了首份"工程纪律手册"。该项目通过22个结构化技能、3种专家角色和7个触发命令，将软件开发生命周期划分为DEFINE→PLAN→BUILD→VERIFY→REVIEW→SHIP六个阶段，强制AI遵循工程规范。每个SKILL.md文件采用标准化格

qcx23

216人浏览 · 2026-05-11 23:38:35

qcx23 · 2026-05-11 23:38:35 发布

在这里插入图片描述

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-reviewer persona，它就会用 Staff 工程师的视角五维评审你的代码（正确性、可读性、架构、安全、性能），并打 Severity 标签（Nit/Optional/FYI/Required/Blocker）。

这跟"在 system prompt 里写’你是一个资深工程师’"有什么区别？

区别在于 Persona 不是空说"你是 X"，而是绑定了一整套规则、Checklist、判断标准。code-reviewer 这个 persona 加载时，会同时激活 code-review-and-quality Skill + 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 marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

# 如果 SSH 不通，走 HTTPS
/plugin marketplace add https://github.com/addyosmani/agent-skills.git

# 本地开发模式（便于自己改）
git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills

2. Cursor

# 把 SKILL.md 复制到 .cursor/rules/ 目录
cp -r agent-skills/skills/*/SKILL.md .cursor/rules/

3. Gemini CLI

# 从远端仓库安装
gemini skills install https://github.com/addyosmani/agent-skills.git --path skills

# 从本地安装
gemini skills install ./agent-skills/skills/

4. GitHub Copilot

# 把核心 skill 内容塞进项目级 instructions
cat agent-skills/skills/*/SKILL.md >> .github/copilot-instructions.md

5. 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-reviewer persona 是低冲突的——它只是给 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