最佳实践

如何编写范围明确且适合任务的技能。

范围明确且经过校准的技能
从真正的专业知识开始
技能创建中的一个常见陷阱是要求 LLM 在不提供特定领域背景的情况下生成技能——完全依赖于 LLM 的一般培训知识。结果是模糊的、通用的程序 (“适当地处理错误”、“遵循身份验证的最佳实践”)，而不是使技能具有价值的特定 API 模式、边缘案例和项目约定。
有效的技能基于真正的专业知识。关键在于将特定领域的背景信息融入创作过程中。
1.
从实际任务中提取
在与智能体的对话中完成一项实际任务，同时提供背景信息、修正和偏好。然后将可重复使用的模式提取为一种技能。注意：
有效的步骤——导致成功的行动顺序
你所做的修正——你在哪些地方引导了特工的方法 (例如，“使用库 X 而不是 Y”,“检查边缘情况 Z”)
输入/输出格式——数据进出时的样子
您提供的背景信息——项目特定事实、约定俗成或代理人不知道的限制
·
合成现有项目工件
当你拥有大量现有知识时，你可以将其输入 LLM，并让它合成一项技能。基于团队实际事件报告和运行手册合成的数据管道技能将优于从通用 “数据工程最佳实践” 文章中合成的技能，因为它捕捉了你的模式、故障模式和恢复过程。关键是项目特定材料，而不是通用参考。
优质的资料来源包括：
内部文档、运行手册和风格指南
API 规范、架构和配置文件
代码审核评论和问题跟踪 (捕获反复出现的问题和审核人员期望)
版本控制历史记录，特别是补丁和修复 (通过实际改变的内容揭示模式)
现实世界中的故障案例及其解决方案
·
通过实际执行进行完善
一项技能的初稿通常需要完善。在真实任务中运用这项技能，然后将结果——所有结果，而不仅仅是失败——反馈回创造过程中。问问自己：是什么触发了假阳性反应？遗漏了什么？哪些可以删除？
即使是执行然后修改的单个步骤也能显著提高质量，而复杂的领域通常会从多个步骤中受益。
读取智能体执行轨迹，而不仅仅是最终输出。如果智能体在无效步骤上浪费时间，常见原因包括指令过于模糊 (智能体尝试了多种方法才找到有效的方法)、指令不适用于当前任务 (智能体无论如何都会遵循这些指令) 或提供了太多没有明确默认的选项。
有关更结构化的迭代方法，包括测试用例、断言和评分，请参阅评估技能输出质量。
·
明智地使用上下文
一旦某个 skill 被激活，其完整的 SKILL.md 体就会与对话历史记录、系统背景和其他活跃 skill 一起载入 Agent 的上下文窗口。你的 skill 中的每一个代币都会与该窗口中的其他所有内容一起争夺 Agent 的注意力。
·
添加智能体缺失的内容，省略它所知道的
专注于代理如果没有你的技能就无法了解的内容：项目特定的约定、领域特定的程序、不明显的边缘情况，以及要使用的特定工具或 API。你不需要解释 PDF 是什么、HTTP 如何工作，或者数据库迁移是做什么的。

Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you’ll need to
use a library. pdfplumber is recommended because it handles most cases well.

Extract PDF text

Use pdfplumber for text extraction. For scanned documents, fall back to
pdf2image with pytesseract.

import pdfplumber

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

问问自己关于每个内容的问题:“如果没有这个指令，智能体会不会把这个搞错？” 如果答案是否定的，就删除它。如果不确定，就测试它。如果智能体已经能够很好地处理整个任务，而不需要这个技能，那么这个技能可能不会增加价值。请参阅评估技能输出质量，了解如何系统地测试这一点。
·
设计连贯的单元
决定一个技能应该涵盖哪些内容，就像决定一个函数应该做什么一样：你希望它封装成一个连贯的工作单元，能够与其他技能很好地协调。范围过窄的技能会迫使多个技能为单个任务加载，从而冒着开销和指令冲突的风险。范围过广的技能将难以精确激活。查询数据库和格式化结果的技能可能是一个连贯的单元，而同时涵盖数据库管理的技能可能试图做太多事情。
·
目标是适度的细节
过于全面的技能可能弊大于利——代理人难以提取相关信息，可能会遵循由不适用于当前任务的指令引发的无效路径。简洁、循序渐进的工作示例指导往往比详尽的文档更有效。当你发现自己涵盖了所有边缘案例时，请考虑大多数案例是否更好地由代理人自己的判断来处理。
·
通过渐进式披露构建大型技能
规范建议将 SKILL.md 保持在 500 行和 5000 个令牌以下——这正是 Agent 在每次运行中所需的核心指令。当 skill 合法地需要更多内容时，将详细的参考资料移动到引用/或类似目录中的单独文件。
关键是告诉代理何时加载每个文件。“如果 API 返回非 200 的状态码，请阅读引用/api-errors.md” 比通用的 “请参阅引用/了解详细信息” 更有用。这使得代理能够根据需要加载上下文，而不是提前加载，这正是渐进式披露设计的目的。
·
校准控制
并非技能的每个部分都需要相同程度的规范性。请根据任务的脆弱性来调整你指示的具体性。
·
将特殊性与脆弱性相匹配
当多种方法有效且任务可以容忍变化时，给予智能体自由。对于灵活的指令，解释为什么可能比严格的指令更有效——一个理解指令背后目的的智能体能够做出更好的上下文相关决策。代码审查技能可以描述要寻找的内容，而无需规定具体步骤：

Code review process

1. Check all database queries for SQL injection (use parameterized queries)
2. Verify authentication checks on every endpoint
3. Look for race conditions in concurrent code paths
4. Confirm error messages don’t leak internal details
   当操作脆弱、一致性重要或必须遵循特定顺序时，应具有规范性：

   Database migration

Run exactly this sequence:

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

Do not modify the command or add additional flags.
大多数技能都是混合的。独立校准每个部分。
·
提供默认值，而不是菜单
当多种工具或方法可能有效时，选择一个默认选项并简要提及其他选项，而不是将它们作为等价选项呈现。

You can use pypdf, pdfplumber, PyMuPDF, or pdf2image…

Use pdfplumber for text extraction:

import pdfplumber

For scanned PDFs requiring OCR, use pdf2image with pytesseract instead.
·
优先程序优先于声明
技能应该教授智能体如何处理一类问题，而不是为特定情况生成什么。比较：

Join the orders table to customers on customer_id, filter where
region = 'EMEA', and sum the amount column.

1. Read the schema from references/schema.yaml to find relevant tables
2. Join tables using the _id foreign key convention
3. Apply any filters from the user’s request as WHERE clauses
4. Aggregate numeric columns as needed and format as a markdown table
   这并不意味着技能不能包含特定的细节——输出格式模板 (参见输出格式的模板)、“永远不要输出 PII” 等约束条件以及工具特定的说明都是有价值的。关键在于，即使个别细节是特定的，这种方法也应该是概括性的。
   ·
   有效指令的模式
   这些是构建技能内容的可重复使用的技巧。并非每个技能都需要所有这些技巧——使用那些适合你任务的技巧。
   ·
   Gotchas 章节
   许多技能中最有价值的内容是一系列 “gochas”——挑战合理假设的特定环境事实。这些不是一般性建议 (“适当处理错误”)，而是对代理人在未被告知的情况下可能犯错误的具体纠正：

   Gotchas

• The users table uses soft deletes. Queries must include
  WHERE deleted_at IS NULL or results will include deactivated accounts.
• The user ID is user_id in the database, uid in the auth service,
  and accountId in the billing API. All three refer to the same value.
• The /health endpoint returns 200 as long as the web server is running,
  even if the database connection is down. Use /ready to check full
  service health.
  在遇到这种情况之前，请将捕获的信息保存在 SKILL.md 中，以便智能体在遇到这种情况之前阅读。如果你告诉智能体何时加载一个单独的参考文件，这个文件会有效，但对于一些不明显的问题，智能体可能无法识别触发器。
  当智能体犯错时，你必须进行纠正，将纠正添加到 “获取” 部分。这是反复提升技能最直接的方法之一 (参见 “通过实际执行进行精炼”)。
  ·
  输出格式的模板
  当你需要 Agent 以特定格式生成输出时，提供一个模板。这比用散文形式描述格式更可靠，因为 Agent 的模式与具体结构非常匹配。短模板可以在 SKILL.md 中内联使用;对于较长的模板，或者只在特定情况下需要的模板，可以将其存储在资源/并从 SKILL.md 中引用，这样它们只会在需要时加载。

  Report structure

Use this template, adapting sections as needed for the specific analysis:

# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data

## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation

·
多步骤工作流的核对清单
明确的检查清单有助于代理跟踪进度并避免跳过步骤，特别是当步骤具有依赖关系或验证门时。

Form processing workflow

Progress:

• Step 1: Analyze the form (run scripts/analyze_form.py)
• Step 2: Create field mapping (edit fields.json)
• Step 3: Validate mapping (run scripts/validate_fields.py)
• Step 4: Fill the form (run scripts/fill_form.py)
• Step 5: Verify output (run scripts/verify_output.py)
  ·
  验证循环
  指示智能体在继续前验证自己的工作。模式是：完成工作，运行验证器 (脚本、参考核对清单或自我检查)，修复任何问题，然后重复直到验证通过。

  Editing workflow

1. Make your edits

2. Run validation: python scripts/validate.py output/

3. If validation fails:

   • Review the error message
   • Fix the issues
   • Run validation again

4. Only proceed when validation passes
   参考文档也可以作为 “验证器”——指示代理在最终完成之前根据参考文档检查其工作。
   ·
   计划 - 验证 - 执行
   对于批处理或破坏性操作，让代理创建一个结构化格式的中间计划，根据真实信息源验证它，然后才执行。

   PDF form filling

5. Extract form fields: python scripts/analyze_form.py input.pdf → form_fields.json
   (lists every field name, type, and whether it’s required)

6. Create field_values.json mapping each field name to its intended value

7. Validate: python scripts/validate_fields.py form_fields.json field_values.json
   (checks that every field name exists in the form, types are compatible, and
   required fields aren’t missing)

8. If validation fails, revise field_values.json and re-validate

9. Fill the form: 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” 这样的错误会给代理提供足够的信息来自我纠正。
   ·
   捆绑可重用脚本
   当迭代一项技能时，比较智能体在不同测试用例中的执行轨迹。如果你注意到智能体在每次运行时都独立地重新创建相同的逻辑——构建图表、解析特定格式、验证输出——这是一个信号，表示要编写一次测试脚本并将其捆绑到脚本/中。
   有关脚本设计和捆绑的更多信息，请参阅在技能中使用脚本。
   ·
   后续步骤
   一旦你掌握了一项工作技能，有两个指南可以帮助你进一步完善它：
   评估技能输出质量——建立测试案例、评分结果，并进行系统迭代。
   优化技能描述——测试并改进你的技能描述栏，使其在正确的提示下触发。