给 Claude Code 装上工程纪律：agent-skills 插件实战指南

Addy Osmani 的 agent-skills 把 Claude Code 从”写最短代码”调教成”守工程纪律”——20 个 skill、7 条斜杠命令、3 个 agent persona 的完整落地指南。

发布于 2026-04-22 · 更新于 2026-04-22

AI 写代码很快，但最短路径通常意味着跳过 spec、跳过测试、跳过 review。agent-skills（Addy Osmani 出品）把资深工程师的纪律编码成 Claude Code 可执行的流程——20 个 skill、7 条斜杠命令，覆盖从”想法”到”上线”的完整生命周期。

---

一、为什么需要这个插件

用 Claude Code 一段时间后，你大概率熟悉这些场景：

• 任务一丢，它直接开写，写到一半才发现需求理解偏了
• 改了 A，B 悄悄坏了——因为没测试
• 说”完成了”，但功能从没跑通过
• Bug 反复修，每次都在猜

不是模型能力不够，是工程纪律缺失。

agent-skills 的做法：把 senior engineer 的每个工作习惯——写 spec、定任务粒度、TDD、五轴 review、灰度发布——拆成独立的 skill，用斜杠命令串成流水线。Claude Code 加载后，默认按这条流水线走。

---

二、一张图看懂全貌

  DEFINE          PLAN           BUILD          VERIFY         REVIEW          SHIP
 ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐
 │ Idea │ ───▶ │ Spec │ ───▶ │ Code │ ───▶ │ Test │ ───▶ │  QA  │ ───▶ │  Go  │
 │Refine│      │  PRD │      │ Impl │      │Debug │      │ Gate │      │ Live │
 └──────┘      └──────┘      └──────┘      └──────┘      └──────┘      └──────┘
  /spec          /plan          /build        /test         /review       /ship

六个阶段对应七条斜杠命令（REVIEW 阶段多一条 /code-simplify）。每条命令背后自动激活相关 skill。

---

三、10 分钟装上并跑通

安装

在 Claude Code 里执行：

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

重启会话后，/spec、/plan、/build、/test、/review、/code-simplify、/ship 七条命令可用。

SSH 报错？ 插件市场默认用 SSH 拉仓库。没配 SSH key 的话，改用 HTTPS：

git config --global url."https://github.com/".insteadOf "[e-mail]:"

跑通一个最小 demo

建个空目录，新开 Claude Code 会话，输入：

/spec 做一个命令行天气查询工具，输入城市，输出当前温度和天气

Claude 会先列出它正在做的假设（“假设用 Node.js + 公开 OpenWeather API，假设只支持英文城市名…”），让你纠正或确认。确认后生成一份完整 SPEC.md，包含：

• Objective（目标和用户）
• Commands（完整的 build / test / dev 命令）
• Project Structure（目录布局）
• Code Style（一段真实代码片段示范）
• Testing Strategy（测试框架和覆盖预期）
• Boundaries（Always / Ask first / Never 三层边界）

然后 /plan 把 spec 拆成可执行任务；/build 进入 TDD 循环一个一个做。整条流水线跑下来，项目根目录会多出 SPEC.md、tasks/plan.md、tasks/todo.md 几个”工作产物”——进版本控制，让人和 agent 共享事实源。

---

四、仓库里有什么

agent-skills/
├── skills/               # 20 个核心 skill（每个一个子目录 + SKILL.md）
├── agents/               # 3 个 staff-engineer 级 persona
├── references/           # 4 份速查清单（测试/安全/性能/可访问性）
├── hooks/                # session 生命周期钩子
└── .claude/commands/     # 7 条斜杠命令

四个目录各司其职：

目录	角色	你和它打交道的方式
skills/	流水线的”工序”	被斜杠命令自动调用，也可直接引用
agents/	特殊场景的”角色扮演”	需要某种视角的深度 review 时手动调
references/	skill 需要时才翻的”附录”	很少直接用，skill 按需加载
.claude/commands/	流水线的”触发器”	日常主要靠它

---

五、七条斜杠命令怎么用

/spec — 先想清楚再写代码

场景：新项目、新功能、需求模糊时。

触发后 Claude 先问关键问题（目标、用户、技术栈、边界），然后产出 SPEC.md。核心技巧是先浮现假设：

ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies (not JWT)
3. The database is PostgreSQL
→ Correct me now or I'll proceed with these.

还有把模糊需求翻译成可验证标准："make the dashboard faster" 会被翻成 LCP < 2.5s, CLS < 0.1，让你点头或修正。

/plan — 把 spec 拆成能做的任务

场景：spec 确定后，下手前。

产出 tasks/plan.md，每个任务带 acceptance criteria 和验证方式，按依赖排序，每个任务触及文件控制在 5 个以内。

/build — 增量实现 + TDD

场景：开始写代码。

这是 7 条命令里最值回票价的一条。它同时激活 incremental-implementation 和 test-driven-development 两个 skill，每个任务走一遍：

读 acceptance → 写失败测试 (RED) → 最小实现通过 (GREEN)
  → 跑全量测试检查回归 → 构建验证 → 带消息 commit → 下一个

任何环节失败，自动切到 debugging-and-error-recovery skill 做五步定位：reproduce → localize → reduce → fix → guard。

/test — 给已有代码补测试

场景：修 bug 或给没测试的代码补保护。

关键技巧是 Prove-It Pattern：bug 报告到达后不要先修，先写一个复现 bug 的测试让它失败；再修代码让测试通过。这样修复和回归保护一步到位。

/review — 五轴 review + 严重度标签

场景：合并前。

对改动按五个维度评分：Correctness / Readability / Architecture / Security / Performance。每条反馈自动带严重度标签：

标签	含义
Critical:	阻塞合并（安全漏洞、数据丢失）
(无前缀)	必改
Optional:	建议
Nit:	可忽略（格式、风格偏好）
FYI:	仅供参考

这套标签体系直接能抄进团队 PR 模板，避免”所有反馈都像必改”的心智负担。

/code-simplify — 减法

场景：代码能跑，但读起来累。

核心原则是 Chesterton’s Fence（不理解围栏为什么在那就别拆）和 Rule of 500（1000 行能 100 行做完就是失败）。只砍复杂度，不改行为。

/ship — 发布清单

场景：准备部署生产。

会按清单过一遍：feature flag 是否就位、灰度策略、回滚方案、监控告警、文档同步。原则是 Faster is safer——小批量、频繁、可回滚，比积攒大版本安全得多。

---

六、20 个 skill 按阶段速览

斜杠命令只是入口，背后是 20 个具体 skill。你可以绕过命令直接引用任何一个。

Define（2）

• idea-refine——散发/收敛式提问把模糊想法变具体
• spec-driven-development——六区块 PRD，带人审关卡

Plan（1）

• planning-and-task-breakdown——任务拆到”单次专注可完成”粒度

Build（6）

• incremental-implementation——纵向切片、feature flag、可回滚
• test-driven-development——RED/GREEN/REFACTOR + 测试金字塔 80/15/5
• context-engineering——按任务加载上下文，不要塞爆
• source-driven-development——每个框架决定都要引官方文档
• frontend-ui-engineering——组件架构 + WCAG 2.1 AA 无障碍
• api-and-interface-design——契约优先、Hyrum’s Law、错误语义

Verify（2）

• browser-testing-with-devtools——走 Chrome DevTools MCP 抓真运行时数据
• debugging-and-error-recovery——五步定位 + Stop-the-line

Review（4）

• code-review-and-quality——五轴 + 严重度标签 + change sizing
• code-simplification——Chesterton’s Fence + Rule of 500
• security-and-hardening——OWASP Top 10 + 三层边界
• performance-optimization——先测量再优化，Core Web Vitals 目标

Ship（5）

• git-workflow-and-versioning——主干开发，~100 行原子 commit
• ci-cd-and-automation——Shift Left + 质量门 + feature flag
• deprecation-and-migration——把代码当负债，主动废弃
• documentation-and-adrs——架构决策记录（ADR）
• shipping-and-launch——发布前清单、灰度、回滚流程

---

七、三个 agent persona 怎么调

斜杠命令给你流水线，persona 给你视角。合并前想要一个更挑剔的 review 时手动调：

Persona	视角	什么时候调
code-reviewer	资深 staff engineer	任何改动合并前——默认五轴 review
test-engineer	QA 专家	测试策略评估、覆盖率分析、补测试
security-auditor	安全工程师	处理用户输入、认证、对外 API 时

典型调法：

Use the security-auditor persona to review this PR for OWASP Top 10 issues.

Claude 会切换成该角色输出，包括 Verdict（APPROVE / REQUEST CHANGES）、Critical / Important / Suggestion 三档 issue、以及”做得好的地方”。直接能贴进 PR 评论。

---

八、一个隐藏亮点：anti-rationalization

agent-skills 最独特的设计不是斜杠命令，是每个 SKILL.md 里的反借口表。

AI 跳步骤时不是”忘了”，而是”主动合理化”：

• “这个任务很简单，不需要 spec”
• “测试一会儿补”
• “这个边界 case 应该不会发生”

test-driven-development skill 里直接写了针对这些借口的反驳：

借口	反驳
”我先写实现再补测试”	那是事后验证，不是 TDD。测试的价值在于先定义正确 = 什么
”这改动太小不用测试”	Beyonce Rule：你喜欢它，就该给它加测试。基础设施改动不负责抓你的 bug
”已经手动验证过了”	手动验证不防回归。下次有人改动它你不会知道

spec-driven-development 也一样：

借口	反驳
”这个简单，不需要 spec”	简单任务不需要长 spec，但仍需 acceptance criteria。两行 spec 也行
”Spec 会拖慢速度”	15 分钟 spec 预防数小时返工
”需求会变”	所以 spec 是 living document。过期 spec 也比没 spec 好

这个设计相当于在 prompt 层给 Claude 打了一针反偷懒疫苗——每次它想走捷径时，反驳已经在同一文档里等着。值得单独拆一篇博客研究。

---

九、我的落地建议

最小可用子集：只开三个，覆盖 AI 辅助开发最关键的质量缺口——

1. spec-driven-development——定义要做什么
2. test-driven-development——证明它工作
3. code-review-and-quality——合并前验证质量

对应只用 /spec、/build、/review 三条命令，其他命令需要时再引。

和团队流程对齐：

• 把 /review 的严重度标签（Critical / Nit / FYI）抄进 PR 模板，所有人的 review 用同一套前缀
• /spec 产出的 SPEC.md 进版本控制，让它成为 PR 描述里可链接的事实源
• /ship 的发布清单可以变成 GitHub Actions 的 check list

什么时候该跳出流程：

• 改一行 typo 不用 /spec
• 探索性 prototype 不用 /test 全覆盖
• 紧急 hotfix 可以先跳 /review、事后补

Skill 是默认纪律，不是镣铐。它帮你守住下限，但上限永远是你自己。

组合其他 MCP：

• 配 Context7 MCP：source-driven-development skill 如虎添翼，框架 API 有官方文档直接引
• 配 Chrome DevTools MCP：browser-testing-with-devtools 能拿真运行时数据，而不是靠 Claude 猜

---

十、参考链接

• 项目主页：github.com/addyosmani/agent-skills
• 作者背景：Addy Osmani，Google Chrome 团队工程主管，web 性能与工程效率长期贡献者
• 官方文档：docs/getting-started.md、docs/skill-anatomy.md
• 理论根基：Software Engineering at Google、Google Engineering Practices

相关阅读：

• AI 辅助开发的工程化之路：Superpowers Skills 全生命周期实战指南——另一套同类工具，可并用
• Levels of Agentic Engineering——AI 工程化的能力分层