如何把真实世界的能力封装为 Agent Skill

通用 AI Agent 能力很强，但缺少每支团队都有的东西：程序性知识。你的代码审核清单、部署手册、API 规范——这些都不在模型的训练数据里。

这就是 Agent Skill 要解决的问题。Anthropic 在 2025 年推出的 Skill，本质上是组织好的文件夹——包含指令、脚本和资源——Agent 可以动态发现并按需加载。把它想象成 Agent 的入职手册。

编写 Skill 就像给新人准备一份 onboarding 指南。你不需要为每个场景构建碎片化的定制 Agent，而是通过捕获和共享你的程序性知识，让通用 Agent 具备专业能力。

这篇教程将带你从零构建一个代码审核 Skill——把团队的审核标准打包成可复用的技能。

什么是 Agent Skill

最简形式下，一个 Agent Skill 就是一个包含 SKILL.md 文件的目录，文件头部带有 YAML frontmatter：

---
name: code-review
description: 按照团队规范和最佳实践审核 Pull Request
---

Agent 启动时，会将每个已安装 Skill 的 name 和 description 加载到系统提示词中。这段元数据很轻量——始终加载，几乎不消耗 token。Agent 用它来判断是否需要加载完整的 Skill。

真正的指令写在 SKILL.md 的正文中，仅在 Agent 判定当前任务相关时才会读取。这是核心设计原则：渐进式披露（Progressive Disclosure）。

渐进式披露

Skill 使用三级信息模型：

第一级：元数据（name + description） 始终加载到系统提示词中。给 Agent 足够的信息来决定是否相关。

第二级：SKILL.md 正文 当 Agent 判定 Skill 与当前任务相关时加载。

第三级：引用文件 从 SKILL.md 中链接——按需加载，仅在需要时读取。可以是 markdown 参考文档、脚本、模板或任何其他资源。

这意味着一个 Skill 可以捆绑的信息量在理论上没有上限。Agent 只为实际用到的内容支付 token。

实战：构建代码审核 Skill

我们来一步步构建一个 Skill，指导 Agent 按照团队标准审核 Pull Request。

第一步：识别能力缺口

在动笔之前，先让 Agent 执行一次真实的代码审核任务。观察它在哪些地方表现不佳：

• 是否漏掉了你们团队的命名规范？
• 是否忽略了你们技术栈特有的安全模式？
• 是否提出了违反你们架构决策的修改建议？

这些缺口就是 Skill 的目录。

第二步：创建目录结构

~/.claude/skills/code-review/
├── SKILL.md
├── conventions.md
├── security-checklist.md
└── review-workflow.md

第三步：编写 YAML Frontmatter

name 和 description 是 Agent 决定是否加载 Skill 的唯一信号。要具体——“审核代码”太模糊，可能在开发过程中误触发。“按团队规范审核 Pull Request”更准确。

---
name: code-review
description: >
  使用团队特定的规范、安全模式和架构指南审核 Pull Request。
  触发词：review、PR、pull request、code review。
---

第四步：编写核心指令

在 SKILL.md 正文中：

## 审核流程

1. 阅读 PR 描述，了解变更背景和目的。
2. 首先阅读 `conventions.md`——所有风格检查按此规则执行。
3. 对每个变更文件执行 `security-checklist.md`。
4. 按照 `review-workflow.md` 的结构化审核顺序进行。

## 输出格式

每个发现的问题需报告：
- **严重级别**：critical / warning / suggestion
- **文件**：路径和行号
- **规则**：违反了哪条规范或模式
- **修复建议**：具体、可操作的建议

第五步：添加引用文件（第三级）

将详细知识拆分到独立文件中。这样核心文件保持精简，Agent 只需加载需要的内容。

conventions.md：

## 命名规范
- React 组件：PascalCase
- Hooks：camelCase，前缀 "use"
- 常量：UPPER_SNAKE_CASE
- 私有函数：下划线前缀

## 导入规范
- 分组顺序：内置库 → 外部依赖 → 内部模块 → 相对路径
- 每组内按字母排序
- 禁止使用 index.ts 的 barrel export

security-checklist.md：

检查每个变更文件：
- 使用字符串拼接的 SQL 查询（应使用参数化查询）
- 未转义的用户输入渲染
- 硬编码的密钥或 token
- 新 API 路由缺少鉴权
- 不安全的直接对象引用（IDOR）

review-workflow.md：

## 审核顺序
1. 规范检查（conventions.md）
2. 安全扫描（security-checklist.md）
3. 架构审查——变更是否符合模块结构？
4. 测试覆盖——新增逻辑是否有对应测试？
5. 文档——公共 API 是否有文档？

## 原则
- 一个 PR 只做一件事。标记混入了重构的特性 PR。
- 小而聚焦的提交优于大型单体提交。
- 如果需要修改，一次性提出，下一轮验证即可。

现在，Agent 每次审核都会读取 conventions.md，但只有在 diff 涉及安全相关代码时才读取 security-checklist.md，只有遇到较大或结构性变更时才读取 review-workflow.md。这就是渐进式披露的实际应用。

第六步：添加脚本处理确定性任务

有些操作更适合用代码而非 LLM 推理来处理。通过 token 生成来排序一个列表，远比运行一个排序算法昂贵。除了效率，很多应用还需要代码才能提供的确定性可靠性。

在 Skill 目录中包含一个辅助脚本：

# diff-stats.py
import sys, re

diff_text = sys.stdin.read()
files = re.findall(r'^\+\+\+ b/(.+)$', diff_text, re.MULTILINE)
lines_added = len(re.findall(r'^\+', diff_text, re.MULTILINE))
lines_removed = len(re.findall(r'^-', diff_text, re.MULTILINE))

print(f"变更文件数: {len(files)}")
print(f"新增行数: {lines_added}")
print(f"删除行数: {lines_removed}")
print(f"范围: {'小' if lines_added < 50 else '中' if lines_added < 200 else '大'}")

在 SKILL.md 中引用它：

开始审核前，运行 `python diff-stats.py`（将 diff 通过 stdin 传入）
评估 PR 范围。根据结果调整审核深度：
- 小：完整审核
- 中：聚焦安全和架构
- 大：仅做高层面总结，标记给人工审核

第七步：用 Agent 迭代优化

这是最重要的一步。让 Agent 在实际 PR 上运行，观察它如何使用 Skill。当它出错时，让它自我反思：

“你漏掉了导入排序规范。重新阅读 conventions.md 并解释哪里出了问题。”

随着时间的推移，将这些经验教训沉淀回 Skill 文件中。Skill 永远不会”完成”——它随着团队一起进化。

开发和评估 Skill 的最佳实践

**从评估开始。**在代表性任务上运行 Agent，观察它在哪些地方遇到困难或需要额外上下文，然后增量构建 Skill 来解决这些不足。

**站在 Agent 的视角思考。**监控 Agent 在实际场景中如何使用你的 Skill。注意意外的执行路径或对某些上下文的过度依赖。如果 Skill 从未触发，说明 name 或 description 有问题。如果触发太频繁，说明它们太宽泛。

**用 Claude 迭代。**在协作过程中，让 Claude 将成功的做法和常见错误捕获到 Skill 中。如果它在使用 Skill 时偏离了轨道，让它自我反思问题所在。这样产出的上下文是 Agent 实际需要的，而不是你预先猜测的。

**为规模化而设计。**当 SKILL.md 过于庞大时，将内容拆分到独立文件中。如果某些上下文互斥或很少同时使用，保持路径分离可以减少 token 消耗。代码既可以作为可执行工具，也可以作为文档参考。

注意事项

**Token 管理。**Skill 中每一行加载的内容都会消耗上下文窗口空间。臃肿的 SKILL.md 会挤占 Agent 的推理空间和用户对话内容。保持核心文件精简；将详细的参考资料推到第三级文件。

命名的精度。name 和 description 是触发的唯一信号。描述如”帮助写代码”会在几乎每次请求时触发。“按团队风格和安全规范审核 PR”则足够精确——能匹配正确场景又避免误触发。这个字段是 Skill 失败最常见的根源。

**跨 Skill 冲突。**多个 Skill 可能给出矛盾的指令——一个说”用 ESLint”，另一个说”用 Prettier”。检查已安装 Skill 的兼容性，尤其是从社区引入时。

**安全风险。**Skill 包含 Agent 会执行的指令和代码。恶意的 Skill 可能窃取数据、修改文件或连接到不受信的主机。只从可信来源安装 Skill，首次使用前逐文件审计。

**维护债务。**Skill 是活的文档。当团队规范变化时，Skill 必须同步更新。过时的 Skill 比没有 Skill 更糟——它会自信地执行错误的规则。把 Skill 当代码对待：版本管理、审查变更、淘汰过时的内容。

不适用场景

Skill 并非所有场景的正确答案：

**一次性任务。**只用一次的临时操作，不值得封装。直接告诉 Agent 即可。

**实时数据或外部 API。**Skill 是静态文件。如果需要查询数据库、获取实时指标或调用 API，请使用 MCP（Model Context Protocol）Server。MCP 处理动态工具执行；Skill 处理静态知识和流程。

**高频变动的流程。**如果你的规范每周都在变，花在更新 Skill 上的时间会超过它节省的时间。先让流程稳定下来，再考虑 Skill。

**确定性执行。**Skill 指导 Agent 的行为，但不强制执行。如果需要 100% 确定性的行为，请编写传统代码或 CI 检查。

**超简单的指令。**如果一句话能说清，直接放在系统提示词中。Skill 有开销——只有复杂度足够时才值得创建。

**需要人工介入的流程。**Skill 假设 Agent 自主执行。如果每一步都需要人工确认，脚本或 CI 流水线更适合。

总结

Agent Skill 的理念出奇地简单：一个文件夹，一个 markdown 文件，以及渐进式披露的原则。正是这种简单赋予了它力量——可组合、可共享、可维护。

最好的开始方式是找到一个具体缺口——你的 Agent 在你团队工作中反复出错的一件事——为它写一个 Skill。不是十个。就一个。

打开一个目录，写一份 SKILL.md，给 Agent 它真正需要的上下文。