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、HTML、Markdown、RTF、MOBI/AZW 等技术书籍与文档转换为结构化 Agent 技能SKILL.md的转换器其输出可直接运行在 Claude Code、GitHub Copilot CLI、Amp 与 Hermes Agent 等支持开放 Agent Skills 标准的宿主上。读完本文你将掌握它的核心设计理念提取结构而非摘要、两种安装路径Agent 技能与独立 CLI、四种操作模式、按需章节与 token 预算机制以及它在源码层面的实现证据。一、为什么需要 book-to-skill知识的读过即忘困境项目 READMEREADME.md描述了一个几乎所有技术读者都经历过的场景你买了一本好书通读一遍三个月后却连第 7 章讲过什么都记不清了。常规的补救手段各有缺陷直接搜 PDF得到的是一串页码而不是答案让 Agent 直接回答这本书Agent 要么幻觉要么承认自己根本没有这本书的内容边读边做笔记最终往往产出一份 200 行的文档之后再也没打开过。book-to-skill 的解法是把书编译成一份结构化技能让 Agent 按需加载——你只需要输入/your-book-slug 主题Agent 就会读取正确的章节文件从真实内容中作答而不是凭空臆测。这背后是一个经济学问题文档docs/index.md与性能文档docs/performance.md都强调把整本书塞进上下文是每一轮对话、每一个会话都要重复支付的 token 账单而 book-to-skill 只支付一次结构化成本之后的每次查询都按答案大小计费实测可比整本书灌入上下文节省24×–51×的 token。二、核心设计理念Structure, not a summarySKILL.mdSKILL.md开头即点明项目哲学Transform written knowledge into actionable agent skills by extracting structure — not producing summaries.提取结构而不是生成摘要。一份技能不是读书报告而是一个工具箱包含命名框架Named frameworks——有明确应用场景的思维模型可执行原则Actionable principles——指导决策的规则技术方法Techniques——逐步的操作方法反模式Anti-patterns——要避免什么、为什么作者语感校准Voice calibration——作者如何思考与表达。文档特别强调保留作者的精确表述框架往往因为特定原因才有特定名字——5 Whys不能写成多问几次为什么必须捕捉原文的确切表述。这也是SKILL.md质量规则第 1、2 条Quality Rules的源码级来源提取结构而非摘要——捕捉命名框架、精确表述、反模式而不是章节复述保留作者的精确性——The 5 Whys ≠ ask why multiple times绝不复制书中的原始文本——始终综合、总结、提炼信号。三、四大核心能力拆解文档首页docs/index.md用四张卡片概括了项目价值下面逐条结合源码展开。3.1 多格式输入本地提取优雅降级支持格式PDF、EPUB、DOCX、HTML、Markdown、RTF、MOBI/AZW经由 Calibre 转换。源码中支持的扩展名集中定义在 book_to_skill/config.pyTEXT_EXTENSIONS {.txt, .text, .md, .markdown, .rst, .adoc, .asciidoc} HTML_EXTENSIONS {.html, .htm, .xhtml} CALIBRE_EBOOK_EXTENSIONS {.mobi, .azw, .azw3} SUPPORTED_EXTENSIONS { .pdf, .epub, .docx, .rtf, *TEXT_EXTENSIONS, *HTML_EXTENSIONS, *CALIBRE_EBOOK_EXTENSIONS, }解析器按格式逐一模块化位于 book_to_skill/parsers/pdf.py、epub.py、docx.py、html.py、rtf.py、calibre.py、text.py。每种格式的提取遵循**最优工具优先、stdlib 兜底**的降级策略README Requirements 一节、docs/architecture.md格式首选工具兜底方案安装命令PDF技术书Docling保留表格与代码块pypdf → pdfminer.sixpip3 install doclingPDF文本为主pdftotextpopplerpypdf → pdfminer.sixsudo apt install poppler-utilsEPUBebooklib beautifulsoup4stdlibzipfile内置pip3 install ebooklib beautifulsoup4DOCXpython-docxstdlib ZIP/XMLpip3 install python-docxHTMLbeautifulsoup4[html]额外使用 trafilatura 做正文去噪stdlibhtml.parserpip3 install beautifulsoup4RTFstriprtf正则pip3 install striprtfMOBI/AZW/AZW3Calibreebook-convert外部应用—从 Calibre 官网下载TXT / Markdown / reStructuredText / AsciiDoc内置——可选依赖的探测与--check报告由 book_to_skill/dependencies.py 实现依赖映射同样定义在 book_to_skill/config.py 的PYTHON_DEPENDENCIES中。README 还给出一个实用技巧用python3 scripts/extract.py --check一条命令即可查看每种格式已安装/缺失的提取器以及补齐命令无需任何输入文件。3.2 结构而非摘要提取作者的工具箱转换的目标不是复述而是捕捉作者多年沉淀的命名框架、思维模型、决策规则与反模式并保留其精确术语。SKILL.md的 Step 7 为每个章节定义了标准模板其中technical型书籍优先呈现 Code Examples、Reference Tables、Commands APIstext型书籍则优先 Frameworks Introduced、Mental Models、Key Takeaways。3.3 按需加载章节token 花费与问题成正比这是项目最核心的效率机制。文档首页的说法是Per-chapter files load only when the topic is relevant, so a 200-page book costs tokens proportional to the question, not the page count.转换产物是一个典型结构README 表格文件用途体量SKILL.md核心思维模型 章节/主题索引~4,000 tokenschapters/ch01-*.md…每章一个文件按需加载~1,000 tokens/个glossary.md全部关键术语按字母排序并带章节引用~1,500 tokenspatterns.md所有技术、算法与设计模式~2,000 tokenscheatsheet.md决策表与快速参考规则~1,000 tokens架构图docs/architecture.md把这一机制总结为设计原则第 3 条On-demand chaptersSKILL.md保持小巧章节文件只有被读取时才产生 token 成本第 5 条Front-loaded SKILL.md则把最重要内容放在最前面因为上下文压缩compaction会从末尾截断。3.4 多 Agent 兼容一个 SKILL.md 全宿主通用项目遵循开放的 Agent Skills 标准一份SKILL.md即可在多个宿主运行。SKILL.md的头部注释明确列出了兼容的技能根目录GitHub Copilot CLI~/.copilot/skills/、~/.agents/skills/、.github/skills/等Amp.agents/skills/、~/.config/agents/skills/、~/.config/amp/skills/Claude Code~/.claude/skills/Hermes Agent$HERMES_HOME/skills/category/默认~/.hermes/skills/。SKILL.md特意省略allowed-tools字段以保持宿主中立Copilot CLI 用shell/MCP-server 名称、Claude 用Bash/Read/Write/Glob/Grep、Amp 用shell_command各宿主会在首次使用时自行提示授权。四、安装Agent 技能 vs 独立 CLI安装文档docs/install.md开篇就提醒不要混淆两种用法作为 Agent 技能在 Claude Code、Copilot CLI、Amp、Codex 或 Hermes Agent 中提供/book-to-skill斜杠命令→git clone到你的技能目录作为独立 CLI仅文本提取引擎→pip install从仓库安装不会注册 Agent 技能。4.1 一键安装任意宿主npx skills add virgiliojr94/book-to-skillskillsCLI 会解析仓库、检测根级SKILL.md并把完整技能含scripts/extract.py与tools/安装到你选择的每个宿主的技能目录。4.2 各宿主手动安装GitHub Copilot CLI个人技能git clone https://github.com/virgiliojr94/book-to-skill.git ~/.copilot/skills/book-to-skill # 然后在 copilot 会话中 /skills reload /skills info book-to-skill跨 Agent 路径Copilot CLI、Amp、Codex 都能发现git clone https://github.com/virgiliojr94/book-to-skill.git ~/.agents/skills/book-to-skillOpenAI Codex直接读取~/.agents/skills且跟随符号链接也可以本地检出后软链ln -s /path/to/book-to-skill ~/.agents/skills/book-to-skillHermes Agent需放入与主题匹配的类别目录git clone https://github.com/virgiliojr94/book-to-skill.git \ ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/book-to-skill项目级安装则用.hermes/skills/category/book-to-skill并在新会话前显式信任项目hermes skills trust /path/to/project。Claude Codegit 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.epub4.3 独立 CLIpip可选book-to-skill尚未发布到 PyPI因此 pip 直接从仓库安装pip install book-to-skill[pdf,epub,docx] githttps://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]扩展比其他重——它会拉入trafilatura连同 lxml、日期解析器、时区数据库、URL 分类器等共 17 个包用于真正的正文/样板检测而非简单剥离script/style不需要该能力时用bs4兜底即可无需[html]扩展只是不做样板去除。五、使用方式与四种操作模式5.1 命令行形态使用文档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。典型示例# 多文件合并为一个统一技能 /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 # 把新素材 fold-in 进已有技能目录更新模式 /book-to-skill ~/articles/new-paper.pdf ~/.claude/skills/project-knowledge技能生成后的调用方式SKILL.mdStep 3/9 的索引机制/designing-data-intensive-apps # 加载核心思维模型 /designing-data-intensive-apps replication # 查找并解释某个主题 /designing-data-intensive-apps ch05 # 深入第 5 章 /designing-data-intensive-apps what chapters do you have? # 浏览索引5.2 四种操作模式SKILL.mdModes of Operation模式触发条件执行内容1. 完整转换默认用户给出路径且无特殊说明执行 Steps 0–9产出完整技能SKILL.md chapters/ glossary patterns cheatsheet2. 仅分析用户说 analyze / just extract执行 Steps 0–3输出结构化提取报告后停止不生成技能文件3. 基于已有分析生成用户已有分析笔记或跑过仅分析模式跳过 Steps 0–3以现有分析为输入执行 Steps 4–94. 更新 / Fold-in输入指向已有技能目录或已存在的技能 slug提取新文件后走 Fold-in 工作流合并章节、术语表与索引更新Fold-in工作流的能力边界在 README 中也有描述研究报告堆若干论文 自己的笔记可合并为统一技能并在新素材到来时持续更新。5.3 发布生成的技能可选转换完成后转换器会询问是否将技能发布为 GitHub 仓库。可见性单独作为一个封闭问题询问且gh repo create默认--private——只有回答是裸词public才会创建公开仓库。SKILL.mdStep 11 强调关于来源许可的一句话不是可见性回答——它是公共领域的描述的是书不是仓库仍会得到私有仓库。 从第三方版权书籍生成的技能必须保持私有见下文版权一节。发布后任意 Agent Skills 宿主可一行安装npx skills add https://github.com/you/your-book-slug --skill your-book-slug六、工作原理确定性提取器 规范驱动的生成器架构文档docs/architecture.md把系统划分为两半一个确定性的 Python 提取器文档 → 干净文本 元数据和一个规范驱动的生成器Agent 遵循SKILL.md把文本转换为结构化技能。6.1 提取器确定性Pythondocuments → scripts/extract.py (shim) → book_to_skill/ ├─ cli.py · utils.py CLI 解析 · 多源解析 · 运行器 ├─ config.py 支持的扩展名 · 路径 · 依赖 ├─ dependencies.py 可选依赖探测 · --check 报告 ├─ sanitize.py 剥离零宽/不可见 Unicode 字符 └─ parsers/ pdf · epub · docx · html · rtf · calibre · text 输出 → tempdir/book_skill_work-pid/ full_text.txt 所有源合并带源标记 metadata.json 页数、词数、token 数、章节、ToC入口 shim scripts/extract.py 保持旧调用方式可用实际逻辑在 book_to_skill/cli.py 与 book_to_skill/utils.py。值得一提的实现细节工作目录是每次运行唯一的tempdir/book_skill_work-pid/book_to_skill/config.py 的default_output_dir()以避免并发提取互相覆盖——历史版本曾因共享固定路径导致后完成的运行静默替换前一运行的输出、Agent 轮询到另一本书的元数据而构建错误技能。BOOK_SKILL_WORKDIR环境变量可完全覆盖该路径。token 估算方面config.py区分了空白分词文本WORDS_PER_TOKEN 0.75与 CJK 文本CJK_CHARS_PER_TOKEN 1.5因为 CJK 几乎没有空格按词切分会严重低估。6.2 生成器Agent 遵循SKILL.md的 Steps 0–11SKILL.md定义了从 Step 0越界检查到 Step 11发布的完整流程关键节点Step 1.5 — 内容类型先询问用户书籍是technical还是text-heavy决定提取工具technical → Docling表格/代码/公式保留为 markdown约 1.5s/页text → pdftotext瞬时。Step 2.5 — 成本预估生成前先给出 token 与成本估算等待用户确认。Step 2.6 — 大书 REPL 式访问超过 ~50k tokens 的书籍不整本Read而是用wc -w、grep -n Chapter、sed -n start,endp按需拉取片段——200 页书约 75k tokens若每章重读一遍28 遍将消耗约 2M 输入 tokensgrepsed 让生成成本与输出成正比。Step 4 — 目的 → DEPTH根据用户回答推断DEPTHreference精简快速查阅或DEPTHstudy更深入、含完整推导的章节不再单独追问。Step 7 — 章节预算矩阵SKILL.md的 Token Budget RuleDEPTHreferenceDEPTHstudyBOOK_TYPEtext800–1,200 tokens1,000–1,800 tokensBOOK_TYPEtechnical1,200–1,800 tokens2,000–3,000 tokens预算按需自适应study深度必须靠真实内容达标复现一个 worked example、把每个框架的 How 展开为显式步骤、为 Top 框架补 Why it works / failure mode而非凑字数reference深度则刻意省略 worked example。Step 8 — 支持文件glossary.md≤1,500 tokens术语按字母排序、patterns.md≤2,000 tokens、cheatsheet.md≤1,200 tokens。SKILL.md特别强调 cheatsheet 是最有差异化的决策层——优先级依次为决策规则当 X 时做 Y因为 Z→ 决策树 → 权衡矩阵 → 阈值与默认值 → 信号与陷阱tells smells并明确裸术语→定义行属于 glossary不是 cheatsheet。Step 9 — 主 SKILL.md正文须保持在 4,000 tokens 以内包含 Core Frameworks约 2,000 tokens、章节索引表、主题索引、支持文件链接与 Scope Limits。Step 9.5 — 安全扫描发布/加载前运行tools/scan_generated_skill.py做建议性提示注入扫描见下文安全一节。Step 10 — 清理与报告只删除本次运行实际使用的 workdir以Workdir -输出为准绝不删除未创建的目录。Step 11 — 发布默认私有遵守可见性硬规则与版权闸门。七、性能与成本Discovery Loop Tax 与实测数据性能文档docs/performance.md强调所有数字均为实测tiktokencl100k_base 计数、tools/discovery_tax.py建模可用命令复现。提取基准103 页技术书仅 CPU方法时间Tokens表格代码块pdftotext0.1s27K00Docling技术模式164s27K1.2%4836真实转换页数 / 提取 tokens / 自动检测章节数书格式页数Tokens章节Think Python 2PDF244119K19Working BackwardsPDF371175K10Pro GitPDF501229K— †Moby-DickEPUB—301K133† 章节自动检测依赖显式的Chapter N/Capítulo N标题Pro Git 用节标题、Moby-Dick 用章标题/罗马数字但其罗马数字目录可被检测出 133 章。提取与转换仍可用只是需要手动指向分节。Discovery Loop Tax回答一个目标问题的入上下文 tokens书章节大小上下文倾倒发现循环book-to-skill对比倾倒 / 循环Think Python 2小119,26412,152~5,00024× / 2.4×Working Backwards中175,25333,444~5,00035× / 6.7×AI Engineering大256,28777,866~5,00051× / 15.6×book-to-skill 只加载驻留核心~4K 一个编译好的章节~1K≈ 5,000 tokens。可复现命令python3 tools/discovery_tax.py --full-text /tmp/book_skill_work/full_text.txt --target-chapter 5上下文倾倒优势24–51×是最强声明该成本在每一轮对话都重复**发现循环优势2.4–15.6×**是一次性成本随章节大小缩放。生成成本一次性完整转换Claude Sonnet 4.5$3/$15 每 MTok 输入/输出估算Think Python 2 约 $0.88、Working Backwards 约 $0.96、Pro Git 约 $1.23、Moby-Dick 约 $1.42——平均每本书约 1 美元一次付清远低于每个会话重读 PDF 的长期成本。输出质量对照自适应深度变更 v1.0.0 前后单章章节文件从 473 tokens 增至 1,219 tokens、补上 worked example、cheatsheet 决策规则从 0 增至 32 条、关键字/定义行从 9 降至 0——印证了cheatsheet 是决策层而非术语表的设计转向。八、安全与隐私从文档到上下文的供应链防护架构文档docs/architecture.md指出不可信文档会流入 Agent 上下文、再进入生成技能、之后又被其他 Agent 加载——这是一条文档 → 上下文的供应链因此加固是分层的提取净化book_to_skill/sanitize.py在每个解析器输出进入指标统计或full_text.txt之前剥离零宽字符U200B/200C/200D/2060/FEFF与 Unicode 标签块UE0000–E007F防止文档携带的不可见指令抵达 Agent报告移除数量并拒绝无可见内容的源。DOCX XXE / Billion-Laughs 防护parsers/docx.py解析前拒绝声明了 DTD 或实体的任何 XML 部件。子进程参数注入防护文件路径在到达pdftotext/pdfinfo/ebook-convert前先绝对化避免-开头的文件名被当作 flag 解析。生成技能扫描tools/scan_generated_skill.py生成器 Step 9.5 的建议性步骤对生成的SKILL.md、chapters/*.md、glossary.md、patterns.md、cheatsheet.md标记指令覆盖短语、模型控制标签、残留不可见 Unicode、扩权 frontmatter 与类外泄内容发现只报规则名与文件位置绝不回显匹配文本。扫描非零退出时停止并交人工复核不得静默改写或加载/发布。CI 层CodeQL、BanditHIGH 级别门禁、Zizmor 与依赖 CVE 审查。隐私方面README 的 Copyright fair use 一节明确处理全程本地进行工具本身不会上传你的文件若 Agent 的模型运行在云端你喂给它的文本遵循该提供商的数据条款与普通提示词相同。九、FAQ 中的关键判断技能 vs 上下文倾倒、RAG、大上下文窗口FAQ 文档docs/faq.md回应了最常见的质疑值得在设计选型时参考直接把 PDF 丢进项目上下文不行吗可以但每一轮对话都要烧掉那份 token 预算。400 页的书约 200K tokens技能只加载相关章节~4K 核心 ~1K 单章。本质是摊还不是大小问题倾倒的账单每一轮、每一会话、永远重复book-to-skill 只付一次。1M 上下文窗口还不够大吗更大的窗口改变的是装得下不是更聪明每 token 每调用都要付费模型在接近满的上下文中检索特定事实的精度会下降lost in the middle窗口 ≠ 结构——原始文本每轮都要重新解析而技能交付的是预提取的框架。这不就是 RAG 吗RAG 在查询时工作分块 → 嵌入 → 相似检索 → 注入提示优化目标是找到讲 X 的那段book-to-skill 在编译时工作一次深度分析提取出作者的框架并命名、描述适用场景、捕捉反模式。二者互补宽而浅的书库检索用 RAG窄而深的工作中要应用的框架用 book-to-skill。热门书 Claude 的训练数据里就有何必费事训练数据是全网讨论的压缩平均可能幻觉具体引文与章节位置book-to-skill 以你的真实副本为准每个框架名、反模式清单、章节号都锚定在你提供的文本上对 Claude 完全陌生的内容小众技术参考、公司内部文档、新近出版物、译本尤其有价值。PDF 是扫描件提取为何立即停止扫描 PDF 是纯图像、没有文本层任何工具都提取不出内容。提取器检查前几页就停下并说明原因让你一秒失败而不是花一整轮处理 400 页后得到空技能。先 OCR 再转换ocrmypdf input.pdf output.pdfbook-to-skill 有意不自带 OCR重依赖 慢且损失质量交给专用工具更好同样图中文字图表/图示中的文本在任何格式下都不提取。十、版权与合理使用转换器不携带任何书籍内容README 明确指出book-to-skill 不随附任何书的内容——一页都没有。它只是一个指向你自己拥有的文件的转换器处理在本地进行你的文件不会由此工具上传用你自己的副本买来的书、公司拥有的文档、你有权阅读的论文输出是你的笔记生成的技能是结构化的合成衍生品框架名、定义、要点不是原文复制——SKILL.md质量规则第 7 条明确禁止复制原始段落应视同手写学习笔记不要分发发布或分享受版权作品衍生技能可能侵权。第三方版权书籍生成的技能务必保持私有内部文档、你自己的写作与开放许可材料可在许可范围内分享。十一、如何继续深入本篇文章以项目文档首页docs/index.md为核心骨架展开。若需进一步深入推荐按以下路径阅读当前仓库架构与组件映射docs/architecture.md提取器/生成器分界、安全设计、如何扩展新格式逐步工作流Steps 0–10与 token 预算SKILL.md生成器规范本体安装与宿主路径细节docs/install.md全部运行模式与实战示例docs/usage.md实测基准与成本模型docs/performance.md常见问题与选型判断docs/faq.md提取器实现book_to_skill/config.py、book_to_skill/parsers/、book_to_skill/sanitize.py配套工具tools/discovery_tax.py成本测量、tools/validate_skill.py技能校验--lens claude|copilot|amp|hermes、tools/scan_generated_skill.py安全扫描一句话总结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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考