五份文件、约一美元：book-to-skill 指南，把技术书变成结构化 Agent 技能-育师

五份文件、约一美元：book-to-skill 指南，把技术书变成结构化 Agent 技能

【免费下载链接】book-to-skillTurn any technical book PDF into a Claude Code skill — ready to study, reference, and use while you work.项目地址: https://gitcode.com/GitHub_Trending/bo/book-to-skill

book-to-skill 是一个把技术书书籍转技能的本地工具：它读取你的 PDF、EPUB、DOCX、RTF 等文件，产出一套结构化技能，让 Claude Code、Copilot CLI、Amp、Hermes 等 Agent 宿主按需加载章节来回答问题。转换本身是一次性成本，约一美元；之后每次提问只为用到的章节付 token。读完这篇，你能判断它适不适合自己，并跑通第一次转换。

先说结果：一本书转换后你得到什么

一份书，五个文件，构成一个可被 Agent 反复使用的知识包：

文件	用途	体量
`SKILL.md`	主文件：核心思维模型 + 章节与主题索引	约 4,000 tokens
`chapters/ch01-*.md`…	每章一个文件，话题相关时才被读取	约 1,000 tokens/个
`glossary.md`	全部关键术语，按字母排序并带章节引用	约 1,500 tokens
`patterns.md`	全部技术、算法与设计模式	约 2,000 tokens
`cheatsheet.md`	决策规则、决策树与快速参考	约 1,000 tokens

它提取的不是"第 3 章讲了什么"这类复述，而是作者多年沉淀的命名框架、决策规则和反模式。比如 "5 Whys" 不能写成"多问几次为什么"——框架的名字本身就是信息，原稿里的精确表述必须保留。质量规则里还有一条硬约束：绝不复制书中原始段落，输出应当是你自己的学习笔记，而不是原文搬运。

安装与第一次转换

两条路径，别混淆。

作为Agent 技能：把仓库克隆进你宿主对应的技能目录，之后会话里才有/book-to-skill斜杠命令。各宿主的位置一句话带过：Claude Code 放~/.claude/skills/，Copilot CLI 放~/.copilot/skills/（或跨 Agent 通用的~/.agents/skills/，Amp 与 Codex 也读这里），Hermes 放$HERMES_HOME/skills/<类别>/（默认~/.hermes/skills/，且要选与书的主题匹配的类别目录）。

git clone https://gitcode.com/GitHub_Trending/bo/book-to-skill.git ~/.claude/skills/book-to-skill

作为独立 CLI：pip从仓库安装，只拿到文本提取引擎，不注册任何技能。适合脚本化或只想验证提取质量的人：

pip install "book-to-skill[pdf,epub,docx] @ git+https://gitcode.com/GitHub_Trending/bo/book-to-skill.git" book-to-skill ~/path/to/book.pdf --mode text

装好后，在任意 Agent 会话里跑第一次转换。语法是/book-to-skill <路径或 glob>... [slug]，几个常用形态：

/book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-research /book-to-skill "~/books/*.epub" my-library /book-to-skill ~/articles/new.pdf ~/.claude/skills/project-knowledge

三条分别是：多个文件合并成一个技能、用 glob 整批转换、把新素材 fold-in（合并更新）进已有技能。技能生成后，四种调用形式就都通了：/designing-data-intensive-apps加载核心框架；加主题词查某个话题；加ch05直接深入第 5 章；问 "what chapters do you have?" 浏览完整索引。

四种用法：完整转换只是其中一种

完整转换（默认）：给路径、不加说明，就走完整流程，产出上文那套文件。
仅分析：说 "analyze" 或 "just extract"，提取并输出结构化报告后停止，不生成技能文件。适合先看看这本书值不值得转。
基于已有分析生成：你手头已有分析笔记或跑过仅分析模式，就跳过提取步骤直接生成。
Fold-in 更新：输入指向一个已有技能目录（或已存在的技能名），新素材被合并进原有章节、术语表与索引，而不是重起炉灶。

为什么 token 账单不会失控

省钱的机制叫 on-demand chapters（按需加载章节）：主文件保持小巧，章节文件只有在话题相关时才被读进上下文。于是那本 200 页的书，只为你的问题本身付 token，而不是为页数付。

转换过程中还有两个确认点，都是停下来等你的：先确认书籍内容类型——technical 或 text-heavy，这决定 PDF 用什么工具解析；再确认成本预估——给出 token 与费用估算后才动手。

深度分两档，DEPTH=reference和DEPTH=study，分别对应精简速查与更深入的研读。章节 token 预算随之浮动：text 类书在 800–1,200 与 1,000–1,800 之间，technical 类书在 1,200–1,800 与 2,000–3,000 之间（前一组是 reference，后一组是 study）。study 档靠真实内容达标——复现一个 worked example、把框架展开成显式步骤——而不是凑字数。

背后发生了什么：提取 + 生成的两段流水线

前一半是确定性的 Python 提取器：按扩展名分发到各格式解析器，遵循"最优工具优先、stdlib 兜底"——PDF 技术书走 Docling，纯文字走pdftotext，EPUB 有 ebooklib 时用它、没有就用标准库zipfile硬拆。全程本地，文件不出机器；每次运行使用独立的临时目录<tempdir>/book_skill_work-<pid>/，避免两次并发转换互相覆盖输出。

后一半由 Agent 完成：按SKILL.md里的规范，把干净文本生成成结构化技能。这份SKILL.md遵循开放的 Agent Skills 标准，一份文件全宿主通用；它刻意省略allowed-tools字段以保持中立——Copilot CLI、Claude、Amp 各自的工具名不同，各宿主首次使用时会自行提示授权。

实测成本：一次付清，约一美元一本书

项目	数字
`pdftotext`提取（103 页技术书）	0.1 秒，0 张表格、0 个代码块
Docling 提取（同一本书，technical 模式）	164 秒，48 张表格、36 个代码块
真实转换样例	Think Python 2：244 页、119K tokens、19 章；Working Backwards：175K；Pro Git：229K；Moby-Dick：301K
对比整书灌入上下文	book-to-skill 约 5,000 tokens/次查询，省 24×–51×
单本完整生成	$0.88–1.42，一次付清

24×–51× 的差距来自上下文倾倒：Think Python 2 灌进去要 119,264 tokens，大书（AI Engineering）要 256,287，而 skill 每次只加载约 4K 主文件加约 1K 章节文件。倾倒那笔钱每一轮对话都在付，skill 那笔约 1 美元只付一次。

📌 边界与注意事项：扫描版、版权与安全

扫描版 PDF 没有文本层，任何提取器都拿不到字。提取器检查前几页就会停下并说明原因——这是有意的快速失败，让你先跑ocrmypdf input.pdf output.pdf补上文本层再转换，而不是处理完 400 页得到空技能。OCR 交给专用工具，这个项目有意不自带。

处理全程在本地完成，文件不会被上传；但如果你的 Agent 接的是云端模型，喂进去的文本仍遵循该服务商的数据条款。版权方面，从第三方版权书生成的技能必须保持私有，不要发布或分享；开放许可材料与自己的写作才适合分发。安全链压成三句话：提取时剥离零宽字符等不可见 Unicode，防止文档夹带隐形指令；DOCX 解析前拒绝声明 DTD 或实体的 XML 部件，挡掉 XXE 类攻击；生成后的技能在发布前过一遍提示注入扫描，非零退出就停下来交人工复核。