这是Bubble2026年的第41篇更新。

我感觉今年以来最火的东西非Skills莫属了。

无论是OpenClaw、Claude Code再到最近热度很高的Hermes Agent 都离不开Skills。

所以比起追逐一个又一个热点，我觉得不如先来看看如何写好Skills。

最近看到Google DeepMind 研究员 Philipp Schmid 总结了 8 个他在大量实践中积累的写Skills技巧，还蛮有用的，结合我自己这段时间的使用经验，翻译转述给大家。 

一个 Skill 本质上就是一个文件夹，核心是一个SKILL.md文件，其他的都是可选的：

my-skill/ 

├── SKILL.md    ← 唯一必须的文件 

├── scripts/    ← 可复用的脚本代码 

├── references/ ← Agent 按需读取的参考文档 

└── assets/     ← 模板、图片等输出用的资源

一个 Skill 由3 层组成：

•名称和描述（Frontmatter）：每次都会加载到 Prompt 中，告诉 Agent什么时候该用这个 Skill

•SKILL.md 正文：Skill 被触发后才加载的 Markdown 指令，告诉 Agent怎么干活

•附属文件（可选）：scripts/、references/、assets/ 文件夹里的辅助资源

这里还有一个很重要的认知，Skill 其实分两种：

•能力型 Skills：弥补模型本身做不好的事情。比如填 PDF 表单。随着模型越来越强，这类 Skill 有可能会被淘汰，定期跑Benchmark就知道它还需不需要了。

•偏好型 Skills：把你自己的工作流固化下来，比如你团队的代码审查流程。这类 Skill 不会过时，但需要跟你实际流程保持同步。

SKILL.md 里的 description 就是触发器。

如果把描述写得太模糊，Agent 不知道啥时候该激活这个 Skill。写得太宽泛，每次请求都会触发，直接干扰正常工作流程。

你需要同时说清楚两件事：

这个 Skill 干什么+什么时候该用它。

举个例子：

太模糊的写法："帮助处理文档"

具体且可执行的写法："创建、编辑和分析 .docx 文件，适用于修订追踪、批注、格式化或文本提取"

太模糊的写法："API 助手"

具体且可执行写法："当需要编写调用 Gemini API 的代码时使用，支持文本生成、多轮对话、图像生成或流式传输"

Philipp 说他见过仅仅改了 description，效果就提升了 50%的案例。

Agent 很聪明，你要做的是告诉它那些它还不知道的事情。

研究表明，过长的、塞了太多上下文的指令反而会让性能下降。

几个核心原则：

用指令式语言，别用描述式语言

• 不好的例子："Interactions API 是推荐的方式。"（这是知识，Agent 不会基于它行动）

• 好的示例："始终使用 interactions.create()"（这是指令，Agent 会照做）

用示例开头，别用大段解释

•5 行代码示例 > 5 段文字解释

解释为什么

• 当一条规则很重要时，说清楚原因："使用 model X，model Y 已弃用并且会返回错误"。这样 Agent 能举一反三，而不是死记硬背。

别过拟合

•不要为了让你手头那 3 个测试 Prompt 通过就反复微调。好的 Skill 应该在上百万次调用中都稳定有效。

别把所有东西都塞进一个文件里。

Agent 是分层加载信息的：

1.始终加载：SKILL.md 的 Frontmatter（名称 + 描述）

2.触发后加载：SKILL.md 的正文（建议控制在 500 行以内）

3.按需加载：reference 文件、脚本、资源

如果你的 Skill 涵盖多个主题，拆分成多个 reference 文件。Agent 只会读它需要的那个，这样能把上下文窗口留给真正重要的任务。

写 Skill 最常见的错误，就是把它变成一份逐步执行的操作手册。

"第一步：读取文件。第二步：解析 JSON。第三步：提取字段…"

当你把每一步都写死了，Agent 就丧失了自适应、纠错和找到更优方案的能力。

描述你想要什么结果，而不是通往结果的路径。

告诉 Agent 目标：

• 不要说："步骤1：读取配置文件。步骤2：找到数据库URL。步骤3：更新端口号。步骤4：写回文件。"

• 要说："将配置文件中的数据库端口更新为用户指定的值。"

给约束，不给流程：

• 不要说："步骤1：创建分支。步骤2：修改代码。步骤3：跑测试。步骤4：提PR。"

• 要说："提 PR 之前必须跑通测试。永远不要直接 push 到 main。"

思考一下你的 Skills不应该在什么时候触发。

一个 description 写成"处理任何编程任务"的 Skill，会在每次请求时都抢着出来干活，直接打乱你的工作流。

正确做法是："处理 PDF 文件时使用。不要用于普通文档编辑、电子表格或纯文本文件。"

你需要同时测试应该触发的场景和不应该触发的场景。

不做反面测试，你的 Skill 只会朝一个方向优化，最终变成一个误触狂魔。

别写完就直接发出去。Agent 的输出是非确定性的，每次跑出来的结果可能都不一样，所以测一次是远远不够的。

具体怎么做：

1.手动跑几次，用不同的 Prompt 试。看它在哪里出错：是否假设某个依赖存在？是否跳过了步骤？

2.定义清楚成功的标准是什么样，并且要可衡量。输出能编译吗？用了对的 API 吗？按步骤走了吗？评估结果，不是评估路径。

3.准备 10-20 个测试 Prompt。混合三类：Skill 应该处理的、Skill 应该忽略的、以及刁钻的边界情况。每个 Prompt 都应该有独立的成功标准。

4.跑多次。每个 Prompt 跑 3-5 次，看分布结果，而不是单次通过/失败。

5.隔离每次测试。用干净的环境跑每一次测试，上下文残留会掩盖真实的问题。

6.出了问题先改 description。大部分问题出在触发条件上，而不是指令本身。

把 Skills 关掉，重新让Agent跑一遍你的Benchmark。

如果不用这个 Skills 也能通过，那就说明模型已经吸收了这个 Skills 的价值，它就不再需要了。大胆扔掉它。

这一点对能力型 Skills尤其重要。模型在不断进步，差距在不断缩小。你去年写的那个 Skills，说不定今天已经是多余的了。

这 8 个技巧看起来都不复杂，但如果你认真对照自己写过的 Skills 复盘一遍，大概率会发现好几个踩过的坑。

我自己的总结就是：写 Skills 跟之前写 Prompt 其实是一脉相承的。

最核心永远是那几件事：

说清楚意图、给足够的上下文、别过度约束、持续迭代测试。

以及，追逐下一个热点Agent，不如先琢磨一下如何写好自己手里的Skills。

欢迎评论区交流你写好Skills的小技巧～