每日一个开源项目（第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 在处理对应任务时读取这些文件，按照其中定义的步骤和检查点执行，而不是凭直觉走最短路径。
没有 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-hardeningSkill 强制在写代码前先做 STRIDE 威胁建模- 内置 LLM 特有的安全风险清单：防止把模型输出直接传入 SQL、
eval、innerHTML
发布流程
/ship覆盖从 Git workflow 到 CI/CD 到可观测性的完整发布链路
快速开始
在 Claude Code 中安装：
# 方式一：克隆整个仓库gitclone https://github.com/addyosmani/agent-skillscp-ragent-skills/skills ~/.claude/skills/cp-ragent-skills/agents ~/.claude/agents/cp-ragent-skills/commands ~/.claude/commands/# 方式二：按需复制单个 Skillcpagent-skills/skills/spec-driven-development/SKILL.md ~/.claude/skills/spec-driven-development.md安装后，在 Claude Code 中直接使用斜杠命令：
/spec 我需要一个用户认证模块，支持邮箱注册、OAuth 登录和密码重置 /build auto 按照刚才的 Spec 实现认证模块 /review 请审查 src/auth/ 下的所有改动 /ship 准备发布 v1.2.0在 Cursor 中使用：
# 把 Skill 文件放到项目根目录cp-ragent-skills/skills .cursor/skills/# 或者放到全局配置目录cp-ragent-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文件的结构是固定的，包含四个核心部分：
SKILL.md 结构 ├── Frontmatter（名称、描述、触发条件） ├── Step-by-step Workflow（分阶段的具体步骤） ├── Anti-rationalization Table（反合理化表格） └── Verification / Exit Criteria（退出条件）最关键的是后两部分。
反合理化表格把 Agent 最常见的"偷懒借口"列出来，并给出反驳：
| 合理化借口 | 现实 |
|---|---|
| “我等下再加测试” | 缺陷会叠加，切片 1 的 Bug 会让切片 2-5 全部出错 |
| “一次做完更快” | 感觉更快，直到 500 行改动里有东西坏了 |
| “这个重构顺手做了” | 把重构混进功能开发，两边都更难审查和调试 |
| “跑一遍看看对不对” | 重复跑同一条命令没有任何意义，除非代码有变化 |
退出条件明确规定什么叫"真正完成"，"看起来对了"不算：
incremental-implementation 的退出条件： - [ ] 每个切片都单独测试并提交 - [ ] 完整测试套件通过 - [ ] 构建干净 - [ ] 功能端到端按规格运行 - [ ] 没有未提交的改动这个设计的意义在于：Agent 有了可以检查的具体标准，而不是靠自我感觉判断任务是否完成。
24 个 Skill 的全景
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 中调用角色：
使用 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 与技能的市场，每一个都经过真实企业工作流验证，去掉浮夸，留下真正有用的。
欢迎访问我的个人主页，发现更多有价值的见解和有趣的产品。