Skill 编写最佳实践
如何编写范围清晰、要求与任务相匹配的 Skill。
从实际专业经验出发
编写 Skill 时,一个常见问题是:不给大语言模型(LLM)提供领域上下文,只依赖模型训练中获得的通用知识,要求它直接生成 Skill。这样得到的往往是“妥善处理错误”“遵循身份验证最佳实践”等模糊、泛化的流程,而非真正赋予 Skill 价值的具体 API 用法、边界情况和项目约定。
有效的 Skill 建立在实际专业经验之上。关键是在编写过程中提供领域特有的上下文。
从亲手完成的任务中提炼
与 Agent 一起完成一项真实任务,在对话中逐步提供上下文、纠正意见和偏好,再将其中可复用的方法提炼为 Skill。重点关注:
- 有效的步骤——最终完成任务所遵循的操作顺序。
- 你作出的纠正——你引导 Agent 调整做法的地方,例如“使用 X 库而非 Y 库”“检查边界情况 Z”。
- 输入与输出格式——输入数据和输出结果的具体形式。
- 你提供的上下文——Agent 原本不知道的项目事实、约定或约束。
从现有项目资料中整合
如果已经积累了一批知识资料,可以交给 LLM,让它整合为 Skill。用团队实际的故障报告和操作手册编写的数据流水线 Skill,会比根据泛泛的“数据工程最佳实践”文章编写的 Skill 更有效,因为它涵盖的是你们的数据结构、故障模式和恢复流程。关键在于项目本身的资料,而非通用参考文献。
适合用作来源的资料包括:
- 内部文档、操作手册和风格指南。
- API 规范、Schema 和配置文件。
- 代码审查评论和问题跟踪记录,可反映反复出现的问题与审查者的要求。
- 版本控制历史,尤其是补丁与修复,可从实际变更中发现规律。
- 真实的失败案例及其解决方法。
用实际执行结果改进
Skill 的初稿通常还需要完善。用真实任务运行 Skill,再将所有结果反馈到编写过程中,不能只看失败的结果。检查:哪些情况导致了误触发?遗漏了什么?哪些内容可以删掉?
哪怕只做一轮“执行后修订”,质量也会明显提升;复杂领域通常需要多轮迭代。
提示
阅读 Agent 的执行轨迹,而不只是最终输出。如果 Agent 在无效步骤上浪费时间,常见原因包括:指令过于模糊,导致 Agent 反复尝试才找到可行方法;指令不适用于当前任务,Agent 却仍然照做;或者提供了太多选项,却没有明确默认方案。
如果需要更系统的迭代方法,包括测试用例、断言和评分,参见评估 Skill 输出质量。
合理使用上下文
Skill 激活后,SKILL.md 的完整正文会加载到 Agent 的上下文窗口,与对话历史、系统上下文和其他已激活的 Skill 共存。Skill 中的每个 token 都与窗口内的其他内容争夺 Agent 的注意力。
补充 Agent 不知道的,省略它已经知道的
重点说明 Agent 离开这个 Skill 就不会知道的内容:项目约定、领域流程、不易察觉的边界情况,以及应使用的具体工具或 API。不必解释 PDF 是什么、HTTP 如何工作,或者数据库迁移的作用。
<!-- 过于冗长——Agent 已经知道 PDF 是什么 -->
## 提取 PDF 文本
PDF(可移植文档格式)是一种常见文件格式,可以包含文本、图像等内容。
从 PDF 提取文本需要使用库。建议使用 pdfplumber,因为它能妥善处理大多数情况。
<!-- 更好的写法——直接说明 Agent 自己不会知道的内容 -->
## 提取 PDF 文本
使用 pdfplumber 提取文本。对于扫描文档,改用 pdf2image 配合 pytesseract。
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
```逐项审视内容:“没有这条指令,Agent 会做错吗?”如果不会,就删掉;如果不确定,就测试。如果没有 Skill,Agent 就能很好地完成整个任务,那么这个 Skill 可能并未增加价值。系统测试的方法参见评估 Skill 输出质量。
围绕完整的工作单元划定范围
决定 Skill 应涵盖什么,与决定函数应完成什么类似:应将一项完整、内在连贯的工作封装起来,并能与其他 Skill 配合。范围太窄,完成一项任务就必须加载多个 Skill,可能增加开销并引发指令冲突;范围太宽,又难以准确激活。查询数据库并格式化结果,可以构成一个完整的工作单元;如果还要负责数据库管理,范围可能就过大了。
细节保持适度
过于详尽的 Skill 可能弊大于利:Agent 难以提取相关内容,还可能受不适用于当前任务的指令影响,尝试无效的做法。简明的分步指导配合可运行的示例,通常比面面俱到的文档更有效。如果发现自己开始罗列所有边界情况,不妨想想,其中大多数是否交给 Agent 自行判断更合适。
用渐进式披露组织大型 Skill
规范建议让 SKILL.md 的篇幅少于 500 行、token 数少于 5,000,只保留每次运行都需要的核心指令。如果 Skill 确实需要更多内容,就将详细参考资料移到 references/ 等目录下的独立文件中。
关键是告诉 Agent 何时加载每个文件。“如果 API 返回非 200 状态码,读取 references/api-errors.md”,比笼统的“详见 references/”更有用。这样,Agent 就能按需加载上下文,不必一开始全部读取,这正是渐进式披露的设计方式。
把握约束程度
Skill 各部分不必采用同样严格的要求。指令应具体到什么程度,取决于任务有多容易出错。
根据任务的容错程度确定指令的具体程度
如果多种方法都可行,任务也允许结果有所变化,就给 Agent 留出选择空间。对于可灵活执行的指令,解释原因可能比规定死板步骤更有效:Agent 理解了指令的目的,便能更好地结合上下文作出判断。代码审查 Skill 可以说明应检查什么,而不必规定具体步骤:
## 代码审查流程
1. 检查所有数据库查询是否存在 SQL 注入风险(使用参数化查询)
2. 确认每个端点都有身份验证检查
3. 检查并发代码路径中是否存在竞态条件
4. 确认错误消息不会泄露内部细节如果操作容易出错、结果必须一致,或者必须遵循特定顺序,就给出严格指令:
## 数据库迁移
严格按以下命令执行:
```bash
python scripts/migrate.py --verify --backup
```
不要修改命令,也不要添加其他参数。大多数 Skill 兼有这两类情况,应分别确定各部分的约束程度。
明确默认方案,不罗列平级选项
多种工具或方法都可行时,选定一个默认方案,再简要说明替代方案,不要将它们作为同等选项一一列出。
<!-- 选项太多 -->
可以使用 pypdf、pdfplumber、PyMuPDF 或 pdf2image……
<!-- 默认方案明确,也留有替代方案 -->
使用 pdfplumber 提取文本:
```python
import pdfplumber
```
对于需要光学字符识别(OCR)的扫描版 PDF,改用 pdf2image 配合 pytesseract。教会方法,而不只是给出结论
Skill 应教会 Agent 如何处理一类问题,而不只是说明某个具体任务应产出什么。比较以下两种写法:
<!-- 具体答案——只适用于这一个任务 -->
通过 `customer_id` 将 `orders` 表与 `customers` 表关联,
筛选 `region = 'EMEA'` 的记录,并对 `amount` 列求和。
<!-- 可复用的方法——适用于任意分析查询 -->
1. 读取 `references/schema.yaml` 中的数据结构,找到相关表
2. 按 `_id` 外键约定关联数据表
3. 将用户请求中的筛选条件写成 WHERE 子句
4. 按需汇总数值列,并将结果整理为 Markdown 表格这并不意味着 Skill 不能包含具体细节:输出格式模板(参见输出格式模板)、“绝不输出个人身份信息(PII)”这样的约束,以及特定工具的使用指令,都很有价值。关键在于,即使个别细节很具体,整体方法也应能适用于同类问题。
有效指令的常见写法
以下方法可用于组织 Skill 内容。并非每个 Skill 都需要全部采用,选择适合任务的方法即可。
易错点说明
许多 Skill 中最有价值的内容,是一份易错点清单:列出特定环境中那些与合理预期不符的事实。这不是“妥善处理错误”之类的通用建议,而是针对 Agent 在未获提醒时容易犯的错误,给出具体纠正:
## 易错点
- `users` 表采用软删除。查询必须包含
`WHERE deleted_at IS NULL`,否则结果会包含已停用账号。
- 用户 ID 在数据库中叫 `user_id`,在身份验证服务中叫 `uid`,
在计费 API 中叫 `accountId`。三者指的是同一个值。
- 只要 Web 服务器仍在运行,`/health` 端点就会返回 200,
即使数据库连接已经中断。请使用 `/ready` 检查完整的服务健康状态。将易错点保留在 SKILL.md 中,让 Agent 在遇到相关情况之前就读到。也可以放入独立参考文件,但必须说明何时加载;对于不易察觉的问题,Agent 可能无法识别加载的触发条件。
提示
如果 Agent 犯了需要你纠正的错误,就把纠正内容加入易错点说明。这是持续改进 Skill 最直接的方法之一,参见用实际执行结果改进。
输出格式模板
如果需要 Agent 按特定格式输出,就提供模板。Agent 善于参照具体结构,因此模板比文字描述更可靠。短模板可直接写在 SKILL.md 中;较长的模板,或仅在特定情况下才需要的模板,可以放入 assets/,再从 SKILL.md 引用,让 Agent 按需加载。
## 报告结构
使用以下模板,并按具体分析需要调整各部分:
```markdown
# [分析标题]
## 执行摘要
[用一段话概括主要发现]
## 主要发现
- 发现 1 及支撑数据
- 发现 2 及支撑数据
## 建议
1. 具体、可执行的建议
2. 具体、可执行的建议
```多步骤工作流检查清单
明确的检查清单有助于 Agent 跟踪进度,避免漏掉步骤,尤其适合步骤之间存在依赖关系,或必须通过验证才能继续的任务。
## 表单处理工作流
进度:
- [ ] 第 1 步:分析表单(运行 `scripts/analyze_form.py`)
- [ ] 第 2 步:创建字段映射(编辑 `fields.json`)
- [ ] 第 3 步:验证映射(运行 `scripts/validate_fields.py`)
- [ ] 第 4 步:填写表单(运行 `scripts/fill_form.py`)
- [ ] 第 5 步:核验输出(运行 `scripts/verify_output.py`)验证循环
要求 Agent 先验证自己的工作,再继续下一步。基本流程是:完成工作,运行验证程序——可以是脚本、参考检查清单或自检——修复问题,然后重复验证,直到通过。
## 编辑工作流
1. 完成修改
2. 运行验证:`python scripts/validate.py output/`
3. 如果验证失败:
- 查看错误消息
- 修复问题
- 再次运行验证
4. 只有验证通过后才能继续参考文档也可以充当“验证程序”:要求 Agent 在定稿前对照参考文档检查自己的工作。
规划、验证、执行
对于批量操作或破坏性操作,要求 Agent 先用结构化格式生成一份中间计划,对照权威依据验证后,再执行操作。
## 填写 PDF 表单
1. 提取表单字段:`python scripts/analyze_form.py input.pdf` → `form_fields.json`
(列出所有字段的名称、类型及是否必填)
2. 创建 `field_values.json`,将每个字段名映射到要填写的值
3. 验证:`python scripts/validate_fields.py form_fields.json field_values.json`
(检查所有字段名是否存在于表单中、类型是否兼容,以及是否遗漏必填字段)
4. 如果验证失败,修改 `field_values.json` 并重新验证
5. 填写表单:`python scripts/fill_form.py input.pdf field_values.json output.pdf`关键在于第 3 步:用验证脚本将计划(field_values.json)与权威依据(form_fields.json)作比较。“未找到字段 'signature_date'——可用字段:customer_name、order_total、signature_date_signed”这样的错误消息,能为 Agent 提供足够的信息,使其自行纠正。
附带可复用的脚本
迭代 Skill 时,对比各个测试用例中 Agent 的执行轨迹。如果发现 Agent 每次都自行重写相同逻辑,例如绘制图表、解析特定格式、验证输出,就应将这段逻辑写成经过测试的脚本,随 Skill 一起放入 scripts/。
关于脚本的设计与组织,参见在 Skill 中使用脚本。
后续步骤
Skill 能够正常工作后,可以参考以下两篇指南继续完善:
- 评估 Skill 输出质量——建立测试用例、为结果评分,并系统地迭代改进。
- 优化 Skill 描述——测试并改进 Skill 的
description字段,使其在遇到合适的 Prompt 时触发。