原文链接：https://www.philschmid.de/agent-skills-tips

编写智能体技能的 8 个技巧

技能（Skills）已成为智能体最常用的扩展点之一——灵活、易于创建，也易于分发。我在实际工作中大量使用了各类技能，以下是我从实践中总结出来的一些心得。

1. 先搞清楚"技能"是什么

技能本质上是一个包含 SKILL.md 文件及可选辅助文件的文件夹：

my-skill/
├── SKILL.md          ← 唯一必需的文件
├── scripts/          ← 智能体可调用的可复用脚本
├── references/       ← 智能体按需读取的参考文档
└── assets/           ← 输出中使用的模板、图片或文件

一个技能由三个层面构成：

• Frontmatter（名称与描述）：每次都会注入提示词，告诉智能体何时该用这个技能。
• SKILL.md 正文：Frontmatter 之后的 Markdown 指令，告诉智能体具体怎么做。
• 资产文件（可选）：scripts/、references/ 和 assets/ 文件夹。

技能通常分为两类：

• 能力型技能：弥补基础模型难以稳定完成的任务（例如填写 PDF 表单）。随着模型能力提升，这类技能可能会逐渐过时——评估结果会告诉你何时该把它们退休。
• 偏好型技能：封装了你特定的工作流程（例如团队的代码审查步骤）。这类技能更具持久性，但需要随着实际流程的变化持续维护。

2. 打磨描述文案

SKILL.md 中的描述就是触发器。描述模糊，智能体就不知道何时激活技能；描述太宽泛，技能会在每次请求时都被激活。

描述中要同时说清楚"做什么"和"什么时候做"。 技能正文只有在被触发后才会加载——仅凭这一点，我曾通过优化描述将效果提升了 50%。

3. 写指令，不要写文章

智能体本身就很聪明，你的职责是告诉它那些它尚不了解的事情。研究表明，过长、铺垫过多的"全面指令"反而会拉低性能。

• 用示例说话：5 行代码片段胜过 5 段解释。
• 说明原因：当某条规则很关键时，解释背后的逻辑。比如"请使用模型 X，模型 Y 已弃用且会报错"——这能帮助智能体举一反三，而不只是死记规则。
• 警惕过拟合：不要只为了通过你手头那几个测试 prompt 而"微调"技能。要写出在数百万次调用中都能稳定生效的技能。

4. 保持精简

不要把所有东西都堆进一个文件。智能体是分层加载信息的：

1. 始终加载：SKILL.md 的 Frontmatter，即名称 + 描述。
2. 触发时加载：SKILL.md 正文（建议控制在 500 行以内）。
3. 按需加载：参考文件、脚本、资产。

如果技能涉及多个主题（例如同时覆盖 AWS 与 GCP 部署），请将它们拆分成独立的参考文件。智能体只会读取当前任务所需的那一个，从而为实际执行节省宝贵的上下文空间。

小贴士：如果参考文件超过 500 行，建议在顶部加一份带行号提示的目录，方便智能体快速定位所需内容。

5. 给智能体留够自由度

编写技能时一个常见的错误，是把它写成一份手把手的操作流程："第一步：读取文件。第二步：解析 JSON。第三步：提取字段……"

当你规定了每一个步骤，就剥夺了智能体自我调整、从错误中恢复、或找到更优路径的能力。描述你想要的结果，而不是达到结果的路径。

告诉智能体目标是什么：

• ❌ "第一步：读取配置文件。第二步：找到数据库 URL。第三步：更新端口号。第四步：写回文件。"
• ✅ "将配置文件中的数据库端口更新为用户指定的值。"

提供约束，而非程序：

• ❌ "第一步：创建分支。第二步：提交更改。第三步：运行测试。第四步：发起 PR。"
• ✅ "发起 PR 前必须先跑通测试。严禁直接推送到主分支。"

如果步骤顺序至关重要、容不得半点差错，那应该写成脚本，而不是技能。

6. 不要忽视反面案例

想清楚技能不该触发的场景。像"适用于任何编码任务"这样的描述，会把每一个请求都劫持过来。

更好的写法是：

"用于处理 PDF 文件时。不适用于常规文档编辑、电子表格或纯文本文件。"

"应该触发"和"不应该触发"的用例都要测试。 否则，你只是在单方面优化，而非真正验证技能的边界。

7. 发布前先测试

不要在没有评估的情况下直接上线。每次运行的表现可能各不相同，只检查一次远远不够。

1. 多次手动运行：换用不同的提示词，观察哪里容易出问题——是否假设了某个前置依赖？是否跳过了某个步骤？
2. 量化"成功"的标准：输出能否编译？是否调用了正确的 API？是否遵循了预期流程？评估结果，而不是评估过程路径。
3. 准备 10–20 个测试提示词：混合"应该处理的"、"应该忽略的"以及"边缘情况"——每个提示词都要有明确的成功标准。
4. 多次重复运行：智能体的输出具有随机性。每个提示词至少跑 3–5 次，看整体分布，而不是只看一次的通过与否。
5. 隔离每次运行环境：为每个测试用例使用干净的上下文。跨轮次的上下文污染会掩盖真正的失败。
6. 优先排查描述问题：大多数问题出在触发器上，而不是指令本身。

8. 知道何时"退休"一个技能

不妨试着在不加载该技能的情况下跑一遍评估。如果结果照样通过，说明模型本身已经具备了这项能力，技能就没有继续存在的必要了——可以安心将它下线。

这一点对能力型技能尤为重要：随着模型持续进化，能力缺口会逐渐收窄，定期回顾、主动淘汰过时技能，是保持技能库健康的关键。

有关实用的分步评估工作流，请参阅： 智能体技能评估与测试实用指南