book-to-skill

将任何技术书籍、文档文件夹或资源集合转化为统一的 agent skill —— 随时准备好在 GitHub Copilot CLI、Amp 或 Claude Code 中进行学习、参考和使用。

🏆 荣获 Trendshift 当日十大 Python 仓库 (#10) 及 当日二十大仓库 (#25)（2026年5月23日）

为什么使用 · 生成内容 · 超越书籍 · 用法 · 环境要求 · 工作原理 · Discovery Loop 开销 · 常见问题 · 安装 · 更新日志 · 性能 · 架构

与直接将整本书倾倒在 context 中相比，回答一个问题所需的 token 量可减少 24 倍至 51 倍，此数据基于真实书籍测量得出（测量方法）。

**工作原理，分为 3 步：** 1. **指向**一个文件、文件夹或 glob 匹配模式 —— `/book-to-skill ./my-book.pdf` 2. **将其提炼**为一个 skill —— 包含框架、决策规则、反模式以及按章节划分的文件。提供的是结构，而非简单的摘要。 3. **你的 agent 按需加载** —— 输入 `/my-book replication`，它就会读取正确的章节并基于真实内容回答，没有幻觉。 ## 🤔 为什么使用 你买了一本很棒的技术书。你读了一遍。三个月后，你甚至不记得还有第 7 章这回事。 常见的变通方法无济于事： - 📄 “让我直接搜索 PDF” → 你得到的是一堆页码，而不是答案 - 🧠 “我会去问 agent 关于这本书的问题” → 它要么产生幻觉，要么说它没有相关内容 - 📝 “我会在阅读时做笔记” → 你最终会得到一份 200 行的文档，然后再也不会打开它 **book-to-skill 通过将书籍转化为 agent 按需加载的结构化 skill 来解决这个问题。** 安装完成后，你只需输入 `/your-book-slug replication`，agent 就会读取正确的章节并根据实际内容进行回答。没有幻觉，也不用在 PDF 里翻找。这本书从此成为你工作流的一部分。 适用于任何支持开放 [Agent Skills](https://github.com/agentskills/agentskills) 标准的宿主环境 —— GitHub Copilot CLI、Amp 和 Claude Code 都能读取相同的 `SKILL.md` 格式。 ## 📦 生成内容 运行 `/book-to-skill your-book.pdf`（或指向一个文件夹、glob 模式或文件列表）会在你的 agent skills 目录中创建一个完整的 skill（Copilot CLI 对应 `~/.copilot/skills//`，Amp 或跨 agent 应用对应 `~/.agents/skills//`，Claude Code 对应 `~/.claude/skills//`）： | 文件 | 用途 | 大小 | |------|---------|------| | `SKILL.md` | 核心心智模型 + 章节索引 | ~4,000 tokens | | `chapters/ch01-*.md` … | 每章一个文件，按需加载 | 每个约 1,000 tokens | | `glossary.md` | 所有关键术语，按字母顺序排列并附带章节引用 | ~1,500 tokens | | `patterns.md` | 所有的技术、算法和设计模式 | ~2,000 tokens | | `cheatsheet.md` | 决策表和快速参考规则 | ~1,000 tokens | **章节文件按需加载** —— 在你询问相关主题之前，它们不会占用 skill 的预算。 ## 🏢 超越书籍 名字虽然叫“book”，但输入的内容可以是任何结构化的文本。同样的提取逻辑也适用于你拥有并经常反复阅读的知识载体： - **内部文档** —— 架构决策记录、运维手册、新员工入职指南。将整个 `docs/` 文件夹折叠成一个 skill，在写代码时随时向它提问。 - **品牌与设计系统** —— 品牌语调指南、文档风格、组件原则。把品牌手册变成你的团队可以随时查询的 skill，而不是去翻阅 60 页的 PDF。 - **研究合集** —— 一堆论文加上你自己的笔记，合并为一个统一的 skill，并在有新材料时进行更新（参见[更新 / 折叠融合](#-usage)）。 - **规范与标准** —— 你经常参考但从未记住的 RFC、API 契约、合规文档。 如果你经常重新打开某个文档，甚至希望自己能背下来，那它就是潜在的候选对象。 ## 🚀 用法 ``` /book-to-skill ... [skill-name-slug] ``` 支持的文档格式：PDF, EPUB, DOCX, TXT, Markdown, reStructuredText, AsciiDoc, HTML, RTF, MOBI/AZW/AZW3。 **示例：** ``` # 将多个文件一起处理为一个统一的 skill /book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-research # 将文件夹中所有支持的文件一起处理 /book-to-skill ~/workspace/project-docs/ project-knowledge # 处理匹配 glob pattern 的文件 /book-to-skill "~/books/*.epub" my-library # 更新/合并新材料到现有的 skill 文件夹中 /book-to-skill ~/articles/new-paper.pdf ~/.claude/skills/project-knowledge ``` skill 创建完成后，像使用其他任何 agent skill 一样使用它： ``` /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?" ``` 在 GitHub Copilot CLI 中，文件写入后你可能需要运行 `/skills reload`，新 skill 才会出现在 `/skills list` 中。Claude Code 和 Amp 会在下一次会话中自动识别它。 ## 🔧 环境要求 提取器会按格式顺序尝试各种工具，并使用第一个可用的工具。如果没有安装任何工具，它会提示你需要运行哪个命令。纯文本、Markdown、reStructuredText 和 AsciiDoc 不需要额外的依赖。 **PDF — 根据书籍类型选择：** | 书籍类型 | 工具 | 安装命令 | 速度 | |-----------|------|---------|-------| | 文本为主（散文、表格较少） | `pdftotext` (poppler) | `sudo apt install poppler-utils` | ⚡ 即时 | | 文本为主的备选方案 | `pypdf` | `pip3 install pypdf` | ⚡ 即时 | | 文本为主的备选方案 | `pdfminer.six` | `pip3 install pdfminer.six` | ⚡ 即时 | | **技术类（代码、表格、公式）** | **`docling`** | `pip3 install docling` | ~1.5秒/页 | **EPUB：** | 工具 | 安装命令 | 质量 | |------|---------|---------| | `ebooklib` + `beautifulsoup4` | `pip3 install ebooklib beautifulsoup4` | ⭐⭐⭐ 最佳 | | 标准库 `zipfile` | 内置 —— 无需安装 | ⭐⭐ 随时可用 | **其他格式：** | 格式 | 工具 | 安装命令 | |--------|------|---------| | DOCX | `python-docx` (备选：标准库 ZIP/XML) | `pip3 install python-docx` | | HTML | `beautifulsoup4` (备选：标准库 `html.parser`) | `pip3 install beautifulsoup4` | | RTF | `striprtf` (备选：regex) | `pip3 install striprtf` | | MOBI / AZW / AZW3 | Calibre `ebook-convert` (外部应用，非 pip) | https://calibre-ebook.com/download | | TXT / Markdown / reStructuredText / AsciiDoc | 内置 | — | ## ⚙️ 工作原理 ``` One file · a folder · a glob · a list of paths │ ▼ Step 1.5 — "Technical or text-heavy book?" │ ├── technical → Docling (tables + code blocks as markdown, ~1.5s/page) └── text → pdftotext → pypdf → pdfminer (instant) │ ▼ scripts/extract.py --mode per source: PDF → pdftotext/Docling · EPUB → ebooklib → stdlib zipfile · DOCX/HTML/RTF/… (one bad source is skipped with a warning; the rest still process) │ ├── /tmp/book_skill_work/full_text.txt (all sources merged, with source markers) └── /tmp/book_skill_work/metadata.json (aggregated stats + per-source array) │ ▼ Claude analyzes structure (title, author, chapters, ToC — spanning all sources) ── or, if targeting an existing skill: folds new content in (Mode 4) │ ▼ Generates per-chapter summaries (800–1,200 tokens each) technical → includes Code Examples + Reference Tables sections Generates glossary, patterns, cheatsheet Generates master SKILL.md with core mental models │ ▼ Skill written to one of: ~/.copilot/skills// (GitHub Copilot CLI) ~/.agents/skills// (Copilot CLI or Amp, cross-agent) ~/.claude/skills// (Claude Code) /tmp/book_skill_work/ 🗑️ cleaned up ``` **提取基准测试**（103页技术书籍，仅使用 CPU）： | 方法 | 耗时 | Tokens | 表格 | 代码块 | |--------|------|--------|--------|-------------| | pdftotext | 0.1秒 | 27K | 0 | 0 | | Docling | 164秒 | 27K (+1.2%) | 48 | 36 | **真实转换案例**（测量数据：页数，提取的 token 数，自动检测到的章节数， 基于 Claude Sonnet 4.5 \$3/\$15 每百万 tokens 估算的单次处理成本）： | 书籍 | 格式 | 页数 | Tokens | 章节数 | ~成本 | |------|--------|------:|-------:|---------:|------:| | Think Python 2 | PDF | 244 | 119K | 19 | \$0.88 | | Working Backwards | PDF | 371 | 175K | 10 | \$0.96 | | Pro Git | PDF | 501 | 229K | — † | \$1.23 | | Moby-Dick | EPUB | — | 301K | — † | \$1.42 | † 章节自动检测需要明确的 `Chapter N` / `Capítulo N` 标题。Pro Git 使用分节标题，而 Moby-Dick 使用章节*标题* / 罗马数字，因此两者都 无法自动分段 —— 提取和转换仍然有效，但你需要手动指定章节位置。 生成一个完整的 skill 成本大约为**每本书 \$1**；这远低于每次会话都要重新阅读 PDF 的代价。

设计原则（点击展开）

1. **密度重于完整性** —— 1,000 token 的摘要胜过 10,000 token 的摘录 2. **实践者口吻** —— 是“当 Y 发生时使用 X”，而不是“书中解释了 X” 3. **前置加载 SKILL.md** —— 压缩机制保留了前 ~5,000 个 token；最重要的内容放在最前面 4. **按需加载章节** —— 主题索引会告诉 Claude 读取哪个文件；章节仅在需要时加载 5. **绝不输出原始文本** —— 始终对源文件进行合成、总结并提取信号

## 🧾 Discovery Loop 开销 一个阅读 PDF 的 agent 不仅仅是阅读 —— 它还在*导航*。你问它一个问题，它就会 抓取目录，发现一个它无法定义的术语，接着拉取更多页面，然后回溯。每一次这样的跳跃操作都会留在对话历史记录中，并在**随后的每一轮对话中被重新处理**。为了维持在预算范围内，sub-agent 随后被迫以极高的压缩率压缩它所读取的内容，最终交给主 agent 一份**它无法根据源文件进行事实核查的劣质摘要**。 book-to-skill 在**编译时一次性支付了这些导航成本**。在运行期间，助手只需加载一个极小的常驻核心文件和它需要的那一个预编译章节 —— 没有 discovery loop，无需为适应限制而压缩，并且完整的提取源文件会保留在磁盘上以供核查。 **实测数据，而非空谈。** 对三本真实书籍运行 [`tools/discovery_tax.py`](tools/discovery_tax.py) —— 即为了回答一个针对性问题而输入 context 的 token 数量 （book-to-skill = 常驻核心 + 一个编译章节 ≈ 5,000 tokens）： | 书籍（大小） | Context 填满 | Discovery loop | book-to-skill | 对比 dump / loop | |-------------|-------------:|---------------:|--------------:|:--------------:| | 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×** | 这种优势会**随着章节大小的增加而放大**：与 context dump 相比，其优势保持在 24–51 倍之间（并且该成本在*每一轮*中都会重复发生）；对比一次性的 discovery loop，其优势在以小章节为主的书籍中为 2.4 倍，而在以大章节为主的书籍中高达 15.6 倍。在你自己的书籍上复现该结果： ``` python3 tools/discovery_tax.py --full-text /tmp/book_skill_work/full_text.txt --target-chapter 5 ``` ## ❓ 常见问题 **“难道我不能直接把 PDF/EPUB 倾倒进我的 Claude 项目 context 中吗？”** 你可以这么做 —— 但每次对话都会在一开始就耗尽那笔 token 预算。一本 400 页的书大约相当于 20 万个 token。使用 skill，只有与你问题相关的章节才会被加载 —— 通常是一个 SKILL.md 核心（~4K）加上你询问的那个章节（~1K其余部分会留在磁盘上，直到你需要它。 其经济学原理在于分摊成本，而不是大小。粘贴整本书意味着在**永远地，每一次会话的每一轮中**都要支付全款 token 账单。book-to-skill 只需支付**一次**提取成本，随后的每次对话只需加载它需要的那一小部分即可。你的 context 窗口越大，这一点就越重要 —— 大窗口只是让这种 dump 变得*可行*，但并不会让它变得*便宜*。 更重要的是：注入原始文本属于检索（retrieval）。而 skill 是推理（reasoning）。当 Claude 加载章节文件时，它不是在寻找关键词匹配 —— 而是在处理预先提取的、命名的框架、原则和心智模型，这些结构是为应用而设计的，而不是为了阅读。 **“Claude 现在有 100 万 token 的 context 窗口了 —— 难道我不能直接把整本书一直加载在里面吗？”** 更大的窗口改变的是*能装下多少*，而不是*有多明智*。有三个原因说明它无法替代 skill： - **每次调用都要为 token 付费。** 1M 的窗口并不能让这些 token 免费 —— 它只是让一笔庞大且重复的账单成为可能。skill 加载的是千字节，而不是兆字节。 - **填满内容后召回率会下降。** 当模型在一个近乎满载的 context 中检索某个特定事实时，精度会降低（即“迷失在中间”现象）。为了回答一个问题，一个经过精心整理的 1K token 章节胜过 20 万 token 的原始文本。 - **窗口 ≠ 结构。** context 中的整本书仍然是原始文本，模型必须在每一轮对话中重新解析它。而 skill 提供的是预先提取的框架 —— 是推理，而非检索。 将大窗口用于它擅长的场景：处理那些你以后再也不会用到的材料。而对于那些你会反复查阅的知识，请使用 skill。 **“这不就是 RAG 吗？”** RAG 工作在查询阶段：将书籍分块 → 对所有内容进行向量化 → 寻找相似的向量 → 注入到 prompt 中。它针对“帮我找到谈论 X 的那部分”进行了优化。 book-to-skill 工作在编译阶段：一次深度的分析过程会提取作者实际的框架，为它们命名，描述每个框架的适用场景，并捕捉反模式。其输出是作者花了数年时间构建的结构 —— 而不是在他们句子上的相似性搜索。 RAG 的回答是：*“这里有一些与你的查询很接近的文本块。”* 而 skill 的回答是：*“这里有这位作者构建的 12 个框架，随时可以用来进行推理。”* 根据任务的性质进行选择： - **广而浅** —— 一个包含数十本书的图书馆，“找到提到 X 的部分” → RAG 工具（例如 CandleKeep）胜出。 - **窄而深** —— 一本书或一组紧密相关的资源，需要你在工作时应用的框架 → book-to-skill 胜出。 它们是互补的，而不是相互竞争的：RAG 索引的是整个书架，而 book-to-skill 掌握的是一本书的核心。 **“那些热门书籍早就包含在 Claude 的训练数据中了。为什么还要费这个劲？”** 对于广为人知的书籍（如《Clean Code》、《DDIA》、《Pragmatic Programmer》），Claude 具备一般性的知识 —— 但这种知识是经过压缩的，是整个互联网上关于该书讨论的平均集合，并且可能会对具体的引用或章节位置产生幻觉。 book-to-skill 基于你的实际副本工作。每一个框架名称、每一份反模式列表、每一个章节号都根植于你提供的文本中。没有训练数据的偏差，也没有幻觉产生的章节标题。 对于 Claude 根本不知道的书籍，它同样大放异彩：比如小众的技术参考书、内部公司文档、最新出版物或翻译作品。 **“NotebookLM 在处理多本书籍方面做得更好。”** 确实如此 —— 如果你的工作流是“我有 80 本不同的书，我想在所有这些书中进行搜索”，那么 NotebookLM 是正确的工具。 book-to-skill 是为另一种需求构建的：你想深入了解某个特定的主题或库，将多个相关文档（论文、章节、笔记）折叠融合为一个单一的、统一的 skill，甚至随着时间的推移通过新材料不断更新它！这会将你定制的知识库直接集成到你的编码或写作工作流中，而不是让它待在一个单独的浏览器标签页里。 ## 📥 安装 该 skill 遵循开放 [Agent Skills](https://github.com/agentskills/agentskills) 标准，只需一次安装即可适用于任何兼容的宿主环境。 **GitHub Copilot CLI**（个人 skill）： ``` git clone https://github.com/virgiliojr94/book-to-skill.git ~/.copilot/skills/book-to-skill # 然后，在一个 `copilot` session 中： /skills reload /skills info book-to-skill ``` 或者使用 Copilot CLI 和 Amp 都能发现的跨 agent 路径： ``` git clone https://github.com/virgiliojr94/book-to-skill.git ~/.agents/skills/book-to-skill ``` **Claude Code**: 将以下内容复制到你的 Claude Code 会话中： ``` Install book-to-skill: https://raw.githubusercontent.com/virgiliojr94/book-to-skill/master/SKILL.md ``` 或者使用标准的 `git clone` 手动安装（确保正确获取模块化的引擎文件）： ``` git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill ``` 然后在任何 agent 会话中： ``` /book-to-skill ~/path/to/your-book.pdf # 或 /book-to-skill ~/path/to/your-book.epub ``` ### 独立 CLI (pip) `pip install book-to-skill` 是一条**独立的、可选的**路径。它仅将 文本提取引擎作为 CLI 安装，用于编写脚本或获取可选的提取器； 它**不会**注册 `/book-to-skill` agent skill（如果要注册 skill，请使用上面的 `git clone` 方法）。 ``` 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 ``` ## 📁 仓库结构 ``` book-to-skill/ ├── SKILL.md # Skill definition + step-by-step instructions (the generator spec) ├── scripts/ │ ├── extract.py # Thin entrypoint wrapper │ └── extractor/ # Modular extraction package │ ├── config.py # Extensions, paths, dependency constants │ ├── dependencies.py # optional-dep probing + --check │ ├── exceptions.py # ExtractionError (per-source failures, batch-safe) │ ├── utils.py # CLI parsing, multi-source resolution, chapter detection, runner │ └── parsers/ # Format-specific parsers (pdf, epub, docx, html, rtf, calibre, text) ├── tools/ │ ├── discovery_tax.py # measures token cost vs context-dump / discovery loop │ └── validate_skill.py # checks a generated SKILL.md against host rules (--lens claude|copilot|amp) ├── tests/ # pytest suite (extraction, detection, discovery tax) ├── docs/ │ ├── PERFORMANCE.md # measured benchmarks, discovery tax, cost │ └── ARCHITECTURE.md # pipeline + component map ├── CHANGELOG.md # release history (semver) ├── CONTRIBUTING.md # dev setup, PR conventions, release process ├── SECURITY.md # vulnerability reporting └── README.md # This file ``` ## ⚖️ 版权与合理使用 book-to-skill **不附带任何书籍内容** —— 连一页都没有。它只是一个转换器，由你指向你已有的文件。 - **本地处理。** 提取和分析都在你的机器上运行。此工具永远不会上传你的文件。（如果你的 agent 模型在云端运行，你输入的文本将遵循该提供商的正常数据条款 —— 与任何 prompt 相同。） - **使用你自己的副本。** 带来你购买的书籍、你公司拥有的文档，或者你有权阅读的论文。 - **输出的是你的笔记。** 生成的 skill 是一种结构化、合成的派生物 —— 包含框架名称、定义、要点 —— 而不是文本的复制品。该 skill 明确声明永远不复制原始段落（参见质量规则 #7）。请把它当作手写的学习笔记：归你所有，仅供个人使用。 - **请勿重新分发。** 发布或共享受版权保护作品的生成 skill 可能会侵犯权利人的权益。请将第三方书籍的 skill 保持私有。对于内部文档、你自己的写作或开放许可的材料，可以在其许可范围内进行分享。 如有疑问，请遵循源文档的许可或条款。本项目仅提供工具；你如何使用它由你自己承担负责。 ## 💖 赞助者 book-to-skill 是免费且基于 MIT 许可证的开源项目，利用个人时间进行维护。如果它为你节省了 token 或学习时间，请考虑赞助其维护工作：包括 PR 审查、多语言修复、发布和文档编写。 **[成为赞助者 → github.com/sponsors/virgiliojr94](https://github.com/sponsors/virgiliojr94)** 每位赞助者都列在 [BACKERS.md](BACKERS.md) 中。感谢你让开源、隐私至上的工具保持活力。✨ ## 许可证 MIT —— 适用于本仓库中的转换器（代码 + skill 定义），**不适用于**你使用它处理的任何书籍或文档。 ## Star 历史

标签：Agent技能, AI编程助手, RAG, SOC Prime, 开发工具, 文档处理, 知识库构建, 逆向工具