一键将技术书转化为 Claude Skill

把任何技术书籍、文档文件夹或资源集合转化为统一的 AI 智能体技能——随时可在 GitHub Copilot CLI、Amp 或 Claude Code 中学习、查阅和使用。

为什么 · 生成的内容 · 超出书籍的应用 · 用法 · 环境需求 · 工作原理 · 发现循环的开销 · FAQ · 安装 · 更新日志 · 性能 · 架构

相比将书籍内容直接倒入上下文来回答一个问题，所需 token 数减少 24×–51×（基于真实书籍测量）。

工作原理，分 3 步：

指向一个文件、文件夹或通配符 — /book-to-skill ./my-book.pdf

它将书籍蒸馏成一项技能 — 框架、决策规则、反模式和按章节的文件。是结构化的，不是摘要。

你的 AI 智能体按需加载它 — 问 /my-book replication，它读取相关章节并从真实内容中回答，没有幻觉。

你买了一本优秀的技术书。读过一遍。三个月后，你已经不记得第 7 章存在了。

常见的替代方案都不行：

📄 "我就搜 PDF 吧" → 你得到页码列表，而不是答案

🧠 "我问 AI 智能体这本书的内容" → 它要么幻觉，要么说没有这些内容

📝 "我读的时候记笔记" → 结果是一份 200 行的文档，你再也没打开过

book-to-skill 用结构化技能解决了这个问题，你的 AI 智能体按需加载这个技能。

装好后，只需输入 /your-book-slug replication，AI 智能体就会读取相关章节并从实际内容中回答。没有幻觉。不用挖 PDF。这本书成为了你工作流的一部分。

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

运行 /book-to-skill your-book.pdf（或一个文件夹、通配符或文件列表）会在你的 AI 智能体技能目录中创建一项完整的技能（GitHub Copilot CLI 为 ~/.copilot/skills/<slug>/，Amp 或跨 AI 智能体为 ~/.agents/skills/<slug>/，Claude Code 为 ~/.claude/skills/<slug>/）：

章节文件按需加载 — 在你询问该主题前，它们不会计入技能预算。

名字说的是"书籍"，但输入可以是任何结构化文本。同样的提取方法适用于你反复阅读的知识库：

内部文档 — 架构决策记录、运维手册、入职指南。把整个 docs/ 文件夹折叠成一项技能，在编码时查询它。

品牌与设计系统 — 话术指南、基调文档、组件原则。把品牌书转换成技能，让你的团队查询它而不是翻阅 60 页 PDF。

研究集合 — 一堆论文加上你自己的笔记，合并成单一统一的技能，随着新材料到达而更新（参见 Update / fold-in）。

规范与标准 — RFC、API 契约、你参考但从不背的合规文档。

如果你经常重新打开一份文档，希望早就把它背下来了，那它就是一个候选。

/book-to-skill <path-to-document-folder-or-glob>... [skill-name-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

# 处理匹配通配符的文件
/book-to-skill "~/books/*.epub" my-library

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

技能创建后，像使用其他 AI 智能体技能一样使用它：

/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 — 按书籍类型选择：

提取开始前，技能会问你这本书是技术类还是文本密集型的，并自动选择正确的工具。Docling 保留 markdown 表格和代码块；pdftotext 对纯文本书籍更快。

一个文件 · 一个文件夹 · 一个通配符 · 一个路径列表
     │
     ▼
第 1.5 步 — "技术书籍还是文本密集型书籍？"
     │
     ├── 技术类 → Docling  (表格 + 代码块作为 markdown，~1.5s/页)
     └── 文本 → pdftotext → pypdf → pdfminer  (瞬间完成)
     │
     ▼
scripts/extract.py <paths…> --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 token)
          技术类 → 包含代码示例 + 参考表部分
          生成词汇表、模式、速查表
          生成带核心心智模型的主 SKILL.md
               │
               ▼
          技能写入到以下位置之一：
            ~/.copilot/skills/<slug>/   (GitHub Copilot CLI)
            ~/.agents/skills/<slug>/    (Copilot CLI 或 Amp，跨 AI 智能体)
            ~/.claude/skills/<slug>/    (Claude Code)
          /tmp/book_skill_work/         🗑️  清空

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

实际转换（测量：页数、提取的 token、自动检测的章节、Claude Sonnet 4.5 单次成本估算，按 $3/$15 每百万 token）：

† 章节自动检测需要明确的 Chapter N / Capítulo N 标题。Pro Git 使用部分标题，Moby-Dick 使用章节标题/罗马数字，所以都不会自动分段 — 提取和转换仍会工作，但你需要手动指向各部分。完整技能的成本大约是每本书 $1；远少于每次会话重新读一遍 PDF。

密度优于完整性 — 1,000 token 的摘要胜过 10,000 token 的摘录

实践者的声音 — "在 Y 时使用 X"，而不是"书中解释了 X"

SKILL.md 优先加载 — 压缩保持了前 ~5,000 token；最重要的内容放在最前面

按需章节 — 主题索引告诉 Claude 读哪个文件；章节只在需要时加载

永不原始文本 — 总是合成、摘要、从源中提取信号

🧾 发现循环的开销

一个 PDF 阅读 AI 智能体不仅仅是阅读 — 它导航。问它一个问题，它获取目录、发现一个它不懂的术语、拉取更多页面、回溯。这些跳转中的每一个都落入对话历史，在后续每一轮都重新处理。为了保持在预算内，一个子 AI 智能体随后被迫以残酷的比率压缩它读过的内容，把降级的摘要交给主 AI 智能体，后者无法根据源验证它。

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

实际测量，而非声称。在三本真实书籍上运行 tools/discovery_tax.py — 为回答一个目标明确的问题而进入上下文的 token（book-to-skill = 常驻核心 + 一个编译章节 ≈ 5,000 token）：

优势随章节大小而缩放：相比上下文转储，它始终保持在 24–51×（且这种开销每轮重复）；相比一次性发现循环，范围从小章节书的适度 2.4× 到大章节书的 15.6×。在你自己的书上重现：

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

坦率地说，也有一些注意事项：(1) 探索阶段的数据代表一次性成本，其模型使用了书籍真实的目录和章节大小——经过良好调优的 AI 智能体会更接近最佳情况；相比之下，转储上下文的成本会在每一轮对话中反复产生。(2) 该工具需要可识别的章节标题才能对书籍进行分段——它能够检测阿拉伯数字、罗马数字（Chapter I / 行首的 I.）、中日韩文字、韩文（제N장）、泰文以及多种欧洲语言的标题形式，但只有标题的书籍（或者未使用 ebooklib 提取的 EPUB）可能无法被清晰分段。当你需要反复查阅这些知识时，book-to-skill 更具优势；如果只是一次性阅读，普通的 PDF AI 智能体就足够了。

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

可以——但每次对话都会在一开始就消耗掉这部分 token 预算。一本 400 页的书大约有 20 万个 token。使用技能时，只会加载与你的问题相关的章节——通常是一个 SKILL.md 核心文件（约 4K）加上你所询问的一个章节（约 1K）。其余内容会保留在磁盘上，直到你需要时才会加载。

这里的经济账取决于成本摊销，而不是内容大小。粘贴整本书意味着在每个会话的每一轮对话中，都要永远重复支付完整的 token 成本。book-to-skill 只需支付一次提取成本，之后的每次对话都只加载所需的那一小部分。上下文窗口越大，这一点就越重要——大窗口只是让转储整本书成为可能，并不会让它变得便宜。

更重要的是：注入原始文本属于检索，而技能用于推理。加载章节文件时，Claude 并不是在搜索匹配的关键词——它使用的是预先提取并命名的框架、原则和心智模型，而且这些内容是按应用场景组织的，而不是按阅读顺序组织的。

“Claude 现在已经有 100 万 token 的上下文窗口了——我不能一直加载整本书吗？”

更大的窗口改变的是能装下多少内容，而不是什么做法更明智。它无法替代技能，原因有三：

你需要为每次调用中的每个 token 付费。100 万 token 的窗口并不会让这些 token 免费——它只是让庞大且反复产生的账单成为可能。技能加载的是 KB 级内容，而不是 MB 级内容。

上下文越满，召回效果越差。模型在接近填满的上下文中检索某个被埋藏的具体事实时，准确性会下降（“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 面向的是另一类任务：你希望深入研究某个特定主题或资料库，把多份相关文档（论文、章节、笔记）整合到一个统一的技能中，甚至在新资料到来时不断更新它！它会将你的定制知识库直接集成到编码或写作工作流中，而不是放在单独的浏览器标签页里。

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

作为 AI 智能体技能（Claude Code、Copilot CLI 或 Amp 中的 /book-to-skill 命令）→ 使用 git clone 将其克隆到你的技能文件夹中（见下文）。这种方式会提供斜杠命令以及完整的书籍转换流程。

作为独立 CLI（仅使用文本提取器）→ pip install book-to-skill，然后运行 book-to-skill --help。这不会注册 AI 智能体技能；它只会安装提取引擎。请参阅 CLI 部分。

该技能遵循开放的 Agent Skills 标准，因此只需安装一次，即可用于任何兼容的宿主。

GitHub Copilot CLI（个人技能）：

git clone https://github.com/virgiliojr94/book-to-skill.git ~/.copilot/skills/book-to-skill
# then, in a `copilot` session:
/skills reload
/skills info book-to-skill

或者使用 Copilot CLI 和 Amp 都能够发现的跨 AI 智能体路径：

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

将以下内容复制到你的 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

然后在任意 AI 智能体会话中运行：

/book-to-skill ~/path/to/your-book.pdf
# or
/book-to-skill ~/path/to/your-book.epub

pip install book-to-skill 是一条独立且可选的安装路径。它只会安装作为 CLI 使用的文本提取引擎，适用于编写脚本或获取可选提取器；它不会注册 /book-to-skill AI 智能体技能（如需注册，请使用上面的 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 不附带任何书籍内容——一页都没有。它是一个转换器，由你指定自己已经拥有的文件。

所有处理都在本地进行。提取和分析均在你的机器上运行。该工具绝不会上传你的文件。（如果你的 AI 智能体模型运行在云端，那么你提供给它的文本将遵循该提供商的常规数据条款——与其他任何提示词相同。）

请使用你自己的副本。你可以提供自己购买的书籍、公司拥有的文档，或者你有权阅读的论文。

输出内容是你的笔记。生成的技能是一种经过结构化和综合处理的衍生内容——包含框架名称、定义和要点——而不是对原文的复制。该技能明确规定绝不复制原始段落（参见质量规则 #7）。请将它视为手写的学习笔记：归你所有，供个人使用。

请勿重新分发。发布或分享基于版权作品生成的技能可能会侵犯权利人的权益。请将根据第三方书籍生成的技能保持为私有。内部文档、你自己的作品以及采用开放许可的材料，可以在其许可证允许的范围内分享。

如有疑问，请遵守源文档的许可证或使用条款。本项目只是一个工具；如何使用由你负责。

book-to-skill 免费提供并采用 MIT 许可证，由作者利用个人时间维护。如果它帮你节省了 token 或学习时间，可以考虑赞助其维护工作，包括 PR 审查、多语言修复、版本发布和文档维护。

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

所有赞助者都会列入 BACKERS.md。感谢你帮助开放、隐私优先的工具持续发展。✨

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