加紧学习，抓住中心，宁精勿杂，宁专勿多。——周恩来  

当一本技术书，不再只是“看过”：book-to-skill 想把知识变成可调用的能力

项目地址：https://github.com/virgiliojr94/book-to-skill

很多人都经历过这种时刻：买了一本很棒的技术书，读的时候觉得醍醐灌顶，过了几个月，再回头想起某个概念，却只记得“好像在哪一章见过”。PDF 还在，EPUB 也在，文档文件夹也在，可真正要用的时候，知识像躲进了层层纸页和目录里，明明拥有，却很难立刻拿出来。

book-to-skill 就是冲着这个问题来的。

它在仓库 description 里的自我介绍非常明确：把任意技术书 PDF 转成一个 Claude Code skill，让它可以被学习、引用，并在工作时直接使用。 而 README 又把这件事进一步展开：它不只处理技术书，也能处理文档文件夹，或者一组来源材料，并把它们统一整理成一个可供 agent 调用的技能。

这不是把一本书“塞进上下文”那么简单，它更像是在说：与其让资料躺在那里等待被翻找，不如让它长成一种可以随时被唤醒的工作能力。

它到底想做什么

README 里用三步概括了整个过程，简单得近乎利落：

  1. 把文件、文件夹或 glob 路径交给它
  2. 它把内容提炼成一个 skill
  3. 你的 agent 按需加载它，并根据真实内容回答问题

这里最耐人寻味的一点，是 README 特意强调：它提炼出来的是结构，而不只是摘要。它会整理出框架、决策规则、反模式，以及按章节拆分的内容文件。换句话说，book-to-skill 想保留下来的，不只是“这本书说了什么”，而是“这本书是怎么组织知识的”。

这种方向很有意思。因为对很多技术资料来说，真正有价值的，往往不是某一页上的某一段字，而是作者如何搭建概念、如何给出判断路径、如何把经验变成可以反复调用的模式。book-to-skill 显然在努力抓住这个层面。

它给出的不是原文堆砌，而是一整套技能结构

README 专门列了一个 “What it generates” 部分，说明运行之后会生成什么。

它会在 agent 的 skills 目录里创建一整套内容，包括：

  • SKILL.md：核心心智模型与章节索引
  • chapters/ch01-*.md：按章节拆分的文件，按需加载
  • glossary.md：按字母排序的关键术语表，并带章节引用
  • patterns.md：技术、算法与设计模式
  • cheatsheet.md：决策表和快速参考规则

这份清单很能说明它的野心。它没有把输出停留在“导出一个文本文件”或者“生成一份摘要”，而是试图把一份材料拆解成多个不同用途的层次：

  • 有总纲
  • 有章节入口
  • 有术语索引
  • 有模式汇总
  • 有速查表

这样的组织方式让人感觉，它更像是在为 agent 准备一套“思考支架”，而不是单纯准备资料文本。

而且 README 还特别强调：章节文件是按需加载的。这意味着它们不会在一开始就全部占据 skill 预算，而是在你问到相关主题时再被读取。这个设计在整个项目里是非常核心的一环，因为它直接关系到后文反复讨论的 token 成本与上下文效率。

它不只面向“书”，也面向一切经常被反复打开的知识材料

虽然名字叫 book-to-skill，README 却明确说，它的输入并不限于书。它处理的是任何结构化的散文式内容。

README 给出的例子包括：

  • 内部文档
  • 品牌与设计系统资料
  • 研究资料集群
  • 规范与标准文档

这一段非常有画面感。你可以把一整个 docs/ 文件夹折叠成一个 skill，在写代码时随手查询；也可以把品牌手册、语气规范、组件原则整理进一个统一技能，不再靠团队成员反复翻 PDF；还可以把论文和笔记合并成一个可更新的知识体。

README 甚至给出了一个判断标准：如果你会频繁重新打开某份文档，甚至希望自己已经把它背下来，那它就是候选对象。

这句话说得很妙。它没有试图无限扩大边界，而是给出了一个非常日常、非常人性化的使用判断：你反复回去找的，就是值得被“技能化”的。

使用方式很直白，像是在对材料下达一道命令

README 给出的命令格式是：

1
/book-to-skill <path-to-document-folder-or-glob>... [skill-name-slug]

支持的文档格式包括：

  • PDF
  • EPUB
  • DOCX
  • TXT
  • Markdown
  • reStructuredText
  • AsciiDoc
  • HTML
  • RTF
  • MOBI / AZW / AZW3

这份支持格式列表很长，但它并不显得凌乱，因为 README 把它很好地嵌在了实际示例里。

例如：

1
2
3
4
5
6
7
8
9
10
11
# Process several files together into a unified skill
/book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-research

# Process all supported files in a folder together
/book-to-skill ~/workspace/project-docs/ project-knowledge

# Process files matching a glob pattern
/book-to-skill "~/books/*.epub" my-library

# Update/fold new material into an existing skill folder
/book-to-skill ~/articles/new-paper.pdf ~/.claude/skills/project-knowledge

这些例子有一种非常实用的美感。它们让人一眼就能看出这个工具的工作方式：可以处理多个文件、可以处理整个文件夹、可以吃 glob、还可以把新材料折叠进已有 skill。不是只能做一次性的转换，而是可以围绕一个知识主题持续扩充。

创建完 skill 后，README 也给出了调用示例：

1
2
3
4
/designing-data-intensive-apps                  # load core mental models
/designing-data-intensive-apps replication      # find and explain a topic
/designing-data-intensive-apps ch05             # dive into chapter 5
/designing-data-intensive-apps "what chapters do you have?"

看到这里，这个项目的意图就越来越清楚了：它希望资料不是被动地存在某个文件夹里，而是能像一个随叫随到、按主题切换深浅层次的知识入口。

它很在意 token，不只是“能用”，还在认真算账

book-to-skill README 里一个非常醒目的说法是：

相比把整本书直接塞进上下文，为回答一个问题，它可以减少 24× 到 51× 的 tokens。

这个数字不是一笔带过的宣传语，README 为它安排了完整的解释、测量方式、表格和推导逻辑。这种写法给人的感觉不是“喊口号”，而是“我把账本摊开给你看”。

Discovery Loop Tax：它为什么觉得直接读 PDF 很贵

README 提出了一个很生动的概念：Discovery Loop Tax。

它认为，阅读 PDF 的 agent 不是在“直接阅读”，而是在“导航”：

  • 先去取目录
  • 发现一个词不确定
  • 再回头找更多页面
  • 再补充更多上下文
  • 这些跳转和压缩，又会不断进入后续对话历史中被重复处理

这段描述非常形象。它把那种我们平时不太会刻意命名的损耗，变成了一个可以被看见的成本模型。README 的核心观点是：book-to-skill 把这种导航代价在编译阶段一次性支付掉，运行阶段只加载一个小的常驻核心和所需章节，因此不需要每次重走发现路径。

它不是让模型一次次去“找”，而是提前把“怎么找、该读哪块、哪些是关键结构”整理好。

README 还给了具体测量

在 “The Discovery Loop Tax” 部分，README 展示了三本真实书籍的测量结果，比较了：

  • 直接 context dump
  • discovery loop
  • book-to-skill

并说明 book-to-skill 典型加载规模约为 5,000 tokens，由常驻核心与一个章节组成。

README 还指出，这种优势会随着章节规模扩大而增长：对 context-dump 的优势稳定在 24× 到 51×，对 discovery loop 的优势则会根据书的章节大小变化。

这里值得注意的是，README 也给出了 caveats，也就是它自己的限制和边界说明。比如它明确承认：

  • discovery 的数值是一次性成本模型
  • 章节分割依赖显式的 Chapter N 或 Capítulo N 标题
  • 标题式章节或罗马数字章节不一定能自动分段
  • 对于一次性的单次阅读，普通 PDF agent 也完全可以

这种表达很难得。它不是一味把自己说成对所有任务都更优，而是认真划出了适用情境：当你会反复回到某份知识材料时，这种预编译式技能就会体现价值。

它还把“不是 RAG”这件事讲得很明白

README FAQ 里有一段很精彩：它直接回答“这难道不就是 RAG 吗？”

它的回答很清楚：

  • RAG 是在查询时切块、嵌入、检索相似向量，再把相关片段塞进提示词
  • book-to-skill 是在编译时做一次深度分析，把作者真正的框架、命名、适用条件、反模式提取出来

README 用一句很有辨识度的话来区分两者：

  • RAG 回答的是：这里是和你的查询相近的片段
  • skill 回答的是：这里是这位作者构建的 12 个框架，已经整理好，可以直接拿来推理

这种差异，在 README 里被总结成两种任务形状：

  • 宽而浅：大量书籍里找某个提法，RAG 更合适
  • 窄而深：围绕一本书或一组紧密相关资料，在工作中反复应用框架，book-to-skill 更合适

这个定位很重要，因为它帮助读者理解：这个项目不是在否定检索，而是在强调“结构化知识编译”的另一条路径。

安装说明写得很清楚，而且特意避免混淆

README 在安装部分一上来就强调：有两种使用方式，不要混淆。

第一种，是作为 agent skill 使用，也就是在 Claude Code、GitHub Copilot CLI 或 Amp 中获得 /book-to-skill 这样的命令。

第二种，是作为 独立 CLI 使用，也就是通过 pip install book-to-skill 安装纯提取引擎。

这两个路径在 README 中被分得非常明确。

作为 GitHub Copilot CLI 的 skill

README 给出的个人 skill 安装方式是：

1
2
3
4
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.copilot/skills/book-to-skill
# then, in a `copilot` session:
/skills reload
/skills info book-to-skill

同时，也提供了 Copilot CLI 和 Amp 共用的跨 agent 路径：

1
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.agents/skills/book-to-skill

作为 Claude Code 的 skill

README 给出的另一种方式是，把这一行内容复制进 Claude Code 会话：

1
Install book-to-skill: https://raw.githubusercontent.com/virgiliojr94/book-to-skill/master/SKILL.md

或者使用手动 git clone：

1
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill

之后就可以在任意 agent 会话中运行：

1
2
3
/book-to-skill ~/path/to/your-book.pdf
# or
/book-to-skill ~/path/to/your-book.epub

作为独立 CLI

README 也保留了独立 CLI 的安装路径：

1
2
3
pip install "book-to-skill[pdf,epub,docx]"   # engine + optional extractors
book-to-skill ~/path/to/book.pdf --mode text  # or: python -m book_to_skill ...
book-to-skill --check                          # report which extractors are installed

这个“不要混淆”的提醒写得非常好，因为它一下子把项目的双重身份讲清楚了：它既可以是一个 agent skill，也可以是一个纯文本提取引擎，但这两者不是同一回事。

它连提取链路都交代得一清二楚

在 Requirements 和 How it works 这两部分，README 对内部流程的解释非常具体。

它会按格式尝试不同工具

README 提到，提取器会针对不同格式按顺序尝试工具，并使用第一个可用的。如果什么都没装，它会告诉你缺什么、该执行什么命令。

并且还提供了一个检查命令：

1
python3 scripts/extract.py --check

这个命令会打印每种格式已安装的提取器以及缺失依赖的安装命令。

PDF 会先区分“技术型”还是“文本型”

这是 README 里非常有辨识度的一点。

对于 PDF，它不是一把梭，而是先问你这本书更偏：

  • technical
  • text-heavy

对应的工具路线也不同。

对于 text-heavy，README 列出：

  • pdftotext
  • pypdf
  • pdfminer.six

对于 technical，README 推荐：

  • docling

并强调 docling 可以保留 Markdown 表格和代码块，而 pdftotext 更适合纯文字内容。

这种分流很符合项目的整体气质：它不只是“能抽文本”，而是很在意内容形态本身，尤其在技术资料里，代码块、表格、公式这些结构往往比纯文本更关键。

流程图写得像一条可视化流水线

README 用一段结构化流程图展示了整个过程：

  • 输入可以是一份文件、一个文件夹、一个 glob、或多条路径
  • 中间会有一次 technical / text-heavy 的分流
  • 然后 scripts/extract.py 调用对应解析链
  • 合并内容写入工作目录
  • Claude 负责分析结构、标题、作者、章节、目录
  • 生成章节摘要、术语表、patterns、cheatsheet
  • 最终写入对应 skill 目录
  • 临时工作目录被清理

这段说明有一种“工程化透明”的魅力。很多工具喜欢把复杂度藏在幕后，而 book-to-skill 反而很愿意把幕后灯打开，让你看见每一步是怎么走过去的。

README 还展示了性能、成本与基准结果

在 “How it works” 中，README 给出了一个 103 页技术书的提取 benchmark，对比：

  • pdftotext
  • Docling

并列出时间、tokens、表格数量、代码块数量。

此外，还给出了几本真实资料的转换测量，包括：

  • 页数
  • 提取后的 tokens
  • 自动检测到的章节数
  • 估算成本

README 总结说，完整生成一个 skill 的成本大约在 每本书 1 美元左右。

这些数据的存在，让这个项目不再只是一个概念，而有了一种非常明确的实践姿态：它不仅想告诉你“这样做更好”，还想告诉你“我测过，它大概会花多少时间、吃多少 token、保留多少结构”。

它对版权与边界问题写得很直接

README 有一整节 “Copyright & fair use”，这部分写得相当克制。

它明确表示：

  • 仓库本身不附带任何书籍内容
  • 处理过程在本地完成
  • 你使用的是你自己拥有的副本
  • 输出是结构化、综合性的衍生笔记，而不是原文复现
  • 不应传播受版权保护作品生成出的 skill

这部分的语气很稳，没有夸张，也没有回避。它把工具、输入、输出和责任边界尽量说清楚，让整个项目看起来更加成熟。

从仓库结构里，也能看出它组织得很认真

README 给出了完整的仓库结构，里面包括：

  • SKILL.md
  • scripts/
  • tools/
  • tests/
  • docs/
  • CHANGELOG.md
  • CONTRIBUTING.md
  • SECURITY.md
  • README.md

其中 scripts/extractor/ 下面又细分出配置、依赖检查、异常定义、工具函数和格式解析器；tools/ 中有用于测量 discovery tax 的工具，也有用于验证生成 skill 是否符合宿主规则的工具。

这份结构说明有一种很舒服的秩序感。它表明这个项目并不是一个临时拼起来的脚本集合，而是已经把提取、验证、测试、文档、架构说明分别安放到了自己的位置上。

这个项目最迷人的地方，是它试图改变“知识被使用的姿势”

读完 README 之后，会感觉 book-to-skill 想做的，并不是“帮你更快看书”，而是“帮你把书变成工作时真的能调用的东西”。

一本技术书放在硬盘里，通常只是一个静态对象。你知道它重要，你也知道它讲得好，但它大多数时候安安静静地躺在那里，等你有耐心时再去翻。book-to-skill 想做的，是让这本书从“对象”变成“技能”，从“我知道它在那儿”变成“我现在就能把它叫过来”。

这也是为什么 README 一再强调结构、按需加载、章节文件、patterns、glossary、cheatsheet。它不是满足于把内容搬运出来，而是努力把知识改造成一种更适合 agent 使用的形态。

如果说传统阅读更像把一本书放进书架，那么 book-to-skill 更像是在给这本书装上一套索引系统、工具腰带和应答机制。它没有替你读书，但它试图让你读过的东西，别那么轻易地再次沉回遗忘里。

而这，恰恰让它显得很有吸引力：它不是在制造更多信息，而是在想办法让已有的信息，终于真正长成能力。