指南

作者： Matt Connor 2026-08-14

如何将技术书籍转换为 Agent Skill

Q: 我需要 docling，还是 pdftotext 就够了？

poppler-utils 中的 pdftotext 足以处理正文，而且几乎立即完成。如果书籍的价值主要在表格和代码清单中，请安装 docling，因为纯文本提取器恰好会丢失这些内容。代价是速度：项目测得 docling 每页大约需要 1.5 秒，因此在 VPS 上处理一本 300 页的手册需要消耗数分钟的 CPU 时间。

Q: 为什么我生成的技能没有显示为斜杠命令？

有两个原因。命令名称来自目录名称，因此技能必须位于 ~/.claude/skills/ /SKILL.md 或 .claude/skills/ /SKILL.md，并且 SKILL.md 必须完全按此拼写。如果路径正确，请重启代理。Claude Code 会获取其已监视的技能目录中的编辑内容，但在会话启动后创建的 skills 目录完全不会被监视。

了解如何把 PDF、EPUB 或内部文档转换为按需加载的 agent skill，涵盖安装方法、令牌预算、无头运行，以及 MIT 许可证和内容授权注意事项。

将技术书籍转换为 agent skill：你将得到什么

要将技术书籍转换为 agent skill，只需让转换器处理 PDF、EPUB、DOCX 导出文件，或你已经拥有的一组内部文档。转换器会生成一个 skill 目录：其中包含一个入口文件，用于保存命名框架和章节索引；每章对应一个文件，agent 只会在问题需要时读取该文件。书籍全文不会进入上下文窗口，但索引会进入。

这与从头编写 agent skill是相反的工作。后者是将你已经掌握的流程编码下来。这里的知识已经存在，但无人能够访问：可能是一份 800 页的供应商 PDF，也可能是一本自撰写者离职后就再未打开过的手册。工作重点是压缩和建立索引。如果你不熟悉 skill 一词，请先阅读agent skill 的实际含义。

本文使用的转换器是 book-to-skill，这是一个在本机运行、采用 MIT 许可证的 skill。截至 2026 年 8 月，当前标签为 v1.4.0。它生成的结构比工具本身更重要，FAQ 前的最后一节将介绍如何手动构建相同的结构。

为什么令牌预算是整体设计的核心

将一本书粘贴到上下文窗口后，每次需要它的对话都要承担完整内容的成本。技能只需为入口文件支付一次成本，之后仅加载问题实际涉及的章节。该项目为它生成的每个文件都规定了预算。

ChartDocumented token budget per generated file, book-to-skill v1.4.0

label

tokens

SKILL.md entry file

4,000

One chapter file

1,000

glossary.md

1,500

patterns.md

2,000

cheatsheet.md

1,000

The data behind this chart

[
  {
    "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 仓库中。将其克隆到所用代理的 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，不会检出之后的版本。必须固定版本，因为技能是一组由代理执行的指令；如果未审核的更改修改了这些指令，服务器上实际运行的内容也会随之改变。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 3.9 或更高版本。

如果克隆后在自动补全中没有出现 /book-to-skill，请重启代理。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 提取器，请创建虚拟环境，并从该环境中启动代理。这样，技能调用的 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

该仓库声明了 pdf、epub、docx、rtf、technical 和 all 这些 extras，其中 technical 是 docling。项目的安装页面还列出了 pip install "book-to-skill[pdf,epub,docx]"，但截至 August 2026，该名称尚未发布到 PyPI，因此请像上面一样从自己的 checkout 安装。

在书籍确实需要 docling 之前，不要安装它。它会引入机器学习软件栈，因此在小型套餐上安装前应先检查可用磁盘空间。

在文档目录上运行，包括无头模式

该命令接受单个文件、目录、带引号的 glob，或一次传入多个路径，后面还可跟一个可选的 skill 名称。只要内容位于同一个目录中，都可以作为输入，包括 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 在 skill 读取前将其展开。将命令指向现有的 skill 目录时，新源会合并到该 skill 中，而不是创建第二个 skill。

交互式运行会询问以下问题：材料是技术内容还是以文本为主，这决定使用哪种提取器；需要参考深度还是学习深度，这决定每章的预算；skill 应使用什么名称，以及应放入哪个 skills 根目录。生成前，命令还会显示 token 和时间估算，并等待您确认。

无头运行时没有人回答这些问题。用户可调用的 skill 在 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 下的临时工作目录中。运行的最后一步会删除该目录。提取失败的源文件会被跳过，因此批处理仍可继续。这意味着即使运行报告成功，实际读取的文件也可能少于您提供的文件。请将最终报告中的文件清单与目录中的实际内容进行比较。缺少章节通常表示缺少源文件。

请为运行指定一台您愿意交给 agent 使用的服务器。在 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 许可不会授予您分发他人书籍衍生内容的权利。
输出内容属于衍生作品。框架和章节要点仍然受到源材料的塑造，而衍生作品仍受源材料版权约束。
根据您无权再分发的材料构建的技能，应保留在生成它的机器上。不能放入公共代码仓库，也不能放入共享的团队市场。
仅当源材料属于您，或采用允许再分发的开放许可时，才可以发布：例如团队编写的文档，或其条款允许再分发的标准。

该工具的设计正是基于这一点。它不包含任何书籍内容，提取过程在本地运行；发布步骤会单独询问代码仓库的可见性，并且只接受单独的单词 public 或 private，不会自行推断。请将此提示视为许可决策，因为它确实是在询问许可决策。

内部手册还存在第二个问题。手册中包含凭据的频率往往高于人们承认的程度，而转换器会将一份无人打开的 PDF 转换为代理可按需读取的文件。提交这些文件前，请至少完整查看生成的文件一次，并参阅避免将机密信息放入 AI 代理。

一次转换的成本是多少？

以下数字来自该项目自行发布的测量结果，并非我们的测量结果。

ChartCost to convert one full-length book, as published by the project

label

cost_usd

Think Python 2

0.88

Working Backwards

0.96

Pro Git

1.23

Moby-Dick

1.42

The data behind this chart

[
  {
    "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 计算；截至 2026 年 8 月，数据已发布在项目的 docs/performance.md 中。您自己的成本会随所用模型和价格变化。

该项目还记录了：与将整本书粘贴到上下文中相比，使用该技能回答一个问题所需的令牌数减少了 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 这类明确的标题及其语言变体。如果书籍只使用普通节标题或罗马数字，章节划分就会出错。解决方法是告诉程序章节从哪里开始，而不是依赖自动猜测。

命令不存在。 自动补全中缺少 /book-to-skill，说明 skills 目录是在当前会话启动后创建的。重启 agent。

Docling 运行时间过长。 按每页大约 1.5 秒计算，一本长篇书籍需要消耗数分钟的 CPU 时间。在共享服务器上运行时，还会与其他托管服务争用资源。当程序询问内容类型时回答 “text-heavy”，或者手动运行 scripts/extract.py 时传入 --mode text。选择 docling 的答案是 --mode technical。

某个源文件悄然消失。 无法读取的文件会被跳过，以便批处理继续完成。随后，运行结果会显示成功处理的源文件数量少于输入数量；最终报告中的文件清单是唯一能显示这一点的位置。

手动应用相同模式

该工具只是为了使用方便。可迁移的是这种结构；使用文本编辑器，您可以为自己拥有的任何参考资料构建相同结构。

编写一个入口文件，并将其长度控制在转换器目标的 4,000 tokens 左右。在其中写入指定概念的准确表述，并添加索引，列出每个详细文件及其包含的主题。
将材料拆分为多个文件，每个文件约含 1,000 tokens，每个文件只包含一个主题。文件名应让您仅凭文件名就能知道文件内容。
在入口文件中描述这些文件，并将描述写在说明何时读取对应文件的句子中。

第 3 步最容易被跳过，但它是这一模式能够发挥作用的关键。代理通过读取索引来决定打开哪些文件，因此索引未描述的文件，代理永远不会打开。索引才是成品，章节文件只是存储内容的载体。

只要将入口文件控制在压缩预算内，整个结构就能在长时间会话中保持有效。无论这些文件是由转换器还是由您创建，这条规则都适用。

FAQ

我可以发布根据自己购买的书籍构建的技能吗？

不可以，除非该书的许可证允许再分发。转换器采用的 MIT 许可证只涵盖转换器代码，不涵盖您提供给它的材料；生成的技能属于该书的衍生作品。请将其保留在您自己的计算机上的 ~/.claude/skills/ 中。对于您自行编写的文档或采用开放许可证的来源，可以发布；工具还会单独询问仓库可见性，只接受单独的 public 或 private，因此您可以明确作出决定。

我需要 docling，还是 pdftotext 就够了？

poppler-utils 中的 pdftotext 足以处理正文，而且几乎立即完成。如果书籍的价值主要在表格和代码清单中，请安装 docling，因为纯文本提取器恰好会丢失这些内容。代价是速度：项目测得 docling 每页大约需要 1.5 秒，因此在 VPS 上处理一本 300 页的手册需要消耗数分钟的 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 启动您的代理。该技能会调用 python3，因此使用 PATH 中的解释器；此时该解释器就是虚拟环境中的解释器。

为什么我生成的技能没有显示为斜杠命令？

有两个原因。命令名称来自目录名称，因此技能必须位于 ~/.claude/skills/<name>/SKILL.md 或 .claude/skills/<name>/SKILL.md，并且 SKILL.md 必须完全按此拼写。如果路径正确，请重启代理。Claude Code 会获取其已监视的技能目录中的编辑内容，但在会话启动后创建的 skills 目录完全不会被监视。

#agent-skills #claude-code #documentation #context #tooling