每日一个开源项目（第128篇）：Agent Skills - 给 AI 编程 Agent 装上工程纪律

引言

"AI 编程 Agent 默认走最短路径，而最短路径通常意味着跳过 Spec、测试和安全审查。"

这是"每日一个开源项目"系列的第128篇文章 。今天的主角是 Agent Skills------Google Chrome 团队工程师 Addy Osmani 开源的 AI 编程 Agent 工作流 Skill 集合。

你有没有用 Claude Code 或 Cursor 写完一个功能，回头一看，发现 Agent 根本没写测试？或者某个 API 端点完全没有输入验证？或者架构文档依然是空白？

这不是偶然。AI Agent 有一种根深蒂固的倾向：走最短路径。给它一个任务，它会尽快让代码"跑起来"，然后认为工作完成。规格文档、测试覆盖、安全加固------这些事情不在"跑起来"的路径上，所以 Agent 自然会跳过。

Agent Skills 的出发点直接：把资深工程师的工作纪律编码进 Skill 文件，让 Agent 在每个开发阶段都有结构化的流程和退出标准可以遵守。

你将学到什么

Agent Skills 的完整架构：24 个 Skill 如何覆盖开发生命周期的 7 个阶段
7 个斜杠命令的用法：从 /spec 到 /ship 的完整流程
Skill 文件的核心设计：反合理化表格和验证退出条件
4 个 Agent 角色：Code Reviewer、Test Engineer、Security Auditor、Web Performance Auditor
项目嵌入的工程哲学：Hyrum's Law、Beyonce Rule、Chesterton's Fence
在 Claude Code、Cursor 等工具中的安装方式

前置知识

使用过 Claude Code、Cursor 或类似 AI 编程工具
有基本的软件工程背景（了解测试、代码审查、CI/CD 的概念）
希望让 AI 辅助编程更可靠、更符合工程规范

项目背景

项目简介

Agent Skills 是一套为 AI 编程 Agent 设计的生产级工程工作流集合，定位是"让 Agent 像资深工程师一样工作"。

它解决的问题不是 Agent 的能力不足，而是 Agent 的默认行为问题。AI Agent 写代码的能力已经很强，但在没有约束的情况下，它会默认走捷径：代码先跑起来再说，文档以后再写，测试先跳过，安全问题"留到后面处理"。这种行为在单次任务里看起来没问题，在一个真实项目里会快速累积成无法维护的技术债。

作者/团队介绍

作者: Addy Osmani
背景: Google Chrome 团队首席工程师，《学习 JavaScript 设计模式》作者，前端工程领域的知名工程师
License: MIT
版本: 当前主分支持续更新

项目数据

⭐ GitHub Stars: 51,900+
🍴 Forks: 5,700+
📦 内容规模: 24 个 Skill + 7 个斜杠命令 + 4 个 Agent 角色
📄 License: MIT

主要功能

核心作用

Agent Skills 的工作方式很直接：把结构化的工程流程以 Markdown 文件的形式提供给 Agent，Agent 在处理对应任务时读取这些文件，按照其中定义的步骤和检查点执行，而不是凭直觉走最短路径。

markdown 复制代码

没有 Skill 的 Agent：
任务 → 直接写代码 → "完成"
          ↓（跳过 Spec、测试、安全检查）
       技术债堆积

有 Agent Skills 的 Agent：
任务 → 读取对应 Skill → 按阶段执行 → 通过验证条件 → 真正完成
         ↓                      ↓
    明确工作流程            每个阶段有退出标准

使用场景

新功能开发
- /spec 强制先写规格文档，把需求变成可测试的验收标准
- /plan 把功能拆解为独立的原子任务，每个任务修改的文件不超过 5 个
- /build 按切片逐步实现，每个切片都有测试和提交
代码质量控制
- /review 做代码审查，按照 Staff 工程师的标准检查可读性、可测试性、可维护性
- /code-simplify 专门用于简化复杂代码，不等同于重构
测试和验证
- /test 运行测试驱动开发流程，Red-Green-Refactor 循环
- 内置"Prove-It"模式：修 Bug 必须先写一个能复现 Bug 的测试
安全加固
- security-and-hardening Skill 强制在写代码前先做 STRIDE 威胁建模
- 内置 LLM 特有的安全风险清单：防止把模型输出直接传入 SQL、eval、innerHTML
发布流程
- /ship 覆盖从 Git workflow 到 CI/CD 到可观测性的完整发布链路

快速开始

在 Claude Code 中安装：

bash 复制代码

# 方式一：克隆整个仓库
git clone https://github.com/addyosmani/agent-skills
cp -r agent-skills/skills ~/.claude/skills/
cp -r agent-skills/agents ~/.claude/agents/
cp -r agent-skills/commands ~/.claude/commands/

# 方式二：按需复制单个 Skill
cp agent-skills/skills/spec-driven-development/SKILL.md ~/.claude/skills/spec-driven-development.md

安装后，在 Claude Code 中直接使用斜杠命令：

bash 复制代码

/spec 我需要一个用户认证模块，支持邮箱注册、OAuth 登录和密码重置

/build auto 按照刚才的 Spec 实现认证模块

/review 请审查 src/auth/ 下的所有改动

/ship 准备发布 v1.2.0

在 Cursor 中使用：

bash 复制代码

# 把 Skill 文件放到项目根目录
cp -r agent-skills/skills .cursor/skills/

# 或者放到全局配置目录
cp -r agent-skills/skills ~/.cursor/skills/

其他 AI 工具兼容性：

工具	支持方式	斜杠命令
Claude Code	`~/.claude/skills/`	✅ 完整支持
Cursor	`.cursor/skills/`	⚠️ 部分支持
Gemini CLI	`~/.gemini/skills/`	⚠️ 部分支持
Windsurf	`.windsurf/skills/`	⚠️ 部分支持
OpenCode	`.opencode/skills/`	⚠️ 部分支持
GitHub Copilot	支持 Markdown prompt	⚠️ 无斜杠命令
Kiro IDE	原生支持	✅ 完整支持

7 个核心命令

命令	开发阶段	核心原则
`/spec`	定义	先写 Spec，再写代码
`/plan`	规划	小而独立的原子任务
`/build`	实现	一次一个切片
`/test`	验证	测试是证明，不是安慰
`/review`	审查	提升代码健康度
`/code-simplify`	简化	清晰优先于聪明
`/ship`	发布	快也是安全的前提

/build auto 是一个特殊模式：你批准一次计划，Agent 自主执行完整实现，但每个任务都单独提交和测试。

项目详细剖析

Skill 文件的解剖

每个 SKILL.md 文件的结构是固定的，包含四个核心部分：

vbnet 复制代码

SKILL.md 结构
├── Frontmatter（名称、描述、触发条件）
├── Step-by-step Workflow（分阶段的具体步骤）
├── Anti-rationalization Table（反合理化表格）
└── Verification / Exit Criteria（退出条件）

最关键的是后两部分。

反合理化表格把 Agent 最常见的"偷懒借口"列出来，并给出反驳：

合理化借口	现实
"我等下再加测试"	缺陷会叠加，切片 1 的 Bug 会让切片 2-5 全部出错
"一次做完更快"	感觉更快，直到 500 行改动里有东西坏了
"这个重构顺手做了"	把重构混进功能开发，两边都更难审查和调试
"跑一遍看看对不对"	重复跑同一条命令没有任何意义，除非代码有变化

退出条件明确规定什么叫"真正完成"，"看起来对了"不算：

css 复制代码

incremental-implementation 的退出条件：
- [ ] 每个切片都单独测试并提交
- [ ] 完整测试套件通过
- [ ] 构建干净
- [ ] 功能端到端按规格运行
- [ ] 没有未提交的改动

这个设计的意义在于：Agent 有了可以检查的具体标准，而不是靠自我感觉判断任务是否完成。

24 个 Skill 的全景

vbnet 复制代码

Define 阶段（3个）
  ├── interview-me             ← 需求挖掘：通过提问澄清模糊需求
  ├── idea-refine              ← 想法打磨：把粗糙想法变成可执行方向
  └── spec-driven-development  ← 规格驱动：写完整 Spec 再动手

Plan 阶段（1个）
  └── planning-and-task-breakdown ← 任务分解：拆成原子任务，每个 ≤5个文件

Build 阶段（7个）
  ├── incremental-implementation  ← 切片实现：垂直切片，每切片测试提交
  ├── test-driven-development     ← TDD：Red-Green-Refactor
  ├── context-engineering         ← 上下文管理：精确控制 Agent 的工作上下文
  ├── source-driven-development   ← 源码驱动：以现有代码为真相来源
  ├── doubt-driven-development    ← 怀疑驱动：主动寻找自己的盲点
  ├── frontend-ui-engineering     ← 前端 UI：组件设计和可访问性
  └── api-and-interface-design    ← API 设计：契约优先，版本化

Verify 阶段（2个）
  ├── browser-testing-with-devtools ← 浏览器测试：DevTools 深度使用
  └── debugging-and-error-recovery  ← 调试恢复：系统化定位和修复

Review 阶段（4个）
  ├── code-review-and-quality  ← 代码审查：可读性、可测试性、可维护性
  ├── code-simplification      ← 代码简化：减少复杂度而不仅仅是重构
  ├── security-and-hardening   ← 安全加固：STRIDE 建模 + 非谈判项清单
  └── performance-optimization ← 性能优化：Core Web Vitals 和后端性能

Ship 阶段（6个）
  ├── git-workflow-and-versioning   ← Git 工作流：trunk-based 开发
  ├── ci-cd-and-automation         ← CI/CD：自动化流水线设计
  ├── deprecation-and-migration    ← 废弃迁移：安全地移除旧 API
  ├── documentation-and-adrs       ← 文档 ADR：架构决策记录
  ├── observability-and-instrumentation ← 可观测性：日志、指标、追踪
  └── shipping-and-launch          ← 发布上线：完整发布清单

Meta（1个）
  └── using-agent-skills  ← 元 Skill：如何有效使用这套体系

4 个 Agent 角色

除了 Skill 文件，项目还提供 4 个专门的 Agent 角色，用于特定类型的工作：

code-reviewer：按 Staff 工程师标准审查代码，关注可读性、可测试性、副作用和边界情况。

test-engineer：专注测试覆盖和 QA，分析测试质量而不只是计算覆盖率数字。

security-auditor：按 OWASP 清单做安全评估，LLM 应用有单独的检查项（Prompt 注入、上下文泄露、不可信的模型输出）。

web-performance-auditor：Core Web Vitals 专项审计，输出可操作的优化建议。

在 Claude Code 中调用角色：

bash 复制代码

使用 security-auditor 角色审查 src/api/auth.ts

使用 web-performance-auditor 分析首页的加载性能

嵌入的工程哲学

这套 Skill 的设计把几个 Google 工程文化里的核心原则直接编码进了工作流：

Hyrum's Law：一旦有足够多的 API 用户，不管接口文档怎么说，用户都会依赖你实现的所有行为。实践含义：修改任何公开行为前，搜索所有调用方，不要假设未文档化的行为没人用。

Beyonce Rule（"如果你喜欢它，就应该为它写测试"）：如果一个行为值得保留，就值得有测试。没有测试覆盖的代码，变更时没有安全网。

Chesterton's Fence：不理解一段代码为什么存在，就不要删它。先搞清楚原因，再决定是否移除。

Shift Left：把安全和测试从发布前移到开发中，越早发现问题，修复成本越低。

trunk-based development：短生命周期的功能分支，频繁集成到主干，避免长期分支引起的合并冲突。

security-and-hardening 深入：LLM 特有的安全规则

这个 Skill 里有一节专门针对 LLM 应用，值得单独拿出来：

"把所有模型输出都当作不可信输入处理。"

具体规则：

永远不要把模型输出直接传入 SQL 查询、eval()、shell 命令或 innerHTML
System prompt 不是安全边界，权限检查必须写在代码里
把用户的私密数据和其他用户的数据隔离在 prompt 之外，因为上下文里的任何内容都可能被模型回显出来

这些规则对应的是当前 LLM 应用开发里真实存在的安全漏洞模式，不是理论。

项目地址与资源

官方资源

🌟 GitHub : addyosmani/agent-skills
👤 作者 : Addy Osmani
📖 《学习 JavaScript 设计模式》: Addy Osmani 的经典著作

工程原则参考

The Beyoncé Rule --- Google SRE 工作手册
Hyrum's Law --- Hyrum Wright，Google 软件工程
Chesterton's Fence --- G.K. Chesterton，《正统》
Shift Left Testing --- 现代 DevOps 实践

总结

Agent Skills 的价值不在于它带来了新的 AI 能力，而在于它约束了 AI 的默认行为。

AI Agent 能力的上限其实相当高，但默认行为里缺少工程纪律：Spec 可以跳过，测试可以等等再写，安全检查可以留到以后。这些"以后"在实际项目里会永远不到来。

这套 Skill 的设计思路值得借鉴：把专家行为编码成可执行的约束，而不是依赖 AI 自己判断"应该怎么做"。反合理化表格把最常见的偷懒模式列成显式对比，退出条件把"完成"定义得不再模糊。这个模式在 PM 领域（pm-skills）、AI 设计领域（taste-skill）都有类似的应用，本质上是把人类积累的领域知识结构化地传递给 Agent。

对于任何在用 AI 辅助编程的工程师，agent-skills 值得试一试，至少可以把 spec-driven-development 和 test-driven-development 这两个 Skill 装上，看看 Agent 的行为是否发生变化。

探索 PrimeSkills ------ 精选 AI Agent 与技能的市场，每一个都经过真实企业工作流验证，去掉浮夸，留下真正有用的。

欢迎访问我的个人主页，发现更多有价值的见解和有趣的产品。