写好 Agent Skills 的八条经验：描述即触发器，指令要短，负向用例不能省

Skills 已经成为智能体最常用的扩展点之一。它们灵活、容易做、分发也简单。

但正是这种灵活，让人很难判断什么是好的、什么真正有效。什么样的技能值得做？写好一个技能的秘诀是什么？什么时候才应该分享给别人？

作者大量使用 Skills，多个技能处于日常活跃状态。以下是他总结的八条经验。

一、先搞清 Skill 是什么

一个 Skill 就是一个文件夹，里面有 SKILL.md 文件和可选的辅助文件：

my-skill/
├── SKILL.md          ← 唯一必需的文件
├── scripts/          ← 智能体可执行的复用代码
├── references/       ← 智能体按需阅读的文档
└── assets/           ← 模板、图片等输出用素材

Skill 由三层构成：

• name 和 description 元信息：进入每一次提示词，告诉智能体何时启用这个技能；
• SKILL.md 正文：元信息下方的 Markdown 指令，告诉智能体怎么做这件事；
• 资产（可选）：scripts/、references/、assets/ 三个文件夹。

技能永远分两类。

能力型技能（capability skills）帮智能体做好基础模型本来做不稳定的事，比如 PDF 表单填写；随着模型进步这类技能可能变得多余，评测会告诉你时机。

偏好型技能（preference skills）固化你的特定工作流，比如团队的代码审查步骤；这类技能更持久，但必须与实际流程保持同步。

二、把 description 写成精确触发器

SKILL.md 里的 description 就是触发机制。写模糊了，智能体不知道何时启用；写太宽泛，每次请求都会误触发。要同时写清”做什么”和”什么时候用”。技能正文只在触发之后才加载。

❌ 太模糊：“帮助处理文档”

✅ 具体可执行：“创建、编辑和分析 .docx 文件，用于修订追踪、批注、格式化或文本提取时使用”；“写调用 Gemini API 做文本生成、多轮对话、图像生成或流式输出的代码时使用”

作者见过只靠改进 description 就带来 50% 性能提升的案例。

三、写指令，不写论文

智能体足够聪明，你的职责是告诉它它还不知道的东西。研究表明，更长、更全面的技能反而伤害性能。

• 用祈使句：“总是使用 interactions.create()“，而不是”The Interactions API 是推荐方案”。前者是指令，后者是智能体不会执行的知识。

• 例子先行：一段五行代码胜过五段解释。

• 解释原因：规则重要时说明为什么。“使用模型 X，模型 Y 已弃用会报错”帮智能体举一反三，而不是死记测试用例。

• 别过拟合：避免只在你那三条测试提示词上生效的”精调”。要写能在上百万次调用中都正常工作的技能。

四、保持精简

别把所有东西塞进一个文件。智能体按层加载信息：

• 始终加载：SKILL.md 的元信息，即 name + description；
• 触发时加载：SKILL.md 正文（控制在 500 行以内）；
• 按需加载：参考文件、脚本、资产。

如果技能覆盖多个主题（比如 AWS 和 GCP 部署），拆成独立的参考文件，智能体只读需要的那份，省下的上下文留给实际任务。

技巧：参考文件超过 500 行时，在文件头加一个带”行号提示”的目录，让智能体快速定位。这个做法在长参考文档里能显著减少无效读取。

五、给正确的自由度

写技能最常见的错误，是把它变成一步步的工作流：“第一步读文件，第二步解析 JSON，第三步提取字段……”当你规定每个步骤，就剥夺了智能体适应变化、从错误中恢复、寻找更优路径的能力。描述你要什么，而不是怎么到达。

告诉智能体要达成什么：

• ❌ “第一步：读配置文件。第二步：找到数据库 URL。第三步：改端口号。第四步：写回文件。”
• ✅ “把配置文件里的数据库端口改为用户指定的值。”

给约束，不给流程：

• ❌ “第一步：建分支。第二步：改代码。第三步：跑测试。第四步：开 PR。”
• ✅ “开 PR 之前必须跑测试。永远不要直接 push 到 main。”

如果步骤顺序真的生死攸关：那说明该写脚本。第 3 步必须在第 2 步之前否则全崩，这不是技能的问题，是脚本的问题。

六、别跳过负向用例

想清楚技能什么时候不该触发。描述写成”任何编程任务都用我”，会劫持每一个请求。

“处理 PDF 文件时使用。不要用于普通文档编辑、表格或纯文本文件。”

“应该触发”和”不该触发”两类用例都要测。不测负向用例，你的优化就只朝一个方向偏。

七、发布前先测试

不做评测就不发布技能。每次运行表现都可能不同，单次检查不够：

• 手动跑几次：用不同提示词，观察哪里出错。它是否假设依赖已存在？是否跳步骤？

• 把”成功”写可测量：输出能编译吗？用对 API 了吗？遵循步骤了吗？给结果打分，不给路径打分。

• 准备 10–20 条测试提示词：混合该处理的、该忽略的和刁钻的边界用例，每条都有独立成功标准。

• 多轮试验：智能体输出不确定。每条提示词跑 3–5 次，看分布而不是单次成败。

• 隔离每次运行：每条用干净环境测试，运行间的上下文泄漏会掩盖真实失败。

• 先修 description：大多数问题出在触发器，不在指令。

八、知道何时退役技能

跑一遍不带技能的评测。如果通过了，说明模型已经内化了技能的价值，技能不再必要，退役它。能力型技能尤其如此——模型在进步，差距在缩小。

怎么把这八条用起来

具体操作路径：先对照第一、二条审计你现有的每个 SKILL.md——description 是否同时写清”做什么”与”何时用”、有没有写负向排除项；再按第四条检查正文行数与分层结构，把超过 500 行的参考文件拆分并加行号目录；然后按第七条给技能建一个 10–20 条提示词的测试集，正负用例各半、每条跑 3–5 次记录通过率分布。改动之后重跑测试集对比前后数据，触发准确率与任务通过率的差值就是你的优化空间。最后每季度跑一次”无技能”对照评测，通过的技能及时退役，保持技能库精简。

原文信息

作者：Philipp Schmid（@_philschmid），AI 工程师

原文地址：