对 /book-to-skill your-book.pdf（或文件夹、glob、文件列表）运行后，会在智能体的 skills 目录中生成完整 skill（Copilot CLI 为 ~/.copilot/skills/<slug>/，Amp 或跨智能体场景为 ~/.agents/skills/<slug>/，Claude Code 为 ~/.claude/skills/<slug>/）：

File	Purpose	Size
`SKILL.md`	核心心智模型 + 章节目录	~4,000 tokens
`chapters/ch01-*.md` …	每章一个文件，按需加载	~1,000 tokens each
`glossary.md`	所有关键术语，按字母排序并附章节引用	~1,500 tokens
`patterns.md`	全部技巧、算法与设计模式	~2,000 tokens
`cheatsheet.md`	决策表与快速参考规则	~1,000 tokens

章节文件按需加载 — 在你询问相关主题之前，不会计入 skill 预算。

🏢 不止于书籍

名字里有「book」，但输入可以是任意结构化散文。同一套提取流程适用于你拥有并反复查阅的知识：

内部文档 — 架构决策记录（ADR）、运维手册（runbook）、入职指南。将整个 docs/ 文件夹折叠为一个 skill，编码时随时提问。
品牌与设计系统 — 语调指南、语气文档、组件原则。把品牌手册变成 skill，团队查询即可，无需翻阅 60 页 PDF。
研究资料簇 — 一叠论文加上你的笔记，合并为单一统一 skill，新资料到来时可更新（见更新 / 折叠并入）。
规范与标准 — 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。

示例：

# Process several files together into a unified skill
/book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-research

# Process all supported files in a folder together
/book-to-skill ~/workspace/project-docs/ project-knowledge

# Process files matching a glob pattern
/book-to-skill "~/books/*.epub" my-library

# Update/fold new material into an existing skill folder
/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 无需额外依赖。

一条命令检查环境： python3 scripts/extract.py --check 会打印每种格式已安装的提取器，以及安装缺失项的确切命令 — 无需任何文件。

PDF — 按书籍类型选择：

Book type	Tool	Install	Speed
文字为主（散文、表格少）	`pdftotext` (poppler)	`sudo apt install poppler-utils`	⚡ instant
文字为主（备选）	`pypdf`	`pip3 install pypdf`	⚡ instant
文字为主（备选）	`pdfminer.six`	`pip3 install pdfminer.six`	⚡ instant
技术类（代码、表格、公式）	`docling`	`pip3 install docling`	~1.5s/page

提取开始前，skill 会询问书籍属于 技术类 还是 文字为主，并自动选择合适工具。Docling 保留 Markdown 表格与代码块；pdftotext 更适合纯散文类书籍，速度更快。

EPUB：

Tool	Install	Quality
`ebooklib` + `beautifulsoup4`	`pip3 install ebooklib beautifulsoup4`	⭐⭐⭐ Best
stdlib `zipfile`	built-in — no install needed	⭐⭐ Always available

其他格式：

格式	工具	安装
DOCX	`python-docx`（备选：stdlib ZIP/XML）	`pip3 install python-docx`
HTML	`beautifulsoup4`（备选：stdlib `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 <paths…> --mode <technical|text>
  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/<slug>/   (GitHub Copilot CLI)
            ~/.agents/skills/<slug>/    (Copilot CLI or Amp, cross-agent)
            ~/.claude/skills/<slug>/    (Claude Code)
          /tmp/book_skill_work/         🗑️  cleaned up

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

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

实际转换（实测：页数、提取的 token 数、自动检测的章节数，以及在 Claude Sonnet 4.5 上单次通行估算成本，按 $3/$15 每 MTok 计）：

书籍	格式	页数	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,000 token 的摘要胜过 10,000 token 的摘录
实践者口吻 — 用「在 Y 情况下使用 X」，而非「本书解释了 X」
前置加载 SKILL.md — 压缩后保留前约 5,000 token；最重要内容放在最前
按需加载章节 — 主题索引告诉 Claude 应读取哪个文件；仅在需要时加载章节
绝不使用原始文本 — 始终综合、总结、从源材料中提取有效信息

🧾 发现循环税（Discovery Loop Tax）

PDF 阅读智能体不只是阅读——它还会导航。你问它一个问题，它会获取目录，发现无法定义的术语，再拉取更多页面，然后回溯。每一次跳转都会进入对话历史，并在后续每一轮中被重新处理。为留在预算内，子智能体不得不以极高压缩比压缩已读内容，交给主智能体一份无法对照源材料核实的劣化摘要。

book-to-skill 将导航成本一次性在编译时支付。在运行时，助手只加载一小份常驻核心（resident core）以及所需的那一个预编译章节 —— 没有 discovery loop、没有 compress-to-fit，完整提取的源码仍留在磁盘上以供校验。

实测，而非断言。 在三本真实书籍上运行 tools/discovery_tax.py —— 为回答一个针对性问题而进入上下文的 token 数（book-to-skill = resident core + 一个编译章节 ≈ 5,000 tokens）：

书籍（规模）	Context-dump	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

坦诚说明：（1）discovery 数据为一次性成本，且基于书籍真实 ToC/章节规模的模型估算 —— 调优良好的 agent 更接近最优情况；相比之下，context-dump 成本会在每一轮重复发生。（2）该工具需要显式的 Chapter N / Capítulo N 标题来切分书籍；仅有标题或罗马数字章节的书籍（以及未使用 ebooklib 提取的 EPUB）无法干净切分。book-to-skill 适合你会反复查阅的知识；若只是一次性阅读，普通 PDF agent 即可。

❓ FAQ

"不能把 PDF/EPUB 直接丢进 Claude 项目上下文吗？"

可以 —— 但每次对话都会预先消耗那份 token 预算。一本 400 页的书约 ~200K tokens。使用 skill 时，只加载与你问题相关的章节 —— 通常是 SKILL.md 核心（~4K）加上你询问的那一章（~1K）。其余内容留在磁盘上，直到你需要为止。

经济学在于摊销，而非体量。粘贴整本书会在每一次会话的每一轮、永远支付全额 token 账单。book-to-skill 将提取成本一次性支付，之后每次对话只加载所需片段。上下文窗口越大，这一点越重要 —— 大窗口让 dump 可行，并不等于便宜。

更重要的是：原始文本注入是检索（retrieval）。skill 是推理（reasoning）。加载章节文件时，Claude 不是在搜索关键词匹配 —— 它处理的是预先提取的命名框架、原则与心智模型，结构面向应用，而非阅读。

"Claude 现在有 1M-token 上下文窗口了 —— 不能把整本书一直加载着吗？"

更大的窗口改变的是能装下什么，而非是否聪明。它不能替代 skill 的三个原因：

按 token、按调用计费。 1M 窗口不会让那些 token 免费 —— 它只是让大额、 recurring 账单成为可能。skill 加载的是千字节（kilobytes），而非兆字节（megabytes）。
填充越多，召回越差。 模型在接近满载的上下文中检索某个具体事实时会损失精度（"lost in the middle"）。回答一个问题时，1K 的精选章节胜过 200K 原始散文。
窗口 ≠ 结构。 上下文中的整本书仍是原始文本，模型每一轮都要重新解析。skill 交付的是预提取框架 —— 推理，而非检索。

把大窗口用在它擅长的事：对你再也不会需要的材料做一次性通读。对你会反复查阅的知识，使用 skill。

"这不就是 RAG 吗？"

RAG 在查询时工作：切分书籍 → 嵌入全部内容 → 查找相似向量 → 注入提示词。它针对的是"帮我找到讲 X 的那一段。"

book-to-skill 在编译时（compile time）运行：一次深度分析即可提取作者真正的框架（frameworks），为其命名，说明各自适用场景，并捕获反模式（anti-patterns）。输出是作者经年累月构建的结构——而不是对其句子的相似度检索。

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，甚至随着新材料到来持续更新！这会把你的定制知识库直接融入编码或写作工作流，而不是放在另一个浏览器标签页里。

📥 安装

两种用法，请勿混淆：

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

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

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

GitHub Copilot CLI（个人 skill）：

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 均可发现的跨 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
# or
/book-to-skill ~/path/to/your-book.epub

独立 CLI（pip）

pip install book-to-skill 是一条独立、可选的路径。它仅将文本提取引擎安装为 CLI，供脚本使用或获取可选提取器；不会注册 /book-to-skill agent 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 的模型在云端运行，你喂给它的文本遵循该提供商的常规数据条款——与任何提示词相同。）
使用你自己的副本。 带上你购买的书、公司拥有的文档，或你有权阅读的论文。
输出是你的笔记。 生成的 skill 是结构化、综合性的衍生内容——框架名称、定义、要点——而非原文复刻。skill 明确从不复制原始段落（见质量规则 #7）。可视为手写学习笔记：归你所有，供个人使用。
请勿再分发。 发布或分享针对受版权保护作品生成的 skill，可能侵犯权利人权益。第三方书籍的 skill 请保持私有。内部文档、你自己的写作以及开放许可材料，可在其许可范围内分享。

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

💖 赞助

book-to-skill 免费且采用 MIT 许可，由个人业余时间维护。若它为你节省了 token 或学习时间，欢迎赞助其持续维护：PR 评审、多语言修复、发布与文档。

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

每位赞助者均列于 BACKERS.md。感谢你让开放、隐私优先的工具得以延续。✨

许可证

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

README.md Unescape Escape

book-to-skill

🤔 为何需要

📦 生成内容