book-to-skill：让吃灰的技术书变成 Claude Code 的私人顾问

你买了本《Designing Data-Intensive Applications》，读完就忘。三个月后遇到分布式系统问题，想翻书找答案——PDF 搜索给一堆页码，问 AI 它要么幻觉要么说没读过。book-to-skill 的解决方案是：把书编译成 Skill。一次提取，终身受用。400 页的书变成 4000 token 的核心模型 + 按需加载的章节文件，Claude Code 里敲 /ddia replication 它就替你翻书作答。GitHub 6000+ Star，Agent Skills 标准兼容，MIT 协议。

一、问题：技术书为什么总是吃灰？

买了书 → 读了一遍 → 记了笔记 → 三个月后忘光 → 遇到问题时翻 PDF 找不到 → 问 AI 它胡说八道。

这个循环的问题在于：

PDF 搜索：给页码，不给答案。你需要自己读完一页再一页才能定位到有用信息。

直接问 AI：Claude/GPT 对流行书有泛泛了解，但具体章节、准确引用、框架名称经常 hallucinate。它说的是"网上讨论版本"的书，不是你买的那个版本。

自己做笔记：200 行的文档你不会再打开。没有结构，没有索引，没有和 AI 工作流的集成。

book-to-skill 的作者 Virgilio 精准描述了这个痛点："You buy a great technical book. You read it once. Three months later you can't remember chapter 7 existed."

二、book-to-skill 是什么？一句话定位

一个将 PDF/EPUB/DOCX 等技术书籍编译成 AI Agent Skill 的开源工具。一次提取运行，生成结构化的 SKILL.md + 章节摘要 + 术语表 + 模式清单 + 速查表。后续在 Claude Code、GitHub Copilot CLI、Amp 中通过 /书名 调用，只加载相关章节，不浪费 token。

GitHub: https://github.com/virgiliojr94/book-to-skill
Stars: 6000+（快速增长中）
License: MIT
标准: Agent Skills 开放标准（兼容 Claude Code / Copilot CLI / Amp）

三、输出结构：一本书变成什么？

运行 /book-to-skill ~/books/ddia.pdf 后，生成：

关键设计：章节文件按需加载。不问你问题时，它们不占 token 预算。问了才读相关章节。

四、工作流：从 PDF 到 Skill

用户: /book-to-skill ~/books/ddia.pdf

1. 提取文本（根据书籍类型选择工具）
   - 技术书（代码、表格、公式）→ Docling（保留 markdown 表格和代码块）
   - 文字书（散文为主）→ pdftotext（秒级）

2. Claude 分析结构
   - 提取书名、作者、章节、目录

3. 生成每章摘要（800-1200 tokens/章）
   - 技术书额外包含：代码示例 + 参考表

4. 生成术语表、模式清单、速查表

5. 生成主 SKILL.md（核心心智模型）

6. 写入 Skill 目录
   ~/.claude/skills/ddia/
   ~/.copilot/skills/ddia/
   ~/.agents/skills/ddia/

成本：一本 400 页的书，提取一次约 ＄1（Claude Sonnet 4.5）。比每次对话都读 PDF 便宜得多。

五、为什么不用 RAG？不用上下文窗口直接加载？

5.1 vs RAG

RAG 说："Here are chunks close to your query."
Skill 说："Here are the 12 frameworks this author built, ready to reason with."

5.2 vs 直接加载 PDF 到上下文

"Claude 有 1M token 上下文了，直接塞进去不就行了？"

三个原因不成立：

1. 你按 token 付费。1M 窗口只是"能装"，不是"免费"。Skill 加载几千 token，PDF 加载几十万。

2. Recall 随填充 degrades。模型在接近满的上下文中找特定事实会丢失精度（"lost in the middle"）。1000 token 精心整理的章节 > 200K 原始散文。

3. Window ≠ Structure。完整的书在上下文里仍是原始文本，模型每轮都要重新解析。Skill 提供预提取的框架——给模型的是推理材料，不是检索材料。

5.3 vs NotebookLM

NotebookLM 擅长："我有 80 本书，想跨书搜索"。

book-to-skill 擅长："我深入学某本书，让它融入我的编码工作流"。

Skill 是代码编辑器的一部分，不是浏览器标签页。

六、发现循环税（Discovery Loop Tax）

这是论文级别的核心洞察。

问题：让 AI 读 PDF 回答一个具体问题，它不会直接翻到你需要的章节。它要：

1. 获取目录
2. 发现不认识的术语，拉更多页
3. 回溯验证
4. 每个 hop 都进入对话历史，每轮都重新处理

为了留在预算内，子 Agent 被迫以极高比例压缩读到的内容，返回主 Agent 一个它无法核实的降级摘要。

book-to-skill 的解法：在编译时一次性支付导航成本。运行时只加载常驻核心（~4000 tokens）+ 一个预编译章节（~1000 tokens）。没有发现循环，没有压缩到失真，原始提取文本存在本地磁盘可供验证。

实测对比（回答一个针对性问题）：

上下文直接加载的成本每轮对话都重复。book-to-skill 提取一次，终身使用。

七、不只技术书：任何结构化文本都可以

• 内部文档 — 架构决策记录、运维手册、入职指南。把整个 docs/ 文件夹变成一个 Skill，编码时随时问。
• 品牌设计系统 — 语音指南、组件设计原则。把品牌书变成 Skill，团队查询而不是翻 60 页 PDF。
• 研究集群 — 一叠论文 + 自己的笔记，合并成一个统一 Skill，新论文来时可增量更新。
• 规范标准 — RFC、API 契约、合规文档。

更新机制：/book-to-skill ~/new-paper.pdf ~/.claude/skills/project-knowledge 直接把新内容折叠进现有 Skill。

八、技术细节

8.1 支持的格式

PDF, EPUB, DOCX, TXT, Markdown, reStructuredText, AsciiDoc, HTML, RTF, MOBI/AZW/AZW3。

8.2 PDF 提取工具选择

自动检测：工具问"技术书还是文字书？"然后选对应提取器。

8.3 代码结构

book-to-skill/
├── SKILL.md              # 技能定义 + 提取指令
├── scripts/
│   ├── extract.py        # 入口包装器
│   └── extractor/        # 模块化提取包
│       ├── parsers/      # 格式专用解析器
│       ├── config.py     # 扩展名、路径常量
│       └── dependencies.py  # 可选依赖探测
├── tools/
│   ├── discovery_tax.py  # 测量 token 成本
│   └── validate_skill.py # 验证 SKILL.md 合规性
├── tests/                # pytest 测试套件
└── docs/
    ├── PERFORMANCE.md    # 基准测试
    └── ARCHITECTURE.md   # 架构图

九、安装与使用

Claude Code:

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

然后任意 session：

/book-to-skill ~/path/to/your-book.pdf

使用示例:

/ddia                    # 加载核心心智模型
/ddia replication        # 查找并解释某个主题
/ddia ch05               # 深入第 5 章
/ddia "what chapters do you have?"

GitHub Copilot CLI:

git clone https://github.com/virgiliojr94/book-to-skill.git ~/.copilot/skills/book-to-skill
/skills reload

十、设计原则

1. Density over completeness — 1000 token 的摘要 > 10000 token 的摘录
2. Practitioner voice — "Use X when Y"，不是 "The book explains X"
3. Front-loaded SKILL.md — 前 5000 tokens 放最重要的内容
4. On-demand chapters — 主题索引告诉 Claude 读哪个文件，需要时才加载
5. Never raw text — 总是合成、总结、提取信号，而不是复制原文

十一、版权与隐私

• 处理本地运行。提取和分析在本地执行，文件不会上传。
• 使用你自己的副本。买过的书、公司文档、有权阅读的论文。
• 输出是你的笔记。生成的 Skill 是结构化衍生作品——框架名、定义、要点——不是原文复制。像手写笔记一样，属于个人使用。
• 不要重新分发。发布或分享版权作品的 Skill 可能侵权。第三方书籍保持私有。内部文档、自己写的、开放许可的材料可以分享。

十二、一句话总结

book-to-skill 的核心洞察是：知识的载体（PDF）和知识的形态（可推理的框架）是两回事。把 400 页的书塞给 AI，你给的是检索材料；把书编译成 Skill，你给的是推理材料。前者让 AI 翻书，后者让 AI 用书。对于吃灰的技术书来说，这是一次从"拥有"到"会用"的转化。

参考信息

• 项目：book-to-skill
• GitHub：https://github.com/virgiliojr94/book-to-skill
• 作者：Virgilio（virgiliojr94）
• License：MIT（工具本身，不适用于你处理的书籍内容）
• 标准：Agent Skills 开放标准
• 兼容：Claude Code / GitHub Copilot CLI / Amp
• 支持格式：PDF, EPUB, DOCX, TXT, MD, RST, AsciiDoc, HTML, RTF, MOBI/AZW/AZW3
• 核心创新：编译时提取框架 + 按需加载章节 + 发现循环税消除
• 成本：~＄1/书（一次提取），vs 每次对话加载 PDF（＄N/对话）
• 提取性能：pdftotext 秒级（文字书），docling ~1.5s/页（技术书）
• 发现循环税：vs 直接加载 PDF 24-51× 更省，vs 发现循环 2.4-15.6× 更省

book-to-skill 让我想到一个更深层的问题：我们积累了太多"知识资产"——书籍、论文、文档、笔记——但它们大部分时间是沉睡的。不是因为没用，而是因为"提取成本"太高。翻书需要时间，搜索需要技巧，问 AI 需要幻觉验证。book-to-skill 的本质是降低知识激活的摩擦。它让我想到一个概念："知识半衰期"。技术书的知识不会过期，但我们的记忆会。编译成 Skill 不是备份，而是让知识从"被动存储"变成"主动可用"。未来的个人知识管理可能不是收集更多，而是让已有的更容易被 AI 调用。吃灰的书不是废物，只是还没被编译。

#book-to-skill #AI技能 #ClaudeCode #技术书 #知识管理 #AgentSkills #开源工具 #PDF转Skill #RAG #知识提取