企业官网建设流程全解析

book-to-skill 实战指南：把技术书转成 Agent Skill，回答一个问题只花约 5,000 token

【免费下载链接】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、HTML、RTF、MOBI 等文件，把全书压缩成一个带章节索引的目录——即一个符合开放 Agent Skills 标准的 skill——由 GitHub Copilot CLI、Amp、Claude Code、Hermes Agent、OpenCode、OpenClaw 这些宿主按主题按需加载。下文基于 README.md、SKILL.md、docs/install.md、docs/usage.md、docs/performance.md、docs/faq.md 与book_to_skill/包源码撰写，覆盖安装、运行模式、产物结构、数据流、实测数据与合规边界。

问题与定位：书读完了，知识没留下

买一本技术书，通读一遍，三个月后你连第七章讲过什么都记不起来。于是你会尝试几个常规补救，各自卡死：

📄 在 PDF 里搜关键词——命中的是一串页码，还得逐页翻回去拼答案； 🧠 把书扔给 Agent 直接提问——要么编造，要么回答"我没有这个内容"； 📝 边读边记笔记——攒出一个两百行的文件，之后再没打开过。

book-to-skill 是一个"文档 → 结构化 skill"的转换器，用来把书里反复要查的知识变成 Agent 可以按章节取用的文件。转换完成后，你在会话里输入/your-book-slug 主题词，Agent 会先查 topic 索引定位到对应章节文件，再基于该文件的真实内容作答。

全局收益：回答一个定向问题，进入上下文的 token 从整本书的约 119K–256K 降到约 5,000，节省幅度实测 24×–51×（见"数据说话"一节）。

安装：两条路径，装进 skills 目录才有斜杠命令

docs/install.md 开头就把两种用法划清了界限，别混用：

• 作为 Agent skill 安装（拿到/book-to-skill斜杠命令与完整转换流程）→ 必须git clone进对应宿主的 skills 目录；
• 作为独立 CLI 安装（只要文本提取引擎）→pip install从仓库装包，不会注册任何 skill。

一条命令装到所有兼容宿主（skillsCLI 会解析仓库、检测根级SKILL.md，把含scripts/extract.py与tools/的完整 skill 装进你选中的每个宿主）：

npx skills add virgiliojr94/book-to-skill

手动安装按宿主分组：

# 跨 Agent 根目录：Copilot CLI、Amp、Codex、OpenCode 均原生扫描 git clone https://gitcode.com/GitHub_Trending/bo/book-to-skill.git ~/.agents/skills/book-to-skill # GitHub Copilot CLI 个人目录 git clone https://gitcode.com/GitHub_Trending/bo/book-to-skill.git ~/.copilot/skills/book-to-skill # Claude Code（生成器默认仍写 ~/.agents/skills，Step 10 会补一条软链） git clone https://gitcode.com/GitHub_Trending/bo/book-to-skill.git ~/.claude/skills/book-to-skill # Hermes Agent（HERMES_HOME 按 profile 解析，默认 ~/.hermes；按类别归档） git clone https://gitcode.com/GitHub_Trending/bo/book-to-skill.git \ "${HERMES_HOME:-$HOME/.hermes}/skills/productivity/book-to-skill" # OpenClaw（按当前 state 目录归档；~/.agents/skills 仅在默认 state 下可被发现） git clone https://gitcode.com/GitHub_Trending/bo/book-to-skill.git \ "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/skills/book-to-skill"

安装验证（各宿主的确认方式不同）：

/skills reload # GitHub Copilot CLI：写文件后先 reload /skills info book-to-skill openclaw skills list # OpenClaw hermes skills list # Hermes Agent

Claude Code、Amp、OpenCode 则在新会话中自动发现；Hermes 的项目级安装（.hermes/skills/<category>/book-to-skill）需先执行hermes skills trust /path/to/project再开新会话，否则不会被加载。

独立 CLI 路径（book-to-skill尚未发布到 PyPI，直接装仓库）：

pip install "book-to-skill[pdf,epub,docx] @ git+https://gitcode.com/GitHub_Trending/bo/book-to-skill.git" book-to-skill --check # 报告已安装哪些提取器 python3 scripts/extract.py --check # skill 安装下的等价体检命令

依赖体检：一条命令按格式列清单

--check由 book_to_skill/dependencies.py 的run_dependency_check()驱动：它遍历DEPENDENCY_GROUPS，对每种格式打印 ✓/✗ 状态与精确的安装命令，不需要提供任何文件。提取器按格式依次尝试工具、取第一个可用的；纯文本、Markdown、reStructuredText、AsciiDoc 零依赖（book_to_skill/config.py 的SUPPORTED_EXTENSIONS定义了受支持集合）。

两个值得提前知道的重量级选项：[html]extra 会拉入trafilatura及其完整 HTML 处理栈（lxml、日期解析器、时区数据库、URL 分类器，共 17 个包），换来真正的正文/样板检测而非仅剥<script>/<style>；不带它时bs4回退仍可用，只是没有样板移除（docs/install.md）。MOBI 系列是唯一的硬依赖格式——book_to_skill/dependencies.py 中该组标记required: True，Calibre 缺失即无法转换。

运行模式与调用：四种入口，一个斜杠命令

SKILL.md 的 "Modes of Operation" 定义了四条路径：

命令调用示例（来自 docs/usage.md）：

/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 # glob /book-to-skill ~/articles/new-paper.pdf ~/.claude/skills/project-knowledge # 折叠进既有 skill

skill 生成后的调用方式：

/designing-data-intensive-apps # 加载核心心智模型 /designing-data-intensive-apps replication # 定位并解释某个主题 /designing-data-intensive-apps ch05 # 深入第 5 章

输入不限于一本书

判断标准：凡是你会反复打开、好到希望背下来的结构化文档，都是候选（README.md "Beyond books"）。

• 内部文档（ADR、runbook、入职指南）→ 把整个docs/目录折成一个 skill，编码时随手问；
• 品牌与设计系统（语气规范、语调文档）→ 团队查询一个 skill，而不是再翻 60 页 PDF；
• 研究集群（论文 + 自己的笔记）→ 合并为统一 skill，新材料落地后走折叠流程持续更新；
• 规范与标准（RFC、API 契约、合规文档）→ "反复引用但没背下来"的速查层。

产物解剖：一个目录就是完整知识资产

运行转换后，默认产物落在跨 Agent 根目录~/.agents/skills/<slug>/（一份物理拷贝服务 Copilot CLI、Amp、Codex、OpenCode 与默认 state 的 OpenClaw；Claude Code 经软链访问，Hermes 走自己的分类目录）：

每个文件的生成规范（对应 SKILL.md Step 7–9）

• 章节文件固定模板：Core Idea→Frameworks Introduced→Key Concepts→Mental Models→Anti-patterns→（技术书）Code Examples+Reference Tables→（study 深度）Worked Example→Key Takeaways→Connects To。每章预算由BOOK_TYPE×DEPTH决定：

DEPTH不单独提问，从 Step 4 的用途问答推导：只选"引用章节"→ reference；选了"工作中应用框架/用作者心智模型思考/全部"→ study。规格明确要求 study 深度靠内容挣到而非注水：必须复现一个书中完整示例（Worked Example）、把每个框架的 "How" 展开为显式步骤、给最关键 1–2 个框架加 "Why it works / failure mode" 注记。

• glossary.md：**Term** — definition (Ch N)格式，上限 1,500 token。
• patterns.md：## Pattern Name+ When to use / How / Trade-offs，上限 2,000 token。
• cheatsheet.md定位是推理辅助而非关键词表，内容按优先级组织：① 决策规则（"当 X 做 Y，因为 Z"）→ ② 决策树 → ③ 权衡矩阵 → ④ 阈值与默认值 → ⑤ 识别信号；明确排除"术语→定义"裸行（那是 glossary 的职责）与散文段落（那是章节的职责）。
• 主 SKILL.md：正文压在前部，因为宿主的压缩截断从文件末尾开始；包含 frontmatter、How to Use、约 2,000 token 的 Core Frameworks、Chapter Index、Topic Index 与 Supporting Files 链接。

按需加载机制：chapters/下的文件在未被读取前不计入 skill 预算，只有当你问到相关主题、Agent 通过 Topic Index 定位后才会加载。"约 5,000 token"这一数字的构成即：常驻的核心SKILL.md（约 4K）+ 单次加载的一章（约 1K），出处见 docs/performance.md 的 Discovery Loop Tax 一节。

内部机制：确定性提取器 + 规格驱动的生成器

转换器由两半组成，边界在源码里清晰可查：

• 提取器（确定性 Python 引擎）：入口 scripts/extract.py 是薄包装——强制 stdout/stderr 为 UTF-8（避免 Windows GBK 控制台对 ✓/✗ 字符抛UnicodeEncodeError）、禁用字节码写入、把项目根注入sys.path，随后调用 book_to_skill/cli.py 的main()；后者挂载可选的pdf_inspector钩子（不可用时为 no-op）并进入book_to_skill.utils.main，格式解析按扩展名分发到 book_to_skill/parsers/ 下的 pdf、epub、docx、html、rtf、calibre、text 各模块。
• 生成器（Agent 照规格执行）：SKILL.md 本身就是规格书，定义 Step 0–11、四种模式、预算矩阵与 8 条质量规则（提取结构而非摘要、保留作者精确命名、密度优先、实践者口吻、SKILL.md 前置加载、章节按需、绝不复制原文、主题索引至关重要）。Agent 照此执行，产物天然符合各宿主对根级SKILL.md的识别要求。

完整数据流：

文件 / 目录 / glob / 路径列表 │ ▼ Step 1.5 — 技术书 or 散文为主?（--mode technical|text） ├── technical → Docling（表格+代码保留为 markdown，约1.5s/页） └── text → pdftotext → pypdf → pdfminer（瞬时） │ ▼ scripts/extract.py <paths…> --mode <…> │ 单源失败即跳过并告警，其余继续 ├── <tempdir>/book_skill_work-<pid>/full_text.txt 合并文本，含来源边界标记 └── 同目录/metadata.json 页数、字数、token、被丢弃图片数、workdir、逐来源明细 │ ▼ Step 2.5 成本预估（用户确认后才继续） │ Step 3 结构分析：书名、作者、章节、目录 │ Step 4 用途问答 → 推导 DEPTH ▼ ├── chapters/chNN-*.md（逐章，按预算矩阵） ├── glossary.md / patterns.md / cheatsheet.md └── SKILL.md（核心框架 + 双索引） │ ▼ Step 9.5 安全扫描 → Step 10 软链校验 + 清理本运行工作目录 ~/.agents/skills/<slug>/ （+ Claude Code 软链 / Hermes 分类目录 / OpenClaw state）

数据说话：全部实测，可复现

测量方法：token 计数用tiktoken（cl100k_base），发现循环建模用 tools/discovery_tax.py；所有数字来自 docs/performance.md，均可用下列命令复现。

回答一个定向问题进入上下文的 token 对比：

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×）是一次性建模成本，且随真实章节大小缩放，模型使用的是书实际的目录与章节尺寸。

提取方法对比（103 页技术书，纯 CPU）：

两者的 token 量基本一致（27K，Docling 多 1.2%），差异在结构保真——pdftotext 瞬时但压平结构，Docling 约 1.5s/页但把表格与代码保留为 markdown。结论即 Step 1.5 的分支依据：散文选 text，含代码/表格选 technical。

真实书籍的一次性生成成本（按 Claude Sonnet 4.5 的 $3/$15 每 MTok 输入/输出估算）：

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

整体口径：一本完整 skill 约 1 美元，一次付清；对比每轮都把同一本 PDF 重读进上下文的长期账单，前者是摊销。

避坑与边界：工作目录、CJK、OCR 与重依赖

• 现象：并发跑两个提取，后完成的运行覆盖先完成者的产物，Agent 甚至可能拿另一份文档的metadata.json去生成。原因：旧版共享固定book_skill_work路径。对策：现行实现按 PID 隔离为book_skill_work-<pid>/（book_to_skill/config.py 的default_output_dir()），可用BOOK_SKILL_WORKDIR完全覆盖；运行结束打印Workdir ->、Text ->、Meta ->三条路径，以输出或metadata.json的workdir字段为准，不要假设固定位置。
• 现象：中文电子书的 token 估算偏低几个数量级。原因：WORDS_PER_TOKEN = 0.75只适用于空格分隔的拉丁文本，CJK 几乎无空格，按词切分会把全书压成几个"词"。对策：CJK 码点按CJK_CHARS_PER_TOKEN = 1.5单独计数，且覆盖增补平面（U+20000–U+3FFFF）与康熙部首范围，防止中文书用部首字形渲染正文时被漏计。
• 现象：提取启动后立刻中止、说明无文本可取。原因：扫描版 PDF 是页面图片、没有文本层，任何工具都无从提取。对策：见下方引用块。
• 现象：约 5 万 token 以上的书，整文件Read一次就会烧掉生成所需的预算。原因：200 页书约 75K token，逐章重读 28 遍约烧 200 万输入 token。对策：Step 2.6 的 REPL 式访问——wc -w查规模、grep -n找章节偏移、sed -n '<start>,<end>p'只拉切片、grep -c验证框架确实被提及，让生成成本正比于输出而非源头。
• 现象：装trafilatura后包体膨胀。原因：它拖入完整 HTML 处理栈共 17 个包。对策：资源受限的机器可只留bs4回退（无样板移除，功能仍可用）。
• 现象：生成前看到一份来源数、页/词/token 汇总与成本预估。原因：Step 2.5 强制在生成前读本运行metadata.json做成本预估并等待确认，可随时改走 "analyze only"。

硬前提：扫描版 PDF 必须先 OCR。提取器会检查开头几页并立即中止、给出解释，而不是跑完整本再产出一个空 skill。先自行运行ocrmypdf input.pdf output.pdf，再转换输出文件；工具不内置 OCR 是刻意选择，避免每个用户背上重型依赖。同理，烧进图表里的文字在任何格式下都不会被提取。

合规与许可：MIT 只覆盖工具，规则管住产物

• 项目以 MIT 许可发布，适用范围是转换器本身（代码 + skill 定义），不覆盖用它处理的任何书籍或文档。
• 提取与分析全部在本地运行，工具不上传文件；若你的 Agent 模型在云端，喂入的文本遵循该提供商常规数据条款。
• 产物是合成摘要（框架名、定义、要点），质量规则 7 明确禁止复制原文段落，但内容仍衍生自源材料：第三方版权书的 skill 必须保持私有；只有用户自己的写作、开放许可内容或明确确认拥有公开再分发权的材料才可公开。
• 发布（Step 11）的两条硬规则：版权门先于建仓；可见性是独立的封闭式提问——gh repo create默认--private，只有回答恰好是裸词public才建公开仓库，子串匹配被禁止（"它是公共领域"描述的是书的版权状态，仍得到私有仓库）。发布前必须通过 tools/scan_generated_skill.py 的扫描（Step 9.5），非零退出即停、交人工审阅，不得静默改写后继续。

结尾

book-to-skill 把"每轮对话重复导航一本书"的持续 token 账单，压缩成"转换一次、按需加载"的一次性成本：单次回答约 5,000 token、一本书约 1 美元，且处理全程在本地，产物是你自己的结构化笔记。

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