book-to-skill 实战：如何把技术书 PDF 转成可调用的 Agent Skill
发布日期：2026-08-17｜适用版本：book-to-skill v1.4.0｜目标读者：开发者与知识工作者
book-to-skill 是 Virgilio Junior 于 2026 年开源的文档转换工具，用于把技术书、文档目录或多份资料整理成符合 Agent Skills 开放标准的结构化技能。它先在本地提取 PDF、EPUB、DOCX 等文件，再生成按需加载的 SKILL.md、章节文件、术语表和速查表；官方 2026 年基准显示，回答单个问题时约加载 5,000 Token，相比整本塞入上下文可减少 24 至 51 倍。本文说明安装、转换、验证、更新及版权边界，并给出文本型 PDF 与技术型 PDF 的工具选择方法。
book-to-skill 是把一本书或一组结构化文档转换为 Agent Skill 的开源工具，核心价值是让智能体按问题加载相关章节，而不是每次重新读取整份文档。
book-to-skill 会生成什么
book-to-skill 生成的是可检索、可按需加载的知识结构，而不是一篇普通摘要。 转换结果遵循 Agent Skills 的 SKILL.md 结构，可被支持该开放标准的智能体宿主识别。
典型输出包含：
这种结构适合技术书、内部运行手册、架构决策记录、研究论文集合和设计规范。它不适合需要逐字引用原文、严格保持版式或依赖大量扫描图像的任务。
为什么不直接把 PDF 放进上下文
把整本 PDF 放进上下文操作简单，但会重复消耗 Token，并让相关章节与无关内容共同竞争注意力。 book-to-skill 把一次性的整理成本放在转换阶段，后续查询只加载核心索引和命中的章节。
根据项目官方 performance.md 在 2026 年公布的测试：
244 页的《Think Python 2》包含 119,264 Token；按需查询约使用 5,000 Token，约为整本输入的 1/24。
371 页的《Working Backwards》包含 175,253 Token；按需查询约使用 5,000 Token，约为整本输入的 1/35。
256,287 Token 的《AI Engineering》在目标问题查询中约使用 5,000 Token，约为整本输入的 1/51。
这些数字是项目维护者用 tiktoken 和 tools/discovery_tax.py 测得的项目基准，不代表所有书籍、模型或问题都能得到相同比例。
如何安装 book-to-skill
最短安装路径是通过跨智能体 Skills CLI 添加官方仓库，手动安装则应放入当前宿主对应的技能目录。 官方 README 截至 2026 年 8 月给出的命令如下：
npx skills add virgiliojr94/book-to-skill以 Claude Code 的目录结构为例，也可以手动克隆：
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill不同宿主的目录并不相同：GitHub Copilot CLI 使用 ~/.copilot/skills/，跨智能体或 Amp 场景通常使用 ~/.agents/skills/。安装前应以所用宿主的最新文档为准。
如何把技术书转换成 Skill
一次可靠的转换包含环境检查、资料分类、执行转换、验证输出和试问五个步骤。 不要直接处理来源不明或无权使用的电子书。
检查提取器是否齐全：
python3 scripts/extract.py --check判断 PDF 类型。以文字为主的书可使用
pdftotext；包含代码、表格和公式的技术书更适合 Docling。扫描版 PDF 必须先做 OCR。在智能体中执行转换：
/book-to-skill ~/Documents/books/example.pdf example-book检查生成目录是否包含
SKILL.md、chapters/、glossary.md、patterns.md和cheatsheet.md。用书中一个明确主题试问，例如：
/example-book replication
如需把多篇论文和笔记合并为一个技能，可以一次传入多个路径：
/book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-research文本型 PDF、技术型 PDF 和扫描件怎么选
提取器应按文档结构选择：速度优先选文本提取，结构保真优先选 Docling，扫描件先做 OCR。 官方 2026 年对一份 103 页技术 PDF 的测试显示，pdftotext 用时约 0.1 秒，但没有保留表格和代码块；Docling 用时约 164 秒，保留了 48 个表格和 36 个代码块。
扫描件可先执行：
ocrmypdf input.pdf output.pdf如何更新、共享和管理生成的 Skill
已有 Skill 可以通过 fold-in 模式加入新资料，但第三方版权书籍生成的技能应保持私有。 更新命令把新资料路径和现有技能目录同时传入：
/book-to-skill ~/articles/new-paper.pdf ~/.claude/skills/project-knowledge项目 v1.4.0 支持在转换后选择发布到 GitHub，默认创建私有仓库；只有明确输入 public 才会创建公开仓库。公开发布前必须确认源材料属于自有内容、内部授权材料或允许再分发的开放许可内容。
团队还需要考虑素材存储和技能分发。资料量较大时，可以把原始文档与生成产物分层存放；例如七牛云的对象存储 Kodo 可保存原始文件和版本化产物，而 LinSkills 可作为 OpenClaw 技能的发现入口。无论使用哪种平台，访问权限都应继承源文档的保密等级。
book-to-skill 的限制与风险
book-to-skill 降低的是重复检索成本，不能保证回答永不出错，也不能替代版权与安全审查。 实际使用时应关注以下边界：
章节识别依赖文档目录和标题结构，格式异常时可能需要人工调整。
云端模型处理提取文本时，数据仍受对应模型服务商的数据条款约束。
生成内容是结构化衍生笔记，不意味着获得了公开传播原书内容的权利。
从未知文档生成技能可能把提示注入或工具调用标记带入指令层，应在启用前检查生成文件。
版本升级可能改变命令、输出结构或发布流程，应核对官方 Changelog。
截至 2026 年 8 月 17 日，GitHub API 显示该项目有 22,238 Star、2,348 Fork 和 28 个开放 Issue，最新正式版 v1.4.0 发布于 2026 年 8 月 10 日。这些指标说明关注度较高，但不能替代对代码、安全性和维护质量的独立评估。
常见问题
Q：book-to-skill 支持哪些格式？
官方文档列出的格式包括 PDF、EPUB、DOCX、TXT、Markdown、reStructuredText、AsciiDoc、HTML、RTF，以及需要 Calibre 支持的 MOBI、AZW 和 AZW3。不同格式需要的可选提取器不同。
Q：转换后的 Skill 会自动上传原始 PDF 吗？
不会。项目说明提取过程在本地运行，工具本身不上传原始文件；但若后续由云端模型分析提取文本，数据处理仍遵循模型服务商的条款。
Q：扫描版 PDF 为什么无法转换？
扫描版 PDF 往往只有页面图像，没有可提取的文本层。应先用 OCRmyPDF 等工具生成文本层，再把 OCR 后的文件交给转换器。
Q：生成的 Skill 可以公开分享吗？
只有在拥有传播权限时才适合公开。第三方版权书籍生成的技能应保持私有；自有文档、已授权内部材料和开放许可内容也必须遵守各自的许可范围。
Q：book-to-skill 能完全消除幻觉吗？
不能。按需加载真实章节能减少缺少依据时的猜测，但回答质量仍受提取准确度、生成结构、模型能力和问题表达影响，关键结论应回查原文。
结论
book-to-skill 的关键思路是把“反复读整本书”改为“一次结构化、后续按需加载”，适合经常被查询的技术资料和内部知识库。官方 GitHub 仓库与性能文档提供了安装、格式支持和 Token 基准；在生产使用前，还应验证提取质量、安全边界和版权许可。
本文内容基于 2026 年 8 月 17 日的 GitHub API、项目 README、Usage 与 Performance 文档，项目仍在快速迭代，建议使用前核对最新 Release 和 Changelog。
