1. Agent Skills 是什么

Agent Skills 是一套面向 AI 编程助手的生产级工程技能包。它把资深工程师在 Define → Plan → Build → Verify → Review → Ship 全流程中的工作方式、质量门禁和最佳实践，编码成 agent 可执行的 Markdown 工作流（Skill）。

简单说，它解决的不是「agent 能不能写代码」，而是「agent 会不会跳过 spec、测试、安全审查这些让软件可靠的关键步骤」。

项目由 Addy Osmani 维护，包含 24 个 Skill、8 个 Slash Command、4 个专家 Persona 和 7 份参考清单。纯 Markdown，无运行时依赖，支持 Claude Code、Cursor、Gemini CLI、Antigravity、OpenCode、Windsurf、Copilot 等主流工具。

• 项目仓库：https://github.com/addyosmani/agent-skills
• 技能规范：https://github.com/addyosmani/agent-skills/blob/main/docs/skill-anatomy.md

2. 为什么需要它

AI 编程助手默认走最短路径——能直接改代码就不写 spec，能「看起来对」就不跑测试，能先 ship 就不做安全审查。这在原型阶段很快，但在生产代码里会留下大量技术债。

Agent Skills 的思路是：把 senior engineer 的判断力结构化——什么时候写 spec、什么要测、怎么 review、何时才能 ship——让 agent 按步骤执行，而不是凭感觉跳过。

没有 Agent Skills，agent 靠通用 prompt 即兴发挥；有了 Agent Skills，agent 按可验证的工作流走，每步都有 exit criteria 和反合理化表。

3. 有/无 Agent Skills 对比

3.1 同一个需求，两条路径

假设你要 agent 实现一个带认证的新 API 端点。

不使用 Agent Skills：

口头描述需求 → agent 直接写代码 → 可能补几个测试
     → 「看起来能跑」就提交 → 漏掉边界校验、错误语义、安全审查
     → 合并后才发现 auth bypass 或缺少回归测试

使用 Agent Skills：

/spec → 写 PRD（目标、命令、结构、测试策略、边界）
     → /plan → 拆成可验证的小任务
     → /build → TDD 增量实现（RED → GREEN → 回归 → commit）
     → /test → 证明行为正确
     → /review → 五轴 code review + security-and-hardening
     → /ship → 并行 fan-out 各 persona，合并 go/no-go

3.2 实测对比（受控实验）

Om Mishra 在 Claude Code 上做过一次受控对比：同一模型（Sonnet 4.6）、同一仓库、同一 prompt，只换 skill 框架（Agent Skills vs Superpowers）：

Agent Skills 在该任务上验证深度更广——全量测试套件发现了 feature 测试未覆盖的兼容性问题。Superpowers 则在前期架构推理上投入更多，更适合探索性、无既定模式的工作。

这是单次实验，不是 benchmark，但说明了核心取舍：广覆盖的纪律化验证 vs 重前期推理的自主执行。

3.3 什么时候不用也行

4. 工作原理

Agent Skills 把工程实践编码为可加载的 Skill 文件，通过 Slash Command 和自动触发两种机制激活。

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

4.1 Skill 解剖

每个 Skill 是一个 SKILL.md，结构固定：

┌─────────────────────────────────────────────────┐
│  Frontmatter（name + description，含触发条件）   │
│  Overview         → 做什么、为什么               │
│  When to Use      → 何时用、何时不用             │
│  Core Process     → 分步工作流                   │
│  Common Rationalizations → 借口 + 反驳           │
│  Red Flags        → 违规信号                     │
│  Verification     → 退出条件 + 证据要求          │
└─────────────────────────────────────────────────┘

关键设计：

• Process，不是 prose：Skill 是 agent 要执行的步骤，不是参考文档
• Anti-rationalization：「我稍后再加测试」这类借口在表里都有反驳
• Verification 不可协商：「看起来对」永远不够，要测试输出、构建结果等证据
• 渐进式披露：启动时只有 name + description 进上下文；完整 Skill 按需加载，Supporting files 再按需读

4.2 24 个 Skill 一览

按 lifecycle 分组：

Skill 也会按任务类型自动触发——设计 API 时激活 api-and-interface-design，做 UI 时激活 frontend-ui-engineering。

4.3 Slash Commands

8 个命令对应 lifecycle 入口，自动加载对应 Skill：

/build auto 不是跳过验证——每个 task 仍走完整 TDD 循环并单独 commit，只是去掉 task 之间的人工 stepping。

4.4 专家 Persona

agents/ 目录提供 4 个预配置审查角色，可与 Skill 组合：

/ship 会并行 fan-out 这些 persona，合并成 go/no-go 决策。

4.5 工程文化嵌入

Skill 内嵌了 Google 工程实践，不是抽象口号而是写进步骤里：

• API 设计：Hyrum’s Law、One-Version Rule
• 测试：Beyonce Rule、测试金字塔 80/15/5、DAMP over DRY
• Review：变更粒度 ~100 行、severity 标签（Nit/Optional/FYI）
• 简化：Chesterton’s Fence、Rule of 500
• Git：Trunk-based development、commit 即 save point
• CI/CD：Shift Left、feature flag
• 废弃：Code as liability、compulsory vs advisory deprecation

5. 快速上手

5.1 Claude Code（推荐）

Marketplace 安装：

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

SSH 报错时改用 HTTPS：

1
2

/plugin marketplace add https://github.com/addyosmani/agent-skills.git
/plugin install agent-skills@addy-agent-skills

本地开发：

1
2

git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills

安装后直接可用 /spec、/build、/review 等命令。

5.2 Cursor

方式 A：Rules 目录（推荐）

1
2
3
4

mkdir -p .cursor/rules
cp /path/to/agent-skills/skills/test-driven-development/SKILL.md .cursor/rules/test-driven-development.md
cp /path/to/agent-skills/skills/code-review-and-quality/SKILL.md .cursor/rules/code-review-and-quality.md
cp /path/to/agent-skills/skills/incremental-implementation/SKILL.md .cursor/rules/incremental-implementation.md

方式 B：按需加载

做 UI 时加 frontend-ui-engineering.md，做安全审查时加 security-and-hardening.md，做完移除以控制上下文。

使用时显式引用：「Follow the test-driven-development rules for this change.」

5.3 Gemini CLI

1

gemini skills install https://github.com/addyosmani/agent-skills.git --path skills

5.4 Antigravity CLI

1

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

5.5 其他 Agent

Skill 是纯 Markdown，复制 SKILL.md 到 CLAUDE.md、AGENTS.md、.github/copilot-instructions.md 或对话 system prompt 即可。详见各工具 setup 文档。

5.6 最小推荐配置

若不想一次加载 24 个 Skill，先装这三个：

1. spec-driven-development — 定义做什么
2. test-driven-development — 证明做对
3. code-review-and-quality — 合并前质量门禁

再加载 using-agent-skills meta-skill，让 agent 自动路由到其余 Skill。

6. 命令与 Skill 映射

/spec 和 /plan 会产出 SPEC.md、tasks/plan.md 等工件，开发期间作为人机共享的 source of truth；合并前可删或加入 .gitignore。

7. 使用建议

1. 非平凡工作先 /spec——超过 30 分钟、多文件、架构决策，都该有 spec
2. 不要一次加载全部 Skill——2～3 个常驻 + 按需加载，控制上下文
3. 显式引用 Skill——告诉 agent「按 test-driven-development 流程做」，不要假设它会读规则
4. 信任 Verification——跳过 checklist 等于没用 Skill
5. Review 用 Persona——把 agents/code-reviewer.md 内容给 agent，换视角抓不同问题
6. 只选一个主框架——可同时借鉴 Matt Pocock 的 grill-me 或 Superpowers 的 worktree，但不要两个 meta-skill 同时当 router
7. /build auto 有门禁——spec 不存在、工作区不干净、高风险步骤会暂停等你确认

几个设计原则值得了解：

• Process over knowledge：Skill 是工作流，不是百科全书
• Evidence over assumption：每步 Verification 要可证明的输出
• Human checkpoint：每个 phase 有人工审查点，不是完全黑盒自主
• Multi-tool：同一套 Skill 跨 Claude Code、Cursor、Gemini 等复用

8. 与其他 Skill 框架对比

选型建议：

• 要全流程纪律 + 多工具覆盖 → Agent Skills
• 要长段自主、重前期推理 → Superpowers
• 要低仪式感的 sharp 日常工具 → Matt Pocock’s skills

可以 cherry-pick 单个 Skill，但不要同时跑两套 router。

9. 参考清单

references/ 目录提供 Skill 按需引用的补充材料：

10. 小结

Agent Skills 把 AI 编程助手从「能写代码的实习生」，变成「按 senior engineer 流程交付的生产级搭档」。

• 对比：无 Skill 时 agent 常跳过 spec/测试/安全；有 Skill 时每 phase 有步骤、反合理化表和 Verification 证据要求
• 原理：24 个 Markdown Skill + 8 个 Slash Command + 4 个 Persona，按 SDLC 阶段路由
• 使用：Claude Code 用 /plugin install；Cursor 复制到 .cursor/rules/；非平凡工作从 /spec 开始

如果你已经在用 Cursor 或 Claude Code，先从 spec-driven-development + test-driven-development + code-review-and-quality 三个 Skill 试起，下一次非平凡需求走一遍 /spec → /plan → /build，通常就能感受到差异。