Agent Skills

渐进式披露

三层，与规范描述的三层一致：

• 目录。每一轮，智能体的提示里只带一份看起来相关的技能菜单：标题、一行描述、slug。永远不含正文。默认每轮三个，最多六个。
• 激活。智能体用 slug 调用 load_playbook 工具来读取完整步骤。slug 参数按轮绑定为一个枚举，里面正好是该轮菜单中的 slug：编造的名字会在分发之前被拒绝，而不是白白消耗智能体的一次往返。没有菜单时，这个工具根本不会注册。
• 资源。尚未支持。这里一个技能就是一个 SKILL.md；随附的 scripts/、references/ 和 assets/ 会被解析后忽略，而不是只支持一半。

技能一旦加载就会一直在。智能体的运行会压缩较早的工具结果以控制成本，而已激活的技能不受影响：它们的指令会原样保留到运行结束，无论运行多长。一个在任务中途悄悄消失的技能，比从未加载更糟。

哪些技能能进菜单

两轮筛选。触发词以不区分大小写的子串方式匹配当前这一轮；随后一轮语义匹配再做补充，依据是每个技能的标题、描述、触发词和正文开头的嵌入向量，只有超过一个校准过的相似度下限才会被接纳。没有触发词的技能始终启用、始终出现在菜单里。激活哪一个由模型决定：这里没有任何东西会把技能强加给它。

把技能放进来

• 技能库。经过筛选的技能包，一键安装到某个智能体上。这是大多数人使用的发现入口。
• 自己写一个。在智能体的「剧本」标签页里填标题、描述、触发词和步骤。
• API。POST /api/agents/:id/playbooks/import 接受 { files: [{ name, content }] }，每个文件独立导入：一个坏文件只会让它自己失败，其余照常入库。任何内容写入之前，每个文件都会先经过安全扫描；导入也绝不覆盖已有技能，slug 冲突会作为「已跳过」返回。
• 从文档里编出一个。POST /api/agents/:id/playbooks/generate 接受 { artifactId }（工作区里已有的文档）或 { content, sourceName }，把文档所教的东西写成一套流程：何时适用、步骤、判断规则、术语。这不是上传流水线——那条路把文档变成可检索的段落；这条路把它变成智能体去做的事。流程是重新写的，绝不摘录：来源可能是别人享有版权的手册，照抄它的技能就是它的副本。长文档只从头读到上限为止，响应会说明在哪里截断。结果处于未启用状态：那些话不是任何人写的，所以要由人读过草稿再打开，否则它永远不会运行。

界面上没有上传按钮，这是刻意的。一个 SKILL.md 会成为某个手握工作区工具的智能体的长期指令，因此任意上传的文件是提示注入的入口，而不是便利功能。上面那条仅限所有者的 API 路由，就是这个有意为之的例外。

把技能带出去

任何技能都可以导出为一个 zip，里面是 <name>/SKILL.md——规范所描述的目录形态，而不是一个散落的文件。把它解压到 ~/.agents/skills/ 或 .claude/skills/，无需改名即可在那个客户端里加载，skills-ref validate 也能直接通过。想要裸文件的 API 调用方可以请求 text/markdown。

frontmatter 里有 name 和 description。我们自己的扩展——触发词、排序，以及标明文件来源的标记——都放在 metadata 之下，因为规范的参考校验器会拒绝未知的顶层键，而我们导出的文件绝不该是让它失败的那一个。

我们拒绝采纳的字段

• allowed-tools 一律丢弃。规范把它定义为该技能可预先批准使用的工具，而这恰恰是最不该从一个经由 API 或共享技能包送来的文件里接受的东西：那等于让导入的内容自行扩大权限。一个智能体能调用哪些工具，取决于它的角色，绝不取决于它读到的某个文件。
• compatibility 也被丢弃，理由更平淡：它描述的是这个技能当初面向的运行环境，与我们的环境无关。
• 文档化 frontmatter 之外的一切都会被忽略，而不是猜测。解析器只接受规范定义的那个小而固定的形状，不接受任何花哨写法。

限制

每个智能体三十个技能，每个导入文件 64 kB，正文也有上限——装不下这个预算的技能，应该拆成两个。名称只能用小写字母、数字和单个连字符：规范允许更多，但在这里名称同时也是 URL。

相关链接

关于格式，规范是权威。关于智能体在网络上行动所用的 HTTP API，请看API 文档。