把文档变成 Skill

教程 · 阅读时间 6 分钟

你希望智能体掌握的知识，通常早已写在某个地方——一份入职 PDF、一份 Word 里的风格指南、一份 Markdown 写的故障手册。缺的不是知识，而是：文档是写给从头读到尾的人看的，而 Skill 必须服务于一个在任务中途加载它、并且需要立刻行动的智能体。

Skilnu 可以完成这次转换的第一遍。上传一份文档，你会得到一份 SKILL.md 草稿——核心心智模型、关键定义、可操作的指引，全部重新组织成指令形式。不会发布任何内容。你来阅读、修正不妥之处，满意后再发布，和其他任何 Skill 完全一样。

1. 上传文档

在应用中打开 + New skill，点击「上传 SKILL.md」旁边的 Draft from a document。选好文件后请稍候——这比应用里的其他操作都慢，因为需要读完并重写一整份文档。

支持以下格式：.pdf、.docx、.txt、.md、.markdown、.rst 和 .adoc。

其他格式在上传前就会被拒绝。如果你的格式不在此列，请先导出为 PDF——这条路径的支持相当完善。

2. 提交一个章节，而不是一整座图书馆

提取文本约有 40,000 字符的长度上限，大致相当于一个长章节。超过这个限度，上传会被拒绝，而不是悄悄截断——一项仅根据 300 页书的前 40,000 字符起草、却以「出自该书」的名义交到你手上的 Skill，比报错更糟。

这没有听上去那么受限，因为让 Skill 出色的要素恰恰就是能装得下的要素：一个自洽的主题。「我们的代码审查标准」是一项 Skill；「整本工程手册」则是一整个文件夹的 Skill。如果文档篇幅很长，请按章节拆分、分别起草——你得到的 Skill 会比一次性通读整本所产出的更好。

3. 扫描版 PDF 需要先做 OCR

如果 PDF 实际上只是一页页的照片，就没有可提取的文本，因此返回的会是一条说明信息，而不是一项空 Skill。请先用任意 OCR 工具处理——多数 PDF 应用都内置「识别文本」——再上传可检索的版本。

一个快速判断方法：打开 PDF，试着选中一句话。如果选不中，那就是图片。

4. 认真通读草稿

草稿会出现在撰写表单中，名称和描述取自它自己的 frontmatter。这是一个只读过你文档一遍的模型完成的初稿，请像阅读一位能干同事的初次尝试那样阅读它，而不要当成定稿。

每次都值得检查这三点：

它保留具体内容了吗？ Commands, thresholds, names of internal tools, the actual numbers. These are the most useful part of a skill and the easiest thing to lose when prose gets condensed.

它有没有凭空杜撰？ The draft is told to stay inside what the document supports, but if your document was vague somewhere, check that the draft was vague in the same place rather than confidently filling the gap.

这是指令，还是摘要？ The failure mode to watch for is a draft that describes what the document says instead of telling the agent what to do. If a section reads like a book report, rewrite it as a rule.

5. 发布它

在表单中编辑到满意为止，然后照常发布。从此它就是一项普通 Skill：可以版本化、可被其他 Skill 依赖、可与团队共享，也可加入你的 MCP 库。

从智能体中完成同样的流程

同样的流程通过 MCP 以两个工具的形式提供，因为文件必须在两步之间进入存储。先申请上传地址，发送字节，然后再请求草稿：

get_document_upload_url(filename="handbook.pdf")
  -> { upload_url, document_key }

PUT the file's bytes to upload_url
  (no auth header -- the URL is already signed)

draft_skill_from_document(document_key=...)
  -> { name, description, skill_md }

智能体版本额外接受一个网页表单并未提供的 instructions 参数，在这里确实很有用——「重点放在第 3 章」「写给刚接触这个主题的人」「保留所有代码示例」。它叠加在你长期的编译说明之上，而不是取代它们。

与别处一样，draft_skill_from_document 只负责起草。发布是另一次独立的 publish_skill 调用，因此智能体无法在你尚未看到草稿的情况下，把一份文档直接变成已发布的 Skill。

这需要多少成本

每份草稿会消耗一次每日编译配额，使用你在「设置」中选择的模型——与带编译的发布共用同一份预算。若草稿因文件不受支持或超出长度上限等原因根本没有到达模型，则不会产生任何消耗。

你上传的文档只是临时空间。无论成功与否，草稿一经生成便会被删除；万一有残留，也会在 24 小时内清除。它绝不会成为已发布 Skill 的一部分——只有你审阅过的草稿才会。

它最适合什么

最合适的素材是那些本身就编码了某种工作方式的文档：风格指南、审查清单、故障处理手册，或是你希望智能体去应用而非引用的技术书籍章节。不含流程的参考资料——API 导出、术语表、导成 PDF 的表格——只会产出一项单薄的 Skill，因为源头里本就没有可提取的指引。

上传前的一个好检验：有人读完这份文档后，会因此换一种做法吗？如果会，它就能做成 Skill；如果只是供人查阅的东西，多半不行。