面向 Skill 创建者的最佳实践

从真实专业经验出发

创建技能时，一个常见误区是：什么领域上下文都不给，直接让大模型“帮我生成一个技能”，只依赖模型预训练时的通用知识。这样的结果往往是泛泛而谈的流程，比如“适当处理错误”“遵循认证最佳实践”，而不是你真正需要的那些内容：具体的 API 使用模式、边界情况处理、项目约定等。

高质量技能必须建立在真实专业经验之上。关键在于：在创建技能的过程中，把与你的领域相关的上下文输入给模型。

从一次真实的动手任务中抽取

先在和智能体的对话中完成一次真实任务，在过程中不断提供上下文、纠正和偏好设置。然后再从这次完成任务的过程里，抽取出可复用的“模式”，整理成一个技能。

在抽取时，重点关注：

• 真正奏效的步骤 —— 那些确实让任务完成的关键行动顺序
• 你做过的纠正 —— 你是如何修正智能体的做法的（例如：“用库 X 而不是 Y”，“记得检查边界情况 Z”）
• 输入/输出格式 —— 数据进入和输出时分别长什么样
• 你补充的上下文 —— 项目特有的事实、约定或约束，也就是智能体原本不知道的东西

从既有项目材料中综合提炼

当你已经有一批现成的知识材料时，可以把它们喂给大模型，让它综合生成一个技能。比如，一个数据管道相关的技能，如果是从你团队的真实事故报告和 runbook 里综合出来的，一定会比根据一篇泛泛而谈的“数据工程最佳实践”文章生成的技能更好用。原因很简单：前者捕捉的是你们自己的数据结构、常见故障模式和恢复步骤。

关键点在于：要使用项目自身的材料，而不是通用参考资料。

比较适合作为输入的包括：

• 内部文档、操作手册、风格指南
• API 规格说明、schema 和配置文件
• 代码评审评论和 issue 追踪记录（体现反复出现的问题与评审标准）
• 版本控制历史，尤其是补丁和修复（通过实际修改暴露出真实模式）
• 现实中的失败案例及其解决方式

通过真实执行来打磨技能

技能的第一版几乎总是需要打磨。用真实任务多跑几次这个技能，然后把执行结果——不只是失败案例，而是所有结果——都反馈回技能创建过程。

要问自己：是什么触发了“误报”？遗漏了什么？哪些内容其实可以删掉？

即便只做一次“执行 → 回顾 → 修改”的循环，技能质量也会有明显提升；在复杂领域里，往往需要多轮迭代。

不要只看最终输出，要阅读智能体的执行轨迹。如果你发现它在一些无效步骤上浪费了时间，常见原因包括：指令太模糊（智能体要试好几种办法才能撞到一个能用的）、指令其实不适用于当前任务（但智能体还是照做了），或者给出了太多选项却没有明确默认选择。

如果你希望用一种更结构化的方式来迭代，包括测试用例、断言和自动打分，可以参考《评估技能输出质量》。

精打细算地使用上下文

一旦某个技能被激活，它完整的 SKILL.md 内容会被加载进智能体的上下文窗口，与当前对话历史、系统上下文和其他已激活的技能一起共享上下文。你的技能中的每一个 token，都会和上下文窗口中其他一切内容“争抢注意力”。

只补智能体缺的，不重复它已经会的

重点写清楚那些智能体如果没有这个技能就会做错的部分：项目特有的约定、领域专门的操作流程、不明显的边界情况、应该使用的特定工具或 API。你没必要再去解释什么是 PDF、HTTP 怎么工作，或者数据库迁移是什么。

对比下面这段：

1<!-- 过于啰嗦 —— 这些关于 PDF 的常识，智能体本来就知道 -->
2## 提取 PDF 文本
3
4PDF（便携式文档格式）文件是一种常见的文档格式，其中包含
5
6文本、图像和其他内容。要从 PDF 中提取文本，您需要
7
8使用一个库。推荐使用 pdfplumber，因为它能够很好地处理大多数情况。
9​
10<!-- 更好 —— 直接切入智能体原本不会知道的具体做法 -->
11## 提取 PDF 文本
12​
13使用 pdfplumber 进行文本提取。对于扫描文档，请回退到使用 pytesseract 的 pdf2image。
14​
15```python
16import pdfplumber
17​
18with pdfplumber.open("file.pdf") as pdf:
19    text = pdf.pages[0].extract_text()
20```

写每一句话前，都可以问自己一句：“如果不写这条指令，智能体真的会做错吗？”如果答案是否定的，那就删掉。如果不确定，就去测一测。而如果你发现：即使不加载这个技能，智能体也已经能很好地完成整个任务，那说明这个技能很可能并没有提供额外价值。要如何系统性地验证这一点，可以参考《如何评估Skill的输出质量》（评估技能输出质量）。

设计“内聚”的技能单元

一个技能应该覆盖什么范围，就像在决定一个函数应该做什么一样：你希望它封装的是一个内聚的工作单元，同时又能和其他技能很好地组合。

范围太细的技能，会导致一个任务需要加载多个技能，不但增加开销，而且更容易出现指令互相冲突的问题。范围太宽的技能，又很难在正确的场景下被精确触发。

比如，“查询数据库并格式化结果”可以算作一个内聚的单元；但如果再把“数据库运维”也塞进来，那这个技能很可能已经在做太多事了。

追求“适度”的细节程度

过于全面、事无巨细的技能往往会产生反效果：智能体难以从中抽取当前任务真正相关的部分，还可能被不适用的指令吸引，走上无效路径。

简明、分步骤的指导，加上一段可直接运行的示例，通常要比一整份穷举式文档更好用。当你发现自己开始想覆盖“所有”边界情况时，值得停下来想一想：这些边界情况里，有多少其实更适合让智能体凭自己的判断去处理。

用“渐进披露”来组织大型技能

规范建议将 SKILL.md 控制在 500 行、5,000 个 token 之内，也就是只保留每次运行都必不可少的核心指令。如果一个技能确实需要更多内容，可以把更详细的参考资料放在 references/ 或类似目录中的单独文件里。

关键在于：让智能体知道什么时候去加载这些文件。比如，“当 API 返回非 200 状态码时，阅读 references/api-errors.md”就要比一句泛泛的“详情见 references/ 目录”有用得多。这样智能体就能按需加载上下文，而不是一上来就全部灌进来，这正是“渐进披露”的设计初衷。

调整“控制力度”的刻度

技能中的不同部分，其实并不需要同样程度的“硬性规定”。要根据任务的脆弱程度和容错空间，调整指令的具体程度。

把“具体程度”与“脆弱程度”对齐

在任务容错高、可选方案多的地方，给智能体更多自由度。在写这类“宽松指令”时，解释“为什么”往往比写死“具体怎么做”更有效——当智能体理解了一条指令背后的目的，就更容易在具体语境里做出合理判断。

比如，一个代码评审技能，可以只描述需要关注哪些点，而不用规定每一步该怎么做：

1## 代码复审流程
2​
3  1.  检查所有数据库查询是否存在 SQL 注入漏洞（使用参数化查询）
4  2.  验证每个端点上的身份验证机制
5  3.  检查并发代码路径中是否存在竞态条件
6  4.  确认错误信息不会泄露内部细节
7在那些操作脆弱、对一致性要求极高、必须按特定顺序执行的场景，就要写得非常具体。
8
9## Database migration
10​
11严格按照下面的顺序执行
12​
13```bash
14python scripts/migrate.py --verify --backup
15```
16​
17请勿修改命令或添加其他标志。

大多数技能都会混合这两种部分。关键是：逐段校准具体程度，而不是一刀切。

提供“默认方案”，而不是“菜单式选项”

当存在多种可行工具或路径时，最好挑一个默认方案，再简短提一下替代选项，而不是把所有选项按“平级菜单”方式一股脑丢给智能体。

1<!-- 选项太多，缺乏指引 -->
2你可以使用 pypdf、pdfplumber、PyMuPDF 或 pdf2image……
3  
4<!-- 有清晰默认选项，同时保留退路 -->
5使用pdfplumber进行文本提取：
6  
7  ```python
8  import pdfplumber
9  ```
10​
11对于需要 OCR 的扫描 PDF 文件，请改用 pytesseract 和 pdf2image。

多写“过程”，少给“现成答案”

一个技能应该教的是：如何处理某一类问题，而不是针对某个具体问题给出唯一答案。对比这两种写法：

1<!-- 针对某一个特定任务的答案，只在这一题有用 -->
2将 `orders` 表与 `customers` 表按 `customer_id` 连接，筛选条件为：`region = 'EMEA'`，并对 `amount` 列求和。
3​
4<!-- 可复用的方法，可以用于任意分析查询 -->
51. 从 `references/schema.yaml` 读取模式文件，找到相关表。
62. 使用 `_id` 外键约定连接表。
73. 将用户请求中的任何筛选条件作为 WHERE 子句应用。
84. 根据需要聚合数值列，并将其格式化为 Markdown 表格。

这并不意味着技能里不能出现具体细节——输出格式模板、诸如“绝不输出任何个人隐私信息（PII）”之类的约束、或特定工具的用法说明，都是很有价值的。但在这些具体细节之上，整体思路仍然应该是可泛化的。

有效指令的常见结构模式

下面这些是可以反复复用的技能结构模式。并不是每个技能都需要全部用上，根据任务类型挑合适的即可。

坑点（Gotchas）

在很多技能里，价值最高的内容，往往是一小段“Gotchas”——也就是和环境强相关、又容易违反直觉的事实。这些不是那种泛泛的建议（比如“要适当处理错误”），而是如果你不写出来，智能体几乎一定会踩坑的那类具体纠正。

1## Gotchas
2​
3- `users` 表使用软删除。查询必须包含 `WHERE deleted_at IS NULL`，否则结果将包含已停用的帐户。
4- 用户 ID 在数据库中为 `user_id`，在身份验证服务中为 `uid`， 在计费 API 中为 `accountId`。这三个 ID 都指向同一个值。
5- 只要 Web 服务器正在运行，`/health` 端点就会返回 200，即使数据库连接已断开。使用 `/ready` 来检查完整的服务运行状况。

这类“坑点”建议最好直接写在 SKILL.md 里，这样智能体在真正碰到问题前就已经读过了。当然也可以放到单独的参考文件里，但那样你就得明确告诉智能体在什么时候去读它；否则智能体可能根本意识不到“现在就是用这份参考资料的时机”。

每当你因为智能体犯错而不得不出手纠正，就可以把这次纠正内容加入 Gotchas 小节。这是迭代提升技能质量最直接的方式之一。

输出格式模板

当你希望智能体以某种特定结构输出结果时，提供一个模板往往比用文字描述格式更可靠——因为智能体在模式匹配方面要比在抽象说明方面强得多。

短一点的模板可以直接写在 SKILL.md 中；更长的模板，或者只在特定场景下才需要用到的模板，可以放在 assets/ 等目录下，并从 SKILL.md 里引用，以避免无谓的上下文开销。

1## 报告结构
2  
3使用此模板，并根据具体分析的需要调整各部分内容：
4  
5  ```markdown
6  # [Analysis Title]
7  
8  ## Executive summary
9  [主要发现的单段概述]
10  
11  ## Key findings
12  - 发现 1（附支撑数据）
13  - 发现 2（附支撑数据）
14  
15  ## Recommendations
16  1. 具体的、可操作的建议
17  2. 具体的、可操作的建议
18  ```

适合多步骤流程的检查清单

对于多步骤的工作流，一份明确的检查清单可以帮助智能体跟踪进度，避免跳步，尤其是在步骤之间存在依赖关系或必须通过某些验证关卡时。

1## Form processing workflow
2​
3进度：
4- [ ] 步骤 1：分析表单（运行 `scripts/analyze_form.py`）
5- [ ] 步骤 2：创建字段映射（编辑 `fields.json`）
6- [ ] 步骤 3：验证映射（运行 `scripts/validate_fields.py`）
7- [ ] 步骤 4：填写表单（运行 `scripts/fill_form.py`）
8- [ ] 步骤 5：验证输出（运行 `scripts/verify_output.py`）

验证循环（Validation loops）

指导智能体在继续下一步之前，先验证自己的工作成果。经典模式是：先完成工作，再运行一个验证器（脚本、参考清单或自检步骤），如果发现问题就修正，然后重复这一过程，直到验证通过。

1## Editing workflow
2  
31. 执行修改
4  2. 运行验证: `python scripts/validate.py output/`
5  3. 若验证失败:
6     - 检查错误信息
7     - 修复相关问题
8     - 重新运行验证
9  4. 只有在验证通过后方可继续

一个参考文档同样可以充当“验证器”的角色——你可以指示智能体在最终确认结果前，将自己的输出与该参考进行逐项对照。

计划 - 验证 - 执行

在处理批量任务或具破坏性的操作时，可以要求智能体先生成一个结构化的中间“计划”，再把这个计划和“事实来源”比对验证通过之后，才真正执行。

1## PDF form filling
2  
31. 提取表单字段：`python scripts/analyze_form.py input.pdf` → `form_fields.json`（列出所有字段名称、类型以及是否必填）
42. 创建 `field_values.json`，将每个字段名称映射到其预期值
53. 验证：`python scripts/validate_fields.py form_fields.json field_values.json`（检查表单中是否存在所有字段名称、字段类型是否兼容以及是否缺少必填字段）
64. 如果验证失败，则修改 `field_values.json` 并重新验证
75. 填写表单：`python scripts/fill_form.py input.pdf field_values.json output.pdf`

这里最关键的一步是第 3 步：用一个验证脚本，把“计划”（field_values.json）和“事实来源”（form_fields.json）对比。像 “Field ‘signature_date’ not found — available fields: customer_name, order_total, signature_date_signed” 这种错误信息，会给智能体足够的信息来自我修正。

打包复用脚本

在迭代技能的过程中（参见“如何评估Skill的输出质量”一节），你可以比较智能体在不同测试用例下的执行轨迹。如果你发现智能体在每次运行里都在“重复发明”某些逻辑——例如绘制特定类型的图表、解析某种固定格式、或验证输出结果——这就是一个信号：可以把这部分逻辑写成一个经过良好测试的脚本，放进 scripts/ 目录里复用。

下一步

当你已经拥有一个可用的技能后，下面两篇指南可以帮助你继续优化：

• 如何评估Skill的输出质量 —— 如何设置测试用例、给结果打分并进行系统性迭代。
• 如何优化 Agent Skill 描述：提升技能触发率的系统方法指南 —— 如何测试并改进技能的 description 字段，让它在合适的提问下被准确触发。