Agent Skills，AI 编程代理的生产级工程技能

Agent Skills，AI 编程代理的生产级工程技能

English

赵中琦 2026年05月14日 ai agent engineering tutorial

项目简介

https://github.com/addyosmani/agent-skills

作者 Addy Osmani 长期从事开发者体验和工程效率工作。当 AI 编程代理兴起后，他发现一个关键问题：AI 有能力写代码，但没有纪律写好代码。于是他把 Google 内部多年积累的工程最佳实践（代码审查规范、测试金字塔、变更管理等，Software Engineering at Google and Google's engineering practices guide）编码成 AI 可以遵循的结构化工作流——这就是 Agent Skills。

这个项目功能上跟盛子瑞之前讲到的 Superpowers 有重叠，但两个项目的定位不同。Superpowers 更侧重于工作流编排（怎么组织工作）问题，而 Agent Skills 则更侧重于工程实践（每一步怎么做好）。

背景问题

AI coding 中可能遇到的问题

  • 用了包中一个不存在的函数
  • 改了 A 文件，没意识到 B 文件依赖 A 文件，结果 B 崩了
  • 直接写代码，没先搞清楚需求和边界
  • 一口气改了十几个文件，你根本看不过来哪里改了什么
  • 没写任何测试，你不确定它改的东西对不对

这些问题的根源是什么

AI agent 的"最短路径"问题

AI 被训练来"快速给出答案"。当你说"实现 X 功能"，它的默认行为是：

收到需求 ──→ 直接写代码 ──→ "完成了！"

而一个靠谱的开发流程应该是：

收到需求 → 澄清需求 → 规划方案 → 分步实现 → 写测试验证 → 审查质量 → 提交

AI 跳过了中间所有让代码靠谱的步骤。

更危险的是，AI 还会给自己找借口——

"这个改动太简单了，不需要测试。"

"我之后再补测试。"

"我已经知道怎么做了，不需要查文档确认。"

这些借口听起来合理，但每一个可能导致 bug 产生。

Agent Skills: 给 AI 装上工程纪律

Agent Skills 是一组精心设计的 Markdown 工作流文件。当它被加载到 agent 的上下文中后，AI 就必须按照流程做事，而不是走"最短路径"。它给了 AI 一套必须遵循的纪律。

三个核心机制

机制一：七个斜杠命令组成一个完整 Development Lifecycle

之前提到 AI 的默认行为是"收到需求 → 直接写代码 → 完成"。Agent Skills 用 7 个斜杠命令 把这条"最短路径"替换成一条完整的工程流水线：

What you're doing Command
① 定义 /spec
② 规划 /plan
③ 构建 /build
④ 验证 /test
⑤ 审查 /review
⑥ 简化 /code-simplify
⑦ 发布 /ship

每个命令背后自动调用一个或多个 Skill（共 22 个），其中每一个 Skill 都有一个单独的 workflow。

这 7 个命令不是 7 个独立工具，而是一起构成一整个 development lifecycle。 按顺序走一遍，就完成了从"有个想法"到"代码可交付"的全过程：

Agent Skills Lifecycle

机制二：反合理化表

这是 Agent Skills 最独特的设计。每个 Skill 内置了一张"借口与反驳"表：

AI 常见的借口 事实是......
"这太简单了，不需要测试" 简单的东西会变复杂。测试是证明，不是开销
"我之后会补测试的" "之后"从不到来。先写测试再写实现
"跳过规格说明可以更快" 没想清楚就写的代码，最后会重写好几遍
"这只是个小改动" 小改动也会引入大 bug

当 AI 试图跳过步骤时，这张表会阻止它。

机制三：证据验证

"Seems right" 永远不够。每个 Skill 结束时要求 AI 提供证据：

  • 测试通过的输出截图
  • 构建成功的日志
  • 代码运行的实际结果

没有证据 = 没有完成。

一个使用几个核心 Skill 的案例

spec-driven-development — 先想清楚再动手

解决的问题：AI 还没理解你要什么就开始写代码，写完 200 行才发现方向错了。

它怎么做：强制 AI 在写第一行代码之前，先输出一份结构化的 specification：

你说："帮我写一个模块，用 PySCF 跑 HF，然后把结果转成量子线路的初始态"

AI 不会直接写代码，而是先回答：
规格说明

▸ 目标：用 PySCF 做 RHF/UHF 计算，生成量子计算所需的 HF 参考态（分子轨道系数 + 占据数）

▸ 输入：分子坐标（xyz 或 Z-matrix）、基组、电荷/自旋

▸ 输出：MO 系数矩阵、单/双电子积分、Hartree-Fock 能量、占据轨道信息

▸ 边界条件：开壳层体系怎么处理？活性空间怎么选？

▸ 成功标准：H₂O/STO-3G 的 HF 能量与文献值误差 < 1e-8 Hartree

我的假设：
1. 量子计算框架用 Qiskit（非 TensorCircuit）
2. 默认 Jordan-Wigner 变换映射到 qubit
→ 以上正确吗？

价值：在 AI 动手之前就发现理解偏差——比如你用的是 TensorCircuit 而不是 Qiskit，或者你需要 Parity 而不是 Jordan-Wigner，这时候纠正成本几乎为零。

planning-and-task-breakdown — 大任务拆成小块

解决的问题：AI 面对一个复杂任务时，试图一口气全写完，结果代码又长又乱，出了问题不知道哪里错的。

它怎么做：把一个大任务拆成小的、有顺序的步骤，每步都有明确的"完成标准"：

不用这个 Skill：                    用了这个 Skill：
─────────────────                  ─────────────────
Task: 写完整个 HF→量子态 模块       Task 1: 构建分子对象 + 跑 RHF
                                   → 验证：H₂O 能量与文献值一致
                                   Task 2: 提取 MO 系数和单双电子积分
                                   → 验证：用积分重构 HF 能量，误差 < 1e-8
                                   Task 3: 选择活性空间（frozen core）
                                   → 验证：活性轨道数 = 预期值
                                   Task 4: 费米子→qubit 映射（Jordan-Wigner）
                                   → 验证：qubit 哈密顿量本征值 = FCI 能量
                                   Task 5: 生成 HF 参考态量子线路
                                   → 验证：线路测量期望值 = HF 能量

关键原则：

  • 垂直切片：不是"先写完所有 PySCF 部分，再写所有量子线路部分"，而是"先对 H₂ 跑通完整流程，再扩展到更复杂的分子"
  • 每步可验证：每个 Task 做完后都能运行、能对数值，不会出现"写了一半跑不了"的状态
  • 任务大小控制：如果一个任务改超过 5 个文件，说明它太大了，需要继续拆

incremental-implementation — 每次只做一件事

解决的问题：AI 一次性写 500 行代码，改了十几个文件，出了 bug 你根本不知道是哪一步引入的。

它怎么做：严格按"实现一小块 → 测试 → 验证 → 提交 → 下一块"的循环：

实现 → 测试 → 验证 → 提交

↑ 下一块

核心规则：

规则 说明
一次一件事 一个提交只做一个逻辑变更，不混杂
保持可运行 每次改完，代码都必须能跑
简单优先 先写最简单的正确版本，测试通过后再优化
不扩大范围 只改当前任务需要的，看到"顺手能改的"先记下来，不要动

价值：如果活性空间选择那步出了问题，你确切地知道就是那一步引入的——因为前面的 RHF 和积分提取都已经验证通过并提交了。

test-driven-development — 先写测试再写代码

解决的问题：AI 写的代码"看起来对"但没有任何验证，你不敢确认它是否真的正确。

它怎么做：强制按 Red-Green-Refactor 流程——

红（RED）
先写一个测试
它必须失败		 → 绿（GREEN）
写最少的代码
让测试通过		 → 重构（REFACTOR）
整理代码
保持测试通过		 → 重复
↓
证明测试
真的在检测		 ↓
代码
正确		 ↓
代码
干净

举个例子：

# 红：先写测试，它会失败（因为函数还没实现）
def test_rhf_energy():
    """H₂O/STO-3G 的 RHF 能量必须与已知值一致"""
    mol = build_molecule("O 0 0 0; H 0 0.757 0.587; H 0 -0.757 0.587",
                         basis="sto-3g")
    result = run_rhf(mol)
    assert abs(result.energy - (-74.942080)) < 1e-6  # 文献值
    assert result.mo_coeff.shape[0] == 7  # STO-3G: 7 个基函数
    assert result.n_occupied == 5  # H₂O: 5 个占据轨道

# 绿：写最少的代码让测试通过
def run_rhf(mol):
    # ... 用 PySCF 实现 RHF 计算 ...

# 重构：整理代码，测试仍然通过

价值：每一段代码都有配套的测试。跑一下测试就知道代码对不对——不用人肉检查。

debugging-and-error-recovery — 遇到 bug 系统性解决

解决的问题：AI 遇到报错就开始瞎猜，"试试这个"、"改改那个"，改来改去越改越乱。

它怎么做：强制按五步法，像做实验一样系统地找根因：

① 复现
稳定重现
这个 bug		 → ② 定位
找到是哪
层出问题		 → ③ 缩小
最小复现
案例		 → ④ 修复
针对根因
修复		 → ⑤ 防护
加测试
防再犯

关键纪律——Stop-the-Line（停线规则）：

遇到错误时，立即停止写新代码。不要想着"先跳过这个 bug 继续做后面的"——错误会累积，比如 MO 系数提取有 bug，后面的活性空间选择、Jordan-Wigner 变换全都建立在错误基础上。

价值：AI 不再"试试改改"地瞎折腾，而是用"控制变量、逐步排查"的思路系统性地解决问题。

code-review-and-quality — 五个维度审查代码

解决的问题：代码写完了，"能跑"不等于"没问题"。自己 review 容易只盯着逻辑对不对，漏掉安全、性能、可读性等维度。

它怎么做：强制从五个维度逐一审查，每条发现标注严重级别：

正确性
逻辑对吗
边界全吗		 可读性
别人能
看懂吗		 架构
模块划分
合理吗		 安全性
有没有
漏洞		 性能
有没有
瓶颈

举个例子：AI 审查你的 PySCF 模块后，可能给出：

严重级别 发现
Critical run_rhf() 没处理 SCF 不收敛的情况，会返回错误的能量
Important MO 系数矩阵没做 shape 校验，换基组会 silent error
Suggestion build_molecule() 函数 60 行太长，建议拆分坐标解析和基组设置

关键设计：发现分级让你知道什么必须改、什么可以先不改。Critical 必须修，Suggestion 可以记下来以后改——避免 review 变成无尽的完美主义修改。

shipping-and-launch — 三个专家并行检查，给出 go/no-go

解决的问题：代码 review 通过了，但"能合并"不等于"能上线"。一个人看不全所有风险。

它怎么做：同时派出三个 AI 专家角色，各自独立检查，最后合并意见给出发布决策：

你的代码 → 代码审查员
逻辑、可读性、架构		 → 合并
↓
GO / NO-GO
→ 安全审计员
漏洞、权限、输入验证
→ 测试工程师
覆盖率、边界、遗漏

核心原则：任何一个 Critical 发现 = 默认 NO-GO。同时要求必须有回滚方案——万一上线后出问题，怎么退回去。

七个 Skill 的配合关系

spec
（想清楚）		 → plan
（拆开来）		 → build
（一步步做）		 → test
（验证）		 → review
（五维审查）		 → ship
（三专家）

↓
出了 bug → debug（系统排查） → 修好后继续

Quick Start

Set up

Claude Code

Marketplace install:

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

Gemini

Install from the repo:

gemini skills install https://github.com/addyosmani/agent-skills.git --path skills

Install from a local clone:

gemini skills install ./agent-skills/skills/

Others

Skills are plain Markdown - they work with any agent that accepts system prompts or instruction files.

告诉 agent 仓库地址 https://github.com/addyosmani/agent-skills，让 agent 帮忙安装，或者自己复制 md 文件到相应文件夹。

Workflow

仓库包含一个叫 using-agent-skills 的 Skill，当我们告诉 agent 要使用 agent-skills 来完成任务的时候，它会自动调用包含的技能来完成上面讲到的 Development Lifecycle，而不是非得每步都自己使用 Slash command。

总结

没有 Agent Skills                有 Agent Skills
─────────────────                ─────────────────
需求 → 直接写代码 → "完成"        需求 → 规格 → 计划 → 编码 → 测试 → 审查 → 完成
   ↓                                                      ↑
bug、返工、不可维护                                    每一步都有检查点和证据

← 返回文章列表