技能是文档,不是插件:教一次,下次少说一遍

插件动的是运行时，技能只提供方法。这篇讲三层加载、描述为什么决定它被想起、四节各挡哪类失败，以及写错一条为什么比不写更糟。

下面说的是 Hermes Agent 的技能系统，一个我天天在用的 agent 工具。

第一次问「这件事你们团队平时怎么做」，它得摸索一遍。第二次问，它直接按上次的步骤走。

差别不在模型。在于第一次做完，它把过程写成了一份文档。

插件注册能力，技能提供方法

这两个东西经常被混为一谈。

插件动的是运行时：注册新工具、挂钩子、接平台适配器。装上之后，它真的多了一个能调用的东西。插件也可以顺带打包几个技能，但打包方式不改变技能本身是什么。

技能不动运行时。它是一份文档，被加载时进的是上下文。

准确的分法是：插件给的是「能不能做」，技能给的是「按不按你的做法做」。

有个例外要说清楚：默认情况下技能只是文本；如果显式打开内联执行（skills.inline_shell），文档里的命令片段会在加载时真的被执行。这个开关默认关闭，从社区装的技能不会自动跑。技能目录里的脚本同理——放着不动手，除非说明里让你跑，或者别的工具去调。

三层加载，分的是频率不是价格

技能放在 Hermes 主目录的 skills/ 子目录下，hermes skills list 能看到装了哪些。加载分三层：

• 索引：名字、一句描述、分类。常驻在系统提示里，官方给的量级是三千 token 上下。
• 正文：整份 SKILL.md。判断需要时才读，工具是 skill_view。
• 引用文件：正文指向的 references/ 单篇，问到细节才读。

分层的依据不是「越往下越贵」，而是越往下加载得越少——一个引用文件可能比整份正文小得多。

索引是唯一每轮都占窗口的部分，技能越多这笔开销越大；命中前缀缓存按缓存价，没命中按全价。

描述负责被想起，正文负责被用对

索引里只有三样东西：名字、描述、分类。要不要翻这条技能，靠的是那句描述。

官方在技能写作规范里建议把描述控制在 60 字符以内——超了会被截断，新建时甚至直接报错。所以描述该写触发词，不是写简介。

「处理文档」这种描述等于没有；「用 PIL 画中文卡片图，字体缺失会渲染成方块」才有区分度。

至于什么时候该用、什么时候别用，写在正文的 ## When to Use 里。这一节要加载之后才看得到，它管的是用对，不是被想起。

一句话：描述决定它想不想得起来，正文决定它用得对不对。

四节，各挡一类失败

官方模板常写四节；/learn 的内部规范还会多几节（前置条件、怎么跑、速查），没有内容可以省。

没有「缺一节就校验不过」这回事。缺的不是及格线，是一道保险。

装完为什么不立刻生效

对话中途装一条技能，你会发现它下一步就能按名字调用，但索引列表要等下一次压缩或新会话才重建。

原因是系统提示里的技能索引在会话开始时被冻结，为的是让前缀缓存有效。所以它走另一条路：下一条消息附一句短通知，新增的带描述，删除的只带名字。

斜杠命令是另一套：/技能名 得等 /reload-skills 刷新。

代价：写错、过期、变死板

一、写错比不写更糟。

没写的时候，它可能问你，也可能按通用做法猜一个；写错了，它照着错的做，还挺自信，而且看起来像「我们本来就这么做」。

二、技能会过期。

流程改了，技能没改，它还在按旧步骤走，而且更笃定，因为文档里就是这么写的。过期不报错，只安静地执行上一版。这件事系列后面会单独讲。

三、写得越细，越死板。

例外没写进去，它可能硬套流程，而不是停下来问。好技能里通常有一句：遇到 X 情况，先确认再继续。

这三条都不靠调参数解决，只能靠人定期看。

什么时候值得写

三个条件同时满足：会做第二次、步骤相对稳定、有明确的完成标准。

反过来，一次性的、每次都要临场判断的、靠人拍板的，写成技能只是给自己找麻烦。

还有个信号很准：你已经在第三次解释同一件事了。

知识型材料是另一类：一本书、一堆论文，产出的不是流程，而是一份精简正文加按章节拆的引用文件，问到哪章读哪章。

写的时候还有三件事值得知道：

来源可以不是自己写。 有个 /learn 入口，指着一个目录、一个网页、或者刚才那套操作，它会把材料整理成技能。

重名按优先级取：已信任的项目目录 → 本地 → 自定义 → 外部。跨目录被盖住会记一条 warning；同一目录里两个技能同名会报 ambiguous，得用路径区分。

代理写技能可以设门禁。 打开 skills.write_approval 后，它写的每条技能先落到待审目录，你用 /skills pending 看、/skills approve 批，才真正生效。注意它只管代理自己的写入，不管你手动装的。

技能的价值不是「一次写好」，而是可以慢慢改到贴合自己的流程。

前提是有人改。没人维护的技能，会安静地变成一段过时的说明书。

你手上有没有那种「已经解释过三遍」的事？评论区说说，也许它该变成一条技能。

说明：本系列由 Hermes Agent 参与写作，作者是它的长期使用者；文中机制来自官方文档与日常使用的对照，不是第三方评测，也不构成选型建议。文档核对时间为 2026 年 11 月，路径、优先级与默认值以当前版本为准。