book-to-skill

将技术书籍PDF（或文档夹）一键转化为AI Agent可直接调用的结构化技能，支持Claude Code、Copilot CLI等平台。一次编译后按需加载章节，相比直接塞全书能节省24-51倍token成本，且本地处理不上传。亮点在于把作者的思维框架而非纯文本提取出来，让Agent真正理解并应用，而不是RAG式的语义搜索。开源MIT，适合频繁翻阅技术书的开发者。

README

book-to-skill 标志

book-to-skill

将任意技术书籍、文档文件夹或源集合转化为统一的 Agent 技能——在 GitHub Copilot CLI、Amp 或 Claude Code 中边工作边学习、查阅和使用。

Agent Skills 标准支持的格式 MIT 许可证

🏆 #10 Python 每日仓库 和 #25 每日仓库，源自 Trendshift（2026年5月23日）

为什么 · 生成内容 · 不止于书籍 · 用法 · 需求 · 工作原理 · 发现循环开销 · 常见问题 · 安装 · 更新日志 · 性能 · 架构

回答一个问题时，使用的 token 比把整本书扔进上下文少 24×–51×，基于真实书籍测量（测量方法）。

工作原理，三步走：

指向一个文件、文件夹或 glob 模式 —— /book-to-skill ./my-book.pdf
它蒸馏书籍为技能 —— 框架、决策规则、反模式、按章节的文件。结构，而非摘要。
你的 agent 按需加载 —— 提问 /my-book replication，它读取对应章节并从真实内容中回答，不会产生幻觉。

🤔 为什么

你买了一本很棒的技术书。读了一遍。三个月后你忘了第7章的存在。

常见的应对方法都不管用：

📄 “让我搜一下 PDF” → 你得到一列页码，而不是答案
🧠 “我让 agent 来问这本书” → 它要么幻觉，要么说没有该内容
📝 “我边读边记笔记” → 你最终得到一份200行的文档，从此再也没打开过

book-to-skill 通过将书籍转化为结构化的 agent 技能来解决这个问题，你的 agent 可以按需加载。

安装后，只需输入 /your-book-slug replication，agent 就会读取相关章节并从实际内容中回答。没有幻觉。无需翻找 PDF。这本书成为你工作流程的一部分。

适用于任何支持开放 Agent Skills 标准的主机 —— GitHub Copilot CLI、Amp 和 Claude Code 都读取相同的 SKILL.md 格式。

📦 生成内容

运行 /book-to-skill your-book.pdf（或一个文件夹、glob 模式、文件列表）会在你的 agent 技能目录中创建完整的技能（Copilot CLI 在 ~/.copilot/skills/<slug>/，跨 agent 或 Amp 在 ~/.agents/skills/<slug>/，Claude Code 在 ~/.claude/skills/<slug>/）：

文件	用途	大小
`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

章节文件按需加载 —— 在你问到相关主题之前，它们不计入技能预算。

🏢 不止于书籍

名字叫“book”，但输入可以是任何结构化的散文。相同的提取方法也适用于你经常重读的知识：

内部文档 —— 架构决策记录、runbooks、入职指南。将整个 docs/ 文件夹合并成一个技能，写代码时直接提问。
品牌与设计系统 —— 语音指南、语调文档、组件原则。将品牌手册转化为技能，团队查询即可，无需翻阅60页 PDF。
研究集群 —— 一堆论文加上你自己的笔记，合并成一个统一的技能，并随着新资料到来而更新（参见更新 / 折叠）。
规范与标准 —— RFC、API 合同、合规文档，你经常参考但从未记住。

如果你经常重新打开一份文档，以至于希望自己已经记住它，那它就是候选。

🚀 用法

/book-to-skill <路径到文档-文件夹-或-glob>... [技能名称-slug]

支持的文档格式：PDF, EPUB, DOCX, TXT, Markdown, reStructuredText, AsciiDoc, HTML, RTF, MOBI/AZW/AZW3。

示例：

# 将多个文件一起处理成一个统一技能
/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

# 将新资料更新/折叠到现有技能文件夹中
/book-to-skill ~/articles/new-paper.pdf ~/.claude/skills/project-knowledge

技能创建后，像使用其他 agent 技能一样使用：

/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，新技能才会出现在 /skills list 中。Claude Code 和 Amp 会在下次会话中自动识别。

🔧 需求

提取器会按格式依次尝试工具，并使用第一个可用的。如果没有任何工具安装，它会告诉你需要运行哪个命令。纯文本、Markdown、reStructuredText 和 AsciiDoc 无需额外依赖。

一条命令检查你的环境： python3 scripts/extract.py --check 会报告每个格式安装了哪些提取器，以及安装缺失项的确切命令——无需文件。

PDF —— 按书籍类型选择：

书籍类型	工具	安装	速度
以文本为主（散文，少量表格）	`pdftotext` (poppler)	`sudo apt install poppler-utils`	⚡ 瞬间
以文本为主备选	`pypdf`	`pip3 install pypdf`	⚡ 瞬间
以文本为主备选	`pdfminer.six`	`pip3 install pdfminer.six`	⚡ 瞬间
技术类（代码、表格、公式）	`docling`	`pip3 install docling`	~1.5秒/页

在提取开始前，技能会询问该书是 技术类 还是 以文本为主，并自动选择合适的工具。Docling 保留 markdown 表格和代码块；pdftotext 对纯散文类书籍更快。

EPUB：

工具	安装	质量
`ebooklib` + `beautifulsoup4`	`pip3 install ebooklib beautifulsoup4`	⭐⭐⭐ 最佳
stdlib `zipfile`	内置——无需安装	⭐⭐ 总是可用

其他格式：

格式	工具	安装
DOCX	`python-docx`（备选：stdlib ZIP/XML）	`pip3 install python-docx`
HTML	`beautifulsoup4`（备选：stdlib `html.parser`）	`pip3 install beautifulsoup4`
RTF	`striprtf`（备选：正则表达式）	`pip3 install striprtf`
MOBI / AZW / AZW3	Calibre `ebook-convert`（外部应用，非 pip）	https://calibre-ebook.com/download
TXT / Markdown / reStructuredText / AsciiDoc	内置	—

⚙️ 工作原理

单个文件 · 一个文件夹 · 一个 glob · 一组路径
     │
     ▼
第1.5步 —— “技术类还是文本类书籍？”
     │
     ├── 技术类 → Docling  （表格 + 代码块以 markdown 形式，~1.5秒/页）
     └── 文本类 → pdftotext → pypdf → pdfminer  （瞬间）
     │
     ▼
scripts/extract.py <路径…> --mode <technical|text>
  每个源：PDF → pdftotext/Docling · EPUB → ebooklib → stdlib zipfile · DOCX/HTML/RTF/…
  （单个损坏的源会跳过并给出警告；其余正常处理）
     │
     ├── /tmp/book_skill_work/full_text.txt   （所有源合并，带源标记）
     └── /tmp/book_skill_work/metadata.json   （聚合统计 + 每个源的数组）
               │
               ▼
           Claude 分析结构
          （标题、作者、章节、目录——跨越所有源）
          ── 或者，如果指定现有技能：将新内容折叠进去（模式4）
               │
               ▼
          生成每章摘要  （800–1,200 tokens 每个）
          技术类 → 包含“代码示例”和“参考表格”部分
          生成术语表、模式、速查表
          生成主 SKILL.md，包含核心心智模型
               │
               ▼
          技能写入以下之一：
            ~/.copilot/skills/<slug>/   （GitHub Copilot CLI）
            ~/.agents/skills/<slug>/    （Copilot CLI 或 Amp，跨 agent）
            ~/.claude/skills/<slug>/    （Claude Code）
          /tmp/book_skill_work/         🗑️ 清理

提取基准测试（103页技术书籍，仅 CPU）：

方法	时间	Tokens	表格	代码块
pdftotext	0.1s	27K	0	0
Docling	164s	27K (+1.2%)	48	36

实际转换（测量：页数、提取的 tokens、自动检测的章节数、在 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 使用章标题 / 罗马数字，因此两者都无法自动分段——提取和转换仍然有效，但需要手动指向章节。一个完整的技能大约花费 每本书 $1；远少于每次会话重读 PDF。

设计原则（点击展开）

密度高于完整性 —— 一个1000 token 的摘要胜过10000 token 的摘录
实践者语气 —— “当X时使用Y”，而不是“书中解释X”
前置 SKILL.md —— 压缩使前~5,000 tokens 紧凑；最重要的内容放前面
按需章节 —— 主题索引告诉 Claude 读取哪个文件；章节仅在需要时加载
绝不使用原始文本 —— 总是综合、摘要、从源中提取信号

🧾 发现循环开销

一个读取 PDF 的 agent 不仅仅是阅读——它还要导航。问它一个问题，它会获取目录，注意到一个无法定义的术语，拉取更多页面，回溯。每次这样的跳转都会进入对话历史，并在 后续每个回合中重新处理。为了保持在预算内，子 agent 随后被迫以粗暴的比例压缩它所读的内容，交给主 agent 一个 无法对源进行事实核查的降质摘要。

book-to-skill 只需 在编译时一次性支付 导航成本。在运行时，助手加载一个小的常驻核心加上它需要的一个预编译章节——没有发现循环，无需压缩适应，完整的提取源保留在磁盘上供验证。

经过测量，而非断言。 运行 tools/discovery_tax.py 在三本真实书籍上——回答一个针对性问题所需进入上下文的 tokens（book-to-skill = 常驻核心 + 一个编译章节 ≈ 5,000 tokens）：

书籍（大小）	全文倾倒	发现循环	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×

优势 随章节大小而扩展：对比全文倾倒，持续为 24–51×（且该成本 每一轮 都会重现）；对比一次性发现循环，范围从小章节书籍的适度 2.4× 到大章节书籍的 15.6×。在你的书籍上复现：

python3 tools/discovery_tax.py --full-text /tmp/book_skill_work/full_text.txt --target-chapter 5

诚实的注意事项： (1) 发现数据是一次性成本，并且是模型使用书籍的真实目录/章节大小 —— 调优良好的 agent 更接近最佳情况；相比之下，全文倾倒在每一轮中都会重现。 (2) 该工具需要明确的 Chapter N / Capítulo N 等标题才能分割书籍；仅标题或罗马数字的书籍（以及未使用 ebooklib 提取的 EPUB）将无法干净分割。book-to-skill 在你反复返回该知识时获胜；对于一次性单次阅读，普通的 PDF agent 就足够了。

❓ 常见问题

“我不能直接把 PDF/EPUB 丢进我的 Claude 项目上下文中吗？”

可以——但每次对话都会提前消耗那个 token 预算。一本 400 页的书大约 200K tokens。使用技能，只有与你问题相关的章节才会加载——通常是一个 SKILL.md 核心（~4K）加上你问到的一个章节（~1K）。其余部分留在磁盘上，直到你需要。

经济原理是摊销，而非大小。粘贴书籍是在 每次会话的每一轮、永久地 支付完整的 token 费用。book-to-skill 一次性支付提取成本，未来每次对话只加载需要的切片。你的上下文窗口越大，这一点就越重要——大窗口使倾倒变得可能，而非廉价。

更重要的是：原始文本注入是检索。技能是推理。当你加载一个章节文件时，Claude 不是在搜索关键词匹配——它是在处理预先提取的命名框架、原则和心智模型，这些是为应用而结构化，而非为阅读。

“Claude 现在有 1M token 上下文窗口了——我能一直加载整本书吗？”

更大的窗口改变的是 能放进去什么，而不是 什么更聪明。三个原因说明它不能替代：

每次调用，每个 token 都要付费。 1M 窗口并不会让这些 tokens 免费——它让一个大额、经常性的账单成为可能。技能加载的是千字节，而非兆字节。
召回率随填充下降。 模型在从接近满的上下文中检索特定事实时精度下降（“lost in the middle”）。一个 1K 的精选章节比 200K 的原始散文更擅长回答一个问题。
窗口 ≠ 结构。 将整本书放入上下文仍然是模型每轮必须重新解析的原始文本。技能携带的是预先提取的框架——推理，而非检索。

把大窗口用在它擅长的地方：一次性翻阅你永远不会再需要的内容。把技能用于你会反复接触的知识。

“这不就是 RAG 吗？”

RAG 在查询时工作：将书籍分块 → 嵌入所有内容 → 找到相似向量 → 注入到提示中。它优化的是“找到谈论 X 的部分”。

book-to-skill 在编译时工作：一次深度分析运行提取作者的实际框架，命名它们，描述何时使用每个，捕获反模式。输出是作者花费多年构建的结构——而不是对其句子进行的相似性搜索。

RAG 回答的是：“这是与你查询接近的块。” 技能回答的是：“这是该作者构建的 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 是为不同的任务构建的：你想深入一个特定主题或库，将多个相关文档（论文、章节、笔记）折叠成一个统一的技能，甚至随着时间的推移随着新资料的到来进行更新！这将你定制的知识库直接整合到编码或写作工作流中，而不是在单独的浏览器选项卡中。

📥 安装

两种使用方式，不要混淆：

作为 Agent 技能（在 Claude Code、Copilot CLI 或 Amp 中的 /book-to-skill 命令）→ git clone 到你的技能文件夹（见下方）。这将为你提供斜杠命令和完整的转换书籍流程。

作为独立 CLI（仅文本提取器）→ pip install book-to-skill，然后 book-to-skill --help。这不会注册 agent 技能；它只安装提取引擎。参见 CLI 部分。

该技能遵循开放的 Agent Skills 标准，因此一次安装适用于任何兼容的主机。

GitHub Copilot CLI（个人技能）：

git clone https://github.com/virgiliojr94/book-to-skill.git ~/.copilot/skills/book-to-skill
# 然后，在 `copilot` 会话中：
/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 技能（要实现该功能，请使用上面的 git clone）。

pip install "book-to-skill[pdf,epub,docx]"   # 引擎 + 可选提取器
book-to-skill ~/path/to/book.pdf --mode text  # 或者：python -m book_to_skill ...
book-to-skill --check                          # 报告安装的提取器

📁 仓库结构

book-to-skill/
├── SKILL.md              # 技能定义 + 分步说明（生成器规范）
├── scripts/
│   ├── extract.py        # 薄的入口封装
│   └── extractor/        # 模块化提取包
│       ├── config.py     # 扩展名、路径、依赖常量
│       ├── dependencies.py  # 可选依赖探测 + --check
│       ├── exceptions.py # ExtractionError（每个源失败，批处理安全）
│       ├── utils.py      # CLI 解析、多源解析、章节检测、运行器
│       └── parsers/      # 格式特定的解析器（pdf, epub, docx, html, rtf, calibre, text）
├── tools/
│   ├── discovery_tax.py  # 测量 token 成本 vs 全文倾倒 / 发现循环
│   └── validate_skill.py # 检查生成的 SKILL.md 是否符合主机规则（--lens claude|copilot|amp）
├── tests/                # pytest 套件（提取、检测、发现开销）
├── docs/
│   ├── PERFORMANCE.md    # 测量的基准、发现开销、成本
│   └── ARCHITECTURE.md   # 流水线 + 组件图
├── CHANGELOG.md          # 发布历史（semver）
├── CONTRIBUTING.md       # 开发环境、PR 约定、发布流程
├── SECURITY.md           # 漏洞报告
└── README.md             # 本文件

⚖️ 版权与合理使用

book-to-skill 不附带任何书籍内容——没有任何一页。它是一个转换器，指向你已经拥有的文件。

处理在本地进行。 提取和分析在你的机器上运行。你的文件永远不会被此工具上传。（如果你的 agent 模型运行在云端，你输入给它的文本将遵循该提供商的正常数据条款——与任何提示一样。）
你使用自己的副本。 带上你买的一本书、你公司拥有的文档、或者你有权阅读的论文。
输出是你的笔记。 生成的技能是结构化的、综合的衍生内容——框架名称、定义、要点——而不是文本的再现。该技能明确从不复制原始段落（参见质量规则第7条）。将其视作手写学习笔记：属于你，用于个人用途。
不要重新分发。 发布或共享受版权保护作品的生成技能可能侵犯权利持有人。将第三方书籍的技能保持私密。内部文档、你自己的写作以及开放许可的材料可以在其许可范围内共享。

如有疑问，请遵循源文档的许可证或条款。本项目是一个工具；如何使用取决于你自己。

💖 赞助者

book-to-skill 是免费且采用 MIT 许可的，在个人时间维护。如果它为你节省了 tokens 或学习时间，请考虑赞助其维护：PR 评审、多语言修复、发布和文档。

成为赞助者 → github.com/sponsors/virgiliojr94

每位赞助者列在 BACKERS.md 中。感谢你让开放且隐私优先的工具保持活力。✨

许可证

MIT —— 适用于本仓库中的转换器（代码 + 技能定义），不适用于你使用它处理的任何书籍或文档。

Star 历史

开源项目virgiliojr942026-07-28原文

打开互动版

book-to-skill

README

book-to-skill

🤔 为什么

📦 生成内容

🏢 不止于书籍

🚀 用法

🔧 需求

⚙️ 工作原理

🧾 发现循环开销

❓ 常见问题

📥 安装

独立 CLI (pip)

📁 仓库结构

⚖️ 版权与合理使用

💖 赞助者

许可证

Star 历史

相关内容

agent-governance-toolkit

speech-to-speech

ag-kit