项目地址：https://github.com/addyosmani/agent-skills
协议：MIT｜作者：Addy Osmani（Google Chrome 团队工程主管）

---

为什么会有这个项目

任何用过 Claude Code、Cursor、Copilot 的人，大概都遇到过同一种"翻车现场"：

你说「帮我加一个用户导出功能」，Agent 噼里啪啦写完代码、跑完了，潇洒地说「Done!」。但它没问你导出格式要不要兼容旧版本、没写测试、没考虑权限边界、提交的 diff 大到没人能 review。

这正是 Addy Osmani 在 README 里点出的问题——AI agent 默认会走最短路径，而资深工程师工作中真正值钱的部分，恰恰是那些「不出现在 diff 里」的工作：写 spec、拆任务、先写测试、做 code review、控制变更范围。

agent-skills 就是把这些「资深工程师的纪律」打包成 Agent 可以加载的 workflow，让它们从「建议」变成「强制流程」。

---

什么是「Skill」？

在 Anthropic 的术语里，Skill 是一个带 frontmatter 的 Markdown 文件，会在合适的时机被注入到 agent 的上下文里。它不是参考文档，也不是「关于 X 你应该知道的一切」——它是一个带验证步骤和退出条件的工作流。
打个比方：

类型	像什么	例子
普通 prompt	一句口号	“记得写测试”
参考文档	教科书	200 页的《单元测试最佳实践》
Skill	手术 checklist	“Step 1: 先写一个会失败的测试；Step 2: 跑测试，确认它失败；Step 3: 写最少的代码让它通过……”

每个 Skill 都按照统一的解剖结构（skill-anatomy）组织：

SKILL.md
├── YAML frontmatter（name + description）
├── Overview         —— 这个 skill 做什么
├── When to Use      —— 触发条件和场景
├── Core Process     —— 一步步的工作流
├── Examples         —— 代码示例和模式
├── Common Rationalizations  —— 常见的偷懒借口 + 反驳
├── Red Flags        —— skill 被违反的信号
└── Verification     —— 退出标准 checklist

其中最有意思的是 Common Rationalizations（常见借口）这一节——这是这套 skill 设计中最独特的地方。后面会专门讲。

---

20 个 Skills，覆盖完整软件开发生命周期

agent-skills 把 20 个核心 skills 映射到了软件开发的 6 个阶段：Define → Plan → Build → Verify → Review → Ship。

flowchart LR
    A[Define<br/>定义] --> B[Plan<br/>计划]
    B --> C[Build<br/>构建]
    C --> D[Verify<br/>验证]
    D --> E[Review<br/>评审]
    E --> F[Ship<br/>交付]

    A1[idea-refine<br/>spec-driven-development]
    B1[planning-and-task-breakdown]
    C1[incremental-implementation<br/>context-engineering<br/>source-driven-development<br/>frontend-ui-engineering<br/>test-driven-development<br/>api-and-interface-design]
    D1[browser-testing-with-devtools<br/>debugging-and-error-recovery]
    E1[code-review-and-quality<br/>code-simplification<br/>security-and-hardening<br/>performance-optimization]
    F1[git-workflow-and-versioning<br/>ci-cd-and-automation<br/>deprecation-and-migration<br/>documentation-and-adrs<br/>shipping-and-launch]

    A -.- A1
    B -.- B1
    C -.- C1
    D -.- D1
    E -.- E1
    F -.- F1

    style A fill:#e1f5ff
    style B fill:#fff4e1
    style C fill:#f0e1ff
    style D fill:#e1ffe9
    style E fill:#ffe1e1
    style F fill:#e1fff4

每个阶段的 skill 都解决一类典型问题：

• Define（定义）：很多人让 AI 直接写代码就翻车了。spec-driven-development 强制 agent 先输出 SPEC：列出它正在做的所有假设，让你纠正。「先 15 分钟讲清楚 spec，胜过事后 15 小时 debug」。

• Plan（计划）：把 feature 拆成一个个可独立验证的薄切片（thin vertical slice），而不是一口气写 1000 行。

• Build（构建）：包含 incremental-implementation、api-and-interface-design（贯彻 Hyrum 定律——“任何可观测的 API 行为都会被人依赖”）、frontend-ui-engineering 等。

• Verify（验证）：test-driven-development 强制 Red-Green-Refactor 循环；遇到 bug 时启用 Prove-It Pattern——必须先写一个能复现 bug 的失败测试，再去修。

• Review（评审）：包含 5 维度 code review 框架、code simplification（带「Chesterton’s Fence」原则——不要拆掉你不知道为什么存在的栅栏）、安全和性能审计。

• Ship（交付）：trunk-based development、CI/CD、feature flag、文档与 ADR、专门的废弃迁移流程（“代码是负债”）。

---

三个层次：Skill / Persona / Slash Command

理解这个项目还需要分清它的三层架构：

flowchart TB
    User[👤 用户/Slash Command<br/>编排者]

    subgraph Commands["Slash Commands —— What/When（入口）"]
        C1["/spec"]
        C2["/plan"]
        C3["/build"]
        C4["/test"]
        C5["/review"]
        C6["/ship"]
    end

    subgraph Personas["Personas —— Who（角色视角）"]
        P1[code-reviewer<br/>代码审查者]
        P2[security-auditor<br/>安全审计员]
        P3[test-engineer<br/>测试工程师]
    end

    subgraph Skills["Skills —— How（工作流）"]
        S1[test-driven-development]
        S2[security-and-hardening]
        S3[code-review-and-quality]
        S4[...更多 skills]
    end

    User --> Commands
    Commands --> Personas
    Commands --> Skills
    Personas --> Skills

    style User fill:#fff4cc
    style Commands fill:#cce4ff
    style Personas fill:#ffd9cc
    style Skills fill:#d4f1d4

• Skills（怎么做）：带步骤和退出条件的工作流，是必经之路。

• Personas（谁来做）：带视角和输出格式的角色——code-reviewer、security-auditor、test-engineer。

• Slash Commands（什么时机）：用户层入口，是真正的编排者。

最经典的组合是 /ship——它会并行扇出到三个 persona（code-reviewer、security-auditor、test-engineer），分别独立审查代码，最后由主 agent 合成一份 go/no-go 决策报告。Addy 在文档里特别强调，这是该 repo 唯一推荐的多 persona 编排模式：不要建造 router persona，编排是 slash command 的工作。

---

这个项目最聪明的设计：Anti-Rationalization

这是我读完整个 repo 觉得最值得学的一点。

每个 skill 文件里都有一节叫 Common Rationalizations——也就是「Agent 用来跳过重要步骤时常说的借口」，每一条配一个反驳。

举几个真实的例子：

Agent的借口	Skill里写的反驳
“这次很简单，先不写 spec 了”	简单任务确实不需要长 spec，但仍然需要验收标准。两行 spec 也是 spec。
“原型代码先不写测试，回头补”	原型会变成生产代码。Day 1 就写测试，避免后期"测试债危机"。
“再跑一次测试以防万一”	测试通过后，没改代码再跑一次毫无意义。改完再跑，不要靠重复运行获得心理安慰。
“我先静默选一个解释往下走”	不要做 yes-machine。遇到模糊点要 STOP，把困惑说出来再继续。

这种设计的精妙之处在于：它对抗的不是知识缺乏，而是行为漂移。一个前沿模型在训练数据里读过 Hyrum 定律，但它在凌晨 3 点设计你的 API 时不会应用它。Anti-rationalization 的存在，就是让模型在准备开溜时，能撞上一面写着「不行，你说过这话，但是……」的墙。

Addy 在他自己的博客里说，这个模式即使不用 AI，团队里也值得借鉴：把团队常说的自欺欺人话写下来，配上反驳。“我们 launch 后再修测试”——错，因为 launch 后没人会回来修。

---

它从 Google 工程文化里偷了什么

Addy 是 Google Chrome 团队的工程主管，所以这套 skills 里塞满了 Software Engineering at Google 一书和 Google 公开工程实践里的内容：

• Hyrum 定律 → 写在 api-and-interface-design 里：你 API 任何可观测的行为，最终都会有人依赖它。

• 测试金字塔（约 80/15/5）+ Beyoncé 法则 → 在 test-driven-development 里。“If you liked it, you should have put a test on it.”

• DAMP > DRY（在测试里） → 测试代码要像规范一样可读，宁可重复也不要过度抽象。生产代码 DRY，测试代码 DAMP。

• Chesterton’s Fence → 在 code-simplification 里：拆掉一个东西之前先理解它为什么存在。

• Trunk-based development → 在 git 工作流里。

• Shift Left + Feature flags → 在 CI/CD 里。

• 专门的 deprecation skill → 把"代码是负债"这件事变成纪律。

这些原则没有一个是新的。关键在于它们默认不在 agent 脑子里——skills 让它们成为 agent 必经的步骤。

---

怎么用？三种姿势

flowchart LR
    Start[选择你的接入方式] --> M1
    Start --> M2
    Start --> M3

    M1[Mode 1<br/>Marketplace 安装<br/>承诺度 ⭐⭐⭐]
    M2[Mode 2<br/>Markdown 直接拷贝<br/>承诺度 ⭐⭐]
    M3[Mode 3<br/>当成规范来读<br/>承诺度 ⭐]

    M1 --> R1[Claude Code 用户首选<br/>/plugin marketplace add<br/>addyosmani/agent-skills]
    M2 --> R2[Cursor → .cursor/rules/<br/>Gemini CLI、Windsurf<br/>各有 docs 指南]
    M3 --> R3[挑出团队最痛的 4-5 个 skill<br/>当成内部 best practices<br/>套到自家流程上]

    style M1 fill:#d4f1d4
    style M2 fill:#fff4cc
    style M3 fill:#ffd9cc

Mode 1：Claude Code 一键安装

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

装完就有了 /spec、/plan、/build、/test、/review、/ship、/code-simplify 七个 slash command，相关 skills 会根据上下文自动激活——你写 API agent 就触发 api-and-interface-design，你做 UI 就触发 frontend-ui-engineering。

Mode 2：拷到其它工具里

skills 是纯 markdown，Cursor 用户放进 .cursor/rules/，Gemini CLI、Windsurf 各有 docs 文件夹下的接入指南。

Mode 3：当成规范来读

这是 Addy 自己推荐起步的方式：就算一个 skill 都不装，把它当成「AI 时代的好工程长什么样」的成文描述。读 code-review-and-quality.md 拿它的 5 维度框架去优化你团队的 review 流程；读 test-driven-development.md 用来终结组里下一次「需不需要先写测试」的争论。

---

一些值得拿走的设计哲学

就算你完全不用 AI agent，这个项目里也有几个模式我觉得任何工程团队都该偷：

1. 流程胜于知识。“运行 npm test” 比 “请确保测试通过” 强一万倍。Skills 全部是动作，不是建议。

2. 退出标准要求证据。每个 verification checkbox 必须有可观测的证据（测试输出、构建结果、截图）。“我觉得没问题” 不算。

3. 每一节都要为存在辩护。如果删掉它不会改变 agent 行为，就删掉。Token 是预算，不是免费的。

4. 渐进披露。SKILL.md 是入口，扩展材料只在需要时才被加载——不要一次性把所有上下文塞进去。

5. 团队级 anti-rationalization 清单。把团队常对自己撒的谎写下来，每条配反驳。

---

最后

agent-skills 让我重新理解了一件事：资深工程师的工作正在被重新定义。

过去十年，“资深"约等于"会写复杂代码”。但当代码本身越来越便宜（agent 几秒就能写完），资深的真正价值就剩下了那些不出现在 diff 里的部分：surfacing assumption、写 spec、控制变更范围、留下可验证的证据、拒绝交付无法验证的东西。

agent-skills 把这些不可见的工作变成了 agent 必经的工作流。它不是一组 prompt，它是一份"AI 时代下，好工程师怎么工作"的活规范。

Repo 在这里：github.com/addyosmani/agent-skills （MIT 协议）。Addy 自己写的解读在 addyosmani.com/blog/agent-skills，比 README 多了很多设计动机。

无论你用不用 Claude Code，先把它当文档读一遍，都不会浪费时间。