Addy Osmani 的 agent-skills：给 AI 编程 Agent 装上资深工程师的工作流

发表于 分类于
Addy Osmani 开源的 agent-skills 是 78k stars 的明星项目，把资深工程师的开发流程（Spec→Plan→Build→Verify→Review→Ship）封装成 24 个 Markdown 技能和 8 个 Slash 命令，让 Claude Code、Cursor、Codex 等 AI Agent 真正按规范工作，而不是随机发挥。一次安装，全员升级。

一、当 AI Agent 写代码越来越像开盲盒

你有没有过这样的经历：让 Claude Code 写一个新功能，它哗哗给你撸了几百行代码，跑起来 ——TypeError: Cannot read property 'map' of undefined。你让它修，它改一处又崩三处。再让它加个测试，它直接把所有测试文件全删了重新生成一套。

问题不在模型，而在于流程。

人类资深工程师不会上来就写代码：他先要写 PRD、和需求方对齐、把任务拆成小块、写测试再写实现、跑 lint、跑 review、确认 OK 才上线。一个完整的开发流程里有十几个质量门禁，每一个都是” 前辈踩过的坑”。

而大多数 AI 编程 Agent 的工作方式是：接收 prompt → 直接生成代码。中间那些” 该问清楚再动手”、” 先写测试再写实现”、” 改之前先确认影响面” 的经验，它一条都没继承。

所以，Addy Osmani（Google Chrome 团队负责人）做了 agent-skills —— 把资深工程师的整套工作流封装成 24 个 Markdown 技能文件 + 8 个 Slash 命令，让 Claude Code、Cursor、Codex 等任何支持系统提示的 AI Agent 都能” 按规矩办事”。

今天 GitHub 上它狂揽 1,116 stars，总量突破 78k。今天就聊聊这个项目到底解决了什么、怎么用、有什么坑。

二、项目背景：从” 代码生成器” 到” 工程搭档”

addyosmani/agent-skills 的核心理念只有一句话：

Skills encode the workflows, quality gates, and best practices that senior engineers use when building software. These ones are packaged so AI agents follow them consistently across every phase of development.

它把整个软件开发生命周期抽象成六个阶段：

1
2
DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP
/spec  → /plan → /build → /test  → /review → /ship

每个阶段对应一个 slash 命令，命令会激活一组相关的技能文件。技能文件就是普通的 Markdown，里面写满了” 在该阶段应该做什么、避免什么、何时停止”。

这跟之前的”AI Agent 框架”（比如 LangChain、AutoGen）不是一个赛道。那些是帮你搭建 Agent；agent-skills 是帮你教育已经搭好的 Agent，让它按工程师的规矩工作。

对比维度 AutoGPT / LangChain agent-skills
解决问题 怎么让 LLM 变成 Agent Agent 怎么按规矩做事
形态 Python/TS 代码框架 24 个 Markdown 文件
学习曲线 几天到几周 几分钟
适配范围 自己的 Agent Claude Code/Cursor/Codex 等 70+ 工具
维护成本 高（依赖、版本、breaking change） 低（纯文本，可读可改）

三、24 个技能怎么工作

技能不是” 插件”，是上下文。Agent 启动时会读取相关的 skill 文件，把里面的规则注入到对话上下文里，然后按规则工作。

3.1 六大阶段的代表技能

DEFINE（定义阶段）

  • interview-me：当需求不清晰时，一次问一个问题，直到 95% 置信度才动手。
  • idea-refine：把模糊的想法通过发散 / 收敛思考变成具体提案。
  • spec-driven-development：写 PRD，覆盖目标、命令、目录结构、代码风格、测试、边界 —— 写代码之前必须先有 spec。

PLAN（计划阶段）

  • planning-and-task-breakdown：把 spec 拆成可执行的原子任务，每个任务带验收标准。

BUILD（构建阶段）

  • incremental-implementation：薄垂直切片（实现→测试→验证→提交），任何改动超过 1 个文件就要切片。
  • test-driven-development：强制 Red-Green-Refactor，测试金字塔 80/15/5，DAMP 优于 DRY。
  • context-engineering：在正确的时间喂给 Agent 正确的信息（rules 文件、MCP）。
  • source-driven-development：框架决策必须基于官方文档，标注引用，未验证的标黄。
  • doubt-driven-development：对抗式 review（CLAIM→EXTRACT→DOUBT→RECONCILE→STOP），用于高风险 / 不可逆操作。
  • frontend-ui-engineering：组件架构、设计系统、WCAG 2.1 AA 可访问性。
  • api-and-interface-design：契约先行、Hyrum’s Law、One-Version Rule、错误语义。

VERIFY（验证阶段）

  • browser-testing-with-devtools：通过 Chrome DevTools MCP 拿实时运行数据。
  • debugging-and-error-recovery：五步定位（复现→定位→最小化→修复→防回归），stop-the-line 规则。

REVIEW（审查阶段）

  • code-review-and-quality：五维评审（正确性 / 可读性 / 可维护性 / 性能 / 安全）。
  • simplify-code：可读性优于巧技，删除冗余。

SHIP（上线阶段）

  • webperf-audit：先测量后优化（Core Web Vitals）。
  • continuous-deployment：渐进式发布、特性开关、快速回滚。

Meta（元技能）

  • using-agent-skills：进会话先看这个，决定后续用哪个技能。

3.2 8 个 Slash 命令

命令是技能集的快捷入口：

1
2
3
4
5
6
7
8
9
/spec        # 把需求变成 PRD
/plan        # 把 PRD 拆成原子任务
/build       # 增量实现（一次一片）
/build auto  # 一次过：生成 plan + 实现 + 验证 + 提交
/test        # 写测试、跑测试
/review      # 五维代码评审
/webperf     # Web 性能审计
/code-simplify  # 简化代码
/ship        # 灰度发布

/build auto 是杀手锏：你审批一次 plan，剩下的实现→测试→提交全自动跑，Agent 只在失败或高风险步骤停下来问你。

四、实战示例：5 分钟装好

4.1 装到 Claude Code（推荐）

1
2
3
4
5
6
7
# 通过 Marketplace 装
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

# 或者本地装（开发调试用）
git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills

如果你没配 SSH key，marketplace 装可能报错。两条路：

  1. 加 SSH key。
  2. 强制 HTTPS：
    1
    git config --global url."https://github.com/".insteadOf "git@github.com:"

4.2 装到 Cursor

1
2
# 把技能文件复制到 .cursor/skills/
# 短规则放 .cursor/rules/*.mdc（不要把完整 skill 塞进 rules）

详细配置见仓库 docs/cursor-setup.md。

4.3 装到 Gemini CLI / Codex / Antigravity

1
2
3
4
5
6
7
8
# Gemini CLI
gemini skills install https://github.com/addyosmani/agent-skills.git --path skills

# Codex (CLI v0.122+)
codex plugin marketplace add addyosmani/agent-skills

# Antigravity
agy plugin install https://github.com/addyosmani/agent-skills.git

4.4 一次性装到 70+ Agent

Vercel Labs 的 skills CLI 已经把 agent-skills 收录：

1
2
3
npx skills add addyosmani/agent-skills
# 装单个技能
npx skills add addyosmani/agent-skills --skill code-review-and-quality

4.5 第一次使用

装好后，进 Claude Code 直接说：

“用 spec-driven-development 帮我做一个 CLI 工具，把 Markdown 转成飞书文档。”

你会观察到：

  1. Agent 先问你几个澄清问题（interview-me 激活）。
  2. 输出一份 PRD 让你确认（spec-driven-development）。
  3. PRD 通过后，它把任务拆成原子单元（planning-and-task-breakdown）。
  4. 一步步实现，每步带测试（incremental-implementation + test-driven-development）。
  5. 完事跑 code-review-and-quality 自审一遍。

跟之前” 上来就写” 的体验完全是两个物种。

五、与同类项目的对比

GitHub trending 上跟它相关的还有几个项目，定位差异：

项目 定位 与 agent-skills 的关系
obra/superpowers (252k stars) 完整的 Agentic Skills 框架 + 软件开发方法论 更重、更哲学，agent-skills 更轻、更工程
mattpocock/skills (165k stars) 真实工程师的 .claude 目录技能集 互补：可以同时装，Matt 偏个人风格，Addy 偏团队规范
vercel-labs/skills 跨平台 skills 安装 CLI 是 agent-skills 的安装器，不替代它
claude-code-templates (28k stars) Claude Code 配置模板 + 监控 偏配置管理，agent-skills 偏行为规范

实际项目里，可以 agent-skills + mattpocock/skills + vercel-labs/skills 三件套一起装，互不冲突：前者定规矩、中者补风格、后者管分发。

六、适用场景和限制

6.1 适合用

  • 团队新成员（包括 AI Agent）需要快速对齐工程规范。
  • 中大型重构：spec → plan → incremental 三连，避免 Agent 一次性输出几千行不可读的代码。
  • 多人协作：所有人（人 + Agent）跑同一套 spec-driven-development，PRD 成为单一事实源。
  • 生产级项目：把 80/15/5 测试金字塔、WCAG 2.1 AA、Core Web Vitals 这些质量门禁沉淀进 skill，新需求自动触发。

6.2 不太适合

  • 一次性脚本 / Demo：上 spec-driven-development 是杀鸡用牛刀，直接 /build 就行。
  • 极小改动（改个 typo、调整文案）：激活完整 skill 流反而拖慢。
  • 需要大量自定义公司内部流程：技能是通用工程实践，公司内部合规、审计流程得自己改 skill。

6.3 已知坑

  1. Skill 是纯 Markdown，没有版本约束。技能更新后，老项目里的 Agent 可能行为不一致。建议把 skill 文件纳入版本控制，固定某个 commit/tag。
  2. Token 消耗上升。24 个 skill 全开，每个会话都会带几千 token 的上下文。生产环境推荐只激活当下需要的几个。
  3. Skill 不等于”AI 会自我反思”。doubt-driven-development 是工具，不是银弹 —— 遇到真正的伦理、架构分歧，Agent 还是会猜。
  4. 跨 Agent 兼容。Slash 命令的触发机制因 Agent 而异（Claude Code 是 /，Cursor 是命令面板，Gemini CLI 是 /，Codex 是 @），同一套 skill 行为可能微妙不同。

七、总结

addyosmani/agent-skills 解决了一个被忽视的问题：AI Agent 不缺能力，缺规矩。

它没有引入新的框架、没有训练新的模型，就是把” 资深工程师怎么做软件” 这件事写成了 24 个 Markdown 文件。然后让任何 AI Agent 在合适的时机读它们、按它们工作。

这件事的价值怎么强调都不过分 ——

我们已经有了越来越强的模型（Claude 4、GPT-5、Gemini 2.5），但生产事故的根因分析里，流程缺失永远排在模型能力不足前面。agent-skills 就是在补这个缺口。

如果你团队正在大规模使用 AI 编程工具，今天花 5 分钟装一下，明天就会发现：

  • Agent 不会上来就动代码了，会先问清楚。
  • 提交前会自己跑测试、做 review。
  • 改了 100 行代码，会自动拆成 5 个独立 commit。
  • PRD 永远是单一事实源。

这不是 Agent 变聪明了，是它终于学会按规矩出牌了。

🔗 项目地址：github.com/addyosmani/agent-skills
⭐ 78k stars | MIT 协议 | 8.3k forks | 最近一次发布 v0.6.4（2026-07-12）