如何将技术书籍转换为 Agent Skill
了解如何把 PDF、EPUB 或内部文档转换为按需加载的 agent skill,涵盖安装方法、令牌预算、无头运行,以及 MIT 许可证和内容授权注意事项。
将技术书籍转换为 agent skill:你会得到什么
要将技术书籍转换为 agent skill,只需让转换器处理 PDF、EPUB、DOCX 导出文件,或你已有的内部文档目录。转换器会生成一个 skill 目录:其中包含一个入口文件,存放指定框架和章节索引;每章对应一个文件,agent 仅在问题需要时读取该文件。书籍全文不会进入上下文窗口,索引会进入。
这项工作与从头编写 agent skill正好相反。后者是将你已经了解的流程编码为 skill。这里的知识已经存在,但无人能够访问:可能是一份 800 页的供应商 PDF,也可能是一份自撰写者离职后就再未打开过的手册。工作重点是压缩和建立索引。如果你不熟悉 skill 一词,请先阅读agent skill 的实际含义。
本文使用的转换器是 book-to-skill,这是一个在本机运行、采用 MIT 许可证的 skill。截至 October 2026,当前标签为 v1.4.0。它生成的结构比工具本身更重要;FAQ 前的最后一节将展示如何手动构建相同的结构。
为什么令牌预算是整体设计的核心
将一本书粘贴到上下文窗口后,每次需要它的对话都要承担完整内容的成本。技能只需为入口文件支付一次成本,之后仅加载问题实际涉及的章节。该项目为它生成的每个文件都规定了预算。
此图表背后的数据
[
{
"label": "SKILL.md entry file",
"tokens": "4,000"
},
{
"label": "One chapter file",
"tokens": "1,000"
},
{
"label": "glossary.md",
"tokens": "1,500"
},
{
"label": "patterns.md",
"tokens": "2,000"
},
{
"label": "cheatsheet.md",
"tokens": "1,000"
}
]入口文件 SKILL.md 限制为 4,000 个令牌,其中包含已命名的框架和章节索引。每个章节文件约为 1,000 个令牌,存放在磁盘上,直到有请求需要它。支持文件的情况类似:glossary.md 为 1,500 个令牌,patterns.md 为 2,000 个令牌,cheatsheet.md 为 1,000 个令牌。
这些预算符合 Claude Code 实际使用上下文的方式。技能的 description 位于技能列表中,以便模型知道该技能存在。调用技能时才会加载正文;加载后,它会在本次会话的剩余时间内持续保留在上下文中,因此入口文件中的每一行都会反复产生成本。支持文件仅在代理读取时加载,这正是按章节拆分文件可以降低成本的原因。
入口文件的令牌数还受到一个更严格的限制。自动压缩长对话时,Claude Code 会在摘要后重新附加每个技能最近一次调用的内容,并保留每个技能的前 5,000 个令牌;所有重新附加的技能共享 25,000 个令牌的总预算。少于 5,000 个令牌的入口文件可以完整保留在压缩后的上下文中。20,000 个令牌的入口文件只会以开头四分之一的内容恢复,而且不会告诉你缺失的是哪三部分。
这就是渐进式披露:一个始终值得其成本的小型索引,以及放在后方、由代理主动打开的大部分材料。Claude Code 如何管理其上下文窗口介绍了其余的计算方式。
在 VPS 上安装转换器,并固定到指定版本
该技能是一个 git 仓库。将其克隆到所用 agent 的 skills 目录中。目录名称会成为斜杠命令,因此克隆路径不能随意选择。
git clone --depth 1 --branch v1.4.0 \
https://github.com/virgiliojr94/book-to-skill.git \
~/.claude/skills/book-to-skill--branch 接受标签,因此该命令只会检出 v1.4.0,不会包含之后的内容。请固定版本,因为技能是一组由 agent 执行的指令;如果这些指令未经审核就发生变化,服务器上运行的内容也会随之变化。GitHub Copilot CLI 读取 ~/.copilot/skills/,Amp 则读取 ~/.agents/skills/。
此外,还有一个单行安装命令 npx skills add virgiliojr94/book-to-skill,它会获取当前版本。可以使用它试用工具。对于需要再次运行的操作,请使用固定版本的克隆副本。
现在确认服务器上有哪些提取器:
cd ~/.claude/skills/book-to-skill
python3 scripts/extract.py --check--check 会报告已安装的提取器,并列出缺少组件的安装方式:对于缺少的 Python 包,它会给出一条合并后的 pip 命令;对于每个缺少的系统工具,它会给出相应提示。该软件包需要 Python 3.9 或更高版本。
克隆后,如果自动补全中没有出现 /book-to-skill,请运行 /reload-skills 或重启 agent。Claude Code 会监视会话启动时已存在的技能目录,因此你在两分钟前创建的 ~/.claude/skills/ 目前还未被监视。
实际需要哪些提取器?
除了 Python 外,不需要其他必需组件,因为每种格式都有标准库回退方案。这些回退方案性能较差。在小型服务器上,安装用不到的提取器只会浪费时间。
pdftotext来自poppler-utils软件包,用于处理以文本为主的 PDF,速度几乎是即时的。使用sudo apt install poppler-utils安装。pypdf和pdfminer.six是 PDF 的 Python 回退方案。docling用于技术类 PDF,这类文件的主要价值在表格和代码清单中。该项目测得的速度约为每页 1.5 秒。ebooklib配合beautifulsoup4才能正确读取 EPUB。没有它们时,该工具会回退到标准库的zipfile读取器。python-docx用于读取 DOCX,striprtf用于读取 RTF。- MOBI 和 AZW 文件必须使用 Calibre 的
ebook-convert。 ocrmypdf会对扫描书籍执行 OCR(光学字符识别)。这类书籍完全没有文本层。
在 Ubuntu 24.04 上,直接运行 pip3 install pypdf 会显示以下错误:
error: externally-managed-environment这不是 pip 损坏。Ubuntu 和 Debian 将系统 Python 标记为由 apt 管理,因此 pip 拒绝向其中写入内容。有两种可行方案。sudo apt install poppler-utils 会安装二进制文件,完全不需要 pip;pdftotext 可以独立处理大多数以正文为主的 PDF。对于 Python 提取器,请创建虚拟环境,并从该环境中启动 agent。这样,技能调用的 python3 就是已安装这些软件包的解释器。
python3 -m venv ~/.venvs/book-to-skill
source ~/.venvs/book-to-skill/bin/activate
pip install "$HOME/.claude/skills/book-to-skill[pdf,epub,docx]"
claude固定版本的 v1.4.0 checkout 声明了额外依赖 pdf、epub、docx、rtf、technical 和 all,其中 technical 是 docling。该项目的安装页面还记录了直接从 GitHub 执行独立命令行安装的方法,即 pip install "book-to-skill[pdf,epub,docx] @ git+https://github.com/virgiliojr94/book-to-skill.git";随后使用 book-to-skill --check 列出已安装的提取器。此方法不需要 PyPI release,但安装的是项目的默认分支,而不是 v1.4.0,并且只提供提取器命令,不提供 /book-to-skill skill。要固定版本,请像上面一样从自己的 checkout 安装。单独使用 pip install book-to-skill 无法工作,因为截至 October 2026,该名称尚未发布到 PyPI。
在书籍确实需要 docling 之前,不要安装它。它会引入机器学习技术栈,因此在小型套餐上安装前,请先检查可用磁盘空间。
对文档目录运行,包括无头模式
该命令接受文件、目录、带引号的 glob,或一次传入多个路径,后面可选技能名称。目录中可以放置任何内容,包括 RFC 集(request for comments,即定义互联网协议的文档)。
/book-to-skill ~/library/platform-docs/ platform-handbook
/book-to-skill "~/books/*.epub" my-library
/book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-research为 glob 加引号,避免 shell 在技能读取前将其展开。将命令指向现有技能目录时,新源文件会合并到该技能中,而不是创建第二个技能。
交互式运行会向您提问。材料是技术内容还是文本密集型内容,这决定提取器。您希望技能帮助完成什么任务,这决定参考深度或学习深度,以及每章的预算。技能应使用什么名称;如果尚未存在 skills 根目录,或存在多个根目录,还会询问应将技能放入哪个根目录。生成前,命令还会显示令牌数和时间估算,并等待您确认。
无头运行时没有人回答这些问题。用户可调用的技能在 claude -p 中仍然有效:将斜杠命令放入提示字符串,Claude Code 会在运行开始前将其展开。因此,请在同一个提示中回答这些问题。
claude -p "/book-to-skill ~/library/platform-docs/ platform-handbook
The sources are technical. Use reference depth. Write the skill to
~/.claude/skills/. Do not publish it to GitHub. Proceed without asking me." \
--allowedTools "Bash,Read,Write,Edit"--allowedTools 会预先批准运行所需的工具,因为没有终端连接时出现权限提示,运行就会一直无法完成。添加 --output-format json 会将 total_cost_usd 写入结果;这是客户端估算值,不是您的计费量。
在任何模型读取源文件前,提取过程会将所有源文件汇总到 /tmp 下的临时工作目录中。运行的最后一步会删除该目录。提取失败的源文件会被跳过,因此批处理仍可继续;这意味着运行可能报告成功,但实际读取的文件少于您提供的数量。将最终报告中的文件清单与目录中的内容进行比较。缺少章节通常意味着缺少源文件。
请为此次运行指定一台您愿意交给代理使用的服务器。在 VPS 上安全运行 Claude Code介绍了权限相关内容。
输出位置,确保您的编码代理可以找到它
生成的 skill 会放在 skills 根目录中。其中有两个目录需要关注。
~/.claude/skills/<skill-name>/是个人目录,在该计算机上的每个项目中都可用。.claude/skills/<skill-name>/位于仓库中,会随仓库一起保存和使用。
这两个目录中都包含 SKILL.md、一个按章节各含一个文件的 chapters/ 目录,以及相关支持文件。目录名就是命令名,因此 ~/.claude/skills/platform-handbook/ 会提供 /platform-handbook;您还可以在其后指定主题或直接输入问题。
请根据许可归属而不是便利性选择根目录。从您购买的书籍生成的 skill 应放在个人目录中。从团队自行编写的文档生成的 skill 应放在仓库中。这样一来,在多个仓库之间共享同一个 skill 就成为下一个需要解决的问题。
每添加一个 skill,都会增加一项成本。每个 skill 的描述都会保留在 skill 列表中,以便模型决定是否使用它;每个条目的合并描述文本会截断为 1,536 个字符,整个列表也有总预算。添加 10 个书籍 skill,就意味着 10 个描述需要共同占用该预算。对于始终按名称调用的 skill,请在生成的 frontmatter 中添加一行:
---
name: platform-handbook
description: Frameworks and chapter index from the internal platform handbook.
disable-model-invocation: true
---使用 disable-model-invocation: true 后,描述会完全排除在上下文之外;当您输入 /platform-handbook 时,该 skill 仍会完整加载。这样会失去自动发现功能,但可以减少上下文窗口中的无关内容。
许可证:MIT 许可证适用于转换器,不适用于书籍
请准确理解这一点,因为这里的问题不是技术问题。
- MIT 许可证适用于转换器的代码及其技能定义。它没有授予您处理所输入文档的任何权利。
- 在您控制的硬件上运行转换器,处理您购买的书籍,属于您根据自己的副本做笔记。
- 发布结果属于分发行为,而工具采用的 MIT 许可证不会授予您分发源自他人书籍的任何内容的权利。
- 输出内容属于衍生作品。框架和章节要点仍然受到源材料的塑造,而衍生作品仍受源材料版权的约束。
- 根据您无权再分发的材料构建的技能,应保留在构建它的机器上。不要放入公共代码仓库,也不要放入共享的团队市场。
- 仅当源材料属于您,或采用允许再分发的开放许可证时,才发布结果:例如由您的团队编写的文档,或其条款允许再分发的标准。
工具的设计正是基于这一点。工具不包含任何书籍内容,提取过程在本地运行。固定的 v1.4.0 只会打印可选的 gh skill publish 行,不会询问可见性,因此决定权完全在您。项目的默认分支后来增加了发布步骤,会单独用一个词询问代码仓库的可见性;只有回复恰好是 public 时,才会创建公共代码仓库;其他任何回复都会创建私有代码仓库。请将该步骤视为许可证决策,因为它本质上就是许可证决策。
内部手册还存在第二个问题。它们包含凭据的频率往往高于人们承认的程度,而转换器会将一份无人打开的 PDF 转换为代理按需读取的文件。在提交这些文件之前,先完整阅读一遍,并参阅避免让 AI 代理接触密钥。
一次转换的成本是多少?
下面的数字来自项目自行发布的测量结果,并非我们的测量结果。
此图表背后的数据
[
{
"label": "Think Python 2",
"cost_usd": 0.88
},
{
"label": "Working Backwards",
"cost_usd": 0.96
},
{
"label": "Pro Git",
"cost_usd": 1.23
},
{
"label": "Moby-Dick",
"cost_usd": 1.42
}
]在项目测量的 4 本书中,每次转换的成本介于 0.88 至 1.42 美元之间,其中 Pro Git 为 1.23。这些数据基于 Claude Sonnet 4.5 测得;令牌数量来自 tiktoken,使用 cl100k_base 计算,并已发布在项目的 docs/performance.md 中,数据截至 October 2026。您的实际成本会随所用模型和价格变化。
项目还记录了:回答技能中的单个问题时,所需令牌数比将整本书粘贴到上下文中少 24 到 51 倍。应将其理解为节省幅度的参考,而不是保证值,因为结果取决于书籍和问题。无论具体数值如何,结构性结论都成立:转换成本只需支付一次,而上下文转储在每次需要这本书的对话中都要重新支付。
为什么不直接粘贴 PDF,或者构建 RAG 索引?
直接粘贴可行。对于针对单份文档提出的单个问题,这是正确的做法。但如果同一本书周二需要使用,周五又需要使用,直接粘贴就不再合适,因为每次都要支付完整的内容长度。
检索,即 RAG(检索增强生成),会在查询时进行搜索,并返回与您的用词匹配的段落。需要精确句子时,这种方式很有效。如果有用内容是分散在整章中的框架,检索就不够理想,因为没有任何单个段落包含完整框架。技能会在转换时完成一次提取,并保存结构,而不是保存段落。
需要明确的是:生成的技能是模型编写的有损摘要。它适合辅助学习,但源文档仍然是权威来源。如果精确措辞具有法律效力或协议要求,请保留 PDF,并以 PDF 为准进行引用。技能与 MCP 服务器及规则文件的比较介绍了每种方法适用的场景。
故障模式及你将看到的字符串
扫描版 PDF 没有生成任何内容。 提取器会检查开头页面是否包含文本层。如果没有,它会说明原因并停止,而不是处理 400 页图像。先运行 ocrmypdf input.pdf output.pdf,再将输出文件交给它。
pip 拒绝安装。 在 Ubuntu 24.04 上,error: externally-managed-environment 是 apt 对系统 Python 的保护机制。使用上面的虚拟环境,或安装 poppler-utils,完全跳过 pip。
章节划分错误。 章节检测会查找 Chapter 7 等显式标题及其语言变体,也能识别 Chapter IV 或 IV. Title 等罗马数字。使用不带编号的普通节标题的书籍会导致划分错误。解决方法是在运行时指定章节起始位置,不要依赖自动猜测。
命令不存在。 自动补全中缺少 /book-to-skill,表示 skills 目录是在当前会话启动后创建的。运行 /reload-skills,或重启 agent。
Docling 运行时间过长。 按每页约 1.5 秒计算,长篇图书会占用数分钟的 CPU 时间。在共享服务器上,该任务还会与托管的其他服务竞争资源。当运行过程询问内容类型时,回答“text-heavy”;或者在手动运行 scripts/extract.py 时传入 --mode text。--mode technical 是选择 docling 的答案。
某个源文件静默消失。 无法读取的文件会被跳过,以便批处理继续完成。随后,运行报告会显示处理成功,但源文件数量少于你提供的数量;最终报告中的文件清单是唯一能显示这一点的位置。将已完成的运行结果与实际提供的输入进行核对,这一习惯同样适用于其他任务;unlazy skill 的深度树方法可以让 agent 遵循同一标准,而不是过早宣布任务完成。
手动应用相同模式
该工具只是为了使用方便。可迁移的是这种结构;使用文本编辑器,您可以为自己拥有的任何参考资料构建相同结构。
- 编写一个入口文件,并将其长度控制在转换器目标的 4,000 tokens 左右。在其中写入指定概念的准确表述,并添加索引,列出每个详细文件及其包含的主题。
- 将材料拆分为多个文件,每个文件约含 1,000 tokens,每个文件只包含一个主题。文件名应让您仅凭文件名就能知道文件内容。
- 在入口文件中描述这些文件,并将描述写在说明何时读取对应文件的句子中。
第 3 步最容易被跳过,但它是这一模式能够发挥作用的关键。代理通过读取索引来决定打开哪些文件,因此索引未描述的文件,代理永远不会打开。索引才是成品,章节文件只是存储内容的载体。
只要将入口文件控制在压缩预算内,整个结构就能在长时间会话中保持有效。无论这些文件是由转换器还是由您创建,这条规则都适用。
FAQ
我可以发布根据所购图书构建的 skill 吗?
不可以,除非该图书的许可证允许再分发。转换器采用的 MIT 许可证只适用于转换器代码,不适用于您提供给它的材料;生成的 skill 是该图书的衍生作品。请将其保存在您自己机器上的 ~/.claude/skills/ 中。您可以发布自己编写的文档,或采用开放许可证的来源。固定的 v1.4.0 从不询问可见性,而项目的默认分支现在会单独询问这一点,并且只有在输入裸 public 时才会公开;无论哪种情况,都应由您有意作出决定。
我需要 docling,还是 pdftotext 就够了?
对于普通文本,poppler-utils 中的 pdftotext 就够了,而且几乎可以立即完成。只有当图书的价值主要在表格和代码清单中时,才安装 docling,因为纯文本提取器恰好会丢失这些内容。代价是速度:该项目测得 docling 每页大约需要 1.5 秒,因此一本 300 页的手册在 VPS 上需要占用数分钟的 CPU 时间。
为什么 pip 在我的 VPS 上因 externally-managed-environment 失败?
Ubuntu 24.04 和当前版本的 Debian 会将系统 Python 标记为由 apt 管理,因此 pip 拒绝向其中安装,并输出 error: externally-managed-environment。使用 python3 -m venv ~/.venvs/book-to-skill 创建虚拟环境,激活该环境,在其中安装提取器,然后从同一个 shell 启动您的 agent。该 skill 会调用 python3,因此使用 PATH 中的解释器;此时该解释器就是虚拟环境中的解释器。
为什么生成的 skill 没有显示为斜杠命令?
有两个原因。命令名称来自目录名称,因此 skill 必须位于 ~/.claude/skills/<name>/SKILL.md 或 .claude/skills/<name>/SKILL.md,并且必须将其准确拼写为 SKILL.md。如果路径正确,请运行 /reload-skills 或重启 agent。Claude Code 会获取其已经监视的 skill 目录中的更改,但在会话启动后才创建的 skills 目录,在执行该操作前根本不会被监视。