🤖 Addy Osmani Agent-Skills 深度研究：让AI编码助手像资深工程师一样工作

📚 学习来源

🎯 核心收获

一、项目背景与动机

1.1 作者背景

Addy Osmani 是 Google Chrome 团队的工程总监，前端工程领域的传奇人物，著有《Learning JavaScript Design Patterns》，是 Lighthouse 的核心贡献者。他每天都在使用 AI 编码工具，因此敏锐地察觉到了一个普遍问题：AI 编码助手默认会走最短路径，而这条路径恰恰会跳过那些"不出现在 diff 里"但至关重要的工程步骤。

1.2 核心问题

"AI coding agents default to the shortest path — which often means skipping specs, tests, security reviews, and the practices that make software reliable."

当用户说"帮我加一个用户导出功能"时，AI 助手会噼里啪啦写完代码、跑通了，潇洒地说"Done!"。但它没有问导出格式要不要兼容旧版本，没有写测试，没有考虑权限边界，提交的 diff 大到没人能 review。

1.3 项目数据

二、六阶段开发流水线

2.1 Define 阶段——澄清要构建什么

技能：idea-refine、spec-driven-development

这是最重要的阶段，却被大多数 AI 助手默认跳过。Define 阶段的核心是：

• 将模糊的想法转化为具体的提案
• 撰写 PRD（产品需求文档）
• 覆盖目标、命令、结构、代码风格、测试和边界
• 在任何代码之前完成

2.2 Plan 阶段——拆解任务

技能：planning-and-task-breakdown

将规格说明分解为小的、可验证的任务：

• 每个任务应该在一次专注的会话中完成
• 任务有显式的验收标准
• 任务有验证步骤（测试、构建、手动检查）
• 任务按依赖排序，而非按感知的重要性排序

2.3 Build 阶段——编写代码

技能（7个）：incremental-implementation、test-driven-development、context-engineering、source-driven-development、doubt-driven-development、frontend-ui-engineering、api-and-interface-design

2.4 Verify 阶段——证明它能工作

技能：browser-testing-with-devtools、debugging-and-error-recovery

五步排查：复现→定位→简化→修复→防护，停止规则：不推进失败的测试或构建

2.5 Review 阶段——合并前的质量门

技能（4个）：code-review-and-quality、code-simplification、security-and-hardening、performance-optimization

五个审查维度：正确性、可读性、架构、安全性、性能

2.6 Ship 阶段——部署上线

技能（5个）：git-workflow-and-versioning、ci-cd-and-automation、deprecation-and-migration、documentation-and-adrs、shipping-and-launch

三、技能解剖规范（Skill Anatomy）

每个 SKILL.md 都遵循统一的解剖结构，这是 Agent-Skills 项目最核心的设计规范之一。

3.1 Frontmatter（必需）

---
name: skill-name-with-hyphens
description: Guides agents through [task/workflow]. Use when [specific trigger conditions].
---

关键规则：

• name：小写、连字符分隔，必须与目录名匹配
• description：以第三人称描述技能做什么，然后包含一个或多个清晰的"Use when"触发条件。必须同时包含"什么"和"何时"

3.2 标准章节结构

# Skill Title

## Overview
1-2 句话解释这个技能做什么以及为什么重要。

## When to Use
- 触发条件的项目符号列表
- When NOT to use（排除项）

## Core Process
Agent 遵循的主要工作流，分解为编号步骤或阶段。

## Common Rationalizations
| Rationalization | Reality |
|-----------------|---------|
| Agent 用来跳过步骤的借口 | 为什么这个借口是错误的 |

## Red Flags
- 表明技能被违反的行为模式

## Verification
技能流程完成后确认：
- [ ] 退出条件清单

四、反借口表机制（Anti-Rationalization）

这是 Agent-Skills 项目最独特、最值得借鉴的设计创新。

4.1 设计哲学

LLM 训练文本中包含大量关于"为什么走捷径是可以的"的推理。反-rationalization 表通过提供同样强有力的反向推理来预先阻止这一点。

4.2 真实示例

4.3 企业 AI 培训的启发

• Prompt 技巧工作坊：训练用户识别 AI 偷懒行为的常见模式
• 质量管控：建立企业 AI 使用的反借口清单
• 教育培训：让员工学会对 AI 的"跳过步骤"请求说"不"

五、重点技能深度解读

5.1 doubt-driven-development：对抗性自检流程

这是 Agent-Skills 中最新、最具创新性的技能之一。

触发条件：

• 生产、安全或不可逆决策
• 工作中接触不熟悉的代码
• 自信的输出现在验证比以后调试便宜

交叉模型验证：可选地在交互式怀疑循环中提供跨模型验证——使用不同模型发现单一模型共享的盲点。

5.2 source-driven-development：基于官方文档验证

来源层级（按权威性排序）：

5.3 context-engineering：上下文打包策略

六、Agent 角色设计

6.1 三个专家角色

6.2 多角色协作模式

唯一推荐的多角色编排模式是并行扇出+合并步骤：

七、Google 工程文化的体现

八、多平台支持与安装

推荐起步配置

最小配置：加载三个核心技能

• spec-driven-development —— 定义要构建什么
• test-driven-development —— 证明它能工作
• code-review-and-quality —— 合并前验证质量

九、与其他 Skills 框架的对比

vs Matt Pocock Skills

核心差异

1. 工程流程导向 vs 能力封装导向：Agent-Skills 不是封装能力（"如何写测试"），而是封装流程（"在写代码之前要做什么"）
2. 强制执行 vs 建议遵循：通过反借口表，技能是强制执行的，而非可选建议
3. 完整生命周期 vs 单点覆盖：覆盖从 idea 到 ship 的完整流程

💭 思考与实践