Agent Skills 最佳实践中文整理
jerry2 CTO
  2026-05-20 21:52:00 2026-05-20 21:52    3.6k 字  12 分钟  

来源文档：Agent Skills - Best practices for skill creators
整理目标：把原文中关于如何创建高质量 Skill 的要点整理成中文，方便后续编写、复用和迭代 Skill。

一、核心目标

这篇文档讲的是：如何写出范围合适、信息密度高、能真正提升 Agent 表现的 Skill。

Skill 不应该只是泛泛地写“遵循最佳实践”，而应该把 Agent 原本不知道、容易做错、需要固定遵守的经验沉淀下来。

1. 从真实经验出发，不要凭空生成

1.1 不要让 LLM 空写 Skill

常见错误是：直接让模型“帮我写一个 Skill”，但不给它具体业务背景。这样生成的内容通常会很泛，比如：

妥善处理错误
遵循认证最佳实践
注意边界情况

这些话看起来没错，但对 Agent 实际执行帮助很小。

好的 Skill 应该来自：

  • 真实项目
  • 真实任务
  • 真实错误
  • 真实约束
  • 真实纠正过程

1.2 从一次真实任务中提炼

推荐做法是：

  1. 先让 Agent 完成一个真实任务
  2. 你在过程中不断补充背景、纠正它、告诉它偏好
  3. 任务完成后，再把可复用的流程抽成 Skill

要重点提炼这些内容：

要提炼的内容 含义
成功步骤 哪些动作顺序最终有效
你做过的纠正 Agent 哪些地方容易走偏
输入输出格式 原始数据长什么样，最终结果应该长什么样
项目上下文 项目里的特殊约定、限制、工具、命名方式

例如：如果 Agent 在做产品原型时漏掉了“加工师傅、质检员、设备流转”，这些纠正就很适合沉淀进一个产品原型 Skill。

1.3 从已有项目资料中合成

如果团队已经有文档，可以把这些资料整理成 Skill。

高价值资料包括：

资料类型 价值
内部文档、Runbook、风格指南 体现团队规范
API 规格、Schema、配置文件 体现真实接口和数据结构
Code Review 评论、Issue 体现反复出现的问题
Git 历史、补丁、修复记录 体现真实变更模式
事故案例和解决方案 体现真实失败模式

核心原则：

项目专属资料比通用最佳实践文章更有价值。

2. 用真实执行结果不断迭代

Skill 的第一版通常不会很好，需要拿真实任务测试，然后根据 Agent 的执行过程修正。

要观察的不只是最终结果，还要看 Agent 的执行轨迹。

现象 可能原因
Agent 绕了很多弯 指令太模糊
Agent 执行了不该执行的步骤 指令适用条件没写清楚
Agent 在多个工具之间犹豫 给了太多选项，没有默认方案
Agent 漏掉关键检查 没有明确 checklist 或 validation

推荐做法：

  1. 执行一次
  2. 复盘一次
  3. 修正一次
  4. 再用真实任务验证

复杂领域通常需要多轮迭代。

3. 节省上下文，不要写废话

Skill 激活后，整个 SKILL.md 会进入 Agent 上下文窗口。

也就是说，Skill 里的每个 token 都会占用注意力和上下文空间。

3.1 只写 Agent 不知道的东西

应该写：

应该写 不该写
项目特殊约定 什么是 PDF
特定 API 用法 什么是 HTTP
容易犯错的边界情况 什么是数据库迁移
必须使用的工具/库 泛泛的技术介绍
特定输入输出格式 大段背景科普

不好的写法：

1
PDF 是一种常见文件格式，包含文本、图片等内容……

更好的写法：

1
使用 pdfplumber 提取文本。扫描件则使用 pdf2image + pytesseract。

判断标准：

如果没有这条说明，Agent 会不会做错？
如果不会，就删掉。

4. Skill 的范围要像函数一样清晰

文档把 Skill 的范围设计类比成写函数：

一个 Skill 应该封装一个连贯的工作单元。

4.1 太窄的问题

如果 Skill 太窄，一个任务可能要加载多个 Skill，容易造成：

  • 上下文浪费
  • 指令冲突
  • Agent 不知道该优先听哪个

4.2 太宽的问题

如果 Skill 太宽，就很难准确触发，而且内容会变得混乱。

Skill 范围 是否合理
查询数据库并格式化结果 合理，属于一个连贯任务
查询数据库 + 数据库管理 + 权限治理 + 运维 太宽

5. 细节要适中，不要写百科全书

过于详尽的 Skill 可能反而降低效果。

因为 Agent 需要从大量内容中找当前任务相关部分，容易被无关指令带偏。

更好的写法是：

  • 简洁
  • 分步骤
  • 有一个能跑通的示例
  • 只覆盖高频和关键边界情况

如果你发现自己在写几十个边界情况，应该思考：

这些是不是应该交给 Agent 自己判断，而不是全部塞进 Skill？

6. 大型 Skill 要使用“渐进式披露”

文档建议：

  • SKILL.md 控制在 500 行以内
  • SKILL.md 控制在 5000 tokens 以内
  • 核心指令放在 SKILL.md
  • 详细资料放到 references/ 等目录里

关键不是简单写：

1
更多内容见 references/

而是要明确告诉 Agent 什么时候读哪个文件：

1
如果 API 返回非 200 状态码，读取 references/api-errors.md。

这样 Agent 只在需要时加载额外资料，不会一开始就被大量内容淹没。

7. 控制力度要匹配任务脆弱程度

不是所有指令都要写得一样死。

7.1 灵活任务：给原则和目标

比如 Code Review，很多路径都可以完成，不必规定死顺序。可以写：

1
2
3
4
检查 SQL 注入风险，确认使用参数化查询。
检查每个接口是否有认证逻辑。
检查并发路径中的竞态条件。
确认错误信息不会泄露内部细节。

这类任务允许 Agent 自主判断。

7.2 脆弱任务：必须强约束

比如数据库迁移、生产环境操作、破坏性操作，应该明确要求：

1
python scripts/migrate.py --verify --backup

并写清楚：

1
不要修改命令，不要添加额外参数。

核心原则：

同一个 Skill 里可以同时有灵活部分和强约束部分，要分别校准。

8. 给默认方案，不要给一堆菜单

当多个工具都能完成任务时，不要把它们平铺成菜单。

不好的写法：

1
你可以使用 pypdf、pdfplumber、PyMuPDF、pdf2image……

更好的写法：

1
2
默认使用 pdfplumber 提取文本。
如果是扫描 PDF，需要 OCR，则使用 pdf2image + pytesseract。

也就是：

先给默认方案，再给逃生出口。

9. 写流程，不要只写结论

Skill 应该教 Agent “如何处理一类问题”，而不是只给某个具体任务的答案。

不好的写法：

1
把 orders 表和 customers 表用 customer_id 关联，筛选 region = 'EMEA'，然后统计 amount。

这个只适用于一个任务。

更好的写法：

1
2
3
4
1. 读取 references/schema.yaml 找到相关表
2. 使用 _id 外键约定关联表
3. 按用户请求添加 WHERE 条件
4. 对数值字段做聚合，并输出 markdown 表格

后者可以复用于多种分析任务。

10. 有效 Skill 的常用结构模式

10.1 Gotchas：专门记录容易踩坑的地方

很多 Skill 里最有价值的部分是 Gotchas，也就是 Agent 如果不知道就很可能犯错的环境特定问题。

例如：

1
2
3
4
5
## Gotchas

- users 表使用软删除，查询必须加 WHERE deleted_at IS NULL。
- 数据库里叫 user_id，认证服务里叫 uid，计费 API 里叫 accountId，它们指的是同一个值。
- /health 只表示 Web 服务还活着，不代表数据库正常。完整健康检查要用 /ready。

注意：

这些不是“注意错误处理”这种泛泛建议，而是非常具体的坑。

每次你纠正 Agent 的错误，都可以考虑把这条补进 Gotchas。

10.2 输出模板

如果你希望 Agent 按固定格式输出，直接给模板，比用文字描述可靠。

例如：

1
2
3
4
5
6
7
8
9
10
11
12
# [分析标题]

## Executive summary
[一段话总结关键发现]

## Key findings
- 发现 1，附数据支持
- 发现 2，附数据支持

## Recommendations
1. 具体建议 1
2. 具体建议 2

短模板可以直接放在 SKILL.md，长模板或低频模板可以放到 assets/。

10.3 多步骤工作流用 Checklist

对于多步骤任务，Checklist 可以防止 Agent 跳步。

例子：

1
2
3
4
5
6
7
8
## 表单处理流程

Progress:
- [ ] Step 1: 分析表单，运行 scripts/analyze_form.py
- [ ] Step 2: 创建字段映射，编辑 fields.json
- [ ] Step 3: 验证映射，运行 scripts/validate_fields.py
- [ ] Step 4: 填写表单，运行 scripts/fill_form.py
- [ ] Step 5: 验证输出，运行 scripts/verify_output.py

这对有依赖关系、必须验证后才能进入下一步的任务尤其重要。

10.4 Validation loop：做完后自检，失败就修

好的 Skill 可以要求 Agent：

1
2
3
4
5
6
7
1. 完成编辑
2. 运行 python scripts/validate.py output/
3. 如果验证失败：
   - 阅读错误信息
   - 修复问题
   - 再次运行验证
4. 只有验证通过后才继续

核心是形成闭环：

执行 → 验证 → 修复 → 再验证 → 通过后交付

这比“完成后检查一下”更可靠。

10.5 Plan-validate-execute：先计划，验证后再执行

对于批量操作或破坏性操作，文档建议不要直接执行，而是：

  1. 先生成结构化计划
  2. 用脚本或真实数据验证计划
  3. 验证通过后再执行

比如 PDF 表单填写：

1
2
3
4
5
1. 提取表单字段 → form_fields.json
2. 创建字段值映射 → field_values.json
3. 验证字段是否存在、类型是否兼容、必填项是否缺失
4. 验证失败则修改 field_values.json
5. 验证通过后再填充 PDF

关键是第 3 步：

验证计划和真实来源是否一致。

这样 Agent 才能根据错误信息自我修正。

11. 可以把重复逻辑封装成脚本

如果你发现 Agent 每次执行 Skill 时都在重复造轮子，比如：

  • 解析固定格式
  • 生成图表
  • 验证输出
  • 转换文件
  • 检查字段

那就应该写成经过测试的脚本，放到 scripts/ 目录，让 Agent 调用，而不是每次临时写一遍。

12. Skill 编写检查清单

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
## Skill 编写检查清单

### 来源
- [ ] 是否来自真实任务、真实项目资料或真实错误？
- [ ] 是否包含项目专属约定，而不是通用废话？
- [ ] 是否记录了 Agent 曾经被纠正过的地方？

### 范围
- [ ] Skill 是否覆盖一个连贯的工作单元？
- [ ] 是否太窄，导致一个任务要加载多个 Skill？
- [ ] 是否太宽，导致触发不精准？

### 内容密度
- [ ] 是否删掉了 Agent 已经知道的基础知识？
- [ ] 每条说明是否能防止 Agent 犯错？
- [ ] 是否控制在适中的长度？

### 指令方式
- [ ] 灵活任务是否给了原则和判断依据？
- [ ] 脆弱任务是否给了明确命令和禁止项？
- [ ] 是否给了默认方案，而不是一堆并列选项？

### 结构
- [ ] 是否有 Gotchas？
- [ ] 是否有必要的输出模板？
- [ ] 多步骤任务是否有 Checklist？
- [ ] 是否设计了验证闭环？
- [ ] 批量/破坏性操作是否采用 plan-validate-execute？

### 迭代
- [ ] 是否用真实任务跑过？
- [ ] 是否看过 Agent 执行轨迹？
- [ ] 是否把失败、误判、绕路的地方补回 Skill？
- [ ] 是否把重复逻辑封装成 scripts/？

13. 简化理解

这篇文档真正想表达的是：

Skill 不是说明书，也不是百科。
Skill 是把“Agent 容易不知道、容易做错、必须遵守、可以复用”的经验压缩成高密度操作指南。

一个好 Skill 应该像这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 做什么
明确任务边界。

# 什么时候使用
说明触发场景。

# 默认流程
给 Agent 一条主路径。

# Gotchas
告诉 Agent 哪些地方不能靠常识猜。

# 输出格式
给模板，不要只口头描述。

# 验证方式
告诉 Agent 怎么证明自己做对了。

# 需要时加载的参考资料
大内容不要全塞进主文件。

14. 可复用的 Skill 模板

下面是一个可以直接改写的 Skill 模板。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
---
name: skill-name
description: 什么时候使用这个 Skill。要写清楚触发场景，不要太宽泛。
---

# Skill Name

## Purpose

这个 Skill 用来完成什么任务。

## When to use

当用户请求包含以下情况时使用：

- 场景 1
- 场景 2
- 场景 3

不要在以下情况使用：

- 排除场景 1
- 排除场景 2

## Default workflow

1. 先做什么
2. 再做什么
3. 如何验证
4. 如何输出

## Gotchas

- 项目特有坑 1
- 项目特有坑 2
- Agent 容易误解的命名、流程、边界情况

## Defaults

默认使用：

- 默认工具：
- 默认格式：
- 默认输出方式：

只有在以下情况才切换方案：

- 例外情况 1
- 例外情况 2

## Output format

按以下格式输出：

```markdown
# 标题

## Summary

## Details

## Next steps

Validation

交付前必须检查：

  • 检查项 1
  • 检查项 2
  • 检查项 3

如果验证失败：

  1. 阅读错误信息
  2. 修复问题
  3. 重新验证
  4. 通过后再交付

References

需要时再读取：

  • references/example.md：当遇到某类问题时读取
  • scripts/validate.py：用于验证输出
    ```

15. 适合沉淀进 Skill 的信息

可以优先沉淀这些内容：

类型 示例
你反复纠正过的问题 “不要只做客户端，还要考虑农民端和平台端”
业务中特有角色 “加工师傅、质检员、叉车、包装员都要进入流程”
流转规则 “返修到包装之间必须有状态跟踪”
输出偏好 “要结构化、易修改、功能不能糊弄”
验证要求 “做完要自己打开页面检查是否合格”
默认技术选择 “HTML demo 要能浏览器直接打开”
不能做的事 “遇到不懂的问我，不要瞎猜”

16. 一句话总结

写 Skill 的本质是：

把你已经付出过的沟通成本、纠错成本、试错经验，变成 Agent 下次可以直接遵守的工作规范。

 评论