Agent Skills 深度解析：Addy Osmani 如何用纯 Markdown 给 AI 编程助手装上「工程纪律」

背景：AI 编程助手最深的缺陷，不是能力问题

如果你日常使用 Claude Code、Cursor 或 GitHub Copilot 超过三个月，你大概率经历过这个循环：AI 快速产出代码，PR 发出去，没人愿意认真 Review——因为这份 PR 里没有规格文档、没有边界情况覆盖、测试覆盖率是个位数、安全审查从未发生。代码能跑，但只覆盖了测试数据中的「理想路径」。

这并非工具的能力问题，而是 AI 行为模式中的结构性缺陷。AI 编码代理默认优化的是「任务完成」信号，而非「代码可以安全合并」信号。它们会系统性跳过写规格、先写测试、安全审查、代码健康检查这些「麻烦但必要」的步骤。

Google Chrome 工程总监 Addy Osmani 在 2026 年 4 月发布了一个项目，精准地切入了这个核心矛盾。这个名为 agent-skills 的仓库，在不到三周内突破 37,000+ Star，单日新增最高超过 3,000 星，被 Claude Code、Cursor、Gemini CLI、GitHub Copilot 等主流 AI 编程工具官方收录。

它的核心思路大胆而简洁：将 Google 内部严苛的工程规范编码为 AI Agent 可直接执行的工作流定义——不是给人读的文档，而是给 AI 执行的进度表。

一、核心问题：AI 编程助手的「反纪律」本能

1.1 资深工程师的价值，不在 diff 里

Addy Osmani 在项目博客中精准描述了这个问题：「资深工程师工作的大部分内容，不在 diff 中可见——暴露隐含假设、编写规格文档、将工作拆分为可审查的粒度、选择朴素的设计、留下结果正确的证据、将变更控制在人类可以真正审查的规模内。这些步骤是构建大规模可靠软件的关键，但 AI 代理会跳过它们，原因和一个初级工程师如出一辙：它们不可见。」

这是一个深刻的观察。资深工程师的核心价值，恰恰在于那些不产生代码行数、但决定代码能否安全上线的决策：写规格文档、边界条件思考、安全审查、选择朴素的而非聪明的设计。而 AI 编程代理在默认状态下把这些全部跳过了。

1.2 为什么 AI 会「走捷径」？

从行为模式上看，AI 编码代理跳步骤的原因和初级工程师如出一辙：

• 激励信号错误：优化目标是「生成看起来合理的代码」，而非「生成可以安全合并的代码」
• 隐含知识不可见：规格文档、安全约束、测试策略——这些在人类工程师脑中是「常识」，但在 AI 上下文中完全不可见
• 「看起来没问题」幻觉：AI 极擅长生成流畅、有说服力的解释，让跳过步骤看起来合理

反观人类工程团队如何解决这个问题：通过流程、文化、代码审查制度。但 AI 没有内化这些流程的能力——你必须从外部「加载」它们。

二、核心设计哲学：Skill 不是文档，是可执行的认知协议

2.1 概念澄清：Skill 的本质

理解 Agent Skills 的创新，必须先澄清一个根本性误读：Skill 不是参考文档，不是最佳实践散文集。

在 Claude Code 和 Anthropic 的术语体系中，Skill 是一份带有 Frontmatter（YAML 头部元信息）的 Markdown 文件，在特定情境下被注入 Agent 的上下文中，充当介于系统提示词片段与操作手册之间的存在。

Addy 给出了决定性定义：「Skill 不是『你应该知道的关于测试的一切』的参考资料，它是一个工作流——一个代理按步骤执行的序列，每个检查点产生证据，以明确的退出条件结束。」

关键洞察：对于 AI Agent 而言，将行为规范以过程化工作流呈现，远比以陈述性知识呈现有效。流程优先于文字，步骤驱动优于知识驱动。

2.2 两种表述的对比

传统知识型表述（无效）：

测试应该覆盖主要功能和边界情况。
应该确保测试的可靠性。
建议使用真实的运行时行为来验证。

Agent Skills 的工作流型表述（有效）：

Step 1: 编写会失败的测试
  Checkpoint: 
    - [ ] 测试在实现前运行并失败
    - [ ] 失败消息清晰指出预期行为
  如果测试已经通过 → 停止执行，这是逻辑错误的信号

Step 2: 编写最小实现使测试通过
  Checkpoint:
    - [ ] 测试现在通过
    - [ ] 最小化实现（没有提前优化）
  
Step 3: 重构并保持测试通过
  Checkpoint:
    - [ ] 重构后测试仍然通过
    - [ ] 代码可读性提升

第二个版本不只是更好的提示词——它是一个 Agent 必须执行的序列，每个检查点产生可验证的证据。

三、技能解剖学：SKILL.md 的七段式结构

每个 Skill 文件遵循统一的结构标准，这一格式在项目贡献指南 CONTRIBUTING.md 中有明确定义：

SKILL.md
│
├─ Frontmatter          # name, description, 触发条件
├─ Overview             # 技能做什么，为什么重要
├─ When to Use          # 触发条件与适用场景
├─ Process              # 分步骤的工作流指令 ← 核心
├─ Common Rationalizations  # 反借口表 ← 核心创新
├─ Red Flags            # 执行异常警告
└─ Verification         # 可验证的证据要求

项目贡献指南对 Skill 设定了四项硬性质量门槛：

这一结构的设计本身就是一个工程决策：拒绝将 Skill 膨胀为「知识库」，严格定义为「工作流定义语言」。每一个字段的存在，都是为了防止 AI 在特定环节跳过责任。

四、六阶段生命周期：Define → Plan → Build → Verify → Review → Ship

Agent Skills 的 20 个核心技能按照完整软件开发生命周期（SDLC）组织，覆盖从需求澄清到生产上线的全过程。

4.1 Define 阶段（/spec 命令）

目标：编码之前先写规格

核心技能：

• idea-refine：通过发散、收敛与假设验证，将模糊想法转化为明确的问题定义、目标用户、MVP 范围和「不做事项清单」
• spec-driven-development：在编码前建立结构化规格说明，明确目标、边界、技术约束、验收标准和测试方式

spec-driven-development 技能最关键的一条规则：禁止在需求模糊时直接进入编码。Agent 必须先把任务整理成一份结构化 spec，包含：目标、结构、代码风格、测试策略、边界、成功标准。对于不明确的地方，Agent 需要先显式列出自己的假设，而不是默认补全。

推进流程：

Specify（规格确认）→ Plan（技术方案）→ Tasks（任务拆解，含验收条件）→ Implement（实现）

4.2 Plan 阶段（/plan 命令）

目标：将规格拆解为可执行、可验证的任务

核心技能：

• planning-and-task-breakdown：将规格拆解为小型、可排序、可验证的任务单元，明确依赖、验收条件和检查点

关键原则：每个任务单元必须足够小——一个 Agent 在一个会话内能够完成的粒度。大任务失控的主要原因是人类/AI 对任务规模的误判。

4.3 Build 阶段（/build 命令）

目标：以可控方式逐步交付

核心技能：

• incremental-implementation：以薄切片（thin slice）方式逐步交付，每个增量都需实现、测试、验证后再扩展，保持系统始终处于可工作状态
• test-driven-development：以失败测试定义预期行为，再实现使其通过；修复 Bug 时先复现再修复
• frontend-ui-engineering：面向生产级 UI 构建组件、状态、响应式、可访问性和交互细节
• api-and-interface-design：以契约优先设计 API、模块边界，关注输入输出、错误语义、兼容性和可扩展性
• source-driven-development：对框架和库相关实现优先查证官方文档，基于当前版本和权威来源决策
• context-engineering：按任务阶段裁剪上下文，控制 Agent 看到的信息范围与顺序

4.4 Verify 阶段（/test 命令）

目标：测试即证明，而非测试通过

核心技能：

• browser-testing-with-devtools：通过真实浏览器运行时数据验证 UI（DOM、控制台、网络请求、截图、性能、可访问性），而非依赖静态推断
• debugging-and-error-recovery：按「复现 → 定位 → 缩小范围 → 修复 → 防回归」的顺序排障

这里最关键的原则是：「测试通过」是证据，不是证明。你还需要检查运行时行为、有人类读过 diff、边界情况被覆盖。

4.5 Review 阶段（/review 和 /code-simplify 命令）

目标：提升代码健康度，而非让代码「看起来更好」

核心技能：

• code-review-and-quality：从正确性、可读性、架构、安全和性能等维度审查变更，确认代码整体健康度提升后再合并
• code-simplification：在行为不变的前提下降低复杂度，以理解成本而非行数作为简化标准
• security-and-hardening：将不可信输入、认证授权、敏感数据、依赖、密钥和外部集成纳入默认安全约束
• performance-optimization：先测量再优化，通过指标、profiling 和瓶颈定位驱动改动

4.6 Ship 阶段（/ship 命令）

目标：快速即安全

核心技能：

• git-workflow-and-versioning：通过短分支、原子提交、清晰提交信息和保存点管理变更
• ci-cd-and-automation：用自动化流水线执行 lint、类型检查、测试、构建、安全扫描和部署门禁
• documentation-and-adrs：记录架构决策、约束、权衡和替代方案（ADR = Architecture Decision Record）
• shipping-and-launch：通过上线清单、灰度发布、feature flag、监控和回滚预案完成发布
• deprecation-and-migration：将废弃、迁移和删除旧系统作为正式流程处理

五、五大核心设计原则

5.1 原则一：流程优先于文字（Process over Prose）

Agent 需要的是步骤序列与检查点，而不是知识。流程导向的指令强制 Agent 产生可验证的行为，而知识性文档只会让 Agent 产生「看起来不错」但实际上什么都没做的输出。

这一原则同样适用于人类团队：「如果你的团队手册有 200 页，没人在时间压力下阅读它。如果它是一组带有检查点的小型工作流，人们实际会执行它们。」

5.2 原则二：反借口表（Anti-Rationalization Tables）—— 最独特的创新

这是 Agent Skills 项目设计中最独特、最值得借鉴的创新。每一个 Skill 中都包含一个「常见借口 + 反驳」对照表，在 Agent 产生「跳过步骤」的念头之前就进行拦截：

这一设计的精妙之处在于它精准地抓住了 LLM 的行为特征：LLM 极其善于合理化——它们会产生一段听起来很有说服力的解释，说明为什么这个特定任务不需要规格文档。反借口表本质上是对 Agent 尚未说出的谎言的预先反驳。

更妙的是，Addy 指出这一机制同样适用于人类团队：大多数工程衰退不是有人选择做糟糕的工作，而是人们接受了听起来合理但实则在偷懒的自我合理化。

5.3 原则三：验证不可协商（Verification is Non-Negotiable）

每一个 Skill 都终止于具体的证据产出：测试通过、构建输出干净、运行时行为符合预期、审查人签名通过。核心原则：「看起来没问题」永远不足够。

这背后是对 AI Agent 能力的清醒认知：Agent 是一个生成器，你需要一个独立的信号来确认工作已完成。 每个 Skill 都内建了这一信号作为硬性退出条件。

5.4 原则四：渐进式披露（Progressive Disclosure）

不要在会话启动时将所有 20 个 Skill 全部加载到上下文中，而是根据当前开发阶段按需激活。一个元技能（using-agent-skills）充当路由器，决定哪些 Skill 适用于当前任务。

Addy 解释了背后的 Token 经济逻辑：「每个被加载到上下文中的 Token 都会在某个地方降低性能，所以你加载相关的内容，将其余的留在磁盘上。渐进式披露就是你如何将一个 20-Skill 的库塞进 5K Token 槽位中，同时不污染上下文。」

三层加载机制：

层级 1：技能发现 → AI 读取所有技能的 name + description（极小上下文）
层级 2：核心指令 → 如果相关，AI 自动读取 SKILL.md 正文
层级 3：资源文件 → 只在需要时读取脚本、示例等额外文件

5.5 原则五：范围纪律（Scope Discipline）

元技能中编码了一条不可协商的原则：只碰你被要求碰的东西。不重构相邻系统，不移除你不完全理解的代码，不在修复一个 Bug 时顺带重写三个无关文件。

Addy 直截了当地指出：「范围纪律是决定 Agent 的 PR 是可以合并还是需要被全部回退的最大单一决定因素。」

这一原则与 Google 代码审查的核心理念直接对齐：审核者会因「一个 PR 做了不止一件事」而拒绝合并。

六、Google 工程 DNA：Hyrum 定律、代码审查与测试金字塔

Agent Skills 的 20 个工作流深度浸透了 Google 公开工程文化中的核心原则。每一项都不是新思想，但关键在于——没有一项是 AI 代理默认就会执行的。

6.1 Hyrum 定律与 API 设计

api-and-interface-design 技能明确编码了 Hyrum 定律：API 的每一个可观察行为最终都会被人依赖，因此设计时必须意识到这种隐含的契约。

Addy：「前沿模型在训练数据里读过『Hyrum 定律』这个短语，但它不会在凌晨三点设计你的 API 时主动应用它。Skill 是你确保它会这样做的机制。」

6.2 测试金字塔与 Beyoncé 规则

test-driven-development 技能中编码了测试金字塔（~80% 单元测试 / 15% 集成测试 / 5% 端到端测试）和源于 Google 测试文化的 Beyoncé 规则：「如果你喜欢它，就应该给它配个测试」。

技能同时强调 DAMP 优于 DRY——测试代码应当像规格说明书一样可读，即便这意味着存在部分重复代码。

# DRY 但难读：
def process_order(order):
    return apply_discount(order, calculate_tax(order))

# DAMP（Descriptive And Meaningful Phrases）更可读：
def process_order(order):
    subtotal = order.quantity * order.unit_price
    tax = subtotal * TAX_RATE
    discounted_price = apply_discount(subtotal)
    return OrderResult(subtotal=discounted_price, tax=tax)

6.3 Google 代码审查规范

code-review-and-quality 技能包含 Google 代码审查规范的核心要素：

PR 规模控制:
  建议规模: ~100 行变更
  大型 PR（>400行）: 自动触发额外审查要求
  
严重性分类:
  - Critical: 必须修复才能合并
  - Nit: 建议修复，可选择性接受
  - Optional: 改进建议，不阻塞合并
  - FYI: 信息分享，不需要回复
  
审查通过条件:
  - 至少 1 位 Reviewer 批准（Critical 需 2 位）
  - 所有 Critical 已解决
  - 测试覆盖无下降

核心原则：大型 PR 不会被真正审查——它们只会被「橡皮图章」通过。这一洞察直接转化为 Skill 中的强制流程。

6.4 Chesterton's Fence 与代码简化

code-simplification 技能嵌入了 Chesterton's Fence 原则：「在你移除某样东西之前，先理解它为什么被放在那里。」

// 反面示例：看起来「聪明」的简化
// 原文
const
```javascript
// 反面示例：看起来「聪明」的简化
// 原文
function calculateTotal(items) {
    let total = 0;
    for (let i = 0; i < items.length; i++) {
        total += items[i].price;
    }
    return total;
}

// 简化后（看起来更好，但可能引入bug）
const calculateTotal = items => items.reduce((a, b) => a + b.price, 0);

// ✅ 正确方式：先理解为什么写成循环
// 可能的原因：需要日志记录每个价格、处理精度问题
// 在不理解原因前，不要「简化」

6.5 安全门禁的工程化

security-and-hardening 技能构建了完整的安全防护体系：

安全门禁默认开启:
  - 输入验证: 所有外部输入必须验证类型、范围、格式
  - 认证授权: 检查当前用户是否有权限执行此操作
  - 敏感数据: 确保密码/密钥/token 不出现在日志或错误信息中
  - 依赖审计: 定期运行 npm audit / cargo audit / pip audit
  - SQL注入防护: 参数化查询，无字符串拼接
  - XSS防护: 输出时转义，而非依赖「信任的输入」

OWASP Top 10 默认覆盖:
  - Broken Access Control
  - Cryptographic Failures
  - Injection
  - Insecure Design
  - Security Misconfiguration

七、三层渐进式披露：Token 经济学的工程实践

7.1 为什么不能一次性全部加载？

20 个 Skill × 平均每个 Skill 约 500-800 字 = 10,000-16,000 字的上下文负担。如果在每个会话启动时全部加载：

• 上下文溢出：大多数 AI 编程工具的上下文窗口有限，满载 Skill 会压缩代码和对话的空间
• 信号噪声：不相关的 Skill 会干扰 Agent 对当前任务的判断
• Token 成本：不必要的 Token = 不必要的费用

Agent Skills 的解决方案是三层渐进式加载：

Layer 1 - 技能发现:
  触发时机: 每个会话启动时（极小 Token 预算）
  内容: 所有 Skill 的 name + description（~100 字的元数据）
  目的: 让 Agent 知道「有哪些工具可用」
  
Layer 2 - 核心指令加载:
  触发时机: Agent 当前任务与某 Skill 描述匹配时
  内容: SKILL.md 的完整内容（~500-800 字）
  目的: 提供具体的工作流程指导
  
Layer 3 - 资源文件按需加载:
  触发时机: Skill 执行过程中需要具体资源时
  内容: 示例代码、模板脚本、参考文档
  目的: 提供执行所需的上下文，但不污染主上下文

7.2 Router 元技能的实现逻辑

using-agent-skills 元技能负责判定哪些 Skill 适用于当前任务。核心逻辑：

# 伪代码：Router 的判定逻辑
def should_activate(skill, context):
    # 检查触发条件
    if skill.trigger_conditions not in context:
        return False
    
    # 检查任务类型匹配
    task_keywords = extract_keywords(context.current_task)
    skill_keywords = extract_keywords(skill.description)
    
    overlap = len(task_keywords ∩ skill_keywords)
    if overlap < MIN_OVERLAP_THRESHOLD:
        return False
    
    # 检查是否已在上下文中
    if skill.name in context.loaded_skills:
        return False
    
    return True

关键设计：一个复杂的功能可能依次激活 11 个 Skill，而一个简单 Bug 修复只需 3 个。Skill 的激活是动态的、上下文感知的。

八、实际使用：三种接入模式

8.1 模式一：Claude Code 插件市场（推荐）

# 在 Claude Code 中安装 Agent Skills
/plugin marketplace add addyosmani/agent-skills

# 安装后自动获得 7 个斜杠命令
/spec     # 进入 Define 阶段
/plan     # 进入 Plan 阶段
/build   # 进入 Build 阶段
/test    # 进入 Verify 阶段
/review  # 进入 Review 阶段
/code-simplify  # 进入代码简化模式
/ship    # 进入 Ship 阶段

8.2 模式二：多工具兼容（Cursor / Gemini CLI / Windsurf）

# Cursor 用户：放入项目级或全局规则目录
.cursor/rules/

# Gemini CLI 有自己的安装路径
# 任何接受系统提示词内容的 AI 工具均可直接读取

# Windsurf、Codex、Aider、OpenCode 均可接入

关键洞察：工具链不是关键，底层的工作流才是。 同一个 SKILL.md 文件可以在 Claude Code、Cursor、Gemini CLI、Codex 等任何接受系统提示词内容的 Agent harness 中工作。

8.3 模式三：零安装借鉴（团队工程规范）

即便是完全不安装运行时的团队，也可以将 Skills 视为软件开发工程标准的参考规范来借鉴：

# 从 Agent Skills 提炼的团队工程原则

## 不可跳过的步骤清单
1. [ ] 规格文档（即使只有 5 行）
2. [ ] 测试覆盖率 > 80%（或显式记录不覆盖原因）
3. [ ] 有人类 Review 签名
4. [ ] 边界情况显式覆盖（不覆盖 = 承认风险）

## 反借口检查表
- [ ] 「太简单不需要测试」→ 验收标准仍然适用
- [ ] 「之后再写测试」→ 不存在「之后」
- [ ] 「只是原型」→ 原型也会被部署

九、3 个预配置专家角色与 4 个检查清单

Agent Skills 还提供了开箱即用的高级工具：

9.1 三个专家 Agent 角色

9.2 四个参考检查清单

• testing-patterns：单元测试 / 集成测试 / E2E 测试的编写模式参考
• security-checklist：安全审查的完整检查项
• performance-checklist：性能优化的测量与验证流程
• accessibility-checklist：无障碍设计（a11y）的检查标准

这些检查清单按需加载，进一步贯彻渐进式披露原则。

十、从 Agent Skills 看 AI 时代软件工程的范式转变

10.1 核心判断：AI 是「没有本能的执行者」

Addy Osmani 给出了一个精准的判断框架：「AI 编码代理是极其能干但没有本能的初级工程师——对工作流程中不产生代码的部分毫无感知。」

这意味着：

10.2 范式转换：从「让 AI 更聪明」到「让 AI 更有纪律」

过去的 AI 编程辅助方向是「让 AI 更聪明」——更强的模型、更多的知识。但 Agent Skills 代表了一个新的方向：让 AI 更有纪律。

不是在约束中写「你应该」，而是在流程中写「现在做」。

10.3 给团队的实践建议

从 Agent Skills 项目中可以直接迁移的工程实践：

1. 为团队定制反借口表

将 AI 和团队成员最常见的偷懒借口写成表格，附上反驳理由，贴在团队的工程规范文档中。

2. 建立证据化的退出标准

将「任务完成」的定义从「代码写完了」改为「代码 + 测试 + 审查 + 文档齐全」。每个阶段都必须有可验证的证据。

3. 在上下文管理层面建立渐进式披露策略

不要将所有规则塞入一个巨大的 AGENTS.md 文件。按阶段、按触发场景分组，按需加载。

4. 用 SKILL.md 的七段结构来构建团队内部的 AI 协作规范

Condition: 触发条件
Process: 分步骤的工作流
Checkpoint: 每个步骤的验证点
Anti-Rationalization: 反借口表
Red Flags: 异常警告
Verification: 最终验证标准

十一、总结与展望

Agent Skills 的成功不是偶然。它出现在一个关键的时间节点：当 AI 编码工具从「能生成代码」发展到「能持续交付生产级代码」的阶段，工程规范的外部强制执行就变成了刚性需求。

这个项目的核心创新不在于任何一项具体技术，而在于一种范式转换：

过去的 AI 编程辅助是「让 AI 更聪明」，Agent Skills 的逻辑是「让 AI 更有纪律」。

Addy Osmani 在项目博客结尾写道：「我更希望人们从这个项目中带走的是这个思考框架，而不只是这些技能本身。AI 编码代理是极其能干但缺乏本能的初级工程师——资深工程师的工作（暴露假设、控制变更规模、写规格、留下证据、拒绝合并无法审查的内容）正是不让 AI 跳过的东西。这些资深工程师的部分，即便当工程师本身是一个模型时，也不再是可有可无的选择。」

截至 2026 年 5 月，agent-skills 项目已突破 37,000+ Star，被 Claude Code 官方收录为插件生态的重要组成部分，Cursor、Gemini CLI、GitHub Copilot 等主流工具也在积极适配。一个 Google Chrome 工程总监用纯 Markdown 写的工作流定义，正在成为 AI 编程时代工程纪律的事实标准。

GitHub 地址：https://github.com/addyosmani/agent-skills

推荐阅读顺序：

1. 先读 CONTRIBUTING.md——理解 Skill 的编写哲学
2. 再读 skills/using-agent-skills.md——理解 Router 机制
3. 然后读 skills/spec-driven-development.md——最核心的 Define 技能
4. 最后按需阅读其他 17 个 Skill

如果你正在使用 AI 编程工具，请从今天开始给你的 AI 加上工程纪律。毕竟，能写代码的 AI 很多，能写出生产级代码的 AI，需要的不仅是能力，还需要流程。

本文参考来源：

• https://github.com/addyosmani/agent-skills
• https://addyosmani.com/blog/agent-skills/
• https://blog.csdn.net/2401_84262484/article/details/160442339
• https://blog.csdn.net/Chen__2024/article/details/160856304
• https://www.runoob.com/ai-agent/claude-agent-skills.html