Skill 创建者最佳实践

本页为最佳实践指南的非官方中文翻译。

Skill 创建者最佳实践

从真实的领域知识出发

Skill 创建中的一个常见陷阱是，要求 LLM 仅凭其通用训练知识生成 Skill，而不提供领域特定的上下文。这样做的结果是模糊、笼统的流程（如”适当处理错误”、“遵循认证最佳实践”），而非使 Skill 有价值的具体 API 模式、边界情况和项目约定。

有效的 Skills 立足于真实的领域知识。关键在于将领域特定的上下文输入到创建过程中。

从实际任务中提炼

在与智能体的对话中完成一个真实的任务，沿途提供上下文、纠正和偏好。然后将可复用的模式提炼成 Skill。请注意：

奏效的步骤 — 导致成功的一系列操作
你做出的纠正 — 你引导智能体方法的地方（例如，“使用库 X 而非 Y”，“检查边界情况 Z”）
输入/输出格式 — 输入和输出数据的样子
你提供的上下文 — 智能体原本不知道的项目特定事实、约定或约束

从现有项目工件中综合

当你拥有大量现有知识时，你可以将其输入 LLM 并要求它综合出一个 Skill。从你的团队实际事件报告和运维手册综合而来的数据管道 Skill，将优于从通用”数据工程最佳实践”文章综合而来的 Skill，因为它捕获了你的模式、失败模式和恢复流程。关键在于项目特定的材料，而非通用参考资料。

优质的源材料包括：

内部文档、运维手册和风格指南
API 规范、模式和配置文件
代码评审意见和 issue 跟踪器（捕获反复出现的关注点和评审者期望）
版本控制历史，尤其是补丁和修复（通过实际更改的内容揭示模式）
真实世界的失败案例及其解决方案

通过真实执行进行改进

Skill 的初稿通常需要改进。针对真实任务运行该 Skill，然后将结果（不仅仅是失败）反馈到创建过程中。问：是什么触发了误报？遗漏了什么？可以删除什么？

即使只是执行一次再修改，也能显著提升质量，而复杂领域通常需要多轮这样的迭代。

译者注：阅读智能体的执行轨迹，而不仅仅是最终输出。如果智能体在不具生产力的步骤上浪费时间，常见原因包括：指令过于模糊（智能体在找到正确方法之前会尝试多种方法）、指令不适用于当前任务（智能体仍然遵循它们），或者在没有明确默认值的情况下提供了过多选项。

如需更结构化的迭代方法（包括测试用例、断言和评分），请参阅评估 Skill 输出质量。

明智地使用上下文

一旦某个 Skill 被激活，其完整的 SKILL.md 正文会与对话历史、系统上下文以及其他激活的 Skills 一起加载到智能体的上下文窗口中。Skill 中的每个 token 都在与该窗口中的所有其他内容争夺智能体的注意力。

添加智能体缺乏的内容，省略它已知的

专注于 没有你的 Skill，智能体就不会知道 的内容：项目特定的约定、领域特定的流程、不明显的边界情况，以及要使用的特定工具或 API。你无需解释 PDF 是什么、HTTP 如何工作或数据库迁移是什么。

<!-- 过于冗长 — 智能体已经知道 PDF 是什么 -->
## 提取 PDF 文本

PDF（便携文档格式）文件是一种常见的文件格式，包含文本、图像和其他内容。
要提取 PDF 中的文本，你需要使用一个库。推荐使用 pdfplumber，因为它能处理大多数情况。

<!-- 更好 — 直接跳到智能体本身不知道的内容 -->
## 提取 PDF 文本

使用 pdfplumber 进行文本提取。对于扫描文档，回退使用 pdf2image 加 pytesseract。

```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

对于每段内容问自己：“没有这条指令，智能体会做错吗？” 如果答案是不会，就删掉。如果你不确定，就测试一下。如果智能体在没有 Skill 的情况下已经能很好地处理整个任务，那么该 Skill 可能并没有增加价值。有关如何系统地测试这一点，请参阅评估 Skill 输出质量。

设计内聚的单元

决定一个 Skill 应该涵盖什么，类似于决定一个函数应该做什么：你希望它封装一个与其他 Skill 良好组合的内聚工作单元。范围过于狭窄的 Skill 会迫使用户为单一任务加载多个 Skill，从而带来开销和指令冲突的风险。范围过于宽泛的 Skill 则难以精确激活。一个用于查询数据库并格式化结果的 Skill 可能是一个内聚单元，而一个同时涵盖数据库管理的 Skill 可能想做太多事情。

适度的详细程度

过于全面的 Skill 可能弊大于利 — 智能体难以提取相关内容，并可能因不适用的指令而走上徒劳的路径。简洁的、分步骤的指导加上可工作的示例，往往胜过详尽的文档。当你发现自己要覆盖每一种边界情况时，请考虑是否大多数情况最好由智能体自己的判断来处理。

用 Progressive Disclosure / 渐进式披露构建大型 Skill

规范建议将 SKILL.md 控制在 500 行和 5,000 tokens 以内 — 只保留每次运行所需的核心指令。当某个 Skill 确实需要更多内容时，将详细的参考资料移至 references/ 或类似目录中的单独文件。

关键在于告诉智能体何时加载每个文件。“如果 API 返回非 200 状态码，请阅读 references/api-errors.md” 比笼统的”参阅 references/ 了解详情”更有用。这让智能体按需加载上下文，而不是预先加载，这正是 Progressive Disclosure / 渐进式披露的设计思路。

校准控制程度

并非 Skill 的每个部分都需要同等程度的规范性。请将指令的具体程度与任务的脆弱性相匹配。

将具体程度与脆弱性匹配

给智能体自由，当多种方法都有效且任务容忍差异时。对于灵活的指令，解释 为什么 可能比死板的指令更有效 — 理解指令背后目的的智能体，能根据上下文做出更好的决策。一个代码审查 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 应该教智能体 如何处理 一类问题，而不是为某个特定实例 产出什么。比较一下：

<!-- 特定答案 — 仅对这一个任务有用 -->
将 `orders` 表通过 `customer_id` 连接到 `customers`，筛选 `region = 'EMEA'`，
并对 `amount` 列求和。

<!-- 可复用方法 — 适用于任何分析性查询 -->
1. 从 `references/schema.yaml` 读取模式以找到相关表
2. 使用 `_id` 外键约定连接表
3. 将用户请求中的任何筛选条件作为 WHERE 子句应用
4. 根据需要聚合数值列并格式化为 markdown 表格

这并不意味着 Skill 不能包含具体的细节 — 输出格式模板（参见输出格式模板）、“绝不输出 PII”之类的约束，以及特定工具的指令都是有价值的。重点是，方法应该具有普适性，即使单个细节是具体的。

有效指令的模式

以下是用于组织 Skill 内容的可复用技术。并非每个 Skill 都需要全部 — 选择适合你任务的部分即可。

注意事项章节

许多 Skill 中价值最高的内容是一个注意事项列表 — 那些违背合理假设的环境特定事实。这些不是泛泛的建议（“适当处理错误”），而是对智能体若未被告知则会犯错误的明确纠正：

## 注意事项

- `users` 表使用软删除。查询必须包含
  `WHERE deleted_at IS NULL`，否则结果将包含已停用的账户。
- 用户 ID 在数据库中为 `user_id`，在认证服务中为 `uid`，
  在计费 API 中为 `accountId`。三者指的是同一个值。
- `/health` 端点只要 Web 服务器在运行就返回 200，
  即使数据库连接已断开也是如此。请使用 `/ready` 检查完整的服务健康状况。

将注意事项保留在 SKILL.md 中，以便智能体在遇到该情况之前就能读到它们。单独使用一个引用文件也可以，前提是你告诉智能体何时加载它，但对于不明显的问题，智能体可能无法识别触发条件。

译者注：当智能体犯了需要你纠正的错误时，将纠正添加到注意事项章节。这是迭代改进 Skill 的最直接方法之一（参见通过真实执行进行改进）。

输出格式模板

当你需要智能体以特定格式生成输出时，请提供模板。这比用散文描述格式更可靠，因为智能体可以很好地针对具体结构进行模式匹配。短模板可以内联在 SKILL.md 中；对于较长的模板，或仅在某些情况下需要的模板，请将它们存储在 assets/ 中并从 SKILL.md 引用，以便仅在需要时加载。

## 报告结构

使用此模板，根据具体分析调整章节：

```markdown
# [分析标题]

## 概要
[一段关于关键发现的概述]

## 主要发现
- 带有支持数据的发现 1
- 带有支持数据的发现 2

## 建议
1. 具体可行的建议
2. 具体可行的建议
```

多步骤工作流的检查清单

明确的检查清单有助于智能体跟踪进度并避免跳过步骤，尤其是在步骤之间存在依赖关系或验证关口时。

## 表单处理工作流

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

验证循环

指示智能体在继续之前验证自己的工作。其模式是：执行工作，运行验证程序（脚本、参考检查表或自检），修复任何问题，并重复直到验证通过。

## 编辑工作流

1. 进行编辑
2. 运行验证：`python scripts/validate.py output/`
3. 如果验证失败：
   - 查看错误消息
   - 修复问题
   - 重新运行验证
4. 仅在验证通过后才继续

参考文档也可以充当”验证器” — 指示智能体在最终确定之前对照参考检查自己的工作。

计划—验证—执行

对于批处理或破坏性操作，让智能体以结构化格式创建中间计划，针对事实来源进行验证，然后再执行。

## 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 步：针对事实来源（form_fields.json）验证计划（field_values.json）的验证脚本。像”找不到字段 ‘signature_date’ — 可用字段：customer_name, order_total, signature_date_signed”这样的错误，为智能体提供了足够的信息来自我纠正。

打包可复用脚本

在迭代改进 Skill 时，比较智能体在测试用例之间的执行轨迹。如果你注意到智能体每次运行都独立地重新发明相同的逻辑（构建图表、解析特定格式、验证输出），那就是一个信号：编写一个经过测试的脚本，并将其打包到 scripts/ 中。

有关设计和打包脚本的更多信息，请参阅在 Skills 中使用脚本。

下一步

一旦你拥有了一个可用的 Skill，以下两个指南可以帮助你进一步改进它：

评估 Skill 输出质量 — 设置测试用例、评分结果并系统地迭代。
优化 Skill 描述 — 测试并改进 Skill 的 description 字段，使其在正确的提示上被触发。