最后更新于 2026 年 8 月 3 日。技术细节核实自 book-to-skill 官方仓库 与 Agent Skills 开放标准。
你买了一本《设计数据密集型应用》或团队内部的架构规范 PDF，读的时候觉得醍醐灌顶，三个月后写代码却想不起第七章讲过什么。常见补救办法都不理想：在 PDF 里全文搜索只能得到页码列表；把整本书贴进 Cursor 对话会迅速吃光上下文；自己整理的 200 行笔记又很少再打开。
Book to Skill 走另一条路：把 PDF（或 EPUB、DOCX、Markdown 文件夹）一次性蒸馏成符合 Agent Skills 标准的结构化技能包。之后在 Cursor、Claude Code 或 GitHub Copilot CLI 里，Agent 只加载与当前问题相关的章节，用作者原话里的框架和术语回答，而不是凭印象编造。
本文按「先理解价值 → 再装环境 → 跑通转换 → 日常调用」的顺序，给出 2026 年可用的完整实操路径。
为什么要把 PDF 变成 AI 知识库
普通 RAG（检索增强生成）把 PDF 切成碎片向量，问什么检索什么。这对 FAQ、合同条款很有效，但对技术书往往不够：书中的价值在于作者命名的框架、决策树和反模式，而不是某一段 512 token 的原文。
Book to Skill 的差异在于结构化蒸馏，而不是简单切块：
- 提取书名、作者、章节树和核心心智模型；
- 为每一章生成 800–1,200 token 的实操摘要（含代码示例与对照表，技术书会保留表格结构）；
- 额外生成术语表、模式清单和决策速查表；
- 主文件
SKILL.md只放索引与框架，章节文件按需加载。
官方基准测试显示：针对真实技术书提问时，相比把整本书塞进上下文，按需加载可节省约 24×–51× 的 Token；整本书转换的一次性成本大约 1 美元量级（以 Claude Sonnet 计价），远低于每次会话重复上传 PDF。
Book to Skill 是什么
book-to-skill 是开源 Python 项目（MIT 协议），同时提供两种形态：
- Agent Skill 模式（推荐）：克隆到
~/.cursor/skills/或~/.claude/skills/，在对话里执行/book-to-skill ./my-book.pdf，由 Agent 驱动完整转换流水线； - 纯 CLI 模式：
pip install book-to-skill只安装文本提取引擎，不注册斜杠命令。
支持的输入包括 PDF、EPUB、DOCX、TXT、Markdown、reStructuredText、AsciiDoc、HTML、RTF，以及经 Calibre 转换的 MOBI/AZW。也可以指向文件夹或 glob，把多份文档合并成一个统一技能。
三种方案怎么选
| 方案 | 优点 | 缺点 | 适合谁 |
|---|---|---|---|
| 整书贴进对话 | 零配置 | Token 爆炸、易超限、无法长期复用 | 一次性问答 |
| 向量 RAG | 适合海量文档、可增量更新 | 难保留全书框架与术语一致性 | 企业知识库、客服 |
| Book to Skill | 保留作者框架；章节按需加载；可版本管理 | 需一次性转换；扫描版 PDF 效果差 | 技术书、规范、Runbook |
如果你反复查阅同一本技术书或内部规范，且希望 Cursor 在写代码时自动引用书中的决策规则，Book to Skill 通常是性价比最高的选择。若你已经在用 GitHub MCP Server 连接仓库，可以把「书里的架构原则」和「仓库里的真实代码」放在同一套 Agent 工作流里。
环境准备
转换前建议先跑环境自检：
git clone https://github.com/virgiliojr94/book-to-skill.git
cd book-to-skill
python3 scripts/extract.py --check
--check 会列出各格式所需的提取器是否已安装，并给出缺失时的安装命令。
PDF 提取器怎么选
开始转换时，工具会询问书籍类型：
| 书籍类型 | 推荐工具 | 安装 | 特点 |
|---|---|---|---|
| 散文为主、少表格代码 | pdftotext（Poppler） | brew install poppler（macOS） | 几乎瞬时完成 |
| 技术书（代码块、表格、公式） | Docling | pip3 install docling | 约 1.5 秒/页，保留 Markdown 表格 |
EPUB 推荐 pip3 install ebooklib beautifulsoup4；DOCX 用 python-docx。纯文本与 Markdown 无需额外依赖。
扫描版 PDF（图片页）没有可靠文字层时，任何提取器都会失败——请先 OCR 或换电子版。
安装 Book to Skill
Cursor 用户
git clone https://github.com/virgiliojr94/book-to-skill.git \
~/.cursor/skills-cursor/book-to-skill
重启 Cursor 或新开 Agent 会话后，在命令面板搜索 /book-to-skill。若你使用项目级技能，也可放到 .cursor/skills/book-to-skill/ 并与团队共享。
Claude Code 用户
git clone https://github.com/virgiliojr94/book-to-skill.git \
~/.claude/skills/book-to-skill
GitHub Copilot CLI 用户
git clone https://github.com/virgiliojr94/book-to-skill.git \
~/.copilot/skills/book-to-skill
# 新建技能后执行
/skills reload
跨 Agent 共用时，也可放在 ~/.agents/skills/。
完整转换流程
假设你有一本技术 PDF：~/Books/ddia.pdf（《设计数据密集型应用》）。
步骤 1：发起转换
在 Cursor Agent 中输入：
/book-to-skill ~/Books/ddia.pdf designing-data-intensive-apps
第二个参数是技能 slug（可选）；省略时从书名自动生成。
步骤 2：选择书籍类型
Agent 会询问 technical 还是 text-heavy。技术书选 technical，触发 Docling 提取以保留代码块与表格。
步骤 3：确认成本预估
转换前会显示 Token 预估与大致费用（完整技能通常约 1 美元/book）。确认后才开始生成，避免误触大额消耗。
步骤 4：等待流水线完成
内部流程为：多格式提取 → 合并全文 → Claude 分析章节结构 → 逐章摘要 → 生成 glossary / patterns / cheatsheet → 写入技能目录。临时文件在 /tmp/book_skill_work/，完成后自动清理。
一本 300–500 页的技术 PDF，Docling 提取可能需要数分钟；生成阶段取决于章节数量与 API 速度。建议在不会休眠的机器上跑——若你常用笔记本合盖中断任务，可考虑在云端 Mac 上完成长转换（见文末）。
生成物长什么样
转换完成后，技能目录结构类似：
~/.cursor/skills-cursor/designing-data-intensive-apps/
├── SKILL.md # 核心框架 + 章节索引（约 4,000 tokens）
├── chapters/
│ ├── ch01-reliable-scalable-maintainable.md
│ ├── ch02-data-models.md
│ └── ...
├── glossary.md # 术语表，带章节回链
├── patterns.md # 技术与设计模式清单
└── cheatsheet.md # 决策表与速查规则
SKILL.md 的 front matter 遵循 Agent Skills 规范，包含 name 与 description，让 Cursor 在相关问题时自动加载该技能。章节文件不会默认全部进入上下文——只有当你问到具体主题时，Agent 才读取对应 chapters/ch05-*.md。
日常怎么用
技能就绪后，用法与任何 Cursor Skill 相同：
# 加载核心心智模型
/designing-data-intensive-apps
# 按主题查询（Agent 会定位章节）
/designing-data-intensive-apps replication
# 直接指定章节
/designing-data-intensive-apps ch05
# 查看技能包含哪些章节
/designing-data-intensive-apps what chapters do you have?
写代码时的典型场景：「我要给订单服务加缓存，按 DDIA 的建议，先帮我对照一致性模型和失效策略。」Agent 会读取相关章节与 cheatsheet.md 中的决策表，而不是泛泛而谈。
若你同时配置了 MCP 工具（例如连接 GitHub 查 Issue），可以让 Agent 一边引用书中原则，一边拉取仓库现状——这与 OpenShip 部署排障 类长文档的「书 + 实操」组合思路一致：知识库负责「该怎么想」，工具负责「现在是什么状态」。
进阶用法
合并多份文档
/book-to-skill ~/papers/*.pdf ~/notes/architecture.md team-knowledge
适合把论文、ADR 和会议纪要合成一个团队技能，后续新文档可指向已有技能目录做增量折叠（fold-in）。
仅分析不生成
对大书不确定是否值得全量转换时，可先走 analyze-only 模式预览提取到的框架与章节树，再决定是否生成完整技能。
版本管理与共享
技能目录是纯 Markdown，可纳入 Git 仓库。团队可在 .cursor/skills/ 提交统一的「编码规范」「On-call Runbook」技能，新人克隆仓库即可获得相同知识底座。
与 create-skill 的关系
Cursor 自带的 create-skill 适合手写短技能；Book to Skill 适合已有长文档、需要自动结构化的场景。两者可并存：短流程用 create-skill，技术书用 book-to-skill。
故障排查
| 现象 | 可能原因 | 处理 |
|---|---|---|
| 提取后章节数为 0 | PDF 无「Chapter N」式标题 | Pro Git 等用书名号分节的书需手动指定章节；或换 EPUB |
| 代码块变成乱码 | 误选 text-heavy 提取技术书 | 重装 Docling，重跑并选 technical |
/book-to-skill 找不到 | 技能未放入正确目录 | 确认路径为 ~/.cursor/skills-cursor/ 并重启 Cursor |
| 回答仍像幻觉 | Agent 未加载章节文件 | 明确提问并带上章节 slug；检查 SKILL.md 索引 |
| 转换中途失败 | 机器休眠或 API 超时 | 在持续在线环境重跑；查看 /tmp/book_skill_work/ 日志 |
提取问题优先运行 python3 scripts/extract.py --check；生成问题检查 API 额度与网络代理。
小结
- 想快速上手：克隆 book-to-skill 到 Cursor skills 目录 →
/book-to-skill your.pdf→ 技术书选 Docling。 - 想长期复用：把生成的技能目录纳入 Git，团队共享；新文档用 fold-in 更新。
- 想省 Token：依赖章节按需加载，不要每次把 PDF 全文贴进对话。
Book to Skill 把「读过但记不住」变成「写代码时随时可问的作者框架」。下一步若你需要在稳定环境中批量转换多本书、或边转换边跑其他 Agent 任务，可以考虑使用持续在线的云端 Mac 工作区，避免本地机器休眠中断长任务。
常见问题
Book to Skill 和向量 RAG 有什么区别？
RAG 按相似度检索文本片段；Book to Skill 先做结构化蒸馏，保留作者命名的框架、反模式和章节索引，再由 Agent 按主题加载整章摘要。前者适合海量非结构化文档，后者适合需要「按书中逻辑思考」的技术书与规范。
必须用 Claude 吗？
转换阶段的结构分析目前由 Claude 驱动（在 Agent 会话中完成）。生成后的技能是标准 Markdown，Cursor 里用任何模型调用都可以；Copilot CLI 与 Claude Code 同样兼容 Agent Skills 格式。
扫描版 PDF 能用吗？
不能可靠使用。book-to-skill 依赖文字层提取；扫描页需先用 OCR 工具处理，或改用出版社提供的 EPUB / 正版电子版。
转换一本书大概多少钱？
官方实测约 1 美元/本（Claude Sonnet 计价，视页数与章节数浮动）。这是一次性成本；之后每次查询只消耗按需加载的章节 Token，远低于重复上传整书。
长任务放在云端 Mac 上，不怕合盖中断
Book to Skill 转换 300 页以上的技术 PDF 时，Docling 提取与多轮 API 生成可能持续数十分钟。把任务放在持续在线的 Mac mini M4 云端节点上，可以避免笔记本休眠、本地环境缺依赖或网络切换导致的中断；转换完成的技能目录还可通过 Git 直接同步到团队仓库。