掌握Agent技能编写的8个关键技巧
Skills 已成为 AI Agent 最常用的扩展机制。它们灵活、易创建、便于分发，但这种灵活性也让人难以把握最佳实践。本文分享了8个经过验证的技巧，帮助您编写出高质量的 Agent 技能。
目录
1. 理解技能的本质
技能是一个包含 SKILL.md 文件的文件夹，可选择性地添加辅助文件：
my-skill/
├── SKILL.md ← 唯一必需的文件
├── scripts/ ← Agent 可执行的可复用代码
├── references/ ← Agent 按需读取的文档
└── assets/ ← 模板、图片或输出文件
技能由三个层次构成：
- 名称和描述前言：进入每个提示词，告诉 Agent 何时使用该技能
- SKILL.md 主体：Markdown 指令，告诉 Agent 如何执行任务
- 资源文件（可选）：scripts/、references/ 和 assets/ 文件夹
技能通常分为两类：
- 能力技能：帮助 Agent 完成基础模型无法稳定完成的任务（如 PDF 表单填写）。随着模型改进，这些技能可能变得不再必要，通过评估可以判断。
- 偏好技能：编码您的特定工作流程（如团队的代码审查步骤）。这些技能持久有效，但需要与实际流程保持同步。
2. 精准定义触发条件
SKILL.md 中的 description 是触发机制。描述过于模糊，Agent 不知道何时激活技能；描述过于宽泛，技能会在每个请求上触发。要具体说明技能的功能和使用时机。技能主体只在技能触发后才加载。
| ❌ 过于模糊 | ✅ 具体可行 |
|---|---|
| "处理文档" | "创建、编辑和分析 .docx 文件，用于跟踪更改、批注、格式化或文本提取" |
| "API 助手" | "在编写调用 Gemini API 进行文本生成、多轮对话、图像生成或流式处理的代码时使用" |
仅通过改进描述，我观察到50%的性能提升。
3. 编写指令而非文章
Agent 很聪明。您的任务是告诉它它不知道的信息。研究表明，过长、过于全面且包含过多上下文的内容实际上会损害性能。
- 使用祈使句："始终使用
interactions.create()"，而不是"Interactions API 是推荐的方法"。前者是指令，后者是 Agent 不会采取行动的琐碎信息。 - 以示例开头：5行代码片段胜过5段解释。
- 解释原因：当规则很重要时，说明原因。"使用模型X，模型Y已弃用并将返回错误"有助于 Agent 泛化到特定测试用例之外，而不仅仅是记忆。
- 避免过拟合：避免只通过三个测试提示词的"微调"更改。编写能在数百万次调用中工作的技能。
4. 保持内容精简
不要将所有内容都放在一个文件中。Agent 分层加载信息：
如果您的技能涵盖多个主题（如 AWS 与 GCP 部署），将它们拆分为单独的参考文件。Agent 只读取它需要的文件，这为实际任务节省了上下文。
提示：如果参考文件超过500行，在顶部添加带有"行提示"的目录，以便 Agent 快速找到所需内容。
5. 设定合适的自由度
创建技能时的一个常见错误是将技能变成逐步工作流："第1步：读取文件。第2步：解析 JSON。第3步：提取字段..."。当您规定每个步骤时，您剥夺了它们适应、从错误中恢复或找到更好方法的能力。描述您想要什么，而不是达到目标的路径。
告诉 Agent 要实现什么：
- ❌ "第1步：读取配置文件。第2步：找到数据库 URL。第3步：更新端口号。第4步：写回文件。"
- ✅ "将配置文件中的数据库端口更新为用户指定的值。"
提供约束而非程序：
- ❌ "第1步：创建分支。第2步：进行更改。第3步：运行测试。第4步：打开 PR。"
- ✅ "在打开 PR 之前始终运行测试。永远不要直接推送到 main。"
如果精确步骤很重要，编写脚本。 如果任务很脆弱，第3步在第2步之前执行会破坏一切，这不是技能问题，而是脚本问题。
6. 考虑负面案例
考虑技能不应触发的情况。像"用于任何编码任务"这样的描述会劫持每个请求。
"在处理 PDF 文件时使用。不要用于一般文档编辑、电子表格或纯文本文件。"
测试"应该触发"和"不应该触发"的案例至关重要。否则，您会将技能优化到一个方向。
7. 发布前充分测试
不要未经评估就发布技能。每次运行可能表现不同，所以单次检查是不够的。
- 手动运行几次：使用不同的提示词进行测试。观察哪里会出错。是否假设依赖项存在？是否跳过步骤？
- 明确定义成功标准：输出是否可编译？是否使用了正确的 API？是否遵循了步骤？评估结果，而不是路径。
- 尝试10-20个测试提示词：混合技能应该处理的提示词、应该忽略的提示词以及棘手的边缘案例。每个提示词都应该有自己的成功标准。
- 运行多次试验：Agent 输出是非确定性的。每个提示词运行3-5次试验，观察分布而不是单次通过/失败。
- 隔离每次运行：为每次测试使用干净的环境。运行之间的上下文泄漏会掩盖真正的失败。
- 优先修复描述：大多数问题在于触发机制，而不是指令。
8. 适时退役技能
在不使用技能的情况下运行评估。如果通过，说明模型已经吸收了技能的价值，技能不再必要。退役它。这尤其适用于能力技能，随着模型改进，差距会缩小。
有关实用的逐步评估工作流，请参阅评估和测试 Agent 技能的实用指南。
常见问题解答
何时应该创建能力技能而非偏好技能？
当基础模型无法稳定完成某项任务时创建能力技能。当您需要编码特定团队工作流程时创建偏好技能。能力技能可能随着模型改进而过时，偏好技能则更持久。
如何判断技能描述是否足够具体？
如果技能在不应该触发时触发，或者在应该触发时未触发，说明描述需要改进。具体的描述应同时包含"做什么"和"何时用"。
技能主体应该保持在多少行以内？
建议保持在500行以内。如果内容更长，应拆分为单独的参考文件，让 Agent 按需加载。
为什么应该避免逐步指令？
逐步指令限制了 Agent 的适应能力。描述目标和约束比规定具体路径更有效，除非任务非常脆弱需要精确步骤。
如何有效测试技能？
使用10-20个测试提示词，每个运行3-5次试验。隔离每次运行，明确定义成功标准，并优先修复触发机制问题。