Agent Skills：给 AI 编码助手装上工程师级的肌肉记忆

写代码这件事，人和机器有一个根本区别——人有经验，有判断力，知道什么时候该停下来写个 spec，什么时候该先补个测试。AI 编码助手呢？它拿到需求就闷头写代码，跳过规划，跳过测试，跳过安全审查，写出来的玩意儿能跑，但经不起生产环境的折腾。

Agent Skills 是 Addy Osmani 主导的开源项目，做的事说白了就一件：把资深工程师的工作流程、质量门禁和最佳实践，编码成 AI 能遵循的结构化技能。24 个 skill 覆盖软件开发生命周期的每个阶段，8 个 slash command 映射到关键动作，4 个专业角色处理专项审查。你装上这套东西，AI 就不再是一个”写代码很快但不靠谱的实习生”，而是有了明确流程约束的工程师搭档。

这篇文章解决的核心问题： Agent Skills 是什么、包含哪些内容、怎么安装、怎么用、内部机制是什么。全部基于项目文档本身，不加推测。

为什么 AI 需要”技能”而不是”提示词”？

一句 prompt 能让 AI 写出一段代码，但没法让它遵循一套工程流程。Agent Skills 不是提示词集合，而是结构化的工作流——每个 skill 有步骤、有检查点、有退出条件，就像给 AI 配了一本操作手册。

这个项目吸收了不少 Google 工程文化里的硬核概念，比如 Hyrum’s Law 用在 API 设计里、Beyonce Rule 用在测试中、Chesterton’s Fence 用在代码简化中、Shift Left 和 Feature Flags 用在 CI/CD 里。这些不是抽象原则，而是直接嵌入到 AI 需要跟着走的步骤里。

Agent Skills 生命周期概览

六阶段生命周期与 8 个 Slash Command

Agent Skills 把开发过程拆成六个阶段：DEFINE（定义）→ PLAN（规划）→ BUILD（构建）→ VERIFY（验证）→ REVIEW（审查）→ SHIP（发布）。每个阶段对应一组 skill，用户通过 slash command 触发对应流程。

实际操作中，这 8 个命令覆盖了日常开发的绝大多数场景：

你在做什么 命令 核心理念
定义要做什么 /spec 先写规范再写代码
规划怎么实现 /plan 拆成小的、原子级任务
增量构建 /build 一次做一小块
证明代码能跑 /test 测试就是证据
合并前审查 /review 改善代码健康度
审计网页性能 /webperf 先测量再优化
简化代码 /code-simplify 清晰度优先于巧妙度
部署上线 /ship 更快等于更安全

有个细节值得注意：技能会根据你正在做的事情自动激活。设计 API 时 api-and-interface-design 会自动生效，构建 UI 时 frontend-ui-engineering 会启动。你不需要记住每个技能的名字，正常的开发行为本身就是触发条件。

/build auto 模式比较特殊——它在 spec 存在的前提下，一次性生成计划并自主实现所有任务。你审批一次计划，剩下的它自己跑。但这里有个底线：每个任务仍然是测试驱动的、独立提交的，遇到失败或高风险步骤会暂停。它去掉的是人在任务之间来回切换的摩擦，不是验证本身。

24 个技能的完整拆解

项目一共 24 个 skill：23 个覆盖生命周期的技能，加 1 个元技能（using-agent-skills，决定该用哪个 skill）。按阶段逐一来看。

DEFINE 阶段：搞清楚到底要做什么

需求没定义清楚就开始写代码，是 AI 助手最常见的翻车原因。这个阶段有 3 个 skill 来解决这个问题：

  • interview-me：像一个会追问的访谈者，一次只问一个问题，一直追问到对需求有 95% 的把握为止。适用于需求描述模糊、用户自己也没完全想清楚的场景。
  • idea-refine：通过发散思维和收敛思维的结构化交替，把一个模糊的念头变成具体的方案。你只有一个大概想法的时候用它。
  • spec-driven-development：在写任何代码之前，先产出一份 PRD（产品需求文档），覆盖目标、命令、代码结构、编码风格、测试策略和边界条件。新项目、新功能、大的改动，都该从这里开始。

PLAN 阶段：把大目标拆成小任务

  • planning-and-task-breakdown：把 spec 分解成小的、可验证的任务，每个任务有验收标准、有依赖排序。拆出来的东西要能直接进入开发流程。

BUILD 阶段：开始写代码

这是技能最密集的阶段，有 7 个 skill：

  • incremental-implementation：薄垂直切片法——实现、测试、验证、提交，每次只做一小块。支持 Feature Flag、安全默认值、回滚友好的变更方式。任何改动涉及一个文件以上时就该用它。
  • test-driven-development：红-绿-重构循环，测试金字塔（80% 单元测试 / 15% 集成测试 / 5% 端到端测试），DAMP 优于 DRY（测试代码要可读，不是要复用），Beyonce Rule（如果你改了生产代码但没改测试，你就违反了规则）。
  • context-engineering：在正确的时间给 AI 喂正确的信息——规则文件、上下文打包、MCP 集成。当你切换任务或输出质量下降时用它。
  • source-driven-development：每个框架决策都要有官方文档支撑——验证来源、引用出处、标注未验证的部分。你想要权威的、有出处的代码时用它。
  • doubt-driven-development：对抗性审查机制，对每个非平凡决策进行新鲜上下文的审查。流程是：声明 → 提取 → 怀疑 → 调和 → 停止。涉及生产环境、安全、不可逆操作时启动。
  • 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 获取运行时数据——DOM 检查、控制台日志、网络追踪、性能剖析。构建或调试浏览器端的东西时用。
  • 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 目标值、专业分析工作流、包体积分析、反模式检测。

SHIP 阶段：部署到生产环境

  • git-workflow-and-versioning：主干开发（Trunk-based）、原子提交、变更规模约 100 行、提交即保存点的模式。
  • ci-cd-and-automation：Shift Left、Faster is Safer、Feature Flag、质量门禁流水线、失败反馈循环。
  • deprecation-and-migration：代码即负债的心态、强制弃用 vs 建议弃用、迁移模式、僵尸代码清理。
  • documentation-and-adrs：架构决策记录（ADR）、API 文档、内联文档标准——记录”为什么”，不只是”是什么”。
  • observability-and-instrumentation：结构化日志、RED 指标、OpenTelemetry 追踪、基于症状的告警——构建时就做监控，不是上线后补。
  • shipping-and-launch：上线前清单、Feature Flag 生命周期、分阶段发布、回滚流程、监控设置。

每个 Skill 到底长什么样？

技能不是散文式的参考文档，而是可执行的工作流。每个 skill 遵循统一的结构：

Frontmatter 包含名称和描述；Overview 说明这个技能做什么；When to Use 列出触发条件；Process 是分步工作流，有检查点和退出条件；Rationalizations 是反辩解表——列出 AI 常用的跳过步骤的借口，逐一给出反驳；Red Flags 列出出问题的信号；Verification 规定必须提供什么证据。

三件事值得展开说。

反辩解表（Anti-rationalization）是这套系统最有意思的设计。 AI 和人一样会给自己找理由——”我之后再加测试”、”这个改动太小不需要测试”、”先让它跑起来再优化”。每个 skill 都预设了这类借口，给出具体的反驳：”测试不是事后补的装饰，而是行为的证据。没有测试的代码不是’基本完成’，是’没有证明能用’。”

验证是强制性的。 “看起来对”不算数。每个 skill 最后要求的是证据——测试通过的输出、构建成功的信息、运行时数据。没有证据，流程就不会往下走。

渐进式信息加载。 SKILL.md 是入口，相关的参考文档只在需要时才加载。这控制了 token 消耗，也避免了信息过载。

4 个专业角色

Agent Skills 不只有流程技能，还有 4 个预配置的专业角色（Agent Personas），每个角色有特定的审查视角：

角色 定位 审查视角
code-reviewer 高级主任工程师 五维度代码审查，标准是”一个资深工程师会批准这个吗？”
test-engineer QA 专家 测试策略、覆盖率分析、Prove-It 模式
security-auditor 安全工程师 漏洞检测、威胁建模、OWASP 评估
web-performance-auditor 网页性能工程师 Core Web Vitals 审计，有 Quick 和 Deep 两种模式，通过 /webperf 触发

角色之间有编排规则——”personas don’t invoke personas”，即角色不调用其他角色，避免多层嵌套的混乱。

参考清单系统

项目还包含 6 个快速参考清单，在对应 skill 需要时被引入：

  • 定义完成标准：项目级别的质量底线，每个变更都要满足，和单个任务的验收标准区分开
  • 测试模式：测试结构、命名、Mock 策略、React/API/E2E 示例、反模式
  • 安全清单：提交前检查项、认证、输入验证、HTTP 头、CORS、OWASP Top 10
  • 性能清单：Core Web Vitals 目标值、前端/后端清单、测量命令
  • 无障碍清单：键盘导航、屏幕阅读器、视觉设计、ARIA、测试工具
  • 可观测性清单：值班问题、结构化日志、RED/USE 指标、追踪、基于症状的告警、上线前门禁

安装配置

支持 8 个主流 AI 编码工具，安装方式各异。

Claude Code（推荐方式） 是通过 plugin marketplace：

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

如果遇到 SSH 错误，可以用 HTTPS URL 强制克隆：

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

本地开发模式：

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

Cursor 的做法是把 SKILL.md 文件复制到 .cursor/rules/ 目录，或者引用整个 skills/ 目录。

Antigravity CLI 作为原生插件安装，支持技能、子代理和斜杠命令：

# 从远程仓库安装
agy plugin install https://github.com/addyosmani/agent-skills.git

# 从本地克隆安装
git clone https://github.com/addyosmani/agent-skills.git
agy plugin install ./agent-skills

Gemini CLI 支持自动发现的原生 skill 安装，也可以加到 GEMINI.md 里做持久化上下文：

# 从远程仓库安装
gemini skills install https://github.com/addyosmani/agent-skills.git --path skills

# 从本地安装
gemini skills install ./agent-skills/skills/

Windsurf、OpenCode、GitHub Copilot、Kiro IDE 各有各的配置方式，具体细节在项目的 docs/ 目录下。所有 skill 本质上都是纯 Markdown 文件，理论上任何支持系统提示词或指令文件的代理都能用。

项目的文件结构

agent-skills/
├── skills/                  # 24 个技能
│   ├── interview-me/        #   DEFINE
│   ├── idea-refine/         #   DEFINE
│   ├── spec-driven-development/
│   ├── planning-and-task-breakdown/
│   ├── incremental-implementation/
│   ├── context-engineering/
│   ├── source-driven-development/
│   ├── doubt-driven-development/
│   ├── frontend-ui-engineering/
│   ├── test-driven-development/
│   ├── api-and-interface-design/
│   ├── browser-testing-with-devtools/
│   ├── debugging-and-error-recovery/
│   ├── code-review-and-quality/
│   ├── code-simplification/
│   ├── security-and-hardening/
│   ├── performance-optimization/
│   ├── git-workflow-and-versioning/
│   ├── ci-cd-and-automation/
│   ├── deprecation-and-migration/
│   ├── documentation-and-adrs/
│   ├── observability-and-instrumentation/
│   ├── shipping-and-launch/
│   └── using-agent-skills/
├── agents/                  # 4 个专业角色
├── references/              # 6 个参考清单
├── hooks/                   # 会话生命周期钩子
├── .claude/commands/        # 8 个斜杠命令（Claude Code）
├── .gemini/commands/        # 8 个斜杠命令（Gemini CLI）
├── commands/                # 8 个斜杠命令（Antigravity CLI）
├── plugin.json              # Antigravity 插件清单
└── docs/                    # 各工具的配置指南

背后的工程哲学

Agent Skills 不是在凭空造概念。它引用的工程实践有明确的出处：Google 的《Software Engineering at Google》、Google 工程实践指南。Hyrum’s Law 在 API 设计技能里是一个实际的检查步骤；Beyonce Rule 在 TDD 技能里是一个可执行的断言；Chesterton’s Fence 在代码简化技能里是一条具体的规则。Shift Left 和 Feature Flags 在 CI/CD 技能里是工作流的一部分，不是教科书上的理论。

这套工具的设计标准也写得很清楚：技能要具体（可执行的步骤，不是模糊建议）、可验证（有明确的退出条件和证据要求）、经过实战检验（基于真实工作流）、精简（只要够用就行）。

项目是 MIT 许可，意味着你可以用在个人项目、团队和工具里，没有商业限制。

实用摘要 / 操作清单

  1. 确认你使用的 AI 编码工具——Claude Code 推荐用 plugin marketplace 一键安装，其他工具各有对应方式
  2. 装好后从 /spec 开始——任何项目的第一步是定义需求，不是写代码
  3. 用 /plan 把 spec 拆成小任务，每个任务有验收标准
  4. /build 做增量实现，/build auto 在 spec 明确的前提下可以一键自动执行
  5. /test 是必须的，不是可选的——没有测试的代码不是”基本完成”
  6. /review 和 /webperf 在合并前跑一遍
  7. /code-simplify 处理可读性问题
  8. /ship 做最终的发布准备
  9. 专业角色按需调用——代码审查、安全审计、性能审计、测试策略各司其职
  10. 所有 skill 都是纯 Markdown，可以按需修改和扩展

一页速览

  • 定位： 为 AI 编码助手提供结构化工程工作流的开源项目
  • 规模： 24 个 skill、8 个 slash command、4 个专业角色、6 个参考清单
  • 核心理念： 流程优先、反辩解机制、验证强制性、渐进信息加载
  • 兼容工具： Claude Code、Cursor、Antigravity CLI、Gemini CLI、Windsurf、OpenCode、GitHub Copilot、Kiro IDE
  • 技术背景： 借鉴 Google 工程文化，嵌入 Hyrum’s Law、Beyonce Rule、Chesterton’s Fence 等实践
  • 许可： MIT

FAQ

Q：Agent Skills 和直接写 prompt 有什么区别？
A：Prompt 是一次性指令，Agent Skills 是带检查点、退出条件和验证要求的完整工作流。区别就像”帮我写个登录功能”和”按 TDD 流程实现登录功能，写完测试覆盖率要过 80%”。

Q：只能用在 Claude Code 上吗？
A：不是。Claude Code 是推荐的安装方式，但 Cursor、Gemini CLI、Windsurf、Antigravity CLI、OpenCode、GitHub Copilot、Kiro IDE 都能用。所有 skill 本质是纯 Markdown，任何支持指令文件的代理都能适配。

Q：/build auto 会不会跳过质量检查？
A：不会。它跳过的是人在任务之间的手动切换，每个任务仍然是测试驱动的、独立提交的，遇到失败或高风险步骤会暂停。

Q：24 个 skill 我都需要装吗？
A：全部一起装的，不需要你单独挑选。系统会根据你正在做的事情自动激活对应的 skill，你也可以手动用 slash command 指定。

Q：反辩解表是什么？
A：每个 skill 里都有一张表，列出了 AI 常用的跳过步骤的借口（比如”测试太慢了””这个改动很小不需要审查”），以及对应的反驳。这是 Agent Skills 区别于普通 prompt 的关键设计之一。

Q：和 Superpowers、Matt Pocock 的 skills 比，有什么不同？
A：项目文档里有一份对比文档 docs/comparison.md，包含三个项目的横向对比和一个控制实验的链接。三者的设计出发点不同，Agent Skills 侧重于完整生命周期的工程纪律。

Q：项目的工程实践来自哪里？
A：主要吸收了 Google 工程文化里的概念，来源包括《Software Engineering at Google》和 Google 工程实践指南。Hyrum’s Law、Beyonce Rule、Chesterton’s Fence、Shift Left 等都是直接嵌入工作流的，不是挂名引用。

Q：我想自己写一个 skill 怎么办？
A：项目的 docs/skill-anatomy.md 有格式规范，CONTRIBUTING.md 有贡献指南。核心要求是：具体、可验证、经过实战、精简。