Paperclip 的 skill 怎么写：SKILL.md 格式、信任等级与技能库的完整流程

2026-08-17

在 Paperclip 里养一批 agent，写到第三周你多半会遇到同一件事：同样的做法要在任务描述里反复交代。issue 怎么分诊、验收要跑哪几步、发版公告用什么格式——这些东西写进每一条任务是浪费，写进 agent 的基础提示词又会让提示词无限膨胀。

skill 就是官方给这件事的答案。按文档的定义，skill 是可复用的指令，agent 在自己的心跳（heartbeat）过程中可以调用；形式上它就是一个 markdown 文件，教 agent 怎么完成某一类具体工作。

但真正写起来，大多数人卡的不是 markdown 本身，而是两件事：一是写完了 agent 好像根本不用它；二是不知道写完之后这个文件要怎么进入系统、能不能分享给别人、别人导入会不会有安全问题。这两件事在官方文档里分别对应「Writing a Skill」和「The Skills Store」两篇，下面按这两篇的原文口径拆一遍。

一个 skill 在磁盘上长什么样

skill 是一个目录，不是一个孤立的文件。目录里必须有 SKILL.md，可选一个 references/ 放补充材料：

skills/
└── my-skill/
    ├── SKILL.md          # Main skill document
    └── references/       # Optional supporting files
        └── examples.md

SKILL.md 本身是带 YAML frontmatter 的 markdown：

---
name: my-skill
description: >
  Short description of what this skill does and when to use it.
  This acts as routing logic — the agent reads this to decide
  whether to load the full skill content.
---

# My Skill

Detailed instructions for the agent...

frontmatter 只有两个字段，文档写得很直白：

name——skill 的唯一标识，用 kebab-case；
description——告诉 agent 什么时候该用这个 skill 的路由描述。文档原话是「把它当决策逻辑写，不要写成营销文案」。

字段少到这个程度，说明设计上把重量全压在了 description 上。

为什么 description 决定这个 skill 有没有人用

官方给了运行时的四步流程，看完就明白 description 的地位：

agent 在自己的上下文里看到 skill 的元信息（name + description）；
agent 判断这个 skill 跟当前任务相不相关；
相关的话，才加载完整的 SKILL.md 内容；
按 skill 里的指令执行。

文档给这套设计的理由是：保持基础提示词很小，完整的 skill 内容只在需要时按需加载。

这条链路解释了一个常见困惑——「我 skill 写得很详细，为什么 agent 不用」。因为 agent 在第 2 步做判断时，看到的只有那一行 description，正文写得再好它都还没读到。技能库那篇文档里又重复强调了一遍同样的道理：agent 的 harness 加载的是 frontmatter 的 name + description 作为路由逻辑，agent 读这些一行描述来决定 skill 是否相关，之后才加载正文；所以 description 应该写成「这个 skill 做什么、什么时候用它」，因为它就是 agent 检索的那个索引。

顺带说一句，skill 是挂在心跳流程里被调用的，所以 agent 本身的驱动方式也值得一起看，参见 Paperclip 里 agent 是怎么被驱动的。

官方列的五条写法建议

文档的 Best Practices 一共五条，我按原意整理成表，并补上它各自对应的失败场景：

官方建议	原文要点	不这么做会怎样
description 写成路由逻辑	包含「use when」和「don’t use when」	agent 判断不了相关性，skill 沉底
具体、可执行	agent 应当能无歧义地照做	指令留白，执行结果随机
带代码示例	具体的 API 调用和命令示例比散文更可靠	agent 得自己猜调用形式
保持聚焦	一个 skill 一件事，别把无关流程捏一起	路由描述说不清，命中率下降
克制引用文件	补充细节放 `references/`，别把主文件撑爆	每次加载都拖着大段无关内容

其中「don’t use when」这一条容易被跳过。它和第四条是一体的：skill 越聚焦，越写得出干净的排除条件。

写完之后：skill 怎么进入你的公司库

写好 SKILL.md 只是第一步。Paperclip 把「skill 从哪来、怎么进来」单独做成了 Skills Store，文档明确区分了两层：

层	是什么	存在哪
目录（catalog）	随 Paperclip 一起发布的、只读的精选技能集	`@paperclipai/skills-catalog` 包
公司库	你这家公司真正装上、agent 能跑的技能	`company_skills` 数据表

文档用了个比方：catalog 是货架，公司库是你结账后的购物车。从 catalog 装一个 skill，是把文件复制进公司库，之后你可以独立编辑、版本化、fork、分享，不影响原件。

catalog 里的技能分两类：bundled 是第一方技能（文档举例 issue-triage、task-planning、qa-acceptance、wireframe、github-pr-workflow、doc-maintenance），占用保留的 paperclipai/paperclip/... 键命名空间；optional 是可选装的精选技能（举例 agent-browser、design-critique、release-announcement、last30days、ramp）。

把 skill 弄进公司库有四条路，各自对应一个接口：

路径	做什么	API
从 catalog 安装	复制 catalog 文件并盖上来源元信息（catalog key、内容哈希、包版本）	`POST /companies/:companyId/skills/install-catalog`
外部导入	粘贴 GitHub 仓库/子目录 URL、`owner/repo` 短引用、注册表链接或裸 markdown URL	`POST /companies/:companyId/skills/import`
本地新建	直接在公司库里写，存为 `local_path` 托管技能	`POST /companies/:companyId/skills`
扫描项目工作区	遍历工作区，找出 `skills/`、`.claude/skills/`、`.agents/skills/` 等约定目录下的 `SKILL.md`	`POST /companies/:companyId/skills/scan-projects`

两个细节值得记：重复安装同一个 catalog 技能是就地更新，不会产生重复条目；一个仓库里可以放很多 skill，导入器会发现路径下的每一个 SKILL.md，也可以用 --skill 过滤到单个 slug。

信任等级：你的 skill 里有没有脚本，决定它能不能被导入

这是我认为整套机制里设计得最克制的一块。因为 skill 目录可以装的不止是文字，Paperclip 按内容给每个 skill 定信任等级，而且这个等级是从文件推导出来的，不是作者自己声明的：

信任等级	内容	说明
`markdown_only`	只有 `.md` 文件	最安全，纯指令
`assets`	markdown 加图片/PDF 等静态文件	没有可执行代码
`scripts_executables`	含任何脚本（`.sh`、`.js`、`.py`、`.ts` 等）	审查最严

规则是硬的：带可执行脚本的 skill 不能从外部来源导入，只有第一方 bundled catalog 技能才允许携带脚本。外部导入（GitHub、注册表、裸 URL）要同时满足两条——必须是 markdown_only 或 assets；Git 来源必须解析到一个钉死的 40 位 commit SHA 之后才能导入，这样一个会移动的分支就没法悄悄改掉你 agent 实际在跑的东西。

这套「按内容定级、按等级卡权限」的思路，跟 Paperclip 对连接器和低信任场景的处理是一脉相承的，可以对照低信任预设（low-trust presets）是什么一起看。

文档还写了一种叫「薄壳」的模式：某些可选技能故意不把第三方的操作手册抄进来，ramp 就是范例——Paperclip 只提供稳定的治理外壳、来源白名单和审批闸口，让 agent 在任务开始时去拉取对方当前发布的说明。文档同时给了很重的限定条件：只有当外部提供方的流程变动频繁到「抄一份快照必然过时」时才用这个模式；涉及金融、法律、账户控制的领域，外壳必须在花钱、注册主体、账户授权、发卡、数据共享等不可逆动作之前要求 Paperclip 审批；如果对方站点把官方手册和社区手册混在一起，外壳必须在来源不明时失败关闭。

装上之后：版本、漂移、审计、fork

Store 把每个已安装的 skill 当成一个小产品来管，这几组能力对应的是「用久了会出什么问题」：

版本：保存新版本会快照完整的文件清单（含内容）并递增修订号，可以查历史、可以回滚（GET/POST /companies/:companyId/skills/:skillId/versions）。
更新与漂移：GET …/update-status 会拿你手上这份和上游最新版本比，告诉你有没有更新、你自己有没有本地改动（drift）、以及有没有该阻止自动更新的原因。装更新用 POST …/install-update（加 force 可以盖掉本地改动），想丢弃本地改动回到原始状态用 POST …/reset。
审计：POST …/audit 比对已安装内容的哈希和记录的来源哈希，标记篡改或意外漂移，返回一个结论和一组代码，Store 把它显示为健康信号。
fork：把一个 skill 复制成独立的新条目（可以换名字、slug 和分享范围），fork 会记录来源，原技能的 forkCount 递增——想改造 catalog 或社区技能又不想失去追溯上游的能力时用它。

另外，skill 在 Store 里是社交对象：成员可以 star（按人切换，驱动 starCount），也可以留带层级的评论。可见范围由 sharing scope 控制，三档分别是 private（只有作者/所有者）、company（公司所有人）、public_link（拿到生成的公开分享令牌的任何人），创建、更新、fork 时都能设，发现页也能按它筛。

所有会改数据的接口都要求「管理公司技能」的权限，并且会记进公司的活动日志。

最后一公里：skill 怎么真的到 agent 手上

安装了不等于 agent 在跑。文档把这一步说得很清楚：运行时，公司已安装的技能会被物化成 agent 工作区里的 SKILL.md 目录，然后 agent 的 harness 读取每个技能的 frontmatter 做路由。

而具体由谁来物化，是适配器的职责。文档原文：适配器负责让技能对自己的 agent 运行时可被发现——claude_local 适配器用一个带符号链接的临时目录加 --add-dir，codex_local 适配器用全局技能目录。所以你换执行后端，skill 的注入方式也跟着换，这块可以参考五类适配器分别怎么接。

还有一个容易忽略的开关：技能同步进 agent 工作区受每个实例的偏好设置管辖，运维方可以控制公司库要不要、以及怎么下推给运行中的 agent。也就是说「我在库里装了但 agent 没有」，先去看这个偏好，而不是怀疑 skill 写错了。

如果你要往 bundled catalog 里加技能，路径是：在 catalog/bundled/** 或 catalog/optional/** 下建目录放 SKILL.md，然后跑包里的 build:manifest 和 validate 脚本重新生成并校验清单。清单本身由 scripts/build-catalog-manifest.ts 编译成 generated/catalog.json，scripts/validate-catalog.ts 负责校验 frontmatter、键和信任分类。

什么时候不该写 skill，以及文档没回答的问题

按官方口径反推，有几种情况写 skill 是白费力气：

一是只用一次的流程。skill 的价值在复用和按需加载，一次性的事直接写进任务描述更省事——任务本身的流转机制是另一套东西。

二是说不清「什么时候用」的流程。既然路由完全靠 description，一个你自己都概括不出触发条件的 skill，agent 更判断不了。

三是想靠 skill 分发脚本给外部团队。信任等级那条规则是死的：带脚本的技能不能从外部来源导入。你的脚本要跨公司复用，得走别的路子——插件是另一条独立的扩展线，规范见 Paperclip 插件规范与开发。

还有几件文档没写、我也不打算替它猜的事：单个 SKILL.md 的体积上限是多少、一个公司库能装多少技能而不影响路由准确率、references/ 里的文件是否随正文一起加载还是二次按需读取——这些官方文档未说明。真要摸底，只能自己在测试公司里装几个技能观察，别照着别人的经验数字当结论。

延伸阅读

从头读起：Paperclip 是什么：一个自己不跑 Agent 的控制平面，怎么管住一整家 AI 公司
本专题共 40 篇，完整分组目录见专题页
Paperclip 插件规范怎么读：哪些能力现在能用，哪些还只是设计稿
Paperclip API 总览：base URL、三种令牌与七个错误码分别代表什么

本文依据 Paperclip 官方仓库（github.com/paperclipai/paperclip，MIT 协议）的 docs/ 用户文档与 doc/ 下的规范、运维与连接器手册整理，核对日 2026-08-17。 我们没有部署或运行过 Paperclip，因此不涉及界面外观与操作手感；部分规范文档描述的是目标架构而非当前实现，文中已就地标注，不构成对实际行为的保证。请以仓库最新内容为准。