book-to-skill

book-to-skill 快速入门：把一本书编译成「按需加载」的技能

这是什么？适合谁？

book-to-skill 是一个 MIT 许可的开源转换器（作者 virgiliojr94，Python 实现）。它做的事一句话能说完：你把一本技术书、一堆内部文档、或一个论文文件夹指给它，它把内容编译成一个结构化的 Agent 技能，之后你的 Agent 需要时按章加载。

它要解决的问题很具体，而且几乎人人遇过：书买了、读了一遍，三个月后连「第 7 章讲过这个」都想不起来。常见的三条退路都不好用——在 PDF 里搜关键词，得到的是页码列表而不是答案；直接问 Agent，它要么编，要么说没这份内容；自己记笔记，最后得到一份再也不会打开的 200 行文档。

区别在于编译发生在什么时候。把整本 PDF 塞进上下文，是每次对话都重新付一遍全文的 token 钱；book-to-skill 只在转换时付一次，把内容压成「核心心智模型 + 章节索引 + 术语表 + 模式表 + 速查表」，之后每次提问只加载「约 4K 的核心 + 约 1K 的那一章」。

它由两半组成，这一点决定了你该在哪一层排错：

• 确定性的 Python 抽取器（scripts/extract.py）：把各种格式的文档变成干净文本 + 元数据，不调用模型；
• 规范驱动的生成器（仓库根目录的 SKILL.md，11 个步骤的生成规程）：由你的 Agent 按规程把抽取结果编译成技能文件。

官方在性能页给出的实测结论是：回答一个针对性问题，book-to-skill 约花费 5,000 tokens，而把书整本塞进上下文分别是 119K / 175K / 256K tokens（Think Python 2 / Working Backwards / AI Engineering 三本书），也就是 24×–51× 的差距——注意这个差距是每一轮对话都要重付的那种成本。

适合谁：

• 有一批要反复查的技术书、规范、RFC、内网 runbook，想要「问一句就得到这一章里的具体做法」的人；
• 想把公司散落在 wiki、Notion、PDF 里的流程编译成一个「入职技能」，让新人第一天就能自己查的人；
• 在读某一主题的论文/笔记，想把它们合成一个可增量更新的知识体（它支持把新资料 fold-in 到已有技能里）。

不太适合谁：

• 想跨几十本书做「找出谁提过 X」的检索——那是 RAG 或 NotebookLM 的场景，官方 FAQ 也直说这类需求 NotebookLM 更合适；
• 手里只有扫描件、又不愿意先做 OCR 的人（它不做 OCR，见踩坑 2）；
• 想拿它批量生产可直接公开分发的「书摘技能」的人——版权边界见踩坑 8。

和站内同类条目对照：markitdown（本站 8.5）做的是「任意格式 → Markdown」，转换完就结束了，不负责结构化和按需加载；anthropic-pdf（本站 8.4）是 PDF 的读写操作技能，管的是文件而不是知识；notebooklm-py（本站 8.0）走 NotebookLM 云端做多源问答，适合宽而浅。book-to-skill 的位置是「窄而深 + 产物落在本地文件系统里、可以进 git」。

核验日期：2026-11-01。依据官方仓库 README、docs/how-it-works.md、docs/performance.md、docs/install.md、docs/faq.md 与 GitHub API。仓库数据：36,664 stars / 3,882 forks / 23 个未关闭 issue / 最近推送 2026-10-28 / 最新发布 v1.4.0（2026-08-10）。

准备工作

• 一个支持 Agent Skills 开放标准的宿主。官方列出 7 个：Claude Code、GitHub Copilot CLI、Amp、Codex、Hermes Agent、OpenCode、OpenClaw。它们读的都是同一份 SKILL.md。

• Python ≥ 3.9（pyproject.toml 里 requires-python = ">=3.9"）。抽取器是 Python 包 book_to_skill。

• Node（只为 npx skills add 那一行命令）。手动 git clone 不需要 Node。

• 按格式选装的抽取器，不装也能起步，缺了会告诉你装什么：

  格式	首选	安装
  PDF（散文类）	pdftotext（poppler）	sudo apt install poppler-utils
  PDF（散文类兜底）	pypdf / pdfminer.six	pip3 install pypdf pdfminer.six
  PDF（代码/表格/公式）	docling	pip3 install docling
  EPUB	ebooklib + beautifulsoup4（兜底用标准库 zipfile）	pip3 install ebooklib beautifulsoup4
  DOCX	python-docx（兜底标准库 ZIP/XML）	pip3 install python-docx
  HTML	beautifulsoup4（兜底标准库 html.parser）	pip3 install beautifulsoup4
  RTF	striprtf（兜底正则）	pip3 install striprtf
  MOBI / AZW / AZW3	Calibre 的 ebook-convert（外部程序，不是 pip 包）	calibre-ebook.com/download
  TXT / Markdown / reStructuredText / AsciiDoc	内置	无需安装

• 扫描件要先做 OCR：官方明确它不跑 OCR，ocrmypdf 是最省事的一条路（ocrmypdf input.pdf output.pdf）。

• 预算：按官方实测表（Claude Sonnet 4.5，$3 / $15 每 MTok），一本书约 $1：244 页 $0.88、371 页 $0.96、501 页 $1.23、EPUB 301K tokens $1.42。这是「生成一次」的钱，不是订阅。

• 时间预算：抽取速度取决于模式——散文类 pdftotext 基本瞬间（103 页 0.1 秒），技术模式 docling 约 1.5 秒/页（同样 103 页 164 秒）。生成阶段由你的 Agent 逐步完成，官方没有公布端到端总时长。

• 版权前提：处理你自己买的书、公司自有文档、或你有权阅读的材料。生成的技能是「衍生的笔记」，不是原文复制（它的质量规则里有一条明确禁止抄长段原文）。

装：先分清「技能」和「CLI」是两条路

这一步是官方 docs 里反复强调的，也是最多人卡住的地方：

• 要 /book-to-skill 这个命令和完整转换流程 → 装成技能（git clone 或 npx skills add）。
• 只要文本抽取引擎 → pip 装成 CLI。它不会注册 /book-to-skill 技能，只给你一个 book-to-skill 命令做抽取与体检。

路线 A：装成技能（推荐）

一条命令，多宿主通吃：

npx skills add virgiliojr94/book-to-skill

手动安装也可以，按宿主选目标目录：

# 跨宿主共享根（Copilot CLI / Amp / Codex / OpenCode 都会读）
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.agents/skills/book-to-skill

# Claude Code（官方会在转换结束后尝试建软链并回读校验）
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill

# GitHub Copilot CLI
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.copilot/skills/book-to-skill

# Hermes Agent：装到自己的分类目录下（它不扫跨宿主根）
git clone https://github.com/virgiliojr94/book-to-skill.git \
  "${HERMES_HOME:-$HOME/.hermes}/skills/productivity/book-to-skill"

# OpenClaw（活动 state 目录）
git clone https://github.com/virgiliojr94/book-to-skill.git \
  "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/skills/book-to-skill"

装完先验证宿主认不认：Copilot CLI 里 /skills reload 然后 /skills info book-to-skill；OpenClaw 用 openclaw skills list；Claude Code、Codex、OpenCode 开一个新会话。

路线 B：装成 CLI（只装抽取器）

book-to-skill 目前不在 PyPI 上（2026-11-01 实测 pypi.org/simple/book-to-skill/ 返回 404，官方 install 文档也写明 “not on PyPI yet”），所以要直接从仓库装：

pip install "book-to-skill[pdf,epub,docx] @ git+https://github.com/virgiliojr94/book-to-skill.git"

book-to-skill --check                     # 逐格式报告装了什么、缺什么、该跑哪条命令
book-to-skill ~/books/x.pdf --mode text    # 只跑抽取

可选依赖里 [html] 会带来 trafilatura 那一整套（lxml、日期解析、时区库等 17 个包），官方提醒「机器受限时要知道这件事」；不装它也有 bs4 兜底，只是不做正文与样板区识别。

四步跑通第一本书

第 1 步：先体检抽取器，别等跑一半报错

python3 scripts/extract.py --check

它按格式打印「已装 / 未装 + 安装命令」，不碰任何文件。你自己机器上缺 docling、缺 poppler 都能在这里看出来。

第 2 步：决定走文本模式还是技术模式

这是全文最有价值的一次选择，因为两种模式的产出结构上不一样。官方对 103 页技术 PDF 的实测：

也就是说：token 数几乎一样，丢掉的 48 个表格和 36 段代码才是差别。散文书用文本模式（快几个数量级），有代码、表格、参数表的技术书必须走技术模式。

第 3 步：跑转换（它会先做成本预估）

在支持技能的主机里：

/book-to-skill ~/books/designing-data-intensive-applications.pdf

流程是这样走的，你只需要回答几个问题：

1. Step 1.5：问你「技术书还是散文书」→ 决定用 docling 还是 pdftotext；
2. Step 2：抽取，合并成一个 full_text.txt + metadata.json（默认工作目录 /tmp/book_skill_work/，正常结束会清理）；
3. Step 2.5：给出成本预估（按章节数 × 每章预算 + 4K 的 SKILL.md + 4.5K 附属文件推算），等你确认；此时说「只分析」会自动切到只分析模式；
4. Step 3–4：分析结构（书名、作者、章节、目录），再问一句「这本书你打算怎么用」——这句决定每章预算是「参考型」还是「学习型」（文本约 1,000 / 技术约 1,800 tokens 起步，学习型更高）；
5. Step 5–9：写章节文件、术语表、模式表、速查表、主 SKILL.md；
6. Step 10：扫描产物、清理工作目录、报告写到了哪个绝对路径。

产出长这样（默认写在跨宿主根 ~/.agents/skills/<slug>/）：

第 4 步：调用它，然后校验产物

装好之后就是普通技能：

/designing-data-intensive-applications              # 加载核心心智模型
/designing-data-intensive-applications replication  # 针对某个主题
/designing-data-intensive-applications ch05         # 直接进第 5 章

生成物可以先用仓库自带脚本按宿主规则校验一遍，再拿去用：

python3 tools/validate_skill.py ~/.agents/skills/<slug> --lens hermes
# --lens 可选：claude | copilot | amp | hermes | openclaw | opencode

常见踩坑

坑 1：pip install book-to-skill 装不上，或者装上了却没有 /book-to-skill

现象：pip install book-to-skill 报找不到包；或者装完在 Claude Code 里敲 /book-to-skill 没反应。 原因：两层。① 它没发布到 PyPI，只能从 git URL 装；② 就算装成功，pip 装的只是抽取器 CLI，官方文档明确写这条路径「不注册 Agent 技能」。 解决：要斜杠命令就 git clone 到对应宿主的 skills 目录（或 npx skills add）；只要抽取就按路线 B 从 git URL 装。

坑 2：扫描版 PDF 一上来就停

现象：还没开始抽取就报错退出，说这份 PDF 没有文本层。 原因：扫描件是一堆页面图片，PDF 抽取链上每个工具读的都是文本层。官方在抽取开头就检查前几页并提前中止——这是设计，为的是不让你跑完 400 页才发现结果是空技能。 解决：先 OCR（ocrmypdf input.pdf output.pdf），再对输出做转换。图与表里的文字同样抽不出来，那是 OCR 与视觉识别的事，不是它的职责。

坑 3：技术书用了文本模式，表格和代码全没了

现象：生成的技能里「参考表」一片空白，代码示例缺失。 原因：pdftotext 会把表格拍平成流水文本。官方实测同一本书：文本模式 0 个表格、0 段代码，技术模式 48 个表格、36 段代码。 解决：含代码、参数表、公式的书一律走技术模式（docling）。代价是抽取从 0.1 秒变 164 秒（103 页），这个代价买的是结构，不是 token。

坑 4：章节没被切出来，变成一个巨大文件

现象：chapters/ 里没有按章分的文件，或只有寥寥几个。 原因：章节自动识别依赖显式的 Chapter N / Capítulo N 标题。官方自己举了两个反例：Pro Git（501 页）用小节标题当头，Moby-Dick 用章节名 + 罗马数字，两者都不会自动分段——抽取和转换照常，但章节要你手动指。 解决：选书时先看有没有规整的章标题；没有的话，把「第几章到第几章」当成独立输入分批转换，或在生成阶段明确指定章节边界。中文书用「第 3 章」这类标题是否命中，官方文档没有承诺，本站也未实测（见 FAQ Q4）。

坑 5：同一本书重跑，被重跑守卫拦住

现象：第二次跑同一份资料时它停下来问你三个选项。 原因：生成规程里有一条重跑守卫——它先用「作者概念式 / 书名式 / 你给的 slug」推导出目标技能名，发现目录已存在就停止，让你选：① 更新与折叠（增量）、② 只校验现有技能是否完整、③ 强制全量重生成。 解决：想补新资料选 ①（增量，便宜）；只是怀疑上次没跑完选 ②；选 ③ 等于重付一次约 $1 的生成成本。

坑 6：中断之后想续跑，工作目录已经不在了

现象：网络断或会话中断后重来，它说要从头抽取。 原因：默认工作目录 /tmp/book_skill_work/ 在正常结束时会被清理；即使还在，续跑也要求 metadata.json 里每个来源在文件名与 sha256 内容指纹上都对得上、且抽取模式一致，否则判定不安全、重新抽取。 解决：大书先固定工作目录（BOOK_SKILL_WORKDIR），中断后保留它；换了文件、改了抽取模式就不用想着续跑了。

坑 7：让 Agent 一次读完 full_text.txt，上下文直接爆

现象：生成阶段开始没多久就报上下文超限，或质量明显下滑。 原因：一本 400 页书抽出来十几万到二十几万 tokens。生成规程为此专门写了「超过 5 万 tokens 的书用 REPL 式访问」——按行偏移分段读、用检索定位章节，而不是整篇读入。 解决：照它的规程走（分段读取、定点抽取）；如果你在别的宿主里自己搭流程，也照这个约束来。

坑 8：把第三方书生成的技能推到了公开仓库

现象：一时的 public 回答，把整份衍生内容发布出去了。 原因：转换结束它会问要不要把技能发布成 GitHub 仓库，可见性单独问一句，gh repo create 默认 --private，只有你回答就是裸的 “public” 这个词才建公开库。而且「这本书是公版」描述的是书，不是你的仓库，不能当成公开的授权。 解决：第三方版权书生成的技能保持私有、不分享、不售卖；自有文档与开放许可材料可以在许可范围内共享。这是官方 README「版权与合理使用」一节的原文立场。

坑 9：装完在 Copilot CLI 或 Hermes 里找不到技能

现象：目录里有文件，宿主里就是没有。 原因：各宿主的发现机制不同。Copilot CLI 需要 /skills reload；Claude Code 与 Amp 下一次会话才加载；Hermes Agent 只扫自己的 ${HERMES_HOME}/skills/<category>/，不看跨宿主根 ~/.agents/skills。 解决：Copilot 先 reload；其余开新会话；Hermes 按路线 A 里那条命令装到分类目录下。

初级用法

1. 单本技术书：/book-to-skill ~/books/ddia.pdf，走技术模式，产出后 /ddia replication 直接问。
2. 一个项目的文档文件夹一起编译：把部署手册、架构决策记录、复盘纪要放进一个目录，一次转成一个统一技能——它的本意就是「任意结构化散文」，不只是书。
3. glob 批量：/book-to-skill "~/papers/*.epub" my-library，把同一主题的电子书合成一个技能。
4. 按章深挖：/slug ch05 只加载第 5 章，比「整本塞进去再问」省得多；章节文件名在 chapters/ 里能看到。

高级玩法

1. 先分析、后生成：先只跑分析，看它挖出来的「作者核心框架 / 原则 / 反模式」清单是否靠谱，再决定要不要花那约 $1 生成。选错书的时候，这一步能省下一整本的钱；生成阶段也能从这份分析直接续跑。
2. 增量折叠：新论文或新章节到了，把新文件指向已有技能目录：/book-to-skill ~/papers/new.pdf ~/.agents/skills/project-knowledge——它走「更新与折叠」流程，只改受影响的章节并重写主 SKILL.md，不用整本重来。
3. 一个技能喂给全团队：生成的技能文件夹是纯文件，进 git 就是团队知识库；也可以按官方给的路径发到私有 GitHub 仓库，别人一条 npx skills add https://github.com/<你>/<slug> --skill <slug> 装上（需要已登录的 gh CLI）。
4. 按宿主分别校验：validate_skill.py --lens hermes 与 --lens copilot 各跑一遍，同一份产物可以确认在多个宿主上符合各自的技能规则。

六个小技巧

1. 先 --check 再选书：抽取器缺哪个格式的依赖，一眼就能看到，比跑到一半失败快得多。
2. 技术书用 docling，散文书用 pdftotext：判断标准不是「是不是 PDF」，而是「有没有代码、表格、公式、参数」。
3. 把成本预估当刹车：Step 2.5 的预估是免费的；看到预估觉得贵，就说「只分析」，先拿到结构分析再决定。
4. 固定工作目录（BOOK_SKILL_WORKDIR）：大书转换中途断了还能续，不然就是重新抽一遍。
5. 产物目录名就是调用名：想好 slug 再跑，改名要连目录带索引一起改。
6. 拿它当「读书的第一遍」：先让它编译，再用 cheatsheet.md 的决策表回看书里对应章节——比从头顺着读一遍快。

常见问题 FAQ

Q1：它和「把 PDF 直接丢进上下文」到底差在哪？1M 窗口不是够了吗？

A：差在付钱的时间点。整本塞进去是每一轮对话都重付全文；book-to-skill 只在转换时付一次，之后每次提问约 5K tokens（4K 核心 + 1K 章节）。官方实测同一问题的对比是 24×（119K 那本）、35×（175K）、51×（256K）。窗口变大只让「塞得下」成立，不改变「一直塞一直付」；而且上下文填得越满，模型捞一个具体事实的精度越差（lost in the middle），一篇精编的 1K 章节好过 200K 原文的情况是常态。

Q2：这不就是 RAG 吗？和 NotebookLM 怎么选？

A：RAG 在查询时工作：切片、向量化、找相似段落塞进 prompt，擅长「找出提到 X 的那段」。book-to-skill 在编译时工作：一次性抽出作者真正的框架、给它们命名、写清什么时候用、把反模式列出来，产物是可推理的结构而不是相似度命中。选型按活儿的形状分：宽而浅（几十本书里找一段）用 NotebookLM 或 RAG；窄而深（一两本要反复用、边工作边查）用 book-to-skill。官方自己也说这两者是互补的。

Q3：收费吗？一本书到底花多少钱？

A：转换器本身 MIT 免费。钱花在模型上——官方按 Claude Sonnet 4.5（$3 / $15 每 MTok）实测估算：244 页 $0.88、371 页 $0.96、501 页 $1.23、EPUB 301K tokens $1.42，也就是一本书约 $1，付一次。换成更便宜的模型会更低，但换算率会变，官方数字只对 Sonnet 4.5 成立。

Q4：中文书支持吗？章节会自动切吗？

A：格式层面没有语言限制，中文 PDF 与 EPUB 都能抽取。但章节自动切分依赖显式的 Chapter N / Capítulo N 标题（官方文档只写了这两类），中文「第 3 章」这种标题是否命中，官方没有承诺，本站也没有实测。稳妥的做法是：转换时确认 chapters/ 里真的有分章文件；没有就手动指定范围、分批转换。术语与质量受原书排版影响，中文 PDF 的字体编码问题也可能让抽取结果错行，能拿 EPUB 就别用 PDF。

Q5：我的书或内部文档会被上传吗？

A：抽取与分析都在本机跑，官方明确「files are never uploaded by this tool」。但生成阶段是你的 Agent 在做——如果你的模型在云端，喂进去的文本就受那家 provider 的数据条款约束，和你平时发 prompt 一样。真正机密的文档，要么用本地模型跑生成，要么别用。

Q6：生成的技能可以分享或卖吗？

A：看素材是谁的。第三方版权书生成的技能应当保持私有，公开发布或分享可能侵权；公司自有文档、你自己写的东西、开放许可材料，在许可范围内可以共享。官方一句话说得很直白：转换器是工具，怎么用在你。另外别把「书是公版」当成「衍生技能可以随便发」的理由。

进阶学习建议

1. 读 docs/how-it-works.md 的 Steps 0–10：那是整条流水线的权威描述（什么条件下换抽取器、每章预算怎么定、产物写到哪里），比 README 细一档；排错时按步骤号定位最快。
2. 读仓库根的 SKILL.md（约 55KB）：它不是普通说明文档，而是生成器的规范本体——Step 5 的命名规则、Step 7 的预算矩阵、Step 9 的模板、以及质量规则（含禁止抄长段原文那条）都在里面。想改生成风格，改的是它。
3. 用 tools/discovery_tax.py 在你自己的书上复算一次：python3 tools/discovery_tax.py --full-text /tmp/book_skill_work/full_text.txt --target-chapter 5，把「省了多少」从别人的表格变成你自己书的数字。
4. 用 tools/validate_skill.py 做宿主合规检查：--lens claude|copilot|amp|hermes|openclaw|opencode 六种规则各跑一遍，做多宿主分发前先过这关。
5. 读 book-to-skill-use-cases：用户自己写的真实案例（含一个 DevEx 书变成 300+ 工程师问卷的用法、以及一个扫描 PDF 卡住最终变成 PR #130 早期中止修复的故事），比宣传语有用。
6. 盯 CHANGELOG 与 releases：v1.0.0 起增加了「自适应深度」（同一章从 473 tokens 提到 1,219，并给学习型章节补了 worked example），说明产物质量规范仍在演进；升级后旧技能不会自动重编，重要资料值得按新规范重跑一次。

免责声明

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。

本次没有安装 book-to-skill，没有实际执行 extract.py、/book-to-skill 或任何生成流程，因此不验证：抽取器在各格式上的成功率、生成产物的实际质量、每本书的真实 token 消耗与费用、中文书的章节切分效果。文中的性能数字、成本表、格式支持、宿主路径、模式与限制，均转述自官方 README、docs/ 下五个文档页、pyproject.toml 与 GitHub API，属官方自述或仓库元数据。

参考链接

• 官方仓库 README：定位、产物结构、宿主支持、抽取器矩阵、版权立场
• 简体中文 README：官方中文版（自注同步于 commit 907be50 / 2026-08-31，可能落后 master）
• docs/usage.md：单文件/文件夹/glob/列表四种输入、调用方式、发布到 GitHub
• docs/install.md：七个宿主的目录、npx skills add、CLI 与技能的差别、未上 PyPI 的说明
• docs/faq.md：与整本上下文、1M 窗口、RAG、NotebookLM 的对比，扫描件处理，训练数据问题
• docs/performance.md：抽取基准、四种书的实测 token 与成本、Discovery Loop Tax 复算方法
• docs/how-it-works.md：Steps 0–10 全流程、抽取模式、章节切分限制
• SKILL.md：生成器规范本体（模式、预算矩阵、质量规则）
• Releases：最新 v1.4.0（2026-08-10）与变更记录
• Agent Skills 开放标准：SKILL.md 格式的规范来源
• skills CLI（skills.sh）：npx skills add 的多宿主安装器
• book-to-skill-use-cases：用户案例索引
• ocrmypdf 文档：处理扫描版 PDF 的 OCR 前置步骤
• Calibre 下载页：MOBI / AZW / AZW3 需要其 ebook-convert
• GitHub API 仓库元数据：stars / forks / 未关闭 issue / 创建与最近推送时间（本文数据核验于 2026-11-01）