- 1Taste Skill 说明与使用
- 2踩坑60+次后，我终于搞懂 Claude Skill 怎么写才会真的触发
- 3Everything Claude Code 详细使用文档
- 4Agent & Skill 编写技巧完全指南
- 5book-to-skill：GitHub2.7万star开源项目，将书籍蒸馏为Agent可调用技能当前
book-to-skill 是 MIT 开源 Python 工具，将 PDF、EPUB 等多格式文档编译为标准化 Agent Skill 包，适配 Claude Code、Copilot CLI 等 AI 助手。它在编译阶段一次性完成结构化解析，将“翻书税”前置，查询时按需加载章节，Token 消耗降低 24-51 倍，解决全量上下文成本高与传统 RAG 片段化丢失逻辑的痛点。工具支持增量更新，适用于技术书、企业文档等场景；文学类收益有限，蒸馏有信息损失，版权作品生成的技能包不宜公开分发。
项目概况
book-to-skill 是一个采用 MIT 开源协议 的 Python 工具，可以将 PDF、EPUB、DOCX、HTML、RTF、MOBI/AZW、Markdown、TXT 等格式的技术书籍或文档批量编译为标准化的 Agent Skill 技能包，原生适配 Claude Code、GitHub Copilot CLI、Amp、Hermes Agent 等 AI 编程助手。
项目增长极快——曾单日获得 1,428 颗 star 登上 GitHub Trending，截至 2026 年 8 月底已超过 2.7 万 stars，forks 近 3,000。
关于隐私： 文件提取阶段完全在本地完成，工具本身不会将原始文件上传到任何第三方服务器。但蒸馏/生成阶段由你的 AI Agent（如 Claude、Copilot）完成——如果 Agent 模型运行在云端，提取出的文本会按该服务商的正常数据条款处理。这一点对企业用户尤其重要，在内部文档场景下需评估所用 Agent 的数据政策。
它解决什么问题？
你买了一本很棒的技术书，读了一遍，三个月后连第 7 章讲什么都不记得了。
传统两种方案都有明显痛点：
方案一：把整本书丢进 AI 上下文。 Token 爆炸、成本高昂，模型在超长上下文中容易丢失细节、产生幻觉。一本 400 页的技术书轻松超过 20 万 token，每次提问都把全书灌进去，费用和延迟都不可接受。
方案二：传统 RAG 检索。 只做向量相似度匹配，返回的是碎片化的文本切片，丢失了全书的逻辑框架和上下文关联。回答「这本书关于 X 的整体方法论是什么」这类问题时尤其吃力，因为答案散落在多个章节里，检索链路很难完整拼回来。
book-to-skill 的核心思路完全不同：一次性在编译阶段完成结构化解析，查询阶段按需加载对应章节，而不是每次提问都重新遍历全书。 项目方的基准测试显示，回答单个问题的 Token 消耗相比全量上下文降低了 24-51 倍。
核心概念：Discovery Loop Tax（翻书税）
项目提出了一个很有洞察力的概念——Discovery Loop Tax（发现循环税）。
当一个 AI Agent 直接读 PDF 时，它不只是在「读」，它在「导航」：每一轮对话都要重新抓取目录、定位相关章节、回溯上下文、重新处理大量文本。这个反复遍历的开销就是「翻书税」。
book-to-skill 的做法是把这份税前置到编译阶段——只付一次，后续所有查询都复用结构化后的产物，开销只与答案本身的大小成正比。
核心工作流程（3 步）
第一步：指向输入源。 传入 PDF、EPUB、文档目录，支持 glob 批量匹配：
book-to-skill ./my-tech-book.pdf第二步：本地蒸馏编译。 这不是简单的摘要生成。工具先用确定性的 Python 提取器将文档转为干净文本和元数据，然后由 AI Agent 按照 SKILL.md 规范将其蒸馏为结构化技能包，提取全书的框架、决策规则、反模式和关键代码样例。
输出的文件结构如下：
| 文件 | 用途 | 大小 |
|---|---|---|
SKILL.md | 技能总入口：核心心智模型 + 章节索引 | ~4,000 tokens |
chapters/ch01-*.md … | 每章一个文件，按需加载 | ~1,000 tokens/章 |
glossary.md | 术语表，附带章节溯源引用 | ~1,500 tokens |
patterns.md | 设计模式、算法、实践方案集合 | ~2,000 tokens |
cheatsheet.md | 决策表、核心规则、反模式速查 | ~1,000 tokens |
第三步：Agent 按需调用。 AI Agent 平时只加载 ~4,000 token 的总入口文件，遇到具体问题时才调取对应的章节文件，基于原书真实内容作答。调用方式就是用技能名作为斜杠命令：
/my-book-slug 讲解分布式事务反模式Agent 会根据索引定位到相关章节，加载对应文件后回答——而不是把整本书塞进上下文。
关键特性
智能区分文档类型。 在提取前工具会询问书籍类型：技术类文档使用 docling 保留表格、代码块和排版布局（约 1.5 秒/页）；叙事类文本则用 pdftotext 等轻量工具快速提取。扫描版 PDF 还会自动检测并提示先做 OCR。
支持格式广泛。 远不止 PDF——EPUB、DOCX、HTML、RTF、MOBI/AZW/AZW3、Markdown、reStructuredText、AsciiDoc、纯文本都可以处理。可以用 python3 scripts/extract.py --check 一键检查当前环境的提取器支持情况。
输出遵循开放的 Agent Skills 标准。 同一个 SKILL.md 格式可以在 Claude Code、GitHub Copilot CLI、Amp、Hermes Agent 上通用，技能包可以导出、分享、二次编辑。
增量更新。 支持 fold-in 模式——当你有新的论文或补充材料时，可以把它合并进已有的技能包，而不需要从头重新编译。
自带基准测试工具。 内置 tools/discovery_tax.py 用于测量实际的 token 开销对比，tools/validate_skill.py 可以按不同平台（Claude/Copilot/Amp）的规范验证生成的技能包是否合规。
不止于书籍
名字虽然叫「book-to-skill」，但输入可以是任何你反复查阅的结构化文档：
开发者场景： 把技术大部头、语言规范、框架官方手册转为编码时随时调用的 AI 技能。读完《Designing Data-Intensive Applications》不再只是「读完了」，而是变成一个你的 Agent 随时可以查阅的活知识库。
企业团队场景： 内部架构规范、运维手册、新人 onboarding 指南，把整个 docs/ 文件夹编译为团队共享 Skill。品牌手册、语调指南也可以——让 Agent 在写作时直接参照你的品牌规范。
研究场景： 一组论文加上你的笔记，合并成一个统一的 Skill，有新材料时增量更新。
合规/规范场景： RFC、API 合约、合规文档——那些你经常要查但永远不会背下来的东西。
判断标准很简单：如果你反复打开某个文档到希望自己已经背下来了，它就是一个候选对象。
和传统 RAG 的对比（个人分析）
以下对比是基于项目文档和实际设计逻辑的分析归纳，非项目方官方对比表：
| 维度 | book-to-skill | 传统 RAG |
|---|---|---|
| 处理时机 | 预编译阶段完成结构化解析 | 查询时实时切片检索 |
| 内容输出 | 框架、规则、模式、反模式——完整心智模型 | 向量相似度匹配的文本片段拼接 |
| Token 消耗 | 仅加载总入口 + 相关章节，开销可控 | 每次检索加载多段切片，开销随问题复杂度增长 |
| 幻觉控制 | 较强，输出带章节溯源，Agent 基于蒸馏后的真实内容作答 | 依赖检索召回质量，易断章取义 |
| 集成方式 | Agent 原生 Skill 协议，无需额外基础设施 | 需要向量数据库 + 检索链路 |
| 全局理解 | 保留全书逻辑结构，能回答跨章节的方法论问题 | 切片粒度限制了对全局逻辑的把握 |
需要注意的是，这不是非此即彼的关系——book-to-skill 更适合你已经读过、想长期复用的「定本」；RAG 更适合持续更新的大规模文档库和需要精确引用原文的场景。
安装方式
# 跨 Agent 的通用安装（需 Node.js）：
npx skills add virgiliojr94/book-to-skill
# 或手动克隆到对应 Agent 的 skills 目录：
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill
# Copilot CLI: ~/.copilot/skills/
# Amp / 跨 Agent: ~/.agents/skills/
# Hermes Agent: ${HERMES_HOME:-$HOME/.hermes}/skills/<category>/
# Python 提取器安装：
pip install -e .安装后在 Agent 中输入 /book-to-skill <文件路径> 即可开始转换。
版权边界
这是一个需要明确说清楚的问题：
book-to-skill 本身不包含任何书籍内容——一页都没有。它是一个你指向自己已拥有的文件的转换器。项目方明确标注，生成的 Skill 是结构化的衍生物（框架名称、定义、要点），不是原文的复制，并且规范中有明确规则禁止照搬原文段落。
但这不意味着可以随意分发——将受版权保护作品生成的技能包公开发布可能构成侵权。项目方建议：自己买的书、公司内部文档、开源许可的材料可以自用和内部共享；第三方版权作品生成的 Skill 应保持私有。
局限性
更适合技术类和方法论类书籍。 结构化的框架、规则、模式是这个工具的甜区；文学小说、散文类作品收益有限，因为它们的价值更多在文字本身而非可提取的「规则」。
编译阶段有成本。 大体积书籍的蒸馏过程会消耗较多模型 Token——这是把「翻书税」前置带来的一次性代价。
蒸馏本身可能引入信息损失。 从 300 页压缩到几千 token 的结构化产物，必然有取舍。对于需要逐字精确引用的场景（法律条文、合同细节），直接查原文仍然更可靠。
依赖 AI 模型质量。 蒸馏阶段的输出质量取决于所用 Agent 的理解和归纳能力，不同模型的效果可能有差异。
文章评论