book-to-skill 实战 FAQ为什么Skill 优于整书塞进上下文、与 RAG 的边界以及扫描版 PDF 的处理方案【免费下载链接】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本文以 docs/faq.md 为主线围绕 book-to-skill 项目最常被问到的七个问题展开能否直接把 PDF/EPUB 塞进 Agent 上下文、1M-token 大窗口能否替代、与 RAG 的本质区别、训练数据已包含本书是否多此一举、与 NotebookLM 的取舍、扫描版 PDF 为何提取立即停止。每个答案都会落到仓库源码与实测数据上读完后你将能准确理解 book-to-skill 的适用场景、成本模型与边界条件并能在自己的工作中正确选用工具。从 FAQ 出发这七个问题回答的是同一个核心决策book-to-skill 的定位是把任意一本技术书变成一个 Agent Skill而 docs/faq.md 中的全部问答本质上都在反复回答一个决策问题当你拥有一本书、希望 Agent 能可靠地利用它时应该用哪种方式把它交给 Agent直接整本塞进上下文context dump靠更大的上下文窗口硬扛走 RAG 相似度检索依赖模型训练数据里已有的这本书用 NotebookLM 这类多文档工具或者把它转换成一个按需加载的结构化 Skill。下面按 FAQ 原文的顺序逐题展开并在每处结合仓库源码、测试与性能文档给出佐证。一、能不能直接把 PDF/EPUB 倒进 Claude 的项目上下文——成本是摊销问题不是体积问题FAQ 的答案是可以但每一轮对话都会在开局烧掉这笔 token 预算。一本 400 页的书大约是 200K token而使用 Skill 时只有与你问题相关的章节会被加载——典型情况下是 SKILL.md 核心约 4K token加上你问到的那个章节约 1K token其余内容一直留在磁盘上直到你需要它。关键论断是这是摊销经济学而不是体积经济学。把整本书粘贴进去意味着每一轮、每一次会话、永远都要支付全额 token 账单而 book-to-skill 只支付一次提取成本之后的每次会话只加载它需要的切片。上下文窗口越大这一点反而越重要——大窗口只是让整本倾倒变得可能并不会让它变得便宜。这一论断在仓库中有实测数据支撑。docs/performance.md 记录了用tiktokencl100k_base在真实书籍上测得的 token 数书格式页数提取 token自动检测章节Think Python 2PDF244119K19Working BackwardsPDF371175K10Pro GitPDF501229K—Moby-DickEPUB—301K133而回答一个针对性问题时的对比发现循环税参见 tools/discovery_tax.py 与 docs/performance.md书章节规模整书倾倒发现循环book-to-skillvs 倾倒 / vs 循环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 一侧约 5,000 token 常驻核心SKILL.md 约 4K 一个预编译章节约 1K。这正是 README.md 里24×–51× fewer tokens这一数字的来源——它比整书倾倒少 2451 倍 token并且这个优势在每个会话的每一轮都会重现因为倾倒的成本是持续发生的。FAQ 还给出了一个更本质的区分原始文本注入是检索retrieval而 Skill 是推理reasoning。当 Agent 加载章节文件时它不是在搜索关键词匹配而是在处理已经预提取的、具名化的框架、原则和心智模型——这些内容是为应用而结构化整理的不是为阅读而存在的。仓库根目录的 SKILL.md 生成规范把这一点落成了可执行的生成规则例如 Quality Rule #3密度优于完整a 1,000-token summary beats a 10,000-token excerpt、#4实践者口吻Use X when Y而不是 The book explains X。二、Claude 现在有 1M-token 上下文窗口能不能把整本书一直加载着FAQ 的回答是更大的窗口改变的是能装下什么而不是什么更聪明。它给出三个不可替代的理由按 token、按调用付费。1M 窗口不会让这些 token 免费——它只是让一张巨大的、持续产生的账单成为可能。Skill 加载的是 KB 级内容而不是 MB 级。recall 随填充度退化。模型在接近满的上下文中检索某个特定事实时精度会下降即著名的 lost in the middle 效应。一个 1K 的精选章节在回答单个问题上胜过 200K 的原始散文。窗口 ≠ 结构。整本书在上下文里仍然是原始文本模型每一轮都必须重新解析而 Skill 交付的是预提取的框架——是推理不是检索。结论是分工明确的大窗口适合一次性扫过、以后再也不碰的材料Skill 适合会反复取用的知识。这一条建议在 docs/how-it-works.md 中体现为明确的架构原则章节文件按需加载on-demand章节文件在被问到之前不计入 skill 预算。SKILL.md 的 Quality Rule #6 原话就是Chapter files are on-demand — they dont count against skill budget until loaded。三、这不就是 RAG 吗——RAG 在查询时检索book-to-skill 在编译时提炼FAQ 对 RAG 的界定非常清晰RAG 在查询时query time工作把书分块 → 全部向量化嵌入 → 找相似向量 → 注入提示词。它优化的目标是帮我找到讲到 X 的那部分。book-to-skill 在编译时compile time工作一次深度分析运行提取作者真正构建的框架为它们命名描述各自的使用时机并捕获反模式。产出的是作者花多年构建的结构而不是对作者句子的相似度搜索。FAQ 用两句话做了精炼对比RAG 的答案这里有一些接近你查询的块。 Skill 的答案这是这位作者构建的 12 个框架随时可以拿来推理。按任务形态选择工具宽而浅wide and shallow——几十本书的库找到提到 X 的部分 → RAG 类工具FAQ 举例 CandleKeep胜出窄而深narrow and deep——一本书或一组紧密相关的资料、在工作时要应用其框架 → book-to-skill 胜出。二者的关系是互补而非竞争RAG 给整个书架建索引book-to-skill 吃透一本书RAG indexes a shelf, book-to-skill masters a spine。仓库实现同样印证了编译时这一性质SKILL.md 的生成流程Steps 0–10要求对每章生成章节文件、合并 glossary/patterns/cheatsheet 三类支撑文件其中 cheatsheet.md 在规范中被明确定义为skill 中最具差异化的一层——把它当作推理辅助而不是关键词列表优先收录决策规则When X, do Y, because Z、决策树/流程图、权衡矩阵、阈值与默认值、识别信号tells smells并明确避免裸的术语→定义行那是 glossary 的活。也就是说最终 Skill 里存的是作者的判断这正是编译期结构提炼与查询期相似度检索的分水岭。四、流行书已经在 Claude 的训练数据里了为什么还要转换FAQ 承认对广为人知的书如 Clean Code、DDIA、Pragmatic ProgrammerClaude 确实有通识——但它是被压缩的、被整个互联网对这本书的讨论平均化过的而且可能对具体引文或章节位置产生幻觉。book-to-skill 的价值在于以你手上的实际副本为准每一个框架名、每一条反模式清单、每一个章节号都以你提供的文本为根基grounded。没有训练数据漂移没有幻觉出来的章节标题。此外它特别擅长处理 Claude完全不了解的书小众技术参考、内部公司文档、近期出版物、翻译作品。FAQ 此处的grounded in the text you provided在实现中对应的是生成环节对全文的引用纪律Step 2.6 要求对 50k token 的大书采用 REPL 式访问用grep/sed按需拉取章节而不是整文件 Read并在生成 SKILL.md 前用grep -c验证某个框架是否真的出现在书中。根目录 SKILL.md 的 Quality Rule #7 则规定绝不复制书的原始文本——永远综合、总结、提取信号Quality Rule #8 强调Topic index 是关键的——它是 Agent 导航到正确章节文件的方式。这些规则共同保证了产出是锚定在真实文本上的结构化提炼而不是模型的记忆回放。五、NotebookLM 处理多本书更在行。FAQ 直言不讳如果你的工作流是我有 80 本互不相干的书想跨全部书目搜索NotebookLM 是正确工具。但 book-to-skill 为另一类任务而生在某个特定主题或类库上深入钻研——把多份相关文档论文、章节、笔记折叠进一个统一的 Skill并随新材料到来持续更新它把定制知识库直接整合进你的编码或写作工作流而不是放在一个单独的浏览器标签页里。这条多文档融合 持续更新能力在仓库里有明确实现SKILL.md 定义了四种操作模式其中Mode 4: Update / Fold-in专门用于把新来源折叠进已有 Skill——读取现有 SKILL.md 的章节索引/主题索引/glossary/patterns/cheatsheet区分既有章节的修订与新增章节新章节从现有最大章节号之后继续编号如ch12之后是ch13-*.mdglossary 词条合并后重新按字母排序并在 SKILL.md 中递增章节数、更新主题索引。FAQ 所说的even updating it over time as new material arrives正是这条工作流。六、我的 PDF 是扫描版提取立刻停止了为什么这是 FAQ 中最具实操性的一题也是仓库实现细节最丰富的一题。FAQ 的解释是扫描版 PDF 是一叠页面图像里面根本没有可提取的文本。PDF 提取链上的每个工具读的都是文字层所以无论跑哪个工具扫描版都提取不出任何内容。提取器会检查前几页并在那里停止并给出解释。这个检查的存在是为了让失败只花你一秒钟而不是对一本 400 页的书跑完整轮提取、最后得到一个空 Skill。先做 OCR再转换产物ocrmypdf input.pdf output.pdfbook-to-skill自己不运行 OCR这是有意的设计那意味着给每个用户引入一个重量级依赖和一条又慢又有损的步骤只为了服务一个专用工具已经处理得更好的场景。同样的逻辑也适用于图片——图表、示意图中烘焙进图片的文字从任何格式中都不会被提取。源码级佐证扫描检测的前置探针这一行为在 book_to_skill/parsers/pdf.py 中有精确实现looks_image_only(pdf_path, pages5)函数用 pdftotext 只读取前 5 页-f 1 -l 5如果这 5 页没有任何可提取文本就判定为扫描/纯图像 PDFdef looks_image_only(pdf_path: str, pages: int 5) - bool: True when the first pages pages yield no extractable text — the signature of a scanned/image-only PDF. Cheap pre-flight so a scan fails in a second instead of after the whole extraction chain has run.这段注释明确写出了设计意图廉价的预检让扫描版在一秒钟内失败而不是在整条提取链跑完之后才失败。而且它是一个**尽力而为best-effort**的探针没有 pdftotext 时返回 False此时常规提取链外加的空文本最终守卫仍然生效。调用点在 book_to_skill/utils.py 的 PDF 分支中提取单文件时PDF 路径先执行looks_image_only(input_str)一旦为真就抛出ExtractionError错误信息明确建议先运行ocrmypdf input.pdf output.pdf再重试。批量场景下这个异常只影响当前这一个源——ExtractionError在 book_to_skill/exceptions.py 中被定义为按源失败的、批量安全batch-safe的异常一个坏源被跳过并给出警告其余源继续处理参见 docs/how-it-works.md 中one bad source is skipped with a warning; the rest still process。测试侧同样有覆盖在 tests/test_book_to_skill.py 中looks_image_only(scan.pdf)被断言为True、looks_image_only(book.pdf)为False且当looks_image_only返回真时抛出的异常文本同时包含scanned与ocrmypdf字样保证用户看到的是可操作的修复指引。为什么不内置 OCR依赖与图片边界FAQ 明确不运行 OCR 是刻意为之这一点在依赖探测上也能看到book_to_skill/dependencies.py 负责可选依赖探测与--check报告PDF 链只覆盖 pdftotextpoppler、pypdf、pdfminer.six 与 docling不含任何 OCR 引擎。README.md 的 Requirements 段落同样只列出上述工具并直接给出针对扫描版的指引A PDF that is page images with no text layer … has nothing for these tools to extract要求用户自行ocrmypdf后再转换。同理图内文字不提取是跨格式的统一策略EPUB 提取器在 book_to_skill/parsers/epub.py 中会统计归档内的图片数量count_epub_images当图片超过 5 张时打印警告[warn] … contains N image(s); their content is not extracted并在生成的 SKILL.md 的 Scope Limits 段中声明N 张源图片未被读取。提取得以继续时的链式回退与立即停止相对的是正常 PDF 的提取链extract_single_file先按用户在 Step 1.5 选择的类型路由——technical 模式优先 docling保留表格与代码块为 Markdown约 1.5s/页失败或 text 模式则依次尝试 pdftotext → pypdf → pdfminer.six全部不可用才抛出带安装命令的ExtractionError见 book_to_skill/utils.py 与 book_to_skill/parsers/pdf.py。扫描版正是被这条链最前面的廉价探针拦截从而避免了无意义的全量空跑。七、成本模型回顾一次性编译成本 vs 每次会话的持续成本把 FAQ 各题串起来看其背后的统一经济模型是编译成本支付一次提取 生成 Skill 的完整转换成本按 docs/performance.md 用 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 美元一次性付清。使用成本按需支付每次会话只加载常驻核心 相关章节约 5K token而不是每轮 200K。整书倾倒则是每轮、每会话、永久的持续账单——这正是 FAQ 反复强调的摊销逻辑。如果你希望自己复现这些数字仓库提供了计量工具 tools/discovery_tax.py它对真实提取的书籍文本建模三种策略回答一个针对性问题的上下文成本——context-dump整书常驻、每轮重复计费、discovery-loop在线 PDF 阅读 Agent 导航 ToC、拉取原始章节、必要时回溯前一章、book-to-skill常驻核心 按需编译章节。注意它复用了提取器的章节检测与 ToC 检测逻辑_chapter_number与_TOC_PATTERN保证计量口径与流水线一致token 计数优先用真实 BPEtiktoken cl100k_base不可用时退化为 words/0.75 启发式并在报告中打印所用方法。八、配套的事实边界与使用建议基于上述七个问答可以把 FAQ 的结论收敛为几条可直接使用的判断准则什么时候不要用整书倾倒只要这本书你会反复取用倾倒的持续成本就高于一次性的转换成本大窗口只解决装得下不解决每轮都贵和召回退化。什么时候用 RAG书目是宽而浅的几十本书、按关键词找段落什么时候用 book-to-skill书目是窄而深的一两本要应用其框架的书或多份紧密相关的资料。二者可以并存——RAG 管书架索引book-to-skill 管单本精熟。什么时候仍需你自己动手扫描版 PDF 要先ocrmypdf图表/示意图里的文字从任何格式都不会被提取这些在 README.md 的 Requirements 与 docs/how-it-works.md 中都有明确说明是工具的设计边界不是缺陷。关于版权book-to-skill 不随附任何书籍内容处理在本地进行产出的 Skill 是结构化的综合衍生品而非原文复制Quality Rule #7SKILL.md 生成规范中的 publish 步骤也内置了版权闸门——第三方受版权保护的书的 Skill 必须保持私有只有你自己的写作、开放许可内容或你明确持有再分发权的内容才允许公开详见 README.md 的 Copyright fair use 章节。小结docs/faq.md 表面上是七个独立问答实际上是一份工具选型决策指南它界定了整书倾倒—大窗口—RAG—训练数据—NotebookLM—Skill六种利用书籍知识的方式各自的成本结构与适用边界而仓库源码book_to_skill/parsers/pdf.py、book_to_skill/utils.py、SKILL.md、tools/discovery_tax.py与测试tests/test_book_to_skill.py则逐一验证了这些论断的实现细节——从前 5 页廉价预检拦截扫描版到编译期结构化提炼 vs 查询期相似度检索再到约 5K token 按需回答一个问题的实测数据。理解这些边界后你就能在自己的工作流里为每一本书选择正确的交付方式。更多细节可继续阅读docs/performance.md实测 benchmark 与复现命令、docs/how-it-works.mdSteps 0–10 完整工作流、docs/install.md各宿主安装与可选提取器与 README.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 book-to-skill 实战 FAQ：为什么“Skill 优于整书塞进上下文“、与 RAG 的边界，以及扫描版 PDF 的处理方案
book-to-skill 实战 FAQ为什么Skill 优于整书塞进上下文、与 RAG 的边界以及扫描版 PDF 的处理方案【免费下载链接】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本文以 docs/faq.md 为主线围绕 book-to-skill 项目最常被问到的七个问题展开能否直接把 PDF/EPUB 塞进 Agent 上下文、1M-token 大窗口能否替代、与 RAG 的本质区别、训练数据已包含本书是否多此一举、与 NotebookLM 的取舍、扫描版 PDF 为何提取立即停止。每个答案都会落到仓库源码与实测数据上读完后你将能准确理解 book-to-skill 的适用场景、成本模型与边界条件并能在自己的工作中正确选用工具。从 FAQ 出发这七个问题回答的是同一个核心决策book-to-skill 的定位是把任意一本技术书变成一个 Agent Skill而 docs/faq.md 中的全部问答本质上都在反复回答一个决策问题当你拥有一本书、希望 Agent 能可靠地利用它时应该用哪种方式把它交给 Agent直接整本塞进上下文context dump靠更大的上下文窗口硬扛走 RAG 相似度检索依赖模型训练数据里已有的这本书用 NotebookLM 这类多文档工具或者把它转换成一个按需加载的结构化 Skill。下面按 FAQ 原文的顺序逐题展开并在每处结合仓库源码、测试与性能文档给出佐证。一、能不能直接把 PDF/EPUB 倒进 Claude 的项目上下文——成本是摊销问题不是体积问题FAQ 的答案是可以但每一轮对话都会在开局烧掉这笔 token 预算。一本 400 页的书大约是 200K token而使用 Skill 时只有与你问题相关的章节会被加载——典型情况下是 SKILL.md 核心约 4K token加上你问到的那个章节约 1K token其余内容一直留在磁盘上直到你需要它。关键论断是这是摊销经济学而不是体积经济学。把整本书粘贴进去意味着每一轮、每一次会话、永远都要支付全额 token 账单而 book-to-skill 只支付一次提取成本之后的每次会话只加载它需要的切片。上下文窗口越大这一点反而越重要——大窗口只是让整本倾倒变得可能并不会让它变得便宜。这一论断在仓库中有实测数据支撑。docs/performance.md 记录了用tiktokencl100k_base在真实书籍上测得的 token 数书格式页数提取 token自动检测章节Think Python 2PDF244119K19Working BackwardsPDF371175K10Pro GitPDF501229K—Moby-DickEPUB—301K133而回答一个针对性问题时的对比发现循环税参见 tools/discovery_tax.py 与 docs/performance.md书章节规模整书倾倒发现循环book-to-skillvs 倾倒 / vs 循环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 一侧约 5,000 token 常驻核心SKILL.md 约 4K 一个预编译章节约 1K。这正是 README.md 里24×–51× fewer tokens这一数字的来源——它比整书倾倒少 2451 倍 token并且这个优势在每个会话的每一轮都会重现因为倾倒的成本是持续发生的。FAQ 还给出了一个更本质的区分原始文本注入是检索retrieval而 Skill 是推理reasoning。当 Agent 加载章节文件时它不是在搜索关键词匹配而是在处理已经预提取的、具名化的框架、原则和心智模型——这些内容是为应用而结构化整理的不是为阅读而存在的。仓库根目录的 SKILL.md 生成规范把这一点落成了可执行的生成规则例如 Quality Rule #3密度优于完整a 1,000-token summary beats a 10,000-token excerpt、#4实践者口吻Use X when Y而不是 The book explains X。二、Claude 现在有 1M-token 上下文窗口能不能把整本书一直加载着FAQ 的回答是更大的窗口改变的是能装下什么而不是什么更聪明。它给出三个不可替代的理由按 token、按调用付费。1M 窗口不会让这些 token 免费——它只是让一张巨大的、持续产生的账单成为可能。Skill 加载的是 KB 级内容而不是 MB 级。recall 随填充度退化。模型在接近满的上下文中检索某个特定事实时精度会下降即著名的 lost in the middle 效应。一个 1K 的精选章节在回答单个问题上胜过 200K 的原始散文。窗口 ≠ 结构。整本书在上下文里仍然是原始文本模型每一轮都必须重新解析而 Skill 交付的是预提取的框架——是推理不是检索。结论是分工明确的大窗口适合一次性扫过、以后再也不碰的材料Skill 适合会反复取用的知识。这一条建议在 docs/how-it-works.md 中体现为明确的架构原则章节文件按需加载on-demand章节文件在被问到之前不计入 skill 预算。SKILL.md 的 Quality Rule #6 原话就是Chapter files are on-demand — they dont count against skill budget until loaded。三、这不就是 RAG 吗——RAG 在查询时检索book-to-skill 在编译时提炼FAQ 对 RAG 的界定非常清晰RAG 在查询时query time工作把书分块 → 全部向量化嵌入 → 找相似向量 → 注入提示词。它优化的目标是帮我找到讲到 X 的那部分。book-to-skill 在编译时compile time工作一次深度分析运行提取作者真正构建的框架为它们命名描述各自的使用时机并捕获反模式。产出的是作者花多年构建的结构而不是对作者句子的相似度搜索。FAQ 用两句话做了精炼对比RAG 的答案这里有一些接近你查询的块。 Skill 的答案这是这位作者构建的 12 个框架随时可以拿来推理。按任务形态选择工具宽而浅wide and shallow——几十本书的库找到提到 X 的部分 → RAG 类工具FAQ 举例 CandleKeep胜出窄而深narrow and deep——一本书或一组紧密相关的资料、在工作时要应用其框架 → book-to-skill 胜出。二者的关系是互补而非竞争RAG 给整个书架建索引book-to-skill 吃透一本书RAG indexes a shelf, book-to-skill masters a spine。仓库实现同样印证了编译时这一性质SKILL.md 的生成流程Steps 0–10要求对每章生成章节文件、合并 glossary/patterns/cheatsheet 三类支撑文件其中 cheatsheet.md 在规范中被明确定义为skill 中最具差异化的一层——把它当作推理辅助而不是关键词列表优先收录决策规则When X, do Y, because Z、决策树/流程图、权衡矩阵、阈值与默认值、识别信号tells smells并明确避免裸的术语→定义行那是 glossary 的活。也就是说最终 Skill 里存的是作者的判断这正是编译期结构提炼与查询期相似度检索的分水岭。四、流行书已经在 Claude 的训练数据里了为什么还要转换FAQ 承认对广为人知的书如 Clean Code、DDIA、Pragmatic ProgrammerClaude 确实有通识——但它是被压缩的、被整个互联网对这本书的讨论平均化过的而且可能对具体引文或章节位置产生幻觉。book-to-skill 的价值在于以你手上的实际副本为准每一个框架名、每一条反模式清单、每一个章节号都以你提供的文本为根基grounded。没有训练数据漂移没有幻觉出来的章节标题。此外它特别擅长处理 Claude完全不了解的书小众技术参考、内部公司文档、近期出版物、翻译作品。FAQ 此处的grounded in the text you provided在实现中对应的是生成环节对全文的引用纪律Step 2.6 要求对 50k token 的大书采用 REPL 式访问用grep/sed按需拉取章节而不是整文件 Read并在生成 SKILL.md 前用grep -c验证某个框架是否真的出现在书中。根目录 SKILL.md 的 Quality Rule #7 则规定绝不复制书的原始文本——永远综合、总结、提取信号Quality Rule #8 强调Topic index 是关键的——它是 Agent 导航到正确章节文件的方式。这些规则共同保证了产出是锚定在真实文本上的结构化提炼而不是模型的记忆回放。五、NotebookLM 处理多本书更在行。FAQ 直言不讳如果你的工作流是我有 80 本互不相干的书想跨全部书目搜索NotebookLM 是正确工具。但 book-to-skill 为另一类任务而生在某个特定主题或类库上深入钻研——把多份相关文档论文、章节、笔记折叠进一个统一的 Skill并随新材料到来持续更新它把定制知识库直接整合进你的编码或写作工作流而不是放在一个单独的浏览器标签页里。这条多文档融合 持续更新能力在仓库里有明确实现SKILL.md 定义了四种操作模式其中Mode 4: Update / Fold-in专门用于把新来源折叠进已有 Skill——读取现有 SKILL.md 的章节索引/主题索引/glossary/patterns/cheatsheet区分既有章节的修订与新增章节新章节从现有最大章节号之后继续编号如ch12之后是ch13-*.mdglossary 词条合并后重新按字母排序并在 SKILL.md 中递增章节数、更新主题索引。FAQ 所说的even updating it over time as new material arrives正是这条工作流。六、我的 PDF 是扫描版提取立刻停止了为什么这是 FAQ 中最具实操性的一题也是仓库实现细节最丰富的一题。FAQ 的解释是扫描版 PDF 是一叠页面图像里面根本没有可提取的文本。PDF 提取链上的每个工具读的都是文字层所以无论跑哪个工具扫描版都提取不出任何内容。提取器会检查前几页并在那里停止并给出解释。这个检查的存在是为了让失败只花你一秒钟而不是对一本 400 页的书跑完整轮提取、最后得到一个空 Skill。先做 OCR再转换产物ocrmypdf input.pdf output.pdfbook-to-skill自己不运行 OCR这是有意的设计那意味着给每个用户引入一个重量级依赖和一条又慢又有损的步骤只为了服务一个专用工具已经处理得更好的场景。同样的逻辑也适用于图片——图表、示意图中烘焙进图片的文字从任何格式中都不会被提取。源码级佐证扫描检测的前置探针这一行为在 book_to_skill/parsers/pdf.py 中有精确实现looks_image_only(pdf_path, pages5)函数用 pdftotext 只读取前 5 页-f 1 -l 5如果这 5 页没有任何可提取文本就判定为扫描/纯图像 PDFdef looks_image_only(pdf_path: str, pages: int 5) - bool: True when the first pages pages yield no extractable text — the signature of a scanned/image-only PDF. Cheap pre-flight so a scan fails in a second instead of after the whole extraction chain has run.这段注释明确写出了设计意图廉价的预检让扫描版在一秒钟内失败而不是在整条提取链跑完之后才失败。而且它是一个**尽力而为best-effort**的探针没有 pdftotext 时返回 False此时常规提取链外加的空文本最终守卫仍然生效。调用点在 book_to_skill/utils.py 的 PDF 分支中提取单文件时PDF 路径先执行looks_image_only(input_str)一旦为真就抛出ExtractionError错误信息明确建议先运行ocrmypdf input.pdf output.pdf再重试。批量场景下这个异常只影响当前这一个源——ExtractionError在 book_to_skill/exceptions.py 中被定义为按源失败的、批量安全batch-safe的异常一个坏源被跳过并给出警告其余源继续处理参见 docs/how-it-works.md 中one bad source is skipped with a warning; the rest still process。测试侧同样有覆盖在 tests/test_book_to_skill.py 中looks_image_only(scan.pdf)被断言为True、looks_image_only(book.pdf)为False且当looks_image_only返回真时抛出的异常文本同时包含scanned与ocrmypdf字样保证用户看到的是可操作的修复指引。为什么不内置 OCR依赖与图片边界FAQ 明确不运行 OCR 是刻意为之这一点在依赖探测上也能看到book_to_skill/dependencies.py 负责可选依赖探测与--check报告PDF 链只覆盖 pdftotextpoppler、pypdf、pdfminer.six 与 docling不含任何 OCR 引擎。README.md 的 Requirements 段落同样只列出上述工具并直接给出针对扫描版的指引A PDF that is page images with no text layer … has nothing for these tools to extract要求用户自行ocrmypdf后再转换。同理图内文字不提取是跨格式的统一策略EPUB 提取器在 book_to_skill/parsers/epub.py 中会统计归档内的图片数量count_epub_images当图片超过 5 张时打印警告[warn] … contains N image(s); their content is not extracted并在生成的 SKILL.md 的 Scope Limits 段中声明N 张源图片未被读取。提取得以继续时的链式回退与立即停止相对的是正常 PDF 的提取链extract_single_file先按用户在 Step 1.5 选择的类型路由——technical 模式优先 docling保留表格与代码块为 Markdown约 1.5s/页失败或 text 模式则依次尝试 pdftotext → pypdf → pdfminer.six全部不可用才抛出带安装命令的ExtractionError见 book_to_skill/utils.py 与 book_to_skill/parsers/pdf.py。扫描版正是被这条链最前面的廉价探针拦截从而避免了无意义的全量空跑。七、成本模型回顾一次性编译成本 vs 每次会话的持续成本把 FAQ 各题串起来看其背后的统一经济模型是编译成本支付一次提取 生成 Skill 的完整转换成本按 docs/performance.md 用 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 美元一次性付清。使用成本按需支付每次会话只加载常驻核心 相关章节约 5K token而不是每轮 200K。整书倾倒则是每轮、每会话、永久的持续账单——这正是 FAQ 反复强调的摊销逻辑。如果你希望自己复现这些数字仓库提供了计量工具 tools/discovery_tax.py它对真实提取的书籍文本建模三种策略回答一个针对性问题的上下文成本——context-dump整书常驻、每轮重复计费、discovery-loop在线 PDF 阅读 Agent 导航 ToC、拉取原始章节、必要时回溯前一章、book-to-skill常驻核心 按需编译章节。注意它复用了提取器的章节检测与 ToC 检测逻辑_chapter_number与_TOC_PATTERN保证计量口径与流水线一致token 计数优先用真实 BPEtiktoken cl100k_base不可用时退化为 words/0.75 启发式并在报告中打印所用方法。八、配套的事实边界与使用建议基于上述七个问答可以把 FAQ 的结论收敛为几条可直接使用的判断准则什么时候不要用整书倾倒只要这本书你会反复取用倾倒的持续成本就高于一次性的转换成本大窗口只解决装得下不解决每轮都贵和召回退化。什么时候用 RAG书目是宽而浅的几十本书、按关键词找段落什么时候用 book-to-skill书目是窄而深的一两本要应用其框架的书或多份紧密相关的资料。二者可以并存——RAG 管书架索引book-to-skill 管单本精熟。什么时候仍需你自己动手扫描版 PDF 要先ocrmypdf图表/示意图里的文字从任何格式都不会被提取这些在 README.md 的 Requirements 与 docs/how-it-works.md 中都有明确说明是工具的设计边界不是缺陷。关于版权book-to-skill 不随附任何书籍内容处理在本地进行产出的 Skill 是结构化的综合衍生品而非原文复制Quality Rule #7SKILL.md 生成规范中的 publish 步骤也内置了版权闸门——第三方受版权保护的书的 Skill 必须保持私有只有你自己的写作、开放许可内容或你明确持有再分发权的内容才允许公开详见 README.md 的 Copyright fair use 章节。小结docs/faq.md 表面上是七个独立问答实际上是一份工具选型决策指南它界定了整书倾倒—大窗口—RAG—训练数据—NotebookLM—Skill六种利用书籍知识的方式各自的成本结构与适用边界而仓库源码book_to_skill/parsers/pdf.py、book_to_skill/utils.py、SKILL.md、tools/discovery_tax.py与测试tests/test_book_to_skill.py则逐一验证了这些论断的实现细节——从前 5 页廉价预检拦截扫描版到编译期结构化提炼 vs 查询期相似度检索再到约 5K token 按需回答一个问题的实测数据。理解这些边界后你就能在自己的工作流里为每一本书选择正确的交付方式。更多细节可继续阅读docs/performance.md实测 benchmark 与复现命令、docs/how-it-works.mdSteps 0–10 完整工作流、docs/install.md各宿主安装与可选提取器与 README.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考