Agent Skills：给 AI 编码代理装上高级工程师的工作纪律

解决什么问题

AI 编码代理（Claude Code、Cursor、Gemini CLI）有一个共同毛病：默认走最短路径。你让它实现一个功能，它直接写代码，跳过规格说明、跳过测试、跳过安全审查、跳过代码审查。写出来的东西能跑，但不是生产级的。

Agent Skills 的做法是把高级工程师在开发过程中遵循的工作流程，编码成 AI agent 可以执行的结构化指令。不是给 agent 一堆"最佳实践"让它参考，而是给它一套带步骤、带检查点、带退出条件的流程。

项目作者是 Addy Osmani，Google Chrome 团队的工程经理，写过《Learning JavaScript Design Patterns》。截至 2026 年 5 月，GitHub 上 33k stars。

7 个命令覆盖开发生命周期

项目把软件开发拆成 6 个阶段，每个阶段对应一个 slash 命令：

bash 复制代码

DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP
/spec    /plan   /build  /test    /review  /ship

加上一个 /code-simplify 做代码简化。

每个命令背后激活对应的技能。输入 /spec，agent 进入 spec-driven-development 技能的流程：先列出假设让你确认，再写规格文档覆盖目标、命令、项目结构、代码风格、测试策略、边界条件，每个阶段都需要人类 review 才能进入下一步。

技能也会根据上下文自动激活。写 API 接口时 api-and-interface-design 自动生效，写前端组件时 frontend-ui-engineering 接管。

20 个技能的分布

阶段	技能	做什么
Define	spec-driven-development, idea-refine	写规格说明，把模糊想法变成具体方案
Plan	planning-and-task-breakdown	把规格拆成可验证的小任务
Build	incremental-implementation, TDD, context-engineering, source-driven-development, frontend-ui-engineering, api-and-interface-design	增量实现、测试驱动、上下文管理、源码驱动、前端工程、API 设计
Verify	browser-testing-with-devtools, debugging-and-error-recovery	浏览器测试、调试和错误恢复
Review	code-review-and-quality, code-simplification, security-and-hardening, performance-optimization	五轴代码审查、代码简化、安全加固、性能优化
Ship	git-workflow-and-versioning, ci-cd-and-automation, deprecation-and-migration, documentation-and-adrs, shipping-and-launch	Git 工作流、CI/CD、废弃迁移、文档 ADR、发布上线

Build 阶段技能最多（6 个），写代码这一步最容易出问题，需要最多约束。

技能的内部结构

每个技能是一个 SKILL.md 文件，结构固定：

vbnet 复制代码

Frontmatter（名称 + 触发条件描述）
Overview（做什么）
When to Use（什么时候激活）
Process（分步流程，带检查点）
Common Rationalizations（反借口表）
Red Flags（危险信号）
Verification（验证清单）

最有意思的设计是 Common Rationalizations（反借口表）。AI agent 和人一样会找理由跳过步骤。TDD 技能里的反借口表：

借口	现实
"代码写完再补测试"	你不会补的。事后写的测试测的是实现，不是行为
"这个太简单不用测"	简单代码会变复杂。测试记录的是预期行为
"测试拖慢我"	现在慢，以后每次改代码都快
"我手动测过了"	手动测试不持久。明天的改动可能破坏它
"只是原型"	原型会变成生产代码。从第一天就写测试

这个设计直接对抗 AI agent 的合理化倾向，把常见的偷懒路径堵死。

几个值得细看的技能

Context Engineering（上下文工程）

Agent 的输出质量高度依赖它看到的上下文。太少会幻觉，太多会失焦。

这个技能定义了五层上下文层级：

Rules Files（CLAUDE.md 等），始终加载，项目级
Spec / Architecture Docs，按功能/会话加载
Relevant Source Files，按任务加载
Error Output / Test Results，按迭代加载
Conversation History，累积，会被压缩

最高杠杆的操作是写好 Rules File。技能里给了一个 CLAUDE.md 模板，包含技术栈、命令、代码规范、边界条件、模式示例。这个文件每次会话开始时自动加载，相当于给 agent 一个持久的项目记忆。

Incremental Implementation（增量实现）

核心原则：薄垂直切片。不要一次实现整个功能，每次实现一个完整的端到端路径，测试通过后再做下一个。

切片策略三种：垂直切片（首选，一次做一个完整的 CRUD 操作）、契约优先切片（先定义 API 契约，前后端并行）、风险优先切片（先做最不确定的部分）。

每个切片的循环：实现 → 测试 → 验证 → 提交 → 下一个切片。

Code Review（代码审查）

五轴审查模型：正确性、可读性、架构、安全、性能。

审批标准来自 Google 的工程实践：如果一个改动确实改善了代码整体健康度，即使不完美也应该批准。不要因为"不是我会写的方式"就阻塞。

变更大小建议控制在 100 行左右，超过就拆分。

工程文化来源

项目大量借鉴 Google 的工程文化：

Hyrum's Law（API 设计），任何可观察的行为都会被依赖
Beyonce Rule（测试），如果你喜欢它就应该给它加个测试
Test Pyramid（测试），80% 单元 / 15% 集成 / 5% E2E
Chesterton's Fence（代码简化），理解为什么存在再决定是否删除
Trunk-based development（Git 工作流），短命分支，频繁合并
Shift Left（CI/CD），把质量检查尽早前移
Code as Liability（废弃迁移），代码是负债不是资产

这些直接嵌入到技能的步骤流程里，agent 在执行过程中自然遵循。

支持的工具

项目设计为跨工具使用：

Claude Code，通过 plugin marketplace 安装，slash 命令直接可用
Cursor ，把 SKILL.md 复制到 .cursor/rules/
Gemini CLI，原生技能安装
Windsurf，加到 rules 配置
GitHub Copilot，用 agents/ 目录的 persona 定义
Kiro IDE ，放到 .kiro/skills/
其他 agent，技能本身是纯 Markdown，任何接受系统提示的 agent 都能用

跨工具兼容是因为技能的载体就是 Markdown 文件，没有工具特定的依赖。

和其他方案的区别

给 AI agent 加约束的方案有几种：

CLAUDE.md / .cursorrules，项目级规则文件，通常是静态的约束列表
Prompt engineering，在对话里给 agent 指令
Agent Skills，结构化的工作流程，带步骤、检查点、反借口表、验证清单

Agent Skills 不只是告诉 agent "要写测试"，而是给出完整的 TDD 流程：先写失败测试、再写最少代码让它通过、再重构，每一步都有验证条件。这比一行规则的约束力强得多。

代价是 token 消耗。每个技能加载进上下文都占 token，20 个技能全加载不现实。项目用渐进式披露解决：SKILL.md 是入口，支撑材料（references/）只在需要时加载。

局限性

模型能力依赖，技能再好，底层模型不够强也执行不了。复杂的多步骤工作流需要模型有足够的指令遵循能力和长上下文理解能力。

过度流程化的风险，简单任务（改个 typo、加一行日志）走完整的 spec → plan → build → verify → review → ship 流程是浪费。技能里有 When NOT to use 的说明，但 agent 不一定每次都能正确判断。

Google 工程文化的适用性，这些实践来自大规模、长期维护的代码库。小项目、原型、黑客松里，有些规则（100 行变更限制、五轴审查）可能过重。

跨技能协调，20 个技能之间的交互没有明确定义。incremental-implementation 说"每个切片都提交"，code-review 说"merge 前要审查"，实际执行中怎么协调取决于 agent 自己的判断。

适合谁

如果你在用 AI 编码代理做生产级开发，觉得 agent 的输出质量不够稳定，经常需要手动补测试、补安全检查、补文档，Agent Skills 值得试试。

如果只是用 agent 做快速原型或一次性脚本，这套流程可能太重了。

项目地址：github.com/addyosmani/...