addyosmani/agent-skills 保姆级部署教程：生产级工程化 Agent 技能包
一句话定位：GitHub 开源项目
addyosmani/agent-skills是 Google Chrome 团队 Addy Osmani 出品的面向 AI 编程智能体的生产级工程化技能包——把资深工程师在写代码前定 spec、拆任务、写测试、做代码评审、上生产时的整套工作流，封装成 25 个结构化 SKILL.md 工作流，让 Claude Code、Cursor、Codex、Gemini CLI 等任意智能体在每个开发阶段都按同一套工程纪律跑。slogan：Production-grade engineering skills for AI coding agents.
仓库地址：https://github.com/addyosmani/agent-skills · 许可证：MIT · ⭐ 112,247 · 维护者：Addy Osmani、Federico Bartoli、Joan León
▲ 图 0：addyosmani/agent-skills 官方 README 横幅（Define → Plan → Build → Verify → Review → Ship 六阶段流水线）与 Trendshift 趋势徽章（官方截图）
一、项目简介
AI 编程智能体默认走最短路径——跳过 spec、跳过测试、跳过安全评审，直接产出能跑但不可靠的代码。Agent Skills 要解决的就是这件事：它把资深工程师脑子里那套「什么时候该写 spec、测试要写到什么程度、代码怎么评审、什么时候才敢上生产」的判断，固化成 25 个结构化工作流，每个工作流都有步骤、检查点、证据要求和「反合理化」对照表（专门拆穿智能体「我待会再补测试」这类借口）。
这套技能包不是又一个提示词合集，而是一整套从 Google 工程文化里提炼出来的方法论：API 设计里的 Hyrum's Law、测试里的 Beyonce Rule 与测试金字塔、代码评审里的变更粒度（约 100 行）、简化里的 Chesterton's Fence、Git 流程里的主干开发、CI/CD 里的 Shift Left 与 Feature Flag、废弃流程里「代码即负债」的心智，全部直接嵌入智能体逐步执行的工作流里。
项目以 MIT 许可证开源，维护者 Addy Osmani 是 Google Chrome 团队工程主管；技能包本身是纯 Markdown，任何能加载系统提示词或指令文件的智能体都能用，并对 Claude Code、Cursor、Codex、Gemini CLI、Copilot、Antigravity、Windsurf、OpenCode、Kiro、Command Code 等主流宿主提供了原生集成适配器。
二、功能特点
| 能力 | 说明 |
|---|---|
| 🧩 25 个结构化技能 | 24 个生命周期技能 + 1 个 meta 技能（using-agent-skills），覆盖 Define / Plan / Build / Verify / Review / Ship 全阶段 |
| ⌨️ 9 条斜杠命令 | /spec、/plan、/build、/test、/constraints、/review、/webperf、/code-simplify、/ship，一键激活对应技能 |
| 🤖 /build auto 全自动 | spec 就绪后，一次批准计划，智能体自动生成计划并逐个任务实现，每个任务仍走测试驱动并独立提交，失败或高风险步骤自动暂停 |
| 🚫 反合理化表 | 每个技能内置「借口 vs 反驳」对照表，专门拆穿「我待会补测试」「这段代码太简单不用测」这类跳过步骤的话术 |
| ✅ 验证不可妥协 | 每个技能结尾都有证据要求——测试通过、构建产物、运行时数据；「看起来对」不算数 |
| 🎭 4 个专家人格 | code-reviewer（资深工程师）、test-engineer（QA 专家）、security-auditor（安全工程师）、web-performance-auditor（Web 性能工程师），按需组合 |
| 📚 7 份参考清单 | Definition of Done、测试模式、安全清单、性能清单、无障碍清单、可观测性清单、编排模式，技能按需加载以省 token |
| 🔌 70+ 智能体通用 | 通过 Vercel Labs 的 skills CLI 一条命令装进任意智能体；同时提供 Claude Code / Cursor / Codex / Gemini CLI 等原生适配器 |
| 🧠 渐进式披露 | SKILL.md 是入口，补充资料仅在需要时加载，避免一次性吃掉大量上下文窗口 |
| 📖 源驱动开发 | 每个框架决策都以官方文档为依据，验证过的写出来、未验证的明确标注，不依赖模型记忆 |
2.1 25 个技能一览
| 阶段 | 技能 | 做什么 |
|---|---|---|
| Meta | using-agent-skills | 把进来的工作路由到对应技能，并定义共享操作规则 |
| Define | interview-me | 一次一个问题地访谈，直到约 95% 置信度提取出真实需求 |
| idea-refine | 发散/收敛结构化思考，把模糊想法变成具体提案 | |
| spec-driven-development | 动代码前先写 PRD：目标、命令、结构、代码风格、测试、边界 | |
| constraint-driven-development | 访谈出质量基线并写进 CONSTRAINTS.md，防止智能体为变绿而跳过检查 | |
| Plan | planning-and-task-breakdown | 把 spec 拆成可验证的小任务，带验收标准与依赖排序 |
| Build | incremental-implementation | 薄垂直切片：实现-测试-验证-提交，Feature Flag、安全默认、可回滚 |
| test-driven-development | 红-绿-重构，测试金字塔 80/15/5，DAMP 优于 DRY，Beyonce Rule | |
| context-engineering | 在正确时间给智能体喂正确信息：规则文件、上下文打包、MCP 集成 | |
| source-driven-development | 每个框架决策都以官方文档为依据，验证过、引来源、标注未验证 | |
| doubt-driven-development | 对抗式 fresh-context 复审：CLAIM→EXTRACT→DOUBT→RECONCILE→STOP，可跨模型升级 | |
| frontend-ui-engineering / api-and-interface-design | 组件架构与 WCAG 2.1 AA 无障碍；契约优先 API 设计、Hyrum's Law、错误语义 | |
| Verify | browser-testing-with-devtools | Chrome DevTools MCP 抓 DOM、console、网络、性能曲线 |
| debugging-and-error-recovery | 五步分诊：复现、定位、缩小、修复、防护；Stop-the-line 规则 | |
| Review | code-review-and-quality | 五轴评审、约 100 行变更粒度、Nit/Optional/FYI 严重度标签 |
| code-simplification | Chesterton's Fence、Rule of 500，在保留行为前提下降复杂度 | |
| security-and-hardening | OWASP Top 10、鉴权模式、密钥管理、依赖审计、三层边界 | |
| performance-optimization | 先测后优，Core Web Vitals 目标、Profiling、Bundle 分析、反模式检测 | |
| Ship | git-workflow-and-versioning | 主干开发、原子提交、变更粒度约 100 行、commit 即存档点 |
| ci-cd-and-automation | Shift Left、Faster is Safer、Feature Flag、质量门流水线、失败反馈环 | |
| deprecation-and-migration | 代码即负债：强制/建议式废弃、迁移模式、僵尸代码清理 | |
| documentation-and-adrs | 架构决策记录（ADR）、API 文档、内联注释——写清 why 而不是 what | |
| observability-and-instrumentation | 结构化日志、RED 指标、OpenTelemetry 追踪、症状式告警 | |
| shipping-and-launch | 上线前清单、Feature Flag 生命周期、灰度发布、回滚流程、监控 |
三、环境要求
- 运行时：技能包本体是纯 Markdown，不需要编译、不依赖运行时。走通用 CLI 路线需要本机有 Node.js（用于执行
npx skills）；走 Claude Code / Codex / Gemini CLI / Antigravity 等原生插件路线，只需要对应宿主本身。 - 宿主：任选其一——Claude Code（官方推荐）、Cursor、Codex CLI v0.122+、Gemini CLI、GitHub Copilot、Antigravity CLI、Windsurf、OpenCode、Kiro IDE/CLI、Command Code，或任何能加载系统提示词/指令文件的智能体。
- 网络：首次安装需能访问 GitHub（
raw.githubusercontent.com与github.com）；npm 路线需能访问 npm registry。 - Git：走 Claude Code marketplace 或 Codex marketplace 路线时，marketplace 默认通过 SSH 克隆仓库；未配置 GitHub SSH Key 的用户需改用 HTTPS 克隆或做 URL 重写（见下文）。
- 磁盘：仓库本体含 25 个技能 + 4 个人格 + 7 份清单 + 文档，整体体量很小，几十 MB 级别。
四、保姆级部署步骤
4.1 通用一键安装（推荐新手，任何智能体都能用）
Vercel Labs 开源的 skills CLI 是最快路径，一条命令把全部 25 个技能装进 70+ 智能体（Claude Code、Cursor、Codex、Copilot、Cline 等）：
npx skills add addyosmani/agent-skills # 安装全部 25 个技能
npx skills add addyosmani/agent-skills --list # 先浏览清单再决定装哪些只想装某几个技能也行：
npx skills add addyosmani/agent-skills --skill code-review-and-quality # 合并前五轴评审
npx skills add addyosmani/agent-skills --skill interview-me # 一次一个问题访谈需求
npx skills add addyosmani/agent-skills --skill test-driven-development # 红-绿-重构，强制执行注意：单技能
npx安装只会拷贝skills/<name>/，不会带上仓库级references/目录。技能本体仍可用，但指向共享检查清单的路径会断。要避免这个移植性缺口，要么整库安装、要么 git clone 后把需要的 checklist 复制进已安装技能目录下的references/。该缺口在官方 issue #361 中跟踪。
4.2 Claude Code 原生安装（官方推荐）
Claude Code 是这套技能的一等公民宿主，技能会作为插件命令注册。在 Claude Code 对话框里执行：
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills如果在 Windows / macOS 上遇到 git@github.com: Permission denied (publickey)，说明你没配 GitHub SSH Key。两种解决办法任选其一：
办法 A——marketplace 步骤直接用 HTTPS 完整 URL（在仓库地址后加 .git）：
/plugin marketplace add <HTTPS 完整仓库 URL，末尾加 .git>
/plugin install agent-skills@addy-agent-skills办法 B——一次性配置 Git 把所有 GitHub SSH 重写成 HTTPS（推荐，对所有子进程克隆生效）：
git config --global url."https://github.com/".insteadOf git@github.com:本地开发模式（从 clone 直接加载，不进 marketplace）：
git clone <HTTPS 完整仓库 URL>
claude --plugin-dir /path/to/agent-skills4.3 Codex CLI 安装
Codex CLI v0.122+ 支持原生插件：
codex plugin marketplace add addyosmani/agent-skills
codex plugin add agent-skills@agent-skills第一条注册 marketplace，第二条安装插件。Codex 直接通过 .codex-plugin/plugin.json 读取根目录 skills/。安装后在对话里用 @ 触发技能，例如 @spec-driven-development。
4.4 Gemini CLI 安装
gemini skills install <HTTPS 完整仓库 URL> --path skills
# 或从本地 clone 安装：
gemini skills install ./agent-skills/skills/装好后会自动发现；也可以把要点写进 GEMINI.md 作为常驻上下文。
4.5 Antigravity CLI 安装
# 从仓库安装
agy plugin install <HTTPS 完整仓库 URL，末尾加 .git>
# 或从本地 clone 安装
git clone <HTTPS 完整仓库 URL>
agy plugin install ./agent-skills注意：受影响的 Antigravity CLI 版本中，legacy 命令 TOML 会被报告为已转换，但 wrapper 命令不可被发现；直接调用底层 namespaced 技能即可。
4.6 Command Code 安装
cmd skills add addyosmani/agent-skills # 选择要装的技能（项目级）
cmd skills add addyosmani/agent-skills --global # 装到全局 ~/.commandcode/skills/
cmd skills add addyosmani/agent-skills -s spec-driven-development # 只装单个技能装完后技能会出现在 TUI 斜杠菜单里，例如 /spec-driven-development。
4.7 Cursor / Windsurf / OpenCode / Copilot / Kiro
- Cursor：把工作流技能放到
.cursor/skills/（从agent-skills/skills/同步），短策略放.cursor/rules/*.mdc——不要把完整技能粘进 rules。详见仓库docs/cursor-setup.md。 - Windsurf：把技能内容加进 Windsurf 规则配置，详见
docs/windsurf-setup.md。 - OpenCode：把技能复制到
.opencode/skills/（或~/.config/opencode/skills/），加项目级AGENTS.md，用内置skill工具驱动；可选在.opencode/commands/加斜杠命令。详见docs/opencode-setup.md。 - GitHub Copilot：把
agents/下的人格作为 Copilot 角色，把技能内容写进.github/copilot-instructions.md。生命周期斜杠命令是 Claude Code 专属，Copilot 里直接用技能名触发（如/spec-driven-development）。独立 copilot CLI 见docs/copilot-cli-setup.md。 - Kiro IDE/CLI：技能放
.kiro/skills/，可项目级或全局；Kiro 同时支持AGENTS.md。
五、配置说明
技能包本体无需任何配置即可工作。几个常用的项目级增强点：
- CONSTRAINTS.md：跑一次
/constraints，智能体会访谈你一个质量基线（测试覆盖率、lint 严格度、依赖审计频率等），写成项目根的CONSTRAINTS.md，之后每次提交都会被这道质量门卡住，防止智能体为了让测试变绿而跳过检查。 - AGENTS.md / GEMINI.md / copilot-instructions.md：把项目的命令、目录结构、常用命令写进这些常驻文件，等价于给所有智能体喂同一份「项目说明书」，这是
context-engineering技能的核心动作。 - Claude Code 命名空间：当宿主自带命令与技能命令同名时（例如 Claude Code 自带
/review），用命名空间形式调用：/agent-skills:review。 - 高级 per-agent 配置：需要给不同模型路由、工具白名单等运行时控制时，参考
docs/advanced-per-agent-configuration.md，在不破坏可移植SKILL.mdfrontmatter 的前提下做扩展。
六、使用方法
6.1 走完整生命周期
新项目或大改动，按六阶段顺序触发即可：
/spec # 写 PRD：目标、命令、结构、代码风格、测试、边界
/plan # 把 PRD 拆成可验证小任务
/build # 一次实现一个垂直切片（实现-测试-验证-提交）
/test # 用测试证明它真的工作
/review # 合并前五轴评审
/ship # 灰度发布、回滚预案、监控接入想省掉中间的人工确认？spec 写好后直接跑 /build auto：你只批一次计划，智能体自动生成计划并逐个任务实现——每个任务仍走测试驱动、单独提交，遇到失败或高风险步骤会自动暂停等你决策。它省掉的是「任务之间的人工步进」，不是「验证本身」。
6.2 让技能自动触发
除了显式斜杠命令，技能也会根据你正在做的事自动激活：设计 API 触发 api-and-interface-design、写 UI 触发 frontend-ui-engineering、调试浏览器触发 browser-testing-with-devtools。Meta 技能 using-agent-skills 会在会话开始时把进来的工作路由到最合适的技能。
6.3 用专家人格做定向评审
| 人格 | 视角 | 什么时候叫 |
|---|---|---|
| code-reviewer | 资深工程师五轴评审 | 合并前任何改动 |
| test-engineer | 测试策略、覆盖分析、Prove-It | 改动涉及逻辑或修 bug |
| security-auditor | 漏洞检测、威胁建模、OWASP | 涉及用户输入、鉴权、外部集成 |
| web-performance-auditor | Core Web Vitals 审计（Quick/Deep） | 跑 /webperf，怀疑性能回归时 |
编排规则见 docs/agents.md；「人格不调用人格」是硬规则，防止评审者再拉评审者形成递归。
6.4 增量落地到既有项目
不是所有项目都适合第一天就上完整生命周期。仓库 docs/adoption-guide.md 给了两条路：绿地项目直接走完整六阶段；已有代码库走「先验证、再增量」——先上 code-review-and-quality 与 test-driven-development 两道门，再逐步把 spec、constraints、observability 接进来。
七、常见问题 FAQ
问一：装了之后和我直接用 Claude Code 有什么区别？是不是只是多了几个 prompt？
答：不是。它把资深工程师的工作流结构化成带步骤、检查点、证据要求的工作流，每个技能都内置「反合理化」对照表（专门拆穿「我待会补测试」「这段太简单不用测」）。更关键的是 verification 不可妥协——每个技能结尾都要求证据（测试通过、构建产物、运行时数据），「看起来对」不算交付。
问二：在 Claude Code 里敲 /review 为什么没反应？
答：Claude Code 自带一个同名 /review 命令，和技能包里的命令冲突。用命名空间形式调用：/agent-skills:review。其他命令（/spec、/plan、/build 等）没有冲突，直接用即可。
问三：npx 单技能安装后 references 路径断了，怎么修？
答：单技能安装只会拷贝 skills/<name>/，不会带仓库级 references/。三种解法：①整库安装而不是单技能；②git clone 仓库后从源码目录加载；③手工把需要的 checklist 复制进已安装技能目录下的 references/。这个移植性缺口在 issue #361 里跟踪。
问四：Claude Code marketplace 安装报 git@github.com Permission denied publickey？
答：marketplace 默认走 SSH 克隆，你机器没配 GitHub SSH Key。两种办法：①marketplace 步骤改用完整 HTTPS URL（仓库地址后加 .git）；②一次性全局重写 git config --global url."https://github.com/".insteadOf git@github.com:，之后所有子进程克隆都走 HTTPS。
问五：25 个技能全装上会不会很吃上下文？
答：设计上就是为了省 token——渐进式披露（progressive disclosure）：SKILL.md 是入口，补充资料（7 份参考清单、4 个人格）只在被技能引用时才加载。如果你是新项目想轻量起步，先装 code-review-and-quality + test-driven-development + using-agent-skills 三个，按 adoption guide 增量铺开即可。
问六：和 obra/superpowers、Matt Pocock's skills 有什么区别？
答：仓库 docs/comparison.md 给了诚实的三方对比：agent-skills 更偏「生产级工程纪律」（Google 工程文化、质量门、反合理化表），superpowers 更偏「通用编码方法论」，Matt Pocock's 更偏 TypeScript 专家视角。文档里还附了一场受控 head-to-head 实验的链接。
相关链接
- 项目仓库：addyosmani/agent-skills
- 通用安装 CLI（Vercel Labs skills）：vercel-labs/skills
- Adoption Guide（落地路线）：docs/adoption-guide.md
- 三方对比：docs/comparison.md
- 技能格式规范：docs/skill-anatomy.md
- 高级 per-agent 配置：docs/advanced-per-agent-configuration.md
- Cursor 接入：docs/cursor-setup.md
- Codex 接入：docs/codex-setup.md
- Gemini CLI 接入：docs/gemini-cli-setup.md
- 团队主页（Addy Osmani）：addyosmani.com
- Google 工程实践参考：Google Engineering Practices