给 AI 编码 Agent 装上「谷歌级工程纪律」：深度解析 Addy Osmani 的 agent-skills，从 Skill 解剖学到亲手写一个生产级技能
2026 年 7 月，GitHub Trending 被一类项目悄悄占领：addyosmani/agent-skills 以日增 400+ Star 的速度冲上前列。它不卖模型、不卷参数，只做一件事——把 Google 级工程师的"工程纪律"，编译成 AI 编码 Agent 能直接执行的技能（Skill）。本文不只讲它是什么，更带你从解剖学到架构，最后亲手写一个能拦住"裸奔上线"的生产级技能。
一、背景：AI 编码 Agent 的「最短路径陷阱」
如果你用过 Claude Code、Cursor 或 Gemini CLI 写代码，大概率见过这一幕：你让它"加个接口"，它啪一下把实现怼出来，没规格、没测试、没迁移脚本，甚至顺手 git push。AI 的天性是走最短路径——它默认会跳过写规格、写测试、做安全审查这些"麻烦事"，直接产出"玩具级"代码。
这不是模型不够聪明，而是缺约束。
- 你写一句 prompt："记得写测试"——AI 读完"大概知道"，然后继续走捷径。
- 你贴一份 200 页《单元测试最佳实践》——AI 读进上下文，但没有任何"强制退出条件"，它照样可以说"我写了测试"然后过。
- 你指望 AI "像资深工程师一样思考"——但它没有资深工程师坐你旁边时那句"先别急着写，说清楚要做什么"。
Addy Osmani（Google 工程总监，Angular、Lighthouse 之父）开源的 agent-skills，本质就是把这个"坐你旁边的资深工程师"固化成一堆结构化的 Markdown 文件。它不是一个独立软件，而是 Claude / Cursor / Gemini 等 AI IDE 的"纪律插件"。
核心洞察一句话：普通 prompt 是口号，参考文档是教科书，而 Skill 是手术 checklist——AI 必须执行完才能继续。
二、核心概念：Skill 不是 Prompt，是「可执行的工程纪律」
2.1 三个东西的区别
| 形态 | 本质 | AI 的反应 | 缺陷 |
|---|---|---|---|
| 普通 prompt | 一句口号（"写测试"） | 读完"大概懂" | 无强制力，易被绕过 |
| 参考文档 | 教科书（200 页规范） | 塞进上下文 | 无退出条件，AI 自说自话 |
| Skill | 手术 checklist | 必须逐步执行 + 过 checkpoint | 几乎没有（除非写错） |
Skill 的关键不在"告诉 AI 做什么"，而在"约束 AI 怎么证明自己做了"。
2.2 Skill 解剖学（skill-anatomy）
agent-skills 里每个 Skill 都按统一的解剖结构组织，这是它能被"强制执行"的基石。一个标准 SKILL.md 长这样：
---
name: spec-driven-development
description: 编码前建立规格说明，明确目标、边界、技术约束与验收标准
---
## Overview
本 skill 强制在写任何实现代码前，先产出可验证的规格说明……
## When to Use
- 接到一个模糊需求，不知道"完成"长什么样
- 涉及 API 契约、数据库 schema、跨模块改动
## Core Process
1. 写下目标用户与核心场景
2. 定义验收标准（可测试）
3. 列出技术约束与"不做事项"
4. 产出 spec 文件，等待人工确认后再进入 /build
## Examples
（代码示例与模式）
## Common Rationalizations
- "这只是个小改动" → 小改动也会滚雪球，先写 spec
- "我脑子里有方案" → 脑子里的方案无法被审查
## Red Flags
- 没有 spec 文件就开始写实现
- spec 里没有可测试验收标准
## Verification
- [ ] spec 文件已创建
- [ ] 至少 3 条可测试验收标准
- [ ] 已列出"不做事项"
注意几个反直觉的设计：
Common Rationalizations（常见偷懒借口）：AI 最擅长给自己找借口。Skill 直接把借口写进去并附反驳——"我会稍后加测试"→"稍后=永不，现在写"；"这只是原型"→"原型也会被部署"。Red Flags（违规信号）：明确告诉 AI"这些情况说明你正在违反本 skill"，让它自我纠偏。Verification（退出标准 checklist）：这是灵魂。AI 不能说"我写了测试"，必须逐条勾选通过才能进入下一步。
2.3 六阶段生命周期 + 七命令
agent-skills 把软件开发拆成六阶段，AI 必须按顺序走，不能跳步：
DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP
定义 → 规划 → 构建 → 验证 → 审查 → 发布
/spec /plan /build /test /review /ship (+ /code-simplify)
7 个斜杠命令，每个自动激活对应 Skill 组合：
| 你在做什么 | 命令 | 核心原则 |
|---|---|---|
| 定义要构建什么 | /spec | 先写规格，再写代码 |
| 规划如何构建 | /plan | 小而原子化的任务 |
| 增量构建 | /build | 每次只改一个切片 |
| 证明它能工作 | /test | 测试即证明 |
| 合并前审查 | /review | 提升代码健康度 |
| 代码简化 | /code-simplify | 删冗余，保可读 |
| 发布上线 | /ship | 非玄学上线 |
系统会根据任务类型自动激活相关 skill（如设计 API 时触发 api-and-interface-design，写前端时触发 frontend-ui-engineering）。仓库内置约 20 个核心 skill，覆盖整个生命周期。
三、架构分析：为什么是"一堆 Markdown 文件"而不是一个大 Prompt
很多人第一反应是："不就是几个 prompt 文件吗？" 但 agent-skills 的目录结构暴露了它的工程化野心：
agent-skills/
├── skills/ # 所有 Skill 的 SKILL.md（按需加载）
├── commands/ # 7 个斜杠命令的 Markdown 定义
├── references/ # 长文档，AI 用时才读，不进主上下文
├── scripts/ # 可执行脚本（校验、生成等）
├── hooks/ # 自动化闸门（PreToolUse / PostToolUse）
├── .claude/ # Claude Code 插件适配
├── .gemini/ # Gemini CLI 适配
├── .opencode/ # OpenCode 适配
└── .github/ # GitHub Copilot 适配
3.1 分文件而非一坨 prompt 的四个理由
- 上下文预算：20 个 skill 全塞进上下文会爆窗口。
references/里的长文档只在 AI 需要时加载，主上下文只保留轻量SKILL.md。 - 按需激活：AI 写前端才加载
frontend-ui-engineering，不会在写 SQL 时被前端规范干扰。 - 可版本化 / 可审查：每个 skill 是独立文件，能走 PR、能 diff、能 code review——工程纪律本身也被工程化了。
- 跨 IDE 复用：同一套
skills/，通过.claude/、.gemini/、.opencode/、.github/四套适配层，能在主流 AI IDE 间无缝迁移。你写一次纪律，全平台生效。
3.2 Hooks：把纪律焊死在工具链上
Skill 靠"AI 自觉遵守"，但总有模型想抄近路。Hooks 是最后一道物理闸门——它在工具真正执行前拦截。比如 PreToolUse hook 可以在 AI 试图 git push --force 或执行 DROP TABLE 时直接拒绝，不给你"求情"的机会。
这正是 agent-skills 比单纯"写个好 prompt"强一个量级的地方：prompt 求 AI 自觉，hook 强制 AI 守规矩。
四、代码实战：从解剖到亲手搓一个生产级技能
光看不练假把式。下面我们从真实结构出发，写一个能拦住"裸奔上线"的数据库迁移安全检查技能，含完整可运行代码。
4.1 解剖一个真实命令文件
Claude Code 插件的命令文件极简——.claude/commands/ship.md：
---
description: 发布前的工程闸门，强制先过 /review 与 /test
---
执行发布前，必须确认以下 checkpoint 全部通过：
- /test 已运行且全绿
- /review 未遗留 BLOCKER
- 数据库迁移已通过迁移安全检查（见 db-migration-safety skill）
若任一 checkpoint 未过，立即停止，不得执行发布相关命令。
这就是"命令即纪律"——输入 /ship，AI 被强制走闸门。
4.2 写一个生产级 Skill：数据库迁移安全检查
真实工程里，最容易被 AI 搞炸的就是数据库迁移：顺手写个 DROP COLUMN、忘了回滚脚本、生产直接翻车。我们做一个 db-migration-safety Skill。
skills/db-migration-safety/SKILL.md：
---
name: db-migration-safety
description: 审查 SQL 迁移文件，拦截破坏性操作、缺失回滚、不可逆变更
---
## Overview
本 skill 在每次生成或修改 SQL 迁移后，强制运行安全检查脚本，
拦截可能导致生产数据丢失或不可回滚的变更。
## When to Use
- 新增 / 修改任何 .sql 迁移文件
- 在 /ship 之前
## Core Process
1. 运行 scripts/check_migration.py 扫描所有待发布迁移
2. 若存在 BLOCKER（破坏性操作 / 无回滚），停止并修复
3. 通过后才允许进入 /ship
## Examples
（见 scripts/check_migration.py）
## Common Rationalizations
- "我就删个没人用的列" → 先确认无外键/无读取，再加回滚
- "回滚太麻烦" → 不可回滚 = 不能上线
## Red Flags
- 迁移文件含 DROP/TRUNCATE 但无配套回滚
- DELETE 无 WHERE 条件
## Verification
- [ ] check_migration.py 退出码为 0
- [ ] 每个迁移都有可逆定义（DOWN/ROLLBACK）
skills/db-migration-safety/scripts/check_migration.py：
#!/usr/bin/env python3
"""数据库迁移安全检查：拦截破坏性操作与不可逆变更。"""
import sys, re, pathlib
# 破坏性/高风险模式
DANGEROUS = [
(r"\bDROP\s+TABLE\b", "检测到 DROP TABLE，需确认无业务依赖且提供回滚"),
(r"\bTRUNCATE\b", "检测到 TRUNCATE，数据不可恢复"),
(r"\bDELETE\s+FROM\b(?![\s\S]*?\bWHERE\b)", "DELETE 缺少 WHERE，将清空整表"),
(r"\bALTER\s+TABLE\b[\s\S]*?\bDROP\s+COLUMN\b", "删除列需确认无读取方并提供回滚"),
]
def check(path: str) -> list[str]:
sql = pathlib.Path(path).read_text(encoding="utf-8")
issues = []
for pat, msg in DANGEROUS:
if re.search(pat, sql, re.IGNORECASE | re.DOTALL):
issues.append(f"[BLOCKER] {msg}")
# 可逆性：必须有 DOWN 或 ROLLBACK 定义
if not re.search(r"\b(DOWN|ROLLBACK)\b", sql, re.IGNORECASE):
issues.append("[BLOCKER] 迁移缺少回滚定义（DOWN/ROLLBACK），不可逆")
return issues
if __name__ == "__main__":
if len(sys.argv) < 2:
print("usage: check_migration.py <file.sql> [...]"); sys.exit(2)
failed = False
for f in sys.argv[1:]:
issues = check(f)
if issues:
failed = True
print(f"[FAIL] {f}")
for i in issues:
print(" " + i)
else:
print(f"[OK] {f}")
sys.exit(1 if failed else 0)
跑一下：python3 check_migration.py migrations/003_drop_old.sql。有 DROP 又没 ROLLBACK？退出码 1，闸门关闭，AI 无法 /ship。
4.3 Hooks：用 PreToolUse 把危险命令焊死
Skill 是"软约束"，Hook 是"硬拦截"。给 Claude Code 加一个 PreToolUse hook，AI 连"尝试"危险命令的机会都没有。
.claude/settings.json：
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [{ "type": "command", "command": "./hooks/guard-bash.sh" }]
}
]
}
}
hooks/guard-bash.sh：
#!/usr/bin/env bash
# PreToolUse hook：拦截高危 Bash 命令（Claude Code 通过 stdin 传入 JSON）
CMD=$(jq -r '.tool_input.command // ""' "$1" 2>/dev/null)
case "$CMD" in
*"git push --force"*|*"git push -f"*|*"DROP TABLE"*|*"rm -rf /"*)
echo "BLOCKED: 检测到高风险命令，已被工程闸门拦截"; exit 1 ;;
esac
exit 0 # 放行
只要 AI 想 git push -f，hook 直接 exit 1，工具调用被拒。这是 agent-skills "纪律即代码" 理念的最后一块拼图。
4.4 Anti-Rationalization：把借口写进 Skill
agent-skills 最精妙的设计，是把"AI 会怎么偷懒"显式建模进 Skill。你可以给任意 Skill 加一段：
## Common Rationalizations
- "我会稍后添加测试" → 稍后 = 永不，现在写
- "这只是原型" → 原型也会被部署
- "重构太复杂" → 小步重构更安全
- "这代码能跑就行" → 能跑 ≠ 可维护
当模型产生"先上线再说"的冲动时，这段被显式加载的"反驳库"会把它拉回纪律轨道。这是纯 prompt 工程很难稳定做到的。
4.5 跨 IDE 复用同一套纪律
agent-skills 通过适配层把同一套 skills/ 映射到不同 IDE：
# CLAUDE.md（或 AGENTS.md）片段
本仓库启用 agent-skills 工程纪律。AI 编码 Agent 必须：
1. 改动前先 /spec 或 /plan
2. 每个功能切片配测试（/test）
3. 合并前 /review，发布前过 db-migration-safety 检查
4. 禁止绕过 hooks 闸门
一份纪律定义，Claude Code / Gemini CLI / OpenCode / GitHub Copilot 通吃。团队再也不用每个人跟自己的 AI "单独讲一遍规矩"。
五、工程收益与优化：Skill 到底改变了什么
5.1 上下文预算优化：references 按需加载
20 个 skill 全进上下文会爆窗口。正确做法：主 SKILL.md 只留轻量指引，references/ 放长文档（如完整规范、API 字典），AI 需要时再读。这样主上下文始终精简，成本与延迟双降。
5.2 Checkpoint 退出标准：让"我写了"变成"我证明"
没有 checkpoint，AI 说"测试已写"就过关；有 Verification checklist，它必须逐条满足（测试覆盖率 > 80%、全绿、无硬编码凭证）才能继续。把"声称"变成"可验证"，是代码质量跃迁的关键。
5.3 可回滚 / 可审查：纪律本身也被工程化
每个 skill 约束"可验证、可回滚、可审查"。skill 文件走 PR、能 diff、能 review——你不是在"调教一个模型"，而是在维护一套可持续演进的工程规范。新人入职，读一遍 skills/ 就知道团队怎么写代码。
5.4 如何度量：skills 真的有用吗
别拍脑袋。建议埋点：
- 每次
/ship前，记录 checkpoint 通过率（测试覆盖率、review 遗留数） - 对比接入 skills 前后的"上线后 24h 回滚率""P0 事故数"
- 把高频触发的
Red Flags反向优化进 skill——skill 自己也在持续进化
六、总结与展望：Skill 即「工程纪律即代码」
回看 agent-skills，它解决的不是"AI 不会写代码"，而是"AI 不守工程纪律"。它的方法论可以浓缩成三条：
- 把口号变成 checklist：
Verification退出标准，让 AI 必须证明而非声称。 - 把借口变成反驳库：
Common Rationalizations，提前堵死偷懒路径。 - 把纪律焊进工具链：
Hooks物理拦截，软约束 + 硬闸门双保险。
展望 2026 下半年，一个清晰趋势是："Skill / 技能"正在成为 Agent 编程的标准基础设施层。就像 Dockerfile 定义了"怎么构建可复现环境"，SKILL.md 正在定义"怎么让 AI 可复现地守纪律"。未来可能出现 skill 市场、团队 skill 仓库、跨项目的 skill 复用——而 agent-skills 这类方法论，正是这场"工程纪律即代码"运动的开篇。
如果你今天只做一件事：给自己常用的 AI 编码工具，写一个 db-migration-safety 这样的小 Skill。它会比你贴一百遍"记得写回滚"都管用。
本文基于 Addy Osmani 开源的 agent-skills（GitHub: addyosmani/agent-skills）公开设计梳理，代码示例均可直接落地运行；具体 skill 列表以仓库最新版本为准。