别再把 PDF等文档拖进 Claude 了,这才是正确姿势

一个 MIT 开源项目，作者 virgiliojr94，冲到 GitHub 8000+ 星。

地址：github.com/virgiliojr94/book-to-skill

一句话概括，它把一本技术书 PDF、EPUB、DOCX 或者一整个文档文件夹，编译成 Claude Code / GitHub Copilot CLI / Amp 都能加载的 Skill，之后按需查询。

它解决什么问题

直接把整本 PDF 拖进 Claude 的 project 或者 context，有三个具体的坑。

第一，一本 400 页的书大约 20 万 token，每一次对话都要全量重刷，费用不谈，注意力也被无关章节稀释。

第二，模型容易把不同章节的例子混在一起，或者引用书里根本不存在的段落。

第三，PDF 里的表格和代码块经过普通抽取后结构全丢，技术书里这两样恰恰是核心。

book-to-skill 的思路是把「找到正确章节」这件事从执行期挪到编译期。编译一次，之后每次提问只加载核心索引 + 相关章节，大约 5000 token 就能回答一个针对性问题，比整本塞进去省 24 到 51 倍。

编译产物长什么样

跑完 /book-to-skill your-book.pdf 之后，~/.claude/skills/<slug>/ 下会生成：

关键点是 chapters 里的每章文件默认不进 context，问到相关话题才被读进来。

支持的输入格式

PDF、EPUB、DOCX、TXT、Markdown、reStructuredText、AsciiDoc、HTML、RTF，以及 MOBI / AZW / AZW3 等 Kindle 格式。

Markdown 因为结构已经干净，编译最快；PDF 因为要过版面还原，最慢。

编译流程

编译前会先问一个问题：这是技术书还是文字书。

技术书走 docling，保留表格和代码块的 Markdown 格式，大约每页 1.5 秒
文字书走 pdftotext → PyPDF2 → pdfminer.six 的降级链，秒级完成

抽取完成后，Claude 自动分析文档结构，识别书名、作者、章节边界和目录，再逐章生成 800 到 1200 token 的摘要，最后统一产出 SKILL.md + glossary + patterns + cheatsheet。

技术书模式下，每章摘要额外保留一个 Code Examples 段和一个 Reference Tables 段。

安装

两个文件搞定，一句 curl。

mkdir -p ~/.claude/skills/book-to-skill/scriptscurl -o ~/.claude/skills/book-to-skill/SKILL.md \  https://raw.githubusercontent.com/virgiliojr94/book-to-skill/master/SKILL.mdcurl -o ~/.claude/skills/book-to-skill/scripts/extract.py \  https://raw.githubusercontent.com/virgiliojr94/book-to-skill/master/scripts/extract.py

或者 git clone：

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

或者在 Claude Code 里直接说一句：

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

依赖

纯文本、Markdown、reStructuredText、AsciiDoc 不需要装任何东西。

PDF 分两种：

书类型	工具	安装	速度
纯文字	pdftotext (poppler)	`sudo apt install poppler-utils`	秒级
纯文字备选	PyPDF2	`pip3 install PyPDF2`	秒级
纯文字备选	pdfminer.six	`pip3 install pdfminer.six`	秒级
技术书（代码 / 表格 / 公式）	docling	`pip3 install docling`	1.5s / 页

EPUB 推荐 pip3 install ebooklib beautifulsoup4。

一键自检当前环境：

python3 scripts/extract.py --check

会列出每种格式当前用的抽取器和还缺哪个包。

使用

编译：

# PDF，自动从文件名推导 skill 名/book-to-skill ~/Downloads/designing-data-intensive-applications.pdf# EPUB，自定义名字/book-to-skill ~/books/clean-code.epub clean-code# 多个文件合并成一个 skill/book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-research# 整个文件夹/book-to-skill ~/workspace/project-docs/ project-knowledge# glob/book-to-skill "~/books/*.epub" my-library# 向现有 skill 增量追加/book-to-skill ~/articles/new-paper.pdf ~/.claude/skills/project-knowledge

编译完成后，像普通 skill 一样调用：

/designing-data-intensive-apps                    # 加载核心心智模型/designing-data-intensive-apps replication        # 查某个话题/designing-data-intensive-apps ch05               # 直接看第 5 章/designing-data-intensive-apps "what chapters do you have?"

GitHub Copilot CLI 需要 /skills reload 刷新一下 skill 列表。Claude Code 和 Amp 下次会话自动识别。

和 RAG 的区别

维度	book-to-skill	RAG + 向量检索
检索单位	结构化章节，对齐目录	切碎的 chunk
索引机制	SKILL.md + 文件系统	embedding 向量相似度
基础设施	无	vector DB + embedding 服务
单次提问 token	~5000	chunk 数 × chunk 大小
切割粒度	语义完整	易切断上下文
幻觉风险	低，答案有章节出处	中，撈错 chunk 仍会误导
适用	一本书 / 结构清楚的文档	大量、异质、跨来源文档库

跨几十本书搜索还是 RAG 的主场；深入一本书用它的框架，book-to-skill 更合适。

不只是书

作者在文档里明确说了几类适合的场景：

内部文档、架构决策记录、runbook、onboarding 指南
品牌语调手册、设计系统原则
一组相关论文加个人笔记，合并成一个统一 skill，可持续增量追加
RFC、API 契约、合规文档

判断标准很简单，一份文档如果被反复打开、多到希望自己已经背下来，就是候选。

局限

需要清楚的三点：

第一，Skill 是编译期的一次性快照，书改版了要重新编译。

第二，摘要本身由模型生成，抽取过程仍可能漏掉或扭曲细节，它降低的是「无中生有」类幻觉，不保证逐字正确。

第三，跨大量无结构文档库的场景，向量检索仍然更合适。

项目自身

全部代码 1300 行左右，两个核心文件：SKILL.md（skill 定义，约 530 行）+ scripts/extract.py（抽取脚本，约 830 行）
MIT 协议
大于 50K token 的书（130 页以上），SKILL.md 用 grep + sed 按章切片读取，避免自身编译时占满 context
不携带任何书本内容，是一个转换器，只处理用户自己的文件

以上，既然看到这里了，如果觉得不错，随手点个赞、在看、转发三连吧，如果想第一时间收到推送，也可以给我个星标⭐～

谢谢你看我的文章，我们，下次再见。