book-to-skill 完整技术指南：将任意技术书籍、文档与资料集转换为跨宿主 Agent Skill

book-to-skill 完整技术指南：将任意技术书籍、文档与资料集转换为跨宿主 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 项目的完整技术指南。book-to-skill 是一个把任意技术书籍、文档文件夹或资料集合转换为统一 Agent Skill 的开源工具，生成的 Skill 可在 GitHub Copilot CLI、Amp、Claude Code 或 Hermes Agent 中随时学习、查阅并在工作中使用。读完本文，你将掌握其核心工作原理（确定性提取器 + Spec 驱动生成器）、四种运行模式、全宿主安装方式、按格式选择的依赖工具链，以及实测的 token 成本数据（比把整本书丢进上下文少消耗 24×–51×）。

为什么需要"书 → Skill"的转换

你买了一本很好的技术书，读了一遍。三个月后，你忘了第 7 章的存在。这是几乎所有开发者都遇到过的场景，而常见的变通办法都不管用：

• 「我搜一下 PDF」——得到的是页码列表，不是答案；
• 「我问 Agent 这本书的内容」——它要么幻觉，要么说没有内容；
• 「边读边做笔记」——最后得到一份 200 行的文档，再也不会打开。

book-to-skill 的解法是：把书变成结构化 Skill，让 Agent 按需加载。安装后，输入/your-book-slug replication，Agent 会读取对应章节，基于实际内容回答——没有幻觉，不用翻 PDF，书成为工作流的一部分。它兼容任何支持开放 Agent Skills 标准的宿主，GitHub Copilot CLI、Amp、Claude Code 和 Hermes Agent 都读取相同的SKILL.md格式。

三步上手：从文件到按需加载的 Skill

整个过程可以概括为三步：

1. 指定文件、文件夹或 glob——/book-to-skill ./my-book.pdf
2. 提炼成 skill——框架、决策规则、反模式，以及按章节拆分的文件。注意这里提取的是结构，不是摘要；
3. Agent 按需加载——输入/my-book replication，它会读取对应章节，基于真实内容回答，避免幻觉。

生成内容：一次转换得到的完整 Skill 结构

运行/book-to-skill your-book.pdf（或文件夹、glob、文件列表）后，会在 Agent 的 skills 目录下生成完整 Skill，例如 Copilot CLI 的~/.copilot/skills/<slug>/、Amp 或跨 Agent 的~/.agents/skills/<slug>/、Claude Code 的~/.claude/skills/<slug>/、Hermes Agent 的$HERMES_HOME/skills/<category>/<slug>/。

章节文件按需加载——在你问到相关主题之前，它们不会占用 Skill 预算。这正是"查询时 token 与答案规模成正比"的原因。

工作原理：确定性提取器 + Spec 驱动的生成器

book-to-skill 由两半组成（详见 docs/architecture.md）：

• 确定性 Python 提取器：把文档（PDF/EPUB/DOCX/…）转成干净文本 + 元数据；
• Spec 驱动的生成器：你的 Agent 遵循仓库根目录 SKILL.md 中的逐步说明（Step 0–10），把提取结果组装成结构化 Skill。

从源码结构看，提取器的实际调用链是：scripts/extract.py（薄入口包装）→book_to_skill/cli.py的main()→book_to_skill/utils.py的main()，其中utils.py负责 CLI 解析、多源解析、章节检测和 runner（见 utils.py）。cli.py还会在启动时安装一个可选的pdf-inspector钩子，作为 PDF 提取的加速/信任层，未安装时该钩子是 no-op（见 cli.py）。

完整的生成流程（Step 0–10 摘要，来自 SKILL.md 与 docs/how-it-works.md）：

文件 · 文件夹 · glob · 路径列表 │ ▼ Step 1.5 — "技术书还是文字为主？" │ ├── technical → Docling（表格+代码块转 markdown，~1.5s/页） └── text → pdftotext → pypdf → pdfminer（即时） │ ▼ scripts/extract.py <paths…> --mode <technical|text> （单个坏源会被警告跳过，其余源继续处理） │ ├── <临时目录>/book_skill_work-<pid>/full_text.txt （所有源合并，带源标记） └── <临时目录>/book_skill_work-<pid>/metadata.json （聚合统计 + 每源数组） │ ▼ Agent 分析结构（书名、作者、章节、目录——跨所有源） ── 或若目标是已有 skill：折叠新内容（Mode 4） │ ▼ 生成每章摘要（800–1,200 tokens/章；technical 模式含 Code Examples 与 Reference Tables 章节） 生成 glossary、patterns、cheatsheet 生成主 SKILL.md（核心心智模型） │ ▼ 写入宿主 skills 目录，清理临时目录

关于工作目录有一个重要细节：每次运行的临时目录名带 PID（book_skill_work-<pid>），确保同一台机器上的并发提取互不覆盖，且可通过环境变量BOOK_SKILL_WORKDIR完全覆盖（见 config.py）。运行结束时会打印Workdir ->、Text ->、Meta ->三个路径，Agent 应取这些输出路径而非假设固定位置。

设计原则

• Density over completeness（密度优先于完整）——1,000 token 的摘要胜过 10,000 token 的摘录；
• Practitioner voice（实践者口吻）——写"Use X when Y"，而不是"本书讲解了 X"；
• Front-loaded SKILL.md（前置加载）——压缩保留前 ~5,000 tokens，最重要的内容放在最前；
• On-demand chapters（按需章节）——主题索引告诉 Agent 读哪个文件，章节只在需要时加载；
• Never raw text（绝不输出原文）——始终综合、总结、从源中提取信号；
• Graceful degradation（优雅降级）——每种格式都有标准库回退；单个坏源被跳过而非致命。

四种运行模式与使用示例

命令形式为（docs/usage.md）：

/book-to-skill <path-to-document-folder-or-glob>... [skill-name-slug]

支持格式：PDF、EPUB、DOCX、TXT、Markdown、reStructuredText、AsciiDoc、HTML、RTF、MOBI/AZW/AZW3。依据 SKILL.md 的 Modes of Operation，共有四条路径：

1. 完整转换（默认）：提供路径即触发，运行 Steps 0–9，输出完整的 SKILL.md + chapters/ + glossary + patterns + cheatsheet；
2. 仅分析：当用户说 "analyze"、"just extract" 或想先审查再生成时，运行 Steps 0–3 后输出结构化提取报告（框架、原则、技巧），停止，不生成 Skill 文件；
3. 从分析结果生成：已有分析笔记或此前跑过 analyze-only，跳过 Steps 0–3，以已有分析为输入运行 Steps 4–9；
4. 更新/折叠合并（针对已有 Skill）：当输入路径指向一个已有 Skill 目录（含SKILL.md和chapters/子目录），或 slug 已存在于SKILLS_HOME时触发。运行 Step 0、1、1.5、2 提取新文件后，跳到 Step 5 进入 Update/Fold-in 流程，把新内容合并进已有 Skill 文件。

命令示例

# 将多个文件一起处理成统一 skill /book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-research # 将文件夹中所有支持的文件一起处理 /book-to-skill ~/workspace/project-docs/ project-knowledge # 处理匹配 glob 模式的文件 /book-to-skill "~/books/*.epub" my-library # 把新资料折叠进已有 skill 文件夹 /book-to-skill ~/articles/new-paper.pdf ~/.claude/skills/project-knowledge

Skill 创建后，像其他 Agent Skill 一样使用：

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

在 GitHub Copilot CLI 中，文件写入后可能需要运行/skills reload让新 Skill 出现在/skills list；Claude Code 和 Amp 会在下一个会话中自动拾取。

发布生成的 Skill（可选）

转换完成后，converter 会询问是否把 Skill 推送到 GitHub 作为独立仓库。可见性会作为单独问题询问，且gh repo create默认使用--private；只有当回答是"public"时才创建公开仓库。注意，关于源文档许可证的一句话（如"它是公有领域"）不能作为可见性回答。第三方版权书籍生成的 Skill 必须保持私有。已发布 Skill 可在任意 Agent Skills 宿主上用一条命令安装：

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

这需要已认证的ghCLI。生成的仓库自带 README，Skill 文件夹即 git 工作副本，后续 fold-in 更新可直接推送到同一远程。

安装：覆盖全部宿主与独立 CLI

需要先区分两种使用方式（docs/install.md）：

• 作为 Agent Skill（在 Claude Code、Copilot CLI、Amp、Codex、Hermes Agent 中获得/book-to-skill斜杠命令）——把仓库 git clone 进你的 skills 文件夹，这才会注册斜杠命令并启用完整转换流程；
• 作为独立 CLI（仅文本提取引擎）——用pip从仓库安装，不注册Agent Skill，只安装提取引擎。

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

跨 Agent skills CLI：一条命令

npx skills add virgiliojr94/book-to-skill

它会解析仓库、检测根级SKILL.md，并把完整 Skill（含scripts/extract.py和tools/）安装到你选择的每个宿主的 skills 文件夹。

各宿主手动安装

GitHub Copilot CLI（个人 Skill）：

git clone https://github.com/virgiliojr94/book-to-skill.git ~/.copilot/skills/book-to-skill # 然后在 copilot 会话中： /skills reload /skills info book-to-skill

或使用 Copilot CLI、Amp 和 Codex 都能发现的跨 Agent 路径：

git clone https://github.com/virgiliojr94/book-to-skill.git ~/.agents/skills/book-to-skill

OpenAI Codex读取~/.agents/skills并跟随符号链接，上述 clone 即可；本地检出也可以用链接而非复制：

ln -s /path/to/book-to-skill ~/.agents/skills/book-to-skill

Hermes Agent：

git clone https://github.com/virgiliojr94/book-to-skill.git \ "${HERMES_HOME:-$HOME/.hermes}/skills/productivity/book-to-skill"

HERMES_HOME是 profile 感知的，默认~/.hermes。converter 也可放在其他已有 Hermes 分类下。生成的书 Skill 应放到与主题匹配的分类，而不是一律复用productivity。项目本地安装用.hermes/skills/<category>/book-to-skill，并需先显式信任项目：

hermes skills trust /path/to/project hermes skills list

Hermes 在项目被信任前不会加载.hermes/skills/或.agents/skills/下的项目本地 Skill。

Claude Code：

git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill

然后在任意 Agent 会话中：

/book-to-skill ~/path/to/your-book.pdf # 或 /book-to-skill ~/path/to/your-book.epub

独立 CLI（pip）

book-to-skill尚未发布到 PyPI，pip直接从仓库安装：

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

注意：[html]extra 比其他重，它会拉入trafilatura（连同 lxml、日期解析器、时区数据库、URL 分类器等共 17 个包），用于真正的主内容/样板检测而不是只剥离<script>/<style>。在资源受限的机器上安装前需知晓这点——不装[html]时bs4回退依然可用，只是没有样板移除。

依赖要求：按格式选择提取工具

提取器按格式依次尝试工具，使用第一个可用的；若均未安装，会提示应运行的安装命令。纯文本、Markdown、reStructuredText 和 AsciiDoc 无需额外依赖。

一条命令检查环境：python3 scripts/extract.py --check会打印每种格式已安装的提取器，以及缺失项的精确安装命令——无需提供文件。该命令在 utils.py 中分发到依赖探测逻辑。

PDF —— 按书籍类型选择

提取开始前，Skill 会询问书籍是技术书还是文字为主，并自动选择合适工具（即流程中的 Step 1.5）。Docling 保留 Markdown 表格与代码块；pdftotext 对纯散文更快。命令行层面对应--mode technical|text（独立 CLI 用法见 utils.py）。

EPUB 与其他格式

EPUB：

其他格式：

从源码看，这些工具与格式的映射集中定义在 config.py：支持扩展名包括.pdf、.epub、.docx、.rtf、.txt/.text/.md/.markdown/.rst/.adoc/.asciidoc、.html/.htm/.xhtml和.mobi/.azw/.azw3，Python 依赖映射则覆盖 pdf-inspector、docling、pypdf、pdfminer.six、ebooklib、beautifulsoup4、python-docx、striprtf、trafilatura。批处理时单个坏源抛出ExtractionError会被捕获并以 WARNING 跳过，其余源继续处理（见 utils.py）。

扫描 PDF 需先 OCR

页面是图片、没有文字层的 PDF（拍照或扫描的书）没有任何可提取的文字。提取器会检查前几页并立即停止并说明原因，而不是处理完整书籍后生成空 Skill。请先自行 OCR，再转换结果：

ocrmypdf input.pdf output.pdf

book-to-skill 刻意不自带 OCR：那会给每位用户带来重型依赖和缓慢有损的步骤，而专门工具已能更好地处理这一场景。同理，图表中内嵌的文字也无法从任何格式提取。

性能与成本：Discovery Loop Tax（发现循环税）

读 PDF 的 Agent 不只是读，它还要导航：反复获取目录、回溯、每一轮重新处理。book-to-skill 在转换时一次性支付结构化成本，查询时 token 与答案规模成正比——比把书丢进上下文少 24×–51×。完整方法论、数据与逐书表格见 docs/performance.md，所有数字均为实测（tiktokencl100k_base 计数 +tools/discovery_tax.py建模），可用文中命令复现。

提取基准

在一本 103 页技术书上（仅 CPU）：

pdftotext 即时但拍平结构；Docling 约 1.5s/页但把表格和代码保留为 markdown。散文书选 text 模式，代码/表格书选 technical 模式。

真实转换数据

† 章节自动检测需要显式的Chapter N/Capítulo N标题。Pro Git 使用小节标题、Moby-Dick 正文使用裸标题/罗马数字，因此两者都不自动分段——提取与转换仍正常，但需要手动指向章节。

查询时 token 对比（回答一个问题）

book-to-skill 加载常驻核心（~4K）+ 一个已编译章节（~1K）≈5,000 tokens：

• 上下文 dump 优势（24–51×）是最强的主张：该成本在每一轮对话都会重现；
• **发现循环优势（2.4–15.6×）**是一次性成本，且假设模型使用书的真实目录/章节大小，随章节大小伸缩。

可用如下命令自行复现（tools/discovery_tax.py）：

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

生成成本

一次完整转换的估算（基于实测 tokens，Claude Sonnet 4.5，$3/$15 每 MTok 输入/输出）：

大致每本书约 $1生成完整 Skill——只付一次；而每个会话都把 PDF 重新读进上下文，长期成本远高于此。

生成 Skill 的输出质量

一次自适应深度改进（v1.0.0，第 20 号 PR）对单个章节的前后对比：

新 spec 把 cheatsheet 从"术语表"变成了"决策层"，并为学习深度的章节提供可复现的完整示例。

不止于书籍：适用输入类型

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

• 内部文档——架构决策记录、运行手册、入职指南。把整个docs/文件夹折叠成一个 Skill，编码时随时提问；
• 品牌与设计系统——语调指南、语气文档、组件原则。把品牌手册变成 Skill，团队查询代替翻阅 60 页 PDF；
• 研究资料簇——一叠论文加自己的笔记，合并为统一 Skill，新资料到来时可更新（见上文 Mode 4）；
• 规范与标准——RFC、API 合约、合规文档——常查但从没背下来。

如果你经常重新打开某份文档、希望自己已经背下来，它就是候选。

安全与版权边界

文档→上下文供应链的安全加固

不可信文档会流入 Agent 上下文，再流入之后会被其他 Agent 加载的生成 Skill——这是一条 document→context 供应链。仓库的加固是分层的（详见 docs/architecture.md）：

• 提取净化（book_to_skill/sanitize.py）——在统计与写出full_text.txt之前，剥离每个解析器输出中的零宽字符（U+200B/200C/200D/2060/FEFF）与 Unicode 标签块（U+E0000–E007F），使文档携带的不可见指令永远到不了 Agent；报告移除数量，并拒绝"无可视内容"的源；
• DOCX XXE / Billion-Laughs 防护（parsers/docx.py）——解析前拒绝任何声明了 DTD 或实体的 XML 部件；
• 子进程参数注入防护——文件路径在到达pdftotext/pdfinfo/ebook-convert前先绝对化，使以-开头的文件名无法被当作 flag 读取；
• 生成 Skill 扫描（tools/scan_generated_skill.py）——生成器 Step 9.5 的咨询性步骤，跨生成的SKILL.md、chapters/*.md、glossary.md、patterns.md、cheatsheet.md标记指令覆盖短语、模型控制标签、残留不可见 Unicode、权限扩大的 frontmatter 和类外泄内容；发现结果只点名规则与文件位置，绝不输出命中的文本；
• CI——PR 上运行 CodeQL、Bandit（HIGH 门禁）、Zizmor 与依赖 CVE 审查。

版权与合理使用

book-to-skill不包含任何书籍内容——一页都没有。它是你指向已有文件的转换器。

• 本地处理。提取与分析在你的机器上运行。本工具不会上传你的文件。（若 Agent 的模型在云端运行，你喂给它的文本遵循该提供商的数据条款——与任何 prompt 相同。）
• 使用你自己的副本。带上你购买的书、公司拥有的文档，或你有权阅读的论文。
• 输出是你的笔记。生成的 Skill 是结构化、综合的衍生内容——框架名、定义、要点——不是原文再现。Skill 明确从不复制原始段落（见 Quality Rule #7）。把它当作手写学习笔记：属于你，供个人使用。
• 不要重新分发。发布或分享受版权保护作品所生成的 Skill 可能侵犯权利人权益。第三方书籍的 Skill 请保持私有。内部文档、自己的写作和开放许可材料可在其许可证范围内分享。

如有疑问，请遵循源文档的许可证或条款。本项目是工具；如何使用由你负责。仓库本身采用 MIT 许可证，仅适用于转换器（代码 + Skill 定义），不适用于你用它处理的任何书籍或文档。

仓库结构与扩展

仓库结构如下（与 README 中 [仓库结构] 说明一致）：

book-to-skill/ ├── SKILL.md # Skill 定义 + 逐步说明（生成器 spec） ├── scripts/ │ └── extract.py # 薄入口包装 ├── book_to_skill/ # 模块化提取包 │ ├── cli.py # 入口 main，pdf-inspector 钩子 │ ├── config.py # 扩展名、路径、依赖常量 │ ├── dependencies.py # 可选依赖探测 + --check │ ├── exceptions.py # ExtractionError（单源失败，批处理安全） │ ├── utils.py # CLI 解析、多源解析、章节检测、runner │ ├── sanitize.py # 零宽/Unicode 控制字符净化 │ └── parsers/ # 各格式解析器（pdf、epub、docx、html、rtf、calibre、text） ├── tools/ │ ├── discovery_tax.py # 测量 token 成本 vs 上下文 dump / discovery loop │ ├── validate_skill.py # 按宿主规则校验生成的 SKILL.md（--lens claude|copilot|amp|hermes） │ └── scan_generated_skill.py # 生成 Skill 的提示注入扫描 ├── tests/ # pytest 套件（提取、检测、discovery tax） ├── docs/ │ ├── performance.md # 实测基准、discovery tax、成本 │ ├── architecture.md # 流水线 + 组件图 │ ├── how-it-works.md # Step 0–10 完整走查 │ ├── usage.md # 全部模式与示例 │ ├── install.md # 全部宿主与独立 CLI │ └── faq.md # 常见问题 ├── CHANGELOG.md # 发布历史（semver） └── README.md # 英文 README（README.zh-CN.md 为简体中文翻译）

扩展新格式：在book_to_skill/parsers/新增<fmt>.py，在config.py注册扩展名，在dependencies.py接入依赖探测，在utils.extract_single_file中分支。

扩展新生成行为：修改 SKILL.md 中对应 Step，保持精简并用证据支撑改动（见 CONTRIBUTING.md）。

FAQ：常见疑问解答

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

可以——但每轮对话都会烧掉那份 token 预算。一本 400 页的书约 200K tokens；而用 Skill，只有与问题相关的章节会加载——通常是 SKILL.md 核心（~4K）加上你问的那一章（~1K），其余留在磁盘上。

经济性是摊还而非规模问题。粘贴书的做法在每个会话的每一轮都付全额 token 账单；book-to-skill 只付一次提取成本，之后每轮只加载需要的切片。上下文窗口越大越重要——大窗口让 dump 变得可能，而不是便宜。

更重要的是：原始文本注入是检索，Skill 是推理。加载章节文件时，Agent 不是在找关键词匹配，而是在用预先提取的具名框架、原则和心智模型工作——这些是为应用而结构化，不是为阅读。

「Claude 已有 1M token 上下文窗口，不能一直保持整本书加载吗？」

更大的窗口改变的是装得下什么，不是什么更聪明：

• 按 token、按调用付费——1M 窗口不会让 token 免费，只会让大额重复账单成为可能；
• 回忆随填充退化——模型在接近满的上下文中找回特定事实会失准（"lost in the middle"）；回答一个问题时，1K 的精选章节胜过 200K 的原始散文；
• 窗口 ≠ 结构——整本书在上下文中仍是每轮都要重新解析的原始文本；Skill 提供的是预先提取的框架——推理，而非检索。

大窗口用在它擅长的地方：一次性扫过永远不会再用的材料；反复查阅的知识用 Skill。

「这不就是 RAG 吗？」

RAG 在查询时工作：切块 → 全部嵌入 → 找相似向量 → 注入 prompt，专为"找到讲 X 的部分"优化。book-to-skill 在编译时工作：一次深度分析提取作者实际的框架、命名它们、描述何时使用、捕获反模式。输出是作者花费多年构建的结构，而不是对其句子的相似度搜索。

RAG 的回答是"这些是接近你查询的块"；Skill 的回答是"这是作者构建的 12 个框架，可用于推理"。按任务形状选择：宽而浅（几十本书的库，找提到 X 的部分）→ RAG 胜出；窄而深（一本书或紧密相关的源簇，工作中应用框架）→ book-to-skill 胜出。两者互补而非竞争：RAG 给书架建索引，book-to-skill 精通一本书。

「热门书已在训练数据里，何必麻烦？」

对广为人知的书，Agent 有一般性知识——但它是被压缩、跨整个互联网讨论平均过的，可能幻觉具体引用或章节位置。book-to-skill 基于你的实际副本工作：每个框架名、每个反模式列表、每个章节号都锚定在你提供的文本上，无训练数据漂移、无幻觉章节标题。它对 Agent 完全不了解的书尤其出彩：小众技术参考、公司内部文档、近期出版物、翻译作品。

「我的 PDF 是扫描件，提取立即停止。为什么？」

因为扫描 PDF 是一叠页面图片——其中没有可提取的文本。PDF 链中的每个工具都读取文字层，扫描件无论跑哪个都会一无所获。提取器检查前几页并立即停止说明原因——这个检查让失败只花你几秒钟，而不是对一本 400 页的书跑完整遍最后得到一个空 Skill。先 OCR 再转换：

ocrmypdf input.pdf output.pdf

结语

book-to-skill 的核心价值在于一次编译、反复受益：转换时一次性支付结构化成本，之后每个会话只按需加载相关章节，把"书"真正变成工作流的一部分。无论输入是一本技术书 PDF、一整个docs/文件夹，还是不断更新的论文资料簇，它都以统一的 Agent Skills 标准产物交付，可跨 GitHub Copilot CLI、Amp、Claude Code、Codex 与 Hermes Agent 使用。想深入掌握细节，可以继续阅读 docs/how-it-works.md（Step 0–10 完整走查）、docs/usage.md（全部模式与示例）、docs/install.md（宿主与依赖安装）、docs/performance.md（实测数据）与 docs/architecture.md（组件与安全设计）。

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