你买了一本厚达 500 页的技术书，认真读完一遍，三个月后只记得大概的章节标题，具体概念和应用场景全忘了。这个场景对每个开发者都不陌生。
book-to-skill 试图用一种新方式解决这个老问题：把整本书"编译"成 AI 编程助手的技能（skill），以后遇到相关问题时，AI 直接从技能中调用对应的知识框架来回答你，不需要你翻书，也不需要把整本 PDF 塞进上下文窗口。
这个项目在 GitHub 上已经积累超过 11,600 个 star，近日日增超过 400 个，被 Trendshift 评为当日 Python 仓库第 10 名。
核心思路：编译时结构化，而非运行时检索
大多数人遇到"让 AI 读书"这个问题时，第一反应是把 PDF 或 EPUB 文件直接丢进 Claude 或 ChatGPT 的上下文窗口。book-to-skill 认为这种方式有三个根本性的问题：
第一，token 成本高昂且持续累积。 一本 400 页的书大约 20 万 token，每次对话都要为此买单。使用技能方案后，只有与你当前问题相关的章节会加载到上下文中，通常只需约 5000 token 的核心技能描述加上约 1000 token 的单章摘要。
第二，"发现循环"的隐形税收。 PDF 阅读 Agent 在回答一个问题时需要反复导航——先看目录，发现一个不认识的术语就去翻对应的页码，然后发现不对再回头继续找。每一次导航的中间结果都留在对话历史中，后续每一轮对话都要重新处理这些历史 token。book-to-skill 把这个导航成本在"编译时"一次性支付，运行时 Agent 只需加载一个小型核心和一个预编译好的章节文件。
项目提供了实测数据来量化这个差距。使用 tools/discovery_tax.py 在三本真实书籍上测量，回答一个针对性问题所需的上下文 token 数：
| 书籍（规模） | 直接注入上下文 | 发现循环 | book-to-skill | 相比注入/循环 |
|---|---|---|---|---|
| Think Python 2（119K，小章节） | 119,264 | 12,152 | ~5,000 | 24× / 2.4× |
| Working Backwards（175K，中章节） | 175,253 | 33,444 | ~5,000 | 35× / 6.7× |
| AI Engineering（256K，大章节） | 256,287 | 77,866 | ~5,000 | 51× / 15.6× |
优势随章节规模增大而扩大。对于拥有大上下文窗口的模型（比如 1M token 窗口），上下文注入变得"可行"但并不"划算"——你每次对话都在为一个你只需要其中一小部分的文本付费。
第三，检索不等于推理。 RAG（检索增强生成）通过分块、嵌入、相似度搜索来找到相关段落并注入提示词，优化的是"找到提到 X 的那段话"。book-to-skill 在编译阶段做的是深度分析：提取作者构建的命名框架、决策规则和反模式，输出的是结构化的推理材料，不是原文的相似度匹配。
用项目自己的类比来说：RAG 回答"这里有一些和你的问题相近的文本片段"，技能回答"这是作者构建的 12 个框架，随时可以用来推理"。
架构：确定性提取 + 生成式分析
book-to-skill 的设计分为两半。前半部分是用 Python 编写的确定性提取器，后半部分是由 AI Agent 按照 SKILL.md 规格驱动的生成器。
提取器（Python，确定性）
提取器的职责是将各种格式的文档转换为干净的纯文本和元数据。它按格式优先使用最佳工具，同时提供标准库兜底：
- PDF：纯文本类书籍用
pdftotext（瞬间完成）或pypdf；技术类书籍（含代码、表格、公式）用docling（约 1.5 秒/页，能保留 Markdown 表格和代码块）。在提取前，工具会询问书籍类型并自动选择。 - EPUB：优先
ebooklib+beautifulsoup4，兜底用标准库zipfile。 - DOCX：
python-docx，兜底用标准库 ZIP/XML 解析。 - 其他：HTML 用
beautifulsoup4，RTF 用striprtf，MOBI/AZW/AZW3 需要 Calibre 的ebook-convert。纯文本、Markdown、reStructuredText、AsciiDoc 不需要额外依赖。
提取结果输出到临时目录，包含一个合并所有源的 full_text.txt（带来源标记）和一个 metadata.json（页数、词数、token 数、章节、目录）。处理完成后临时目录被清理。
提取器对安全性也做了加固。最新的 CHANGELOG 显示：DOCX 解析器会在解析前扫描存档并拒绝声明 DTD 或实体的 XML 部分，阻断 XXE 和实体扩展攻击；所有传给 pdftotext / pdfinfo / ebook-convert 的文件路径都会先转为绝对路径，防止文件名以 - 开头时被解释为命令行参数；生成的技能在被接受或发布前会经过一个无依赖的提示注入扫描器，标记指令覆盖短语、模型控制标签、不可见 Unicode 字符等。
生成器（Agent，遵循 SKILL.md 规格）
生成器是 AI Agent（Claude Code、GitHub Copilot CLI 或 Amp）按照项目的 SKILL.md 定义执行的生成流程。关键步骤包括：
- 判定书籍类型：技术类还是纯文本类，决定提取工具。
- 结构分析：从提取文本中识别标题、作者、章节结构和目录。
- 按章节生成摘要：每章 800-1200 token，技术类书籍额外包含代码示例和参考表格。
- 生成决策层文件：glossary.md（术语表）、patterns.md（技术/算法/设计模式）、cheatsheet.md（决策表和快速参考规则）。
- 生成 SKILL.md 核心：包含核心思维模型和章节索引，约 4000 token。
最终的技能文件结构：
| 文件 | 用途 | 大小 |
|---|---|---|
SKILL.md | 核心思维模型 + 章节索引 | ~4,000 token |
chapters/ch01-*.md 等 | 每章一个文件，按需加载 | ~1,000 token/章 |
glossary.md | 全部关键术语，按字母排序并标注章节引用 | ~1,500 token |
patterns.md | 所有技术、算法和设计模式 | ~2,000 token |
cheatsheet.md | 决策表和快速参考规则 | ~1,000 token |
章节文件是按需加载的——在你问到对应话题之前，它们不计入技能的 token 预算。
实际转换成本
项目在真实书籍上测量了转换成本（使用 Claude Sonnet 4.5 定价 $3/$15 per MTok 估算）：
| 书籍 | 格式 | 页数 | Token 数 | 章节数 | 约花费 |
|---|---|---|---|---|---|
| Think Python 2 | 244 | 119K | 19 | $0.88 | |
| Working Backwards | 371 | 175K | 10 | $0.96 | |
| Pro Git | 501 | 229K | — | $1.23 | |
| Moby-Dick | EPUB | — | 301K | — | $1.42 |
大约每本书 1 美元的转换成本。这个成本只支付一次，之后每次使用都只加载需要的片段。
Agent Skills 开放标准
book-to-skill 遵循开放的 Agent Skills 标准。同一份生成的技能可以被多个 AI 编程助手读取：
- GitHub Copilot CLI：安装到
~/.copilot/skills/<slug>/ - Amp（跨 Agent 路径）：安装到
~/.agents/skills/<slug>/ - Claude Code：安装到
~/.claude/skills/<slug>/
安装后，在 Agent 会话中直接用斜杠命令调用：
# 加载核心思维模型
/designing-data-intensive-apps
# 查找并解释某个话题
/designing-data-intensive-apps replication
# 直接进入第 5 章
/designing-data-intensive-apps ch05Agent 根据你的输入判断需要加载哪个章节文件，只读取相关内容来回答，不需要扫描全书。
不只是书：内部文档、品牌规范、论文集
虽然项目名叫 "book-to-skill"，但输入可以是任何结构化的文本内容。README 中列出了几个适用场景：
- 内部文档：架构决策记录、运维手册、新人入职指南，把整个
docs/目录折叠成一个技能，编码时随时查询。 - 品牌和设计系统：语气指南、品牌手册，把一份 60 页的 PDF 变成团队查询的技能。
- 论文集群：一堆论文加上你自己的笔记，合并成一个统一的技能，新论文可以随时追加（通过 Update/fold-in 模式）。
- 规范和标准：RFC、API 合约、合规文档，你经常需要引用但记不住全部内容的东西。
项目还支持多文件一次性处理。可以把多个 PDF、EPUB、Markdown 文件指向同一个技能：
# 把多份文件合并成一个统一技能
/book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-research
# 处理整个文件夹
/book-to-skill ~/workspace/project-docs/ project-knowledge
# 后续追加新材料到已有技能
/book-to-skill ~/articles/new-paper.pdf ~/.claude/skills/project-knowledge章节检测的限制
book-to-skill 的自动章节检测依赖明确的标题格式：Chapter N、Capítulo N、第N章、บทที่ N（泰语）等。使用标题或罗马数字标记章节的书籍（如 Pro Git 用章节标题而非序号、Moby-Dick 用罗马数字）无法自动分段，提取和转换仍然正常工作，但需要手动指向各个章节。
这一点在 CHANGELOG 中被标注为已知限制，项目正在逐步扩展支持的标题格式。
与 NotebookLM 和 RAG 的定位差异
book-to-skill 在 FAQ 中明确了自己的定位边界：
- 对 NotebookLM：如果你有 80 本书需要跨库搜索，NotebookLM 是正确的工具。book-to-skill 适用于你想在某个具体话题上深入、把多份相关文档合并成一个技能、并随时间不断更新的场景。
- 对 RAG：RAG 优化的是"找到提到 X 的那段话"（宽而浅），book-to-skill 优化的是"掌握一本书的框架并应用到工作中"（窄而深）。两者互补：RAG 索引一个书架，book-to-skill 精读一本书脊。
安装方式
项目提供两种安装路径，两者不可混淆：
作为 Agent 技能（获取 /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作为独立 CLI（仅安装文本提取引擎，用于脚本化场景，不注册 Agent 技能）：
pip install "book-to-skill[pdf,epub,docx]"
book-to-skill ~/path/to/book.pdf --mode text项目采用 MIT 协议，处理在本地完成，不上传你的文件。生成的技能是你自己的笔记——结构化的衍生品（框架名称、定义、要点），不是原文的复制。项目明确提醒：对受版权保护的书生成的技能应保持私有，不要公开分发。
适用场景与局限
book-to-skill 在以下场景中表现最好：你拥有一本书并会反复回到它，需要在实际工作中调用其中的框架和决策规则。对于只读一次就不再翻阅的内容，普通的 PDF Agent 就够了。
当前版本的局限包括：章节自动检测需要明确的序号格式标题；转换过程依赖 AI Agent 的模型质量（需要 Sonnet 级别或更强的模型来生成高质量摘要）；整本转换大约花费 1 美元/书的 API 成本。
项目活跃维护中，最新更新加入了泰语章节标题检测、提示注入安全扫描、XXE 攻击防护等安全加固，以及 PyPDF2 到 pypdf 的迁移。GitHub 上 16 位贡献者持续提交改进。
项目地址：github.com/virgiliojr94/book-to-skill
License：MIT