book-to-skill 完整实战指南：10 分钟把技术书转成按需加载的 Agent Skill

book-to-skill 完整实战指南：10 分钟把技术书转成按需加载的 Agent Skill

【免费下载链接】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 等）转换成 Agent 可按需加载 Skill 的开源转换器。如果你日常用 Agent 干活，可以让读过一遍的书变成随时可查的知识库。本文覆盖安装、跑通首次转换，以及每个数字的出处。

先算一笔账：问 Agent「这本书里怎么讲背压」，它不只是读，而是在导航——每轮重新拉目录、回溯、重处理内容。官方实测里，一本 501 页的书，回答一个定向问题会把 256,287 token 拉进上下文。book-to-skill 把这份导航成本前置到转换时一次性付清，之后查询只加载相关章节。

先跑起来：10 分钟安装并首次转换

二选一：Agent skill 还是独立 CLI

两条安装路径能力不同，别混用（详见 docs/install.md）：

一条命令装进任意宿主

skill 遵循开放 Agent Skills 标准，一次安装覆盖所有兼容宿主：

npx skills add virgiliojr94/book-to-skill

skillsCLI 会解析仓库、检测根级SKILL.md，把完整 skill（含scripts/extract.py与tools/）装进你选择的每个宿主的 skills 目录。

手动安装：各宿主路径

# 跨 Agent 路径：Copilot CLI、Amp、Codex 都能发现 git clone https://gitcode.com/GitHub_Trending/bo/book-to-skill ~/.agents/skills/book-to-skill # GitHub Copilot CLI 个人 skill git clone https://gitcode.com/GitHub_Trending/bo/book-to-skill ~/.copilot/skills/book-to-skill # Claude Code git clone https://gitcode.com/GitHub_Trending/bo/book-to-skill ~/.claude/skills/book-to-skill # Hermes Agent（HERMES_HOME 按 profile 感知，默认 ~/.hermes） git clone https://gitcode.com/GitHub_Trending/bo/book-to-skill \ "${HERMES_HOME:-$HOME/.hermes}/skills/productivity/book-to-skill" # OpenClaw（活动状态目录；默认 ~/.openclaw） git clone https://gitcode.com/GitHub_Trending/bo/book-to-skill "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/skills/book-to-skill" # OpenCode 自有托管根（可选；跨 Agent 路径同样有效） git clone https://gitcode.com/GitHub_Trending/bo/book-to-skill ~/.config/opencode/skills/book-to-skill

独立 CLI 则从仓库直接装（尚未发布到 PyPI）：

pip install "book-to-skill[pdf,epub,docx] @ git+https://gitcode.com/GitHub_Trending/bo/book-to-skill" book-to-skill ~/path/to/book.pdf --mode text # 或 python -m book_to_skill ... book-to-skill --check # 报告已安装哪些提取器

30 秒体检依赖

python3 scripts/extract.py --check

对每种格式打印已安装/缺失的提取器，并给出安装缺失项的精确命令，无需提供任何文件。报告由 book_to_skill/dependencies.py 的run_dependency_check()遍历DEPENDENCY_GROUPS生成，逐项显示 ✓/✗ 与 ready / fallback available / MISSING 结论。

依赖矩阵（提取器按格式依次尝试、取第一个可用）：

缺失包时提取前会询问是否安装（--install-missing ask传入，见 SKILL.md Step 2）；非交互会话默认走回退，除非显式yes。环境变量BOOK_SKILL_INSTALL_MISSING可预设该行为。

跑第一次转换并验证产物

在 Agent 会话里：

/book-to-skill ~/path/to/your-book.pdf

流程中 skill 会先问书是 technical 还是 text-heavy（Step 1.5，决定提取链），随后运行 scripts/extract.py，在每次运行独立的工作目录<tempdir>/book_skill_work-<pid>/下产出两个文件：full_text.txt（全部来源合并文本，带来源边界标记）与metadata.json（总 token、页数、逐来源明细）。结束时终端打印Workdir ->、Text ->、Meta ->三行——以这三行输出为准，不要假设固定路径。

验证产物：

# 查看本次运行的统计（用 Meta -> 打印的路径） cat /tmp/book_skill_work-<pid>/metadata.json # 按指定宿主规则校验生成的 SKILL.md（lens 可选 claude|copilot|amp|hermes|opencode） python3 ~/.agents/skills/book-to-skill/tools/validate_skill.py --lens claude ~/.agents/skills/<slug>/SKILL.md # 建议性安全扫描（加载/发布前） python3 ~/.agents/skills/book-to-skill/tools/scan_generated_skill.py ~/.agents/skills/<slug>

然后开新会话调用（GitHub Copilot CLI 需先/skills reload才会出现在/skills list；Claude Code 与 Amp 下一个会话自动识别）：

/<slug> ch05

提取完成后生成器会清理本次运行的工作目录（Step 10），不留下临时产物。

生成物解剖：5 个文件与它们的 token 预算

运行/book-to-skill your-book.pdf后，skills 目录下会出现这样一套文件（规模出自 README.md 的 What it generates 表）：

章节文件按需加载——不问到相关主题之前，不占用 skill 的常驻预算。常驻的只有SKILL.md加上一次读入的一章。

逐文件的生成规范（SKILL.md Steps 7–9）

• 逐章文件（Step 7）用固定模板顺序：Core Idea→Frameworks Introduced→Key Concepts→Mental Models→Anti-patterns→（技术书才有）Code Examples+Reference Tables→（study 深度才有）Worked Example→Key Takeaways→Connects To。
• glossary.md（Step 8）：每个重要术语按字母排序，格式**Term** — definition (Ch N)。
• patterns.md（Step 8）：所有具体技术/设计模式/算法，格式## Pattern Name+ When to use / How / Trade-offs。
• cheatsheet.md（Step 8）定位是推理辅助而非关键词表。优先级：① 决策规则（"当 X 时做 Y，因为 Z"）→ ② 决策树/流程图 → ③ 权衡矩阵 → ④ 阈值与默认值 → ⑤ 识别信号（tells & smells）。刻意避免裸的"术语→定义"行（那是 glossary 的活）和散文段落（那是章节的活）。
• 主 SKILL.md（Step 9）：正文严格 < 4,000 token，且最重要的内容放最前——因为压缩截断从文件末尾开始。含 frontmatter（name、description）、How to Use、约 2,000 token 的 Core Frameworks & Mental Models、Chapter Index、Topic Index 与 Supporting Files 链接。

每章花多少 token 由谁决定

SKILL.md Step 7 的预算由BOOK_TYPE（Step 1.5 问出）与DEPTH（Step 4 用途问答推导）两维决定：

DEPTH不单独提问：用途只选"引用特定章节"→ reference；选到"工作中应用框架 / 用作者心智模型思考 / 以上全部"→ study。study 深度靠内容挣来——必须补一个可复现的 Worked Example、把每个框架的 How 展开为显式步骤、给最关键的 1–2 个框架加 Why it works / failure mode 注记，而不是把数字调大。

生成之后怎么调用

/designing-data-intensive-apps # 加载核心心智模型 /designing-data-intensive-apps replication # 查找并解释某个主题 /designing-data-intensive-apps ch05 # 深入第 5 章 /designing-data-intensive-apps "what chapters do you have?" # 浏览章节索引

另有三种运行模式（SKILL.md Modes of Operation）：Analyze Only（只走 Steps 0–3，产出结构化提取报告不生成文件）、Generate from Prior Analysis（拿既有分析直接走 Steps 4–9）、Update / Fold-in（新素材折进已有 skill，下节细讲）。

底层机制：PDF 到 Skill 的五步链路

整套系统拆成两半：一半是确定性的 Python 提取器，一半是规格驱动的 Agent 生成器。

1. 入口。scripts/extract.py 是薄包装：强制 UTF-8 输出（避免 Windows GBK 控制台对 ✓/✗ 抛UnicodeEncodeError）、把项目根注入sys.path，然后调用 book_to_skill/cli.py 的main()；cli 可选挂载pdf_inspector钩子（缺失时为空操作），再交给book_to_skill.utils.main。
2. 选工具。Step 1.5 问出 technical / text 后，以--mode <technical|text>传入：technical 走 Docling，text 走 pdftotext → pypdf → pdfminer 回退链。
3. 按扩展名分发。book_to_skill/parsers/ 下每个格式一个模块（pdf、epub、docx、html、rtf、calibre、text）；单个坏来源跳过并告警，其余继续处理。
4. 落盘。合并文本与聚合统计写入<tempdir>/book_skill_work-<pid>/的full_text.txt和metadata.json（目录名含 PID，为并发运行互不覆盖，见 book_to_skill/config.py）。
5. 生成。Agent 拿 SKILL.md 当规格书，按 Step 0–11 执行——Step 2.5 先做成本预估等用户确认，Step 2.6 规定大书用切片读取，Step 9.5 做安全扫描，Step 10 清理工作目录并汇报，Step 11 可选发布——最后把 skill 写入 Step 5 表格对应的宿主目录。

生成器受 8 条质量规则约束（SKILL.md Quality Rules）：提取结构而非摘要、保留作者的精确命名、密度优先于完整、实践者口吻（"Use X when Y" 而非"书中讲到 X"）、SKILL.md 前置加载、章节文件按需加载、绝不复制原文、主题索引是导航路径。提取一半可复现，生成一半照规格走，产物布局因此天然符合各宿主对根级SKILL.md的要求。

数字：24×–51× 的 token 节省与约 1 美元的一次性成本

所有 token 计数口径为tiktoken（cl100k_base），发现循环建模在 tools/discovery_tax.py，以下数字均可用仓库内命令复现；成本列是按实测 token 乘以 Claude Sonnet 4.5 每 MTok $3/$15 的估算，不是实测账单（方法论见 docs/performance.md）。

回答一个问题，三种口径

回答一个定向问题进入上下文的 token 数（实测）：

~5,000 的构成：常驻核心 ~4K + 一章编译摘要 ~1K。复现：

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

官方口径的解读：vs 塞入上下文（24–51×）是最强主张，因为那份成本在每一轮对话都会重新发生；vs discovery loop（2.4–15.6×）是一次性导航成本，且随章节大小缩放——建模用的是书真实的目录与章节尺寸。

提取基准：pdftotext 与 Docling 的取舍

103 页技术书、纯 CPU 实测：

pdftotext 瞬时完成但把结构压平；Docling 约 1.5s/页，把表格和代码块保留为 markdown。散文书选 text 模式，含代码/表格的书选 technical 模式。

每本书的一次性成本（实测提取 + 估算成本）

真实转换的页数、提取 token 与自动检出章节数为实测（可用python3 scripts/extract.py <你的书.pdf> --mode text后读metadata.json复现）；成本列为按价格估算：

† Pro Git 用小节标题而非Chapter N作章首，不自动分段；‡ Moby-Dick 正文是裸标题，但罗马数字目录被检出 133 章。两种情况提取与转换都照常工作，只是需要手动指向小节。

一本完整 skill 约 1 美元、一次性；对比表里每个会话都把同一本 PDF 重新读进上下文的长期成本，差距随使用次数放大。

产物质量的一次可验证改进

docs/performance.md 记录了 v1.0.0 自适应深度规格升级在某章上的前后对比（实测 token 计数）：

变化方向很具体：cheatsheet 从"术语表"改造成"决策层"，学习深度章节带上可复现的完整示例。

进阶玩法：glob 输入、fold-in 更新与发布独立仓库

多文件、目录、glob 输入

/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

最后一行同时是 fold-in 形态：输入指向一个已存在的 skill 文件夹（含SKILL.md和chapters/），即触发 Mode 4。

Fold-in：新材料怎么折进已有 skill

SKILL.md 的 Update / Fold-in Workflow 分五步：

1. 解析既有 skill：读SKILL.md的 Chapter Index、Topic Index、Core Frameworks，列chapters/找最高章节号（如ch12），读三个支撑文件看已收录术语与框架；
2. 内容匹配：新内容与既有章节同题 → 读原章节文件，合并新细节后整体重写；引入新主题 → 从最高号之后续编ch13-*.md，按 Step 7 模板生成；
3. 合并支撑文件：glossary 合并后重新字母排序，同术语追加新引用（**Term** — definition (Ch 4, Ch 13)）；patterns 追加新条目并保持 < 2,500 token；新决策规则并入 cheatsheet；
4. 重生成主SKILL.md：章节数递增、更新日期、Chapter Index 追加新章节、Topic Index 按字母合并（- **Topic** → ch05, ch13）；
5. 重走 Step 9.5 扫描、清理与汇报。

各宿主的手动安装细节

• GitHub Copilot CLI：文件写入后需/skills reload，新 skill 才出现在/skills list；/skills info book-to-skill可查详情。
• Claude Code：只扫~/.claude/skills。skill 写在跨 Agent 根时，转换器会自动ln -sfn建符号链接并读回验证（Windows 上ln -s可能变成拷贝，报告以磁盘实际状态为准，不会谎报"已链接"）。
• Hermes Agent：个人 skill 按类别分区存放，不扫跨 Agent 根，生成书籍 skill 应放入与主题匹配的类别；项目级安装（.hermes/skills/<category>/book-to-skill）必须hermes skills trust /path/to/project之后开新会话，否则不加载。
• OpenClaw：共享的~/.agents/skills路径只在OPENCLAW_STATE_DIR未设置或为默认~/.openclaw时被发现；换过状态目录时用openclaw skills list验证。
• OpenCode：原生扫~/.agents/skills，无需 trust 步骤；skill 不出现时开新会话。

把 skill 发布成独立仓库（可选）

转换完成后，转换器会询问是否发布（SKILL.md Step 11）。要求已认证的ghCLI；没有则走免 gh 路径——你在 Web 界面建好空仓库，再执行git init/add/commit加git push。发布前必须通过 Step 9.5 扫描（tools/scan_generated_skill.py）：扫描失败即停，交人工审阅，不得静默改写。两条硬规则：

1. 可见性是独立、封闭式的提问，绝不推断、绝不从先前回答里读出来。gh repo create默认--private；只有回答恰好是裸词public才建公开仓库。子串匹配被禁止——"它是公共领域"描述的是书的版权状态，不是仓库可见性，仍然得到私有仓库。多义词句、沉默或自行推断都不算同意；重问一次仍非裸词，用--private并在报告中说明。私有仓库可随时转公开，公开推送的书籍衍生内容无法撤回。
2. 版权门始终先于建仓。章节文件是合成摘要而非原文，但仍衍生自源材料：第三方版权书的 skill 必须保持私有；只有用户自己的写作、开放许可内容、或用户明确确认拥有公开再分发权的材料才可公开，且要说明属于哪种情况。

发布后仓库自带 README，根级SKILL.md布局正是skillsCLI 检测的形态，任何宿主一条命令安装：

npx skills add https://github.com/<you>/<your-book-slug> --skill <your-book-slug>

skill 文件夹同时成为 git 工作副本，后续 fold-in 更新可直接推送到同一远端。

踩坑清单：源码与文档里聚合的 8 个易错点

• 两次并发转换互相覆盖、skill 生成自错误文档→ 旧版共享固定book_skill_work目录，后完成者静默替换先完成者的产物，轮询metadata.json可能拿到别的文档 → 现行版本每次运行独立目录book_skill_work-<pid>（book_to_skill/config.py）；一律以输出Workdir ->或metadata.json的workdir字段为准，可用BOOK_SKILL_WORKDIR完全覆盖。
• 扫描版 PDF 产出空 skill→ 页面只是图片、没有文本层，任何工具都无从提取；提取器检查开头几页会立即中止 → 先跑ocrmypdf input.pdf output.pdf再转换。
• 中日韩电子书 token 估算严重偏低→WORDS_PER_TOKEN = 0.75按空格分词，中文几乎没有空格 → 源码对 CJK 码点按CJK_CHARS_PER_TOKEN = 1.5直接计数，且覆盖增补平面（U+20000–U+3FFFF）与康熙部首范围，部首字形渲染正文不会漏计。
• 大书的生成成本爆炸→ 每读一章就整文件重读full_text.txt：200 页约 75K token，28 章重读约 200 万输入 token → 超过约 50K token 的书改用wc -w查规模、grep -n找章节偏移、sed -n '<start>,<end>p'拉切片、grep -c验证框架确实被提及（SKILL.md Step 2.6）。
• 某格式提取质量差却说不出原因→ 可选依赖缺失时静默走了回退链（ebooklib→zipfile、python-docx→ZIP/XML、bs4→html.parser、striprtf→正则）→ 先跑python3 scripts/extract.py --check，按它打印的精确命令装缺失项。
• pip 装[html]后依赖膨胀→trafilatura带进 17 个包的完整 HTML 处理栈（lxml、日期解析、时区库、URL 分类器） → 只需基础 HTML 解析时用 bs4 回退即可（无样板移除），确实要正文/样板检测再装[html]（docs/install.md）。
• MOBI/AZW 直接失败→ 这是唯一无回退的格式，只认 Calibreebook-convert（book_to_skill/dependencies.py 中该组required: True）→ 先装 Calibre。
• pipx 装的 docling 体检却显示缺失→ 可执行文件在 PATH 上但模块在当前解释器不可导入 →--check会识别该情况并提示改用对应虚拟环境的 Python 运行提取脚本。

边界：版权、合理使用与 MIT 的范围

book-to-skill 不包含任何书籍内容——它是转换器，指向你已拥有阅读权的文件（README.md Copyright & fair use）：

• 处理在本地进行。提取与分析都在你的机器上，工具不上传文件。若 Agent 模型在云端，喂给它的文本遵循该提供商的常规数据条款——与任何 prompt 相同。
• 用你自己的副本。你买的书、公司拥有的文档、你有权阅读的论文。
• 输出是你的笔记。生成的 skill 是结构化、综合后的衍生品——框架名、定义、要点，不是原文复刻；质量规则 7 明确禁止复制原始段落。
• 不要重新分发。发布或共享版权作品的生成 skill 可能侵犯权利人利益：第三方书籍的 skill 保持私有；内部文档、你自己的写作与开放许可材料可在许可范围内共享。

许可证是MIT，覆盖本仓库的转换器（代码 + skill 定义），不覆盖你用它处理的任何书籍或文档。拿不准时，遵循源文档的许可或条款。

一次转换之后，书就不再是需要搜索的文件，而是 Agent 可随时调用的工具——每次提问的 token 账单从"整本书"降到"答案本身"。

进一步阅读

• docs/how-it-works.md — Steps 0–10 完整走查、提取模式与 token 预算
• docs/usage.md — 所有运行模式与命令示例
• docs/install.md — 全部宿主的安装方式、可选提取器与独立 CLI
• docs/performance.md — 实测基准、Discovery Loop Tax 方法论与生成成本
• docs/architecture.md — 流水线与组件图
• docs/faq.md — "为什么不直接塞 PDF"、成本、隐私、非书籍输入
• CHANGELOG.md — semver 版本历史

【免费下载链接】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