把一本书编译成可调用的 Skill，一周涨 3,957 stars

book-to-skill 在 GitHub Trending 的周榜卡片上拿到 3,957 stars this week，累计已经达到 18,862 stars。

真正抓住我的并不是“PDF 转 Skill”这句介绍，而是它交付的东西：一本 244 页的技术书，最后会变成 SKILL.md、按章文件、术语表、模式库和一张决策速查表。下次再问书里的问题，Agent 不需要重新读完整本书，只加载核心索引和相关章节。

换句话说，它想做的不是更快地总结一本书，而是把反复查资料的成本，提前编译成一套可以长期调用的知识结构。

我们来拆解一下它是怎么做的，以及什么资料适合这样处理。期望对大家有所帮助。

一本书最后变成什么

按照项目的 README，输入可以是一份 PDF，也可以是一个文档目录、glob，或者一组不同格式的文件。当前支持 PDF、EPUB、DOCX、HTML、Markdown、纯文本、RTF，以及通过 Calibre 处理的 MOBI/AZW。

转换完成后，得到的不是一个越来越长的摘要文件，而是下面这套目录：

my-book/
├── SKILL.md
├── chapters/
│   ├── ch01-*.md
│   ├── ch02-*.md
│   └── ...
├── glossary.md
├── patterns.md
└── cheatsheet.md

这些文件各自承担不同任务：

文件	实际用途
SKILL.md	保存核心框架、章节索引和主题索引
chapters/*.md	保存每章的概念、方法、例子和反模式，按需读取
glossary.md	按字母整理术语，并标注来源章节
patterns.md	汇总书里的技术、算法和设计模式
cheatsheet.md	整理决策规则、权衡表、阈值和问题征兆

这里最关键的是 cheatsheet.md。项目的 Skill 生成规范明确要求它不能只是另一份术语表，而要把作者的判断写成“遇到 X 时选择 Y，因为 Z”。

这才是一本书进入工作流后的实质变化。你不再只能问“这一章讲了什么”，还可以问“我现在遇到这个条件，按照书里的方法应该怎么选”。

它先提取，再让 Agent 组织知识

book-to-skill 没有把所有步骤都交给模型。它把转换分成了两半：

PDF / EPUB / DOCX / Markdown / HTML
                 ↓
确定性的 Python extractor
                 ↓
full_text.txt + metadata.json
                 ↓
Agent 按 SKILL.md 规范分析结构
                 ↓
核心 Skill + 章节 + 术语 + 模式 + 决策表

第一半是确定性的 Python 提取器。它负责展开多份输入、选择解析器、清理文本、识别章节，并把结果写成带来源边界的 full_text.txt 和统计信息 metadata.json。架构文档把这一层称为 extractor。

第二半才是 Agent。它按照仓库里的 SKILL.md 分析书名、作者、目录和主题，再生成每章文件、主题索引、术语表和速查表。这一层不是固定模型写死的生成器，而是一份长达十个步骤的执行规范。

这种拆法解决了两个问题。

首先，文件解析、格式降级和章节检测更适合交给程序。PDF 是纯文字还是包含代码和表格，也会影响提取器选择：文字型 PDF 优先走 pdftotext 等快速路径；技术型 PDF 可以使用 Docling 保留 Markdown 表格和代码块。

其次，哪些内容算框架、哪些应该进入决策表、不同章节怎么建立联系，更适合让模型判断。程序负责把材料处理得稳定，Agent 负责理解和重组。

真正省下的是重复导航

平时让 Agent 回答一本书里的问题，常见做法有两种。

一种是把整本书塞进上下文。优点是材料都在，代价是每次会话都要重新承担大段输入。

另一种是临时搜索目录、定位章节、读取内容。它比全文输入节省，但 Agent 每次仍要重新走一遍“找目录 - 猜章节 - 读取 - 回退”的过程。

book-to-skill 的思路是把导航工作预先做完：SKILL.md 常驻核心框架和主题索引，具体章节留在独立文件里。问到某个主题时，Agent 再顺着索引读取对应章节。

项目的 性能数据用 Think Python 2 做了一个例子：

路径	回答一个目标问题时进入上下文的 token
整本书直接输入	119,264
项目建模的临时发现流程	12,152
book-to-skill 核心 + 一个章节	约 5,000

对应的差异是 24 倍和 2.4 倍。项目在另外两本书上给出的完整区间是 24 - 51 倍，但这里必须说清楚：这些是项目方用 tiktoken 和自己的 discovery model 得到的上下文 token 对比，不是独立复现的答案质量 benchmark。

它没有证明生成后的 Skill 一定答得更准，也没有把首次转换所需的模型调用、时间和费用消除。它证明的是另一件更窄、也更可信的事：当同一批资料会被反复查询时，预先建立索引和章节文件，可以减少以后重复搬运与定位材料的开销。

不只是把书变成笔记

项目名字里虽然有 book，但 用法文档支持一次输入多份文件：

/book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-research
/book-to-skill ~/workspace/project-docs/ project-knowledge
/book-to-skill "~/books/*.epub" my-library

这让它更适合处理几类经常被重新打开的资料：

• 团队的 ADR、runbook、入职文档和架构说明。
• 一组 RFC、API 合约或合规规范。
• 品牌语气、设计原则和组件规范。
• 相关论文、自己的阅读笔记和后续新增材料。

它还支持 fold-in：把新文件合并进已有 Skill，更新章节、主题索引、术语表和速查表。对于不断变化的内部文档，这比每次重新生成整套内容更实际。

比如，我可以把 Codex 仓库的 README.md、根目录 AGENTS.md，再加上官方 Prompting、AGENTS.md 和 Skills 指南整理成一个资料集合。以后询问“根目录规则、子目录规则和可复用 Skill 应该怎样分工”，Agent 就可以从不同来源里找到对应依据，而不是只返回一次网页搜索的摘要。

这个例子也说明了它最适合的材料：不是读完一次就结束，而是你会持续查阅、反复应用，并且希望答案保留来源结构的内容。

先把快速路径跑通

项目当前明确支持 GitHub Copilot CLI、Amp 和 Claude Code。以 Claude Code 为例，可以先把仓库安装到 Skill 目录：

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

处理技术书之前，先检查本机可用的提取器：

python3 ~/.claude/skills/book-to-skill/scripts/extract.py --check

然后在 Agent 中调用：

/book-to-skill ~/Documents/thinkpython2.pdf think-python-2

流程会先询问资料是技术型还是文字型，再显示来源数量、页数、预计 token、生成文件和成本估算。确认后才继续生成。完成后可以按主题或章节调用：

/think-python-2 word frequency analysis
/think-python-2 ch13
/think-python-2 "what chapters do you have?"

第一次体验，我会选一本章节标题清楚、自己有权处理的公开技术书。这样最容易检查章节识别、代码块保留和主题索引是否正确。

生成 Skill 之前先检查这几件事

这类工具最容易制造一个错觉：文件生成齐全，就等于知识已经可靠。实际上，转换后的 Skill 仍然需要抽查。

第一，确认提取模式。项目自己的测试里，一份 103 页技术 PDF 使用 pdftotext 只用了 0.1 秒，但没有保留表格和代码块；Docling 用了 164 秒，保留了 48 张表格和 36 个代码块。速度和结构质量不能同时假设为最好。

第二，检查章节边界和主题索引。没有明确 Chapter N、多栏排版或标题格式特殊的书，可能识别失败，需要手动指定章节。

第三，不要把本地提取等同于数据不会离开机器。安全说明写明提取器本身不会上传文件，但如果 Agent 背后的模型运行在云端，送给模型的文本仍然受对应服务的数据条款约束。

第四，检查文档里的恶意指令。7 月 30 日发布的 v1.3.0加入了不可见 Unicode 清理、DOCX XML 防护和生成 Skill 的 prompt injection 扫描。这些改动说明维护者正在处理真实的 document-to-context 供应链风险，但扫描器被项目明确标为 advisory，不能代替人工审阅。

第五，核对版权。转换器使用 MIT 协议，不代表输入的书也能重新发布。自己购买的书可以作为个人学习资料处理，生成后的 Skill 是否能分享，仍取决于原始内容的许可。

book-to-skill 这周的增长有一个很清楚的原因：它没有继续承诺“更长上下文能装下更多资料”，而是把问题换成了“怎样让 Agent 下次只读真正需要的部分”。

对于只查一次的 PDF，转换整套 Skill 可能没有必要。对于一本会反复引用的技术书，或者一组每天都要遵守的团队文档，先把结构整理好，下一次提问才真正开始省时间。

---

• 项目仓库：virgiliojr94/book-to-skill