一天一个开源项目（第94篇）：Agent Skills - 为 AI 代码助手注入工程师级纪律

引言

"AI agents are only as good as the workflows they follow."

这是"一天一个开源项目"系列的第94篇文章。今天带你了解的项目是 Agent Skills。

如果说上一篇的 Symphony 解决了"如何在规模上运行 AI 代理"的问题，那么 Agent Skills 解决的则是更基本的问题：如何让一个 AI 编码助手真正具备一名高级工程师的工程素养？

这个项目来自 Google Chrome 的工程总监 Addy Osmani------前端工程界的传奇人物，《Learning JavaScript Design Patterns》的作者。他用一个简洁的洞察描述了 AI 工具的现状：AI 会"走捷径"。它会跳过写 spec、跳过测试、跳过安全审查，只要能交出一份看起来能运行的代码就算完成任务。而 Agent Skills 的使命就是通过 20 套精心设计的工作流，从根本上改变这一现状。

你将学到什么

• 什么是"结构化工作流"，它如何改变 AI 代理的行为模式
• Agent Skills 如何通过"反理由化（Anti-Rationalization）"设计消除常见的 AI 偷懒借口
• 7 个 Slash Command 如何贯穿开发全生命周期
• 如何在 Claude Code、Cursor 等主流工具中安装并使用
• 与其他 AI 编码提升方案的对比

前置知识

• 日常使用过 Claude Code、Cursor 等 AI 编码工具
• 对软件工程的基本流程（需求 → 设计 → 编码 → 测试 → 上线）有基本了解
• 无需任何特定编程语言背景

---

项目背景

项目简介

Agent Skills 是一个纯文本（Markdown）的工程工作流集合。它不是一个框架、不是一个 SDK，而是一套可被 AI 工具直接加载的"思维规程"。当你在 Claude Code 或 Cursor 中加载这套技能后，AI 不再会随意开始写代码------它会先问：我们有 spec 吗？任务分解了吗？测试通过了吗？

核心理念来自 Google 内部的工程文化：Hyrum's Law（接口的隐性依赖会被滥用）、测试金字塔、主干开发（Trunk-based Development） ，以及最关键的------把代码视为负担而非资产。

作者/团队介绍

• 作者：Addy Osmani
• 身份：Google Chrome 工程总监，知名前端工程师
• 代表作：《Learning JavaScript Design Patterns》、Lighthouse 性能工具核心贡献者、众多前端最佳实践规范的奠基人
• 创建动机：在日常使用 AI 编码工具时，Addy 发现 AI 会系统性地跳过"麻烦但必要"的工程步骤，于是将他多年积累的工程规范编码成 AI 可直接执行的工作流

项目数据

• ⭐ GitHub Stars: 30,800+
• 🍴 Forks: 3,600+
• 👀 Watchers: 219
• 📝 Commits: 162
• 📄 License: MIT
• 🌐 仓库: addyosmani/agent-skills

---

主要功能

核心作用

Agent Skills 的核心价值在于：把隐性的工程纪律变成显性的、AI 可执行的步骤清单。

一个普通的 AI 助手被要求"修复一个 bug"时，它会直接写代码然后说"完成了"。而一个加载了 Agent Skills 的 AI 助手会依次经历：问题确认 → 根因分析 → 最小化复现 → 修复 → 测试覆盖 → 代码审查 → 文档更新，每一步都有明确的验证标准。

使用场景

1. 个人开发者提升 AI 协作质量

   • 为 Claude Code 或 Cursor 加载工作流，让 AI 帮你从头完整做一个功能，而不是只写代码主体扔给你收拾边角料。

2. 团队统一 AI 使用规范

   • 在团队的代码仓库中放置项目级的工作流配置，让所有成员的 AI 助手遵循一致的工程标准。

3. AI 代理流水线的质量门控

   • 在自动化 CI/CD 中使用 Agent Skills 作为 AI 生成代码的审查框架，防止低质量代码进入主干。

4. AI 编码教育与培训

   • 通过观察 AI 在工作流约束下如何处理各类工程问题，学习最佳实践。

快速开始

方法 1：Claude Code 插件市场（推荐）

# 在 Claude Code 会话中执行
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

安装后，直接使用 Slash Command：

# 定义需求
/spec 我需要一个用户认证功能，支持 OAuth 2.0

# 规划任务
/plan

# 开始实现
/build

# 验证功能
/test

# 代码审查
/review

# 化繁为简
/code-simplify

# 部署上线
/ship

方法 2：本地克隆（适用于所有工具）

# 克隆仓库
git clone https://github.com/addyosmani/agent-skills.git

# 在 Claude Code 中加载
claude --plugin-dir /path/to/agent-skills

# 在 Gemini CLI 中加载
gemini skills install https://github.com/addyosmani/agent-skills.git --path skills

方法 3：直接在 CLAUDE.md 中引用

# CLAUDE.md
Load the following skills for this project:
- skills/build/incremental-implementation
- skills/verify/test-driven-development
- skills/review/code-review-and-quality

核心特性

1. 20 个专业技能（Skills）

   • 覆盖 Define、Plan、Build、Verify、Review、Ship 六个开发阶段，每个技能都有明确的触发条件、执行步骤和验证标准。

2. 7 个 Slash Command

   • /spec、/plan、/build、/test、/review、/code-simplify、/ship，将复杂工作流压缩为单个命令。

3. 3 个专家角色（Agent Personas）

   • code-reviewer（代码审查专家）、test-engineer（测试工程师）、security-auditor（安全审计员）------让 AI 以专业角色的视角审视你的代码。

4. 反理由化（Anti-Rationalization）设计

   • 每个技能文件内置"借口与反驳表"，预先堵住 AI 常用的偷懒借口，例如："需求还没确认，先写代码吧" → "不，先用 /spec 锁定需求"。

5. 验证优先（Verification-First）

   • 每个步骤完成后必须提供可验证的证据（测试通过截图、构建产物、运行时数据），而不是主观判断"应该没问题了"。

6. 工具无关性

   • 同一套技能支持 Claude Code、Cursor、Gemini CLI、Windsurf、OpenCode、GitHub Copilot、Kiro IDE 等所有主流 AI 编码工具。

7. 4 份参考检查表

   • 测试模式、安全规范、性能优化、无障碍访问------提供随时可调用的专业检查清单。

项目优势

对比项	Agent Skills	普通 System Prompt	Rules 文件 (.cursorrules)
结构化程度	完整的工作流，有步骤和检查点	自由文本，AI 理解因人而异	偏向代码风格规范
工程深度	覆盖全生命周期（spec 到 ship）	通常只覆盖代码生成	主要约束代码格式
防偷懒机制	内置反理由化表	无	无
多工具支持	7+ 主流 AI 工具	工具相关	工具相关
可维护性	版本化的 Markdown，可 PR 更新	散落在各处	仓库级单文件

为什么选择 Agent Skills？

• 出身于工程文化最严格的团队之一（Google Chrome），工程质量有保证
• 30k+ Stars 代表了大量真实用户的验证
• 纯 Markdown 实现意味着零侵入、随时可调整、无供应商锁定

---

项目详细剖析

1. 技能文件的解剖：一个 Skill 长什么样？

以 skills/build/incremental-implementation/SKILL.md 为例，每个技能文件遵循一套固定的解剖结构：

---
name: incremental-implementation
description: Build features in small, testable increments
triggers:
  - "start implementation"
  - "begin coding"
  - "implement feature"
---

## Overview
[技能的目的和适用范围]

## When to Use
[触发这个技能的具体场景]

## Process
[逐步执行的工作流，每步都有明确的交付物]

### Step 1: Understand the task
- 确认需求是否已经有 spec
- 明确这次实现的边界（in scope / out of scope）
...

## Rationalizations (借口与反驳)
| 常见借口 | 为什么不行 |
|:---|:---|
| "需求很简单，直接写" | 简单不代表不需要边界定义 |
| "先跑通再写测试" | 这会导致测试覆盖不足... |

## Red Flags
[应该警惕的错误信号，如一次提交超过 400 行]

## Verification
[完成这个技能需要提供的证明]

这种结构的精妙之处在于：它不是写给人看的文档，而是写给 AI 执行的程序。每个字段都在约束 AI 的行为边界。

2. 六阶段工作流：从想法到上线的完整闭环

Define → Plan → Build → Verify → Review → Ship
  ↓         ↓       ↓        ↓        ↓       ↓
/spec    /plan   /build   /test   /review  /ship
  ↓         ↓       ↓        ↓        ↓       ↓
需求锁定  任务分解  增量实现  测试证明  质量门控  安全发布

每个阶段都有对应的技能支撑：

Define（定义阶段）：

• idea-refine --- 将模糊想法磨砺成可执行需求
• spec-driven-development --- 用规范驱动开发，而非凭感觉

Plan（规划阶段）：

• planning-and-task-breakdown --- 将需求拆分为原子级、可验证的最小任务

Build（构建阶段）：

• incremental-implementation --- 小步快跑，每一步都可测试
• test-driven-development --- 先写测试，再写实现
• frontend-ui-engineering --- 前端工程的专项规范（无障碍、性能、响应式）
• source-driven-development --- 用官方文档/源码驱动实现，而非靠记忆
• documentation-as-code --- 文档即代码，与实现同步更新
• code-as-liability --- 把代码视为需要管理的负担（包括删除）

Verify（验证阶段）：

• browser-testing-with-devtools --- 用真实工具验证，不依赖主观感觉
• debugging-and-error-recovery --- 系统化的调试方法论

Review（审查阶段）：

• code-review-and-quality --- 代码审查的完整流程
• security-and-hardening --- 安全审计专项
• performance-optimization --- 性能瓶颈识别与优化
• change-sizing --- 控制变更粒度（符合谷歌的"小 PR"文化）

Ship（发布阶段）：

• git-workflow-and-versioning --- Git 工作流规范
• ci-cd-and-automation --- CI/CD 流水线配置
• shipping-and-launch --- 安全发布检查清单
• trunk-based-development --- 主干开发实践
• code-deprecation --- 老代码的退役流程

3. 专家角色（Agent Personas）：让 AI 穿上"职业制服"

这是 Agent Skills 中一个非常有创意的设计。与其让同一个 AI 又写代码又审代码，不如让它"变身"为一个纯粹的专家：

security-auditor 角色示例：

You are a security auditor. Your ONLY job is to find vulnerabilities.
Do NOT suggest new features. Do NOT improve code quality.
Focus EXCLUSIVELY on:
- Input validation gaps
- Authentication/Authorization flaws  
- Injection vulnerabilities (SQL, XSS, SSTI...)
- Exposed secrets or credentials
- Insecure dependencies

当你调用 security-auditor 角色审查代码时，AI 会完全进入安全专家的视角，不会被功能实现分心------这种**单一职责原则（SRP）**在 AI 使用层面的应用，效果出人意料地好。

4. 反理由化（Anti-Rationalization）：工程纪律的"护城河"

这是整个项目最独特的设计之一。每个技能文件都包含一张"借口-反驳"对照表，专门针对 AI（和人）在压力下的常见逃避行为：

AI 常见借口	工程纪律的反驳
"这个功能很简单，直接写"	简单性是主观判断，没有 spec 就没有验收标准
"测试之后再补"	补测试的技术债通常不会被还清
"只是临时的 workaround"	临时方案的平均寿命超乎你的想象
"PR 已经很大了，再加点也无所谓"	大 PR 是审查盲区，也是 merge 冲突的来源
"性能优化以后再说"	以后很可能意味着永远不会

---

项目地址与资源

官方资源

• 🌟 GitHub : github.com/addyosmani/...
• 📚 技能解剖文档 : docs/skill-anatomy.md
• 🤝 贡献指南 : CONTRIBUTING.md
• 🛠️ Claude Code 文档 : docs/claude-code.md

适用人群

• 日常使用 Claude Code、Cursor 等 AI 编码工具，但发现 AI 经常"偷工减料"的开发者
• 希望在团队中统一 AI 使用规范的技术负责人
• 对工程最佳实践感兴趣，希望借助 AI 工具实践 Google 工程文化的工程师
• 构建自动化 Agent 流水线，需要质量保障机制的 AI 应用开发者

---

总结与展望

核心要点回顾

1. AI 默认会走捷径，Agent Skills 通过结构化工作流强制 AI 遵循工程纪律
2. 纯 Markdown 实现，零依赖、工具无关、完全可自定义
3. 覆盖完整开发生命周期，从需求 spec 到代码退役，7 个 Slash Command 贯穿始终
4. 反理由化设计是最独特的亮点，预先消除 AI 的常见偷懒借口
5. 来自 Google Chrome 工程总监，工程理念经过大规模生产验证

一句话评价

如果说 AI 编码工具让你写代码快了 10 倍，那么 Agent Skills 让你写的代码也好了 10 倍。

---

欢迎来我的个人主页找到更多有用的知识和有趣的产品