1. 项目概述：为AI编码智能体注入“资深工程师思维”

如果你和我一样，每天都在和Claude Code、Cursor、Antigravity IDE这类AI编码助手打交道，你肯定经历过这种时刻：你让它写个功能，它噼里啪啦给你生成了一堆代码，乍一看能用，但仔细一瞧，发现它跳过了写技术方案、没写测试、代码结构有点乱，安全风险也没考虑。结果就是你得花更多时间去“擦屁股”——补测试、重构、做安全审查。这感觉就像带了一个天赋异禀但缺乏纪律的实习生，它很聪明，但总想走捷径。

这就是Addy Osmani（谷歌工程总监，也是前端社区的大牛）开源 agent-skills 这个项目的初衷。它不是一个新工具，而是一套**“工程技能包”**，或者说，是一本写给AI智能体的“资深工程师工作手册”。它的核心目标很明确： 把那些需要十年一线经验才能内化的软件工程最佳实践、工作流程和质量关卡，编码成一套AI智能体可以理解并严格执行的“技能” 。简单说，就是教会你的AI助手，像一位经验丰富的Staff Engineer（首席工程师）那样去思考和工作。

这套技能包覆盖了软件开发的完整生命周期，从灵光一现的“想法”（Define），到拆解任务的“计划”（Plan），再到“构建”（Build）、“验证”（Verify）、“评审”（Review），最后“发布”（Ship）。它通过7个简单的斜杠命令（如 /spec , /plan , /build , /test ）来触发，背后对应着20个结构化的核心技能。每个技能都不是泛泛而谈的建议，而是一个包含明确步骤、验证关卡，甚至带有“反借口表”的 可执行工作流 。例如， /spec 命令会激活“规格驱动开发”技能，强制AI在写第一行代码前，先产出包含目标、接口设计、测试策略的详细需求文档。

我花了一周时间，在我的Claude Code和Cursor里深度集成了这套技能。实测下来，效果是颠覆性的。它彻底改变了我与AI协作的模式——从一个需要我不断纠正、提示的“代码生成器”，变成了一个能主动遵循工程规范、有质量意识的“协作工程师”。接下来，我会带你深入拆解这套技能体系的设计哲学、核心技能怎么用，以及如何在不同主流AI编码工具里落地，让你也能立刻获得这种“开挂”般的体验。

2. 核心设计哲学：为什么“技能”比“提示词”更有效？

在接触 agent-skills 之前，我相信很多人和我一样，试图通过写长篇大论的“系统提示词”来调教AI。比如，在Claude的系统指令里塞满“请写出健壮的代码”、“记得写测试”、“注意安全”。但效果往往不尽如人意。AI要么忽略，要么机械执行，遇到复杂场景就抓瞎。 agent-skills 的成功，在于它从根本上跳出了“提示词工程”的思维，采用了更底层的“技能工程”范式。理解这一点，是用好它的关键。

2.1 从“静态知识”到“动态工作流”

传统的提示词本质上是给AI一堆静态的“知识”或“规则”。比如，“写函数前先写注释”。但AI在生成代码时，面对的是动态、复杂的上下文。一个简单的“写注释”规则，无法告诉AI： 什么时候该写什么样的注释？函数注释的格式是什么？参数说明要详细到什么程度？哪些复杂的逻辑需要额外解释？

agent-skills 的每个技能（例如 spec-driven-development ）都是一个 动态的工作流引擎 。它不是一个段落，而是一个包含多个步骤的流程图。当AI激活这个技能时，它不是“记住了一个要求”，而是“进入了一个预设的程序”。这个程序会一步步引导它：第一步，明确目标和范围；第二步，定义公开的API接口；第三步，规划模块结构；第四步，制定测试策略……每一步都有明确的输入、处理和输出标准。这就把模糊的“要好代码”指令，变成了可执行、可验证的 操作序列 。

实操心得 ：这种设计最大的好处是“抗遗忘”。AI在生成长篇代码时，很容易陷入局部细节而忘记全局约束。技能工作流像是一个内置的“导航系统”，会在每个关键节点弹出检查点，确保AI不会跑偏。例如，在 incremental-implementation （增量实现）技能中，明确要求“一次只实现一个垂直功能切片，并立即验证”，这就强制打断了AI试图一口气生成所有代码的冲动，转向更安全、可控的迭代模式。

2.2 “反合理化”表：堵住AI的“偷懒”借口

这是我认为 agent-skills 设计中最精妙、也最实用的一点。开发者，包括AI，都倾向于选择最短路径。AI尤其擅长为自己的“偷懒”行为生成听起来很合理的解释。比如：

• 借口 ：“这个函数很简单，不需要写测试。”
• 借口 ：“为了快速验证想法，我先跳过写规格文档。”
• 借口 ：“这个代码改动很小，直接合并应该没问题。”

普通的提示词对这些借口毫无办法。但 agent-skills 在每个技能里都内置了一个 “Rationalizations & Rebuttals”（合理化借口与反驳） 表格。这个表格预判了AI在试图跳过该技能关键步骤时可能使用的所有常见借口，并提供了强有力的、基于工程实践的反驳论据。

例如，在 test-driven-development 技能中，针对“跳过测试”的借口，反驳是：“ 测试是正确性的证明，而不是事后的补充。‘简单’的代码往往隐藏着边界条件错误，并且未来会被修改。没有测试的代码就是债务。 ” 这些反驳论据通常引用自权威工程实践（如“Beyoncé Rule”：如果你想让代码没问题，就给它写测试），使得AI无法轻易绕过。

踩坑记录 ：在我早期使用中，有一次让AI修复一个复杂的正则表达式bug。AI生成了修复代码，但当我问“测试呢？”，它回复“正则逻辑已清晰，手动验证即可”。在我引入 agent-skills 后，同样场景下，AI在生成修复代码前自动激活了测试技能，并给出了反驳：“即使逻辑清晰，正则表达式极易因边界情况出错，必须通过测试用例固化行为。” 然后它主动补充了针对空字符串、特殊字符、超长字符串的测试用例。这个转变让我印象深刻。

2.3 验证优先：要证据，不要感觉

“看起来没问题”（Looks good to me）是软件质量的头号杀手。人类工程师会犯这个错，AI更甚。 agent-skills 的每个技能都以 “Verification”（验证） 环节收尾，并且这个环节是 非协商的 。它明确要求AI提供客观证据，而不是主观判断。

证据的形式因技能而异：

• 构建类技能 ：要求提供成功的构建输出日志、通过的测试套件结果。
• 测试类技能 ：要求展示测试运行通过的截图或终端输出，并说明覆盖率。
• 设计类技能 ：要求提供生成的API接口规范（如OpenAPI片段）、架构图。
• 安全类技能 ：要求提供依赖安全扫描（如 npm audit ）的结果、关键输入验证的代码片段。

这种“证据驱动”的模式，把质量保障从一种模糊的期望，变成了一个必须完成的、有明确产出的 交付任务 。AI在完成任务后，会主动附上这些证据，让你作为人类工程师可以快速复核，而不是去逐行审查代码逻辑。

2.4 模块化与组合性：按需装配的工程能力

agent-skills 不是一个庞然大物，而是由20个独立技能模块组成的工具箱。这种设计带来了极大的灵活性。你可以根据项目阶段、当前任务类型，激活不同的技能组合。

• 开发新功能 ：可以串联 /spec -> /plan -> /build -> /test 。
• 代码审查 ：直接使用 /review 命令，激活 code-review-and-quality 技能。
• 性能优化 ：在发现性能瓶颈时，可以手动引用 performance-optimization 技能。
• 修复复杂Bug ：可以结合 debugging-and-error-recovery 和 test-driven-development 技能。

更重要的是，这些技能可以与你自己团队的内部规范结合。你可以基于 agent-skills 的格式，创建你们公司特有的技能，比如“ 合规性检查技能 ”或“ 内部UI组件库使用规范技能 ”，然后让AI在相应场景下自动应用。这相当于为你团队的AI助手进行了“企业级定制培训”。

3. 核心技能深度解析与实战指南

agent-skills 包含20个核心技能，贯穿开发全流程。我们不可能面面俱到，但我会挑出几个最具代表性、最能体现其设计深度的技能，结合我的实战经验，为你详细拆解它们是如何工作的，以及你该如何最大化利用它们。

3.1 规格驱动开发：把“要做什么”说清楚再动手

技能文件 ： spec-driven-development 触发命令 ： /spec 核心价值 ：解决“方向性错误”，这是最昂贵的一类错误。

很多AI生成的代码问题，根源在于需求理解偏差。你说了“做一个登录框”，AI可能给你一个只有用户名密码的框，而你心里想的是包含OAuth、忘记密码、验证码的完整流程。 spec-driven-development 技能强制按下“暂停键”，在编码前先产出一份轻量级但结构化的产品需求文档（PRD）。

它的工作流分为六步 ：

1. 目标与范围 ：明确要解决的用户问题、成功标准和不做什么。
2. 命令与接口 ：定义用户或系统如何与功能交互（CLI命令、API端点、UI操作）。
3. 核心数据结构 ：设计主要的数据模型、状态形状。
4. 代码结构与风格 ：规划模块划分、目录结构，约定代码风格（如函数命名规则）。
5. 测试策略 ：提前确定要写哪些测试（单元、集成、E2E）、测试什么。
6. 边界与约束 ：明确性能、安全、兼容性等方面的限制。

我的实战案例 ：我曾让AI（搭载此技能）为一个内部工具设计一个数据导出功能。在没有技能时，AI直接开始写 exportToCSV 函数。而激活 /spec 后，AI首先反问了一系列问题：导出支持哪些格式（CSV/JSON）？数据量级多大（涉及分页吗）？是否需要异步处理和进度提示？导出文件如何命名？权限如何控制？在得到我的回答后，它生成了一份包含 /export?format=csv&filters={...} 的API设计、分页流式响应方案、以及基于用户角色的权限检查点。 后续的编码过程异常顺畅，因为所有模糊点都在前期被扫清了。 这个技能节省的不是几分钟，而是可能浪费数小时的重构时间。

3.2 增量实现与测试驱动开发：告别“大爆炸式”集成

技能文件 ： incremental-implementation & test-driven-development 触发命令 ： /build & /test 核心价值 ：降低认知负荷，确保每一步都是正确且可回滚的。

AI喜欢生成大段代码。你让它“实现用户管理系统”，它可能一口气给你生成 UserModel.js , AuthService.js , UserController.js 等十个文件。这带来了巨大的集成和调试风险。 incremental-implementation 技能的核心原则是 “垂直切片” 和 “薄层发布” 。

它的工作流要求 ：

• 一次只实现一个端到端的功能切片 。例如，不是实现整个“用户注册”，而是先实现“用邮箱密码注册”这个最小闭环，包括前端表单、后端API、数据库写入。
• 立即验证 ：实现后，立刻运行相关测试（由 test-driven-development 技能驱动），确保这个切片本身是工作的。
• 立即提交 ：验证通过后，立即做一个小的Git提交。这个提交就是一个安全的回滚点。
• 使用特性开关 ：对于可能影响线上功能的部分，使用特性开关（Feature Flag）包裹，确保未完成的代码不会影响主流程。

test-driven-development 技能则提供了具体的测试方法论。它不仅仅是“写测试”，而是遵循 “红-绿-重构” 循环，并强调测试金字塔（80%单元测试，15%集成测试，5%E2E测试）。它引入了 “Beyoncé Rule” ：如果你希望代码没问题（“Flawless”），就为它写测试。这个技能会引导AI先写一个失败测试（描述期望行为），再写最少代码让测试通过，最后重构代码同时保持测试通过。

避坑技巧 ：这两个技能结合使用时，最大的挑战是AI有时会过度拆分或测试过度。我的经验是，在 /build 命令后，可以追加一句人类指令来定义“切片”的粒度。例如：“ /build 请先实现用户登录API的JWT令牌签发功能，包含成功和无效密码的测试。” 这样既利用了技能的增量框架，又由你控制了节奏。

3.3 代码审查与质量门禁：引入“虚拟首席工程师”视角

技能文件 ： code-review-and-quality 触发命令 ： /review 核心价值 ：在合并前发现那些“能跑但很糟糕”的代码。

AI写的代码能运行，但不一定“好”。它可能忽略了错误处理、使用了不推荐的API、写出了难以理解的“聪明”代码。 /review 命令会激活一个虚拟的“资深代码审查员”视角。这个技能不是简单地检查语法，而是从五个维度进行系统评估：

审查维度	检查要点	示例问题
正确性	逻辑是否正确？边界条件处理了吗？	循环缺少退出条件，空数组处理不当。
可读性	命名是否清晰？结构是否一目了然？	函数名 processData 过于模糊，嵌套过深。
可维护性	代码是否模块化？重复了吗？	相同的验证逻辑在三个地方重复出现。
性能	有无低效操作？算法复杂度合理吗？	在循环内进行数据库查询（N+1问题）。
一致性	是否符合项目代码风格和架构模式？	使用了项目不推荐的 var 声明，或打破了现有的状态管理约定。

该技能还内置了 “变更大小”原则 ：鼓励每次代码审查的变更控制在100行左右。如果AI生成的变更太大，审查技能会建议将其拆分成多个更小的、独立的提交。这极大地提高了审查的效率和深度。

实操心得 ：我习惯在AI生成一段代码后，即使我觉得没问题，也运行一次 /review 。大约有30%的时候，它能提出我第一眼没发现的问题。例如，有一次它生成了一段使用 Array.reduce 的复杂数据转换代码，通过了测试。但 /review 指出：“此 reduce 回调函数副作用明显，且难以理解。建议拆分为 map 和 filter 两个步骤，或添加详细注释。” 我采纳了建议，代码的可读性得到了显著提升。这相当于拥有一个不知疲倦、严格遵循最佳实践的结对编程伙伴。

3.4 上下文工程：喂给AI“该知道的”信息

技能文件 ： context-engineering 触发命令 ：自动触发（当切换文件或任务时） 核心价值 ：解决AI“失忆”或“上下文不足”问题，提升输出质量。

这是所有技能中比较“元”但至关重要的一个。AI智能体的表现严重依赖于它拥有的上下文。 context-engineering 技能提供了一套方法论，指导你（或AI自身）如何为当前任务 主动地、结构化地提供最相关的信息 。

它的核心实践包括 ：

• 规则文件 ：在项目根目录维护 .cursor/rules 、 claude.md 等文件，明确项目架构、技术栈、代码风格和禁忌。
• 上下文打包 ：在开始一个复杂任务前，主动将相关的架构图、接口文档、现有类似功能的代码示例“喂”给AI。
• 会话管理 ：当AI输出质量下降时，识别是否是上下文窗口被无关信息污染，并指导如何开启一个新会话并重新注入关键上下文。

这个技能让我意识到，与AI协作不是一次性指令，而是一个 持续的上下文管理过程 。例如，在开发一个React组件时，我会确保AI的上下文中包含了我们的 组件设计规范.md 、 全局状态管理约定.md 以及 Ant Design Pro 的用法示例。这能确保AI生成的组件在风格和模式上与现有代码库无缝集成。

4. 主流IDE集成与实战配置详解

agent-skills 的强大之处在于它不绑定任何特定工具。它提供的是纯Markdown格式的技能定义，可以集成到几乎所有主流AI编码助手和IDE中。下面我以最常用的 Claude Code 和 Cursor 为例，详细说明配置步骤和实战技巧。

4.1 Claude Code 集成：最丝滑的体验

Claude Code（原Claude Desktop）是官方推荐的首选工具，集成最为直接。

安装方法（二选一） ：

1. 市场安装（推荐） ：在Claude Code聊天框中直接输入：

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

   这会将所有技能作为插件安装，并自动注册7个斜杠命令（ /spec , /plan 等）。

2. 本地开发模式 ：如果你需要修改或自定义技能，可以克隆仓库后本地链接。

   git clone https://github.com/addyosmani/agent-skills.git
   # 启动Claude Code时指向插件目录
   claude --plugin-dir /path/to/agent-skills
   

重要提示 ：市场安装使用SSH克隆。如果你在GitHub上没有配置SSH密钥，可能会失败。解决方法有两种：一是在GitHub账户中添加你的SSH公钥；二是在全局Git配置中为GitHub仓库临时使用HTTPS替代SSH（执行： git config --global url."https://github.com/".insteadOf "git@github.com:" ），安装完成后再改回来。

集成后效果 ： 安装成功后，你在Claude Code的输入框里输入 / ，就会看到新增的7个命令。整个交互是无缝的。例如，新建一个文件 api.js ，输入 /spec ，Claude会自动进入规格设计模式，引导你完成需求澄清并输出PRD。

4.2 Cursor 集成：规则文件的威力

Cursor是另一个强大的AI IDE。 agent-skills 通过 规则文件（Rules） 与Cursor集成。规则文件是Cursor的一个核心特性，它允许你为特定项目或全局定义AI的行为准则。

配置步骤 ：

1. 克隆或下载技能库 ：将 agent-skills 仓库克隆到本地，或直接下载ZIP包解压。
2. 复制技能文件 ：你有两种选择：
   • 全技能集成 ：将整个 skills/ 目录复制到你的项目根目录下的 .cursor/rules/ 目录中（如果没有则创建）。
   • 按需集成 ：只将你需要的单个技能文件（如 skills/code-review-and-quality/SKILL.md ）复制到 .cursor/rules/ 目录下，并重命名为一个清晰的名称，如 code_review_rule.md 。
3. 引用技能 ：你可以在Cursor的聊天中直接通过 @ 提及规则文件名来激活特定技能。例如，输入“ @code_review_rule 请审查这段代码：...”。

高级用法 ： 你可以在项目的 .cursor/rules 目录下创建一个主规则文件（例如 project_rules.md ），在里面通过相对路径引用你需要的技能，并混合你自己的项目规则。

// .cursor/rules/project_rules.md
# 项目开发规范

## 核心工程技能（基于 agent-skills）
请遵循以下来自 agent-skills 的工程实践：
- 规格设计: 参见 `./skills/spec-driven-development/SKILL.md`
- 代码审查: 参见 `./skills/code-review-and-quality/SKILL.md`
- 测试驱动: 参见 `./skills/test-driven-development/SKILL.md`

## 本项目特定规则
- 前端组件统一使用 Function Component + Hooks。
- API请求必须使用封装后的 `request` 工具，处理统一错误。
- ...

这样，Cursor AI在项目中的任何会话，都会自动继承这些混合了通用技能和项目特定规则的上下文。

4.3 其他工具集成思路

对于其他工具如 Windsurf 、 GitHub Copilot 、 Gemini CLI 等， agent-skills 的 docs/ 目录下都有对应的设置指南（ windsurf-setup.md , copilot-setup.md 等）。其核心思想万变不离其宗：

1. 将技能内容作为系统提示词 ：把相关技能的Markdown内容，粘贴到工具的“自定义指令”、“系统提示”或“全局规则”配置区域。
2. 利用工具的特性 ：例如，在Windsurf中，你可以将技能定义为“工作区规则”；在Copilot中，可以将技能内容放入 .github/copilot-instructions.md 文件。
3. 手动触发 ：在没有斜杠命令集成的工具中，你可以通过输入类似“请按照 spec-driven-development 技能的要求，为这个功能编写规格说明”这样的自然语言指令来手动激活技能。

5. 自定义技能与团队实践进阶

当你和你的团队熟练使用这套标准技能后，下一个自然的发展阶段就是 定制属于你们自己的技能 。这是将团队内部知识资产化、流程标准化的重要一步。

5.1 如何创建一个自定义技能？

agent-skills 的每个技能都遵循一个清晰的 “技能解剖结构” （在 docs/skill-anatomy.md 中有详细说明）。创建一个新技能，就是创建一个新的Markdown文件，并填充以下部分：

1. Frontmatter（元数据） ：YAML格式，定义技能名称和简短描述。

   name: my-custom-skill
   description: 用于处理我们团队特有的数据上报规范
   

2. Overview（概述） ：这个技能是做什么的？解决什么问题？
3. When to Use（何时使用） ：明确的触发条件。例如：“当编写任何会向‘事件中心’发送数据的代码时”。
4. Process（流程） ： 核心部分 。用编号步骤列出具体工作流。例如：

   1. 确定上报事件类型（ page_view , button_click , api_call ）。
   2. 在 events.yaml 中查找或定义该事件的唯一 event_id 和字段规范。
   3. 使用统一的 trackEvent(eventId, properties) 函数进行上报。
   4. 确保 properties 对象不包含任何用户个人身份信息（PII）。
   5. 为关键事件编写对应的单元测试，验证上报数据格式。

5. Rationalizations & Rebuttals（反合理化） ：预判偷懒借口。

   借口	反驳
   “这只是个临时调试，不需要走规范流程。”	“临时代码往往变成永久代码。不规范的上报会导致数据污染，影响数据分析的准确性。”

6. Red Flags（危险信号） ：哪些情况说明可能用错了或出了问题？例如：“直接调用第三方上报SDK而不是使用封装函数”、“上报了 user.email 字段”。
7. Verification（验证） ：如何证明正确完成了？例如：“展示调用了 trackEvent 的代码行”、“展示 events.yaml 中对应的事件定义”、“展示通过的数据格式测试”。

5.2 团队落地实践与文化建设

引入 agent-skills 不仅仅是安装一个插件，更是一种工程文化的推广。以下是我在团队中推行的一些有效实践：

• 从“代码审查”技能开始 ：在团队代码审查流程中，鼓励大家使用 /review 命令或引用审查技能作为辅助工具。将AI发现的问题（如复杂度高、缺少错误处理）作为审查意见的一部分进行讨论。这能快速统一团队的代码质量标尺。
• 建立团队技能库 ：在团队共享的Git仓库中，建立一个 team-skills/ 目录。将自定义的技能（如“ 微前端接入规范 ”、“ GraphQL API设计指南 ”）放在这里。新成员 onboarding 时，第一件事就是配置好AI助手并加载这些团队技能。
• 在PR描述中引用技能 ：鼓励开发者在提交Pull Request时，在描述中说明本次变更遵循了哪些技能（如“本PR遵循了 incremental-implementation 和 test-driven-development 技能，功能已切片实现并包含完整测试”）。这能让审查者快速理解你的工作方式，提升信任度。
• 定期复盘与技能迭代 ：在团队技术复盘会上，可以讨论：“最近AI在哪个环节最常‘犯错’？我们能否创建一个新技能来规避它？” 例如，如果发现AI经常生成不兼容旧版API的代码，就可以创建一个“ 向后兼容性检查 ”技能。

6. 常见问题与排错实录

在实际使用 agent-skills 的过程中，你可能会遇到一些疑问或障碍。以下是我和社区成员遇到的一些典型问题及解决方案。

问题现象	可能原因	解决方案
在Claude Code中输入 /spec 无反应。	1. 插件未成功安装。 2. 当前会话上下文不支持命令。	1. 检查插件列表 ( /plugin list )。重新运行安装命令。 2. 尝试在新会话或新文件中使用命令。确保焦点在输入框。
AI似乎忽略了技能中的某些步骤（如跳过写测试）。	1. 技能上下文未正确加载或权重不足。 2. AI的“偷懒”倾向压过了技能约束。	1. 在Cursor中，用 @ 明确引用技能文件。在Claude中，确保插件已激活。 2. 使用更明确的指令，如“ 请严格遵守 test-driven-development 技能中的‘红-绿-重构’流程，先写一个失败测试。 ”
技能输出的内容过于冗长或模板化。	AI可能机械地套用了技能模板，缺乏对具体问题的深入思考。	在触发技能后，追加具体、细致的上下文。例如，不要只说 /spec ，而说“ /spec 我们需要一个用户积分排行榜功能，数据来自后端API，需要支持按日/周/月筛选，前端用React Table展示。”
自定义技能似乎不起作用。	1. 技能文件格式错误，缺少必要部分。 2. 技能文件未被AI助手正确读取。	1. 对照 docs/skill-anatomy.md 检查格式，确保有完整的Process和Verification部分。 2. 在Cursor中，检查规则文件路径是否正确，尝试在聊天中直接 @ 文件名看是否能被识别。
多个技能同时激活产生冲突或混乱。	AI同时接收了多个复杂指令，导致行为不一致。	一次聚焦一个技能 。通常，生命周期命令（ /spec -> /plan -> /build ）是顺序使用的。对于复杂任务，可以分阶段进行，一个阶段完成后再进入下一个。

终极心法 ：记住， agent-skills 是你用来 引导和约束 AI的工具，而不是替代你思考的“自动驾驶”。你最了解你的项目和需求。把这些技能看作是一套强大的“脚手架”和“检查清单”，用来提升AI输出的下限和一致性，而创造性和关键决策依然在你手中。当AI输出不理想时，结合你的领域知识，对技能指令进行微调，或者直接介入，给出更明确的指引。人机协作的最佳状态，是“人类掌舵，AI划桨”。