book-to-skill：1.5 万 Star，把技术书变成 Agent 按需加载的技能
book-to-skill：1.5 万 Star，把技术书变成 Agent 按需加载的技能
先收藏，回头一定用得上。
买技术书的时候兴致勃勃，读完一遍就吃灰了。三个月后你想查某个知识点，搜 PDF 搜到的是一堆页码而不是答案；问 AI 它要么幻觉要么说没这个内容；自己做的笔记写到 200 行就再也没打开过。
book-to-skill 解决的就是这个问题：把技术书转成结构化的 Agent Skill，你写代码时随时按需查询，从真实内容回答，零幻觉。1.5 万 Star，MIT 协议，支持 PDF/EPUB/DOCX 等十种格式，兼容 Claude Code、GitHub Copilot CLI 和 Amp。
本文提纲
- book-to-skill 是什么
- 核心价值：24-51 倍的 token 节省
- 三步工作流
- 生成什么：结构化而非摘要
- 十种格式支持与优雅降级
- 四种运行模式
- 安全设计：防注入
- 跨 Agent 兼容
- 上手体验
book-to-skill 是什么
book-to-skill 是一个把技术书、文档目录、资料集合转成结构化 Agent Skill 的工具。用 Python 编写，Apache 兼容 Agent Skills 开放标准。
项目关键数据：
| 项目 | 值 |
|---|---|
| 仓库 | virgiliojr94/book-to-skill |
| Stars | 15,753 |
| Forks | 1,690 |
| License | MIT |
| 语言 | Python 3 |
| 支持格式 | PDF, EPUB, DOCX, TXT, MD, RST, AsciiDoc, HTML, RTF, MOBI/AZW |
| 支持 Agent | Claude Code, GitHub Copilot CLI, Amp |
| 创建时间 | 2026-05-01 |
一句话定位：不是把书塞进上下文窗口，而是转成按需加载的结构化知识。
核心价值：24-51 倍的 token 节省
最核心的卖点在数据上。把一整本书塞进 AI 上下文窗口回答一个问题，和用 book-to-skill 转成 Skill 后按需加载回答同一个问题，token 消耗差 24 到 51 倍。
原因在于按需加载机制。生成的 Skill 里有一个 SKILL.md 核心文件（约 4000 token），包含核心心智模型和章节索引。当你问问题时，Agent 只加载相关章节文件（每个约 1000 token），而不是整本书。
对比一下：
| 方式 | 回答一个问题需要的 token |
|---|---|
| 整本书塞进上下文 | 数万到数十万 |
| book-to-skill 按需加载 | ~5000（SKILL.md + 一个章节） |
这不是微优化，是量级差距。尤其对长技术书（动辄 500+ 页），差距更明显。
三步工作流
使用流程极其简单：
/book-to-skill ./my-book.pdf第一步：指向一个文件、文件夹或 glob 模式。
第二步：蒸馏成 Skill。提取框架、决策规则、反模式和每章独立文件。是结构化提取，不是摘要。
第三步：按需加载。安装后在 Agent 里输入 /my-book-slug replication，Agent 读取对应章节，从真实内容回答，没有幻觉。
整个过程的核心设计是确定性提取和 AI 生成分离。提取部分用 Python 代码做，可复现；生成部分由 Agent 按照 SKILL.md 规范执行。这种分离保证了提取结果的一致性，同时利用 AI 的理解能力做结构化。
生成什么：结构化而非摘要
运行后生成一个完整的 Skill 目录：
| 文件 | 用途 | 大小 |
|---|---|---|
SKILL.md |
核心心智模型 + 章节索引 | ~4,000 token |
chapters/ch01-*.md |
每章一个文件，按需加载 | ~1,000 token/个 |
glossary.md |
所有关键术语，按字母排序带章节引用 | ~1,500 token |
patterns.md |
所有技术、算法和设计模式 | ~2,000 token |
cheatsheet.md |
决策表和快速参考规则 | ~1,000 token |
关键设计：章节文件按需加载。你不问那个话题，对应的章节文件不计入 skill 预算。只有你问到相关内容时，Agent 才去读取对应章节。
这和"把书总结成一篇文章"完全不同。摘要丢失了细节，而 book-to-skill 保留的是结构化知识--你问 replication，它读 replication 那一章的原汁原味内容来回答。
十种格式支持与优雅降级
每种格式都有"最优工具优先，标准库兜底"的策略。如果最优提取器没装，自动尝试下一个，所有选项都失败才报错：
| 格式 | 首选工具 | 兜底方案 | 需要安装？ |
|---|---|---|---|
| PDF（文本为主） | pdftotext (poppler) | pypdf -> pdfminer.six | 可选 |
| PDF（技术文档） | docling | 回退到文本链 | 可选 |
| EPUB | ebooklib + beautifulsoup4 | 标准库 zipfile 解析 | 可选 |
| DOCX | python-docx | 标准库 ZIP/XML 解析 | 可选 |
| HTML | beautifulsoup4 | 标准库 html.parser | 可选 |
| RTF | striprtf | 正则清理 | 可选 |
| MOBI/AZW/AZW3 | Calibre ebook-convert | 无（必须装 Calibre） | 是 |
| TXT/MD/RST/AsciiDoc | 内置 | - | 否 |
一行命令检查哪些提取器已安装：
python3 scripts/extract.py --check不用提供文件就能看到每种格式的提取器状态和安装命令。这个设计很贴心--你不用翻文档找依赖，直接跑一下就知道缺什么。
四种运行模式
不只是"转书"，book-to-skill 有四种模式适配不同场景：
| 模式 | 触发方式 | 输出 |
|---|---|---|
| 完整转换 | 默认，提供路径即可 | 完整 Skill（SKILL.md + 章节 + 术语表 + 模式 + 速查表） |
| 仅分析 | 说"analyze"或"just extract" | 结构化提取报告，不生成文件 |
| 从已有分析生成 | 提供已有的分析笔记 | 跳过提取，直接从笔记生成 Skill 文件 |
| 更新/合并 | 指向已有的 Skill 目录 | 合并新旧章节，统一索引 |
第四种模式特别实用。你有一本《Designing Data-Intensive Applications》的 Skill，作者出了第二版，你不用从头来--直接指向新版的 PDF，book-to-skill 会把新内容合并进去，更新章节和索引。对于持续更新的文档（比如内部架构决策记录、API 文档），这个模式让 Skill 能随文档进化。
安全设计：防注入
这点容易被忽略但很重要。sanitize.py 模块负责移除不可见的 Unicode 字符。
技术书的 PDF 里可能包含不可见 Unicode 字符（零宽空格、方向覆盖字符等），这些字符可以用于 prompt injection 攻击--在看起来正常的内容里藏入恶意指令。book-to-skill 在提取阶段就把这些字符清掉，防止它们进入生成的 Skill 文件污染 Agent 的上下文。
对于从不可信来源（比如用户上传的文档、抓取的网页）转换 Skill 的场景，这个安全层是必要的。
跨 Agent 兼容
生成的 Skill 兼容任何支持 Agent Skills 开放标准的宿主：
| Agent | 个人 Skill 路径 | 项目级路径 |
|---|---|---|
| GitHub Copilot CLI | ~/.copilot/skills -> ~/.agents/skills |
.github/skills -> .claude/skills -> .agents/skills |
| Amp | ~/.agents/skills -> ~/.config/agents/skills |
.agents/skills |
| Claude Code | ~/.claude/skills |
.claude/skills |
当多个有效 Skill 根目录存在时，系统会问一次你要用哪个，然后记住这次的选择。不会静默默认。
同一个 SKILL.md 格式在三个 Agent 上都能用。你不用为每个 Agent 单独转换一次。
上手体验
安装
直接用 Agent Skills 标准安装：
npx skills add virgiliojr94/book-to-skill或者让 Agent 自己装：
Set up book-to-skill for me: https://github.com/virgiliojr94/book-to-skill基本用法
/book-to-skill ./my-book.pdf或者转换整个文档目录：
/book-to-skill ./docs/ my-project-docs不只是书
项目名字叫 book-to-skill，但输入是任何结构化文档：
- 内部文档：架构决策记录、运维手册、入职指南。把整个
docs/目录转成一个 Skill，写代码时随时问。 - 品牌设计系统：语音指南、语气规范、组件原则。把品牌手册转成团队可查询的 Skill。
- 研究资料：一堆论文加你的笔记，合并成一个统一的 Skill，新论文来了就更新。
- 规范标准：RFC、API 合约、合规文档--你经常查但从不会背的东西。
README 里有一句话总结得很好：如果你经常重新打开一个文档到希望自己背下来，它就是候选对象。
项目结构
book-to-skill/
├── book_to_skill/
│ ├── cli.py # 入口
│ ├── utils.py # CLI 解析、多源解析、章节检测
│ ├── config.py # 支持的扩展名、路径、依赖映射
│ ├── dependencies.py # 可选依赖探测、--check 报告
│ ├── sanitize.py # 不可见 Unicode 移除（防注入）
│ └── parsers/ # 每种格式一个模块
│ ├── pdf.py # docling -> pdftotext -> pypdf -> pdfminer 链
│ ├── epub.py # ebooklib -> 标准库 zipfile 链
│ ├── docx.py # python-docx -> 标准库 ZIP/XML 链
│ └── ...
├── tools/
│ ├── discovery_tax.py # token 成本测量
│ ├── validate_skill.py # SKILL.md 验证
│ └── scan_generated_skill.py # 质量扫描
├── SKILL.md # 生成器规范（Steps 0-10 + 合并工作流）
└── docs/ # 文档站如果你经常读技术书或维护大量文档，book-to-skill 能把这些静态知识变成 Agent 随时可查的动态参考。24-51 倍的 token 节省不是噱头--按需加载机制让每本书只在你需要时才"打开"对应的章节。
参考文档与链接
- GitHub: virgiliojr94/book-to-skill - 15000+ Star，MIT 协议，把技术书转成 Agent Skill
- Agent Skills 开放标准 - 跨 Agent 的 Skill 格式标准
- book-to-skill 文档站 - 快速入门、格式支持、架构概览
- 架构文档 - 设计原理和组件交互
- SKILL.md 生成器规范 - 完整的 10 步生成工作流
- 性能文档 - token 成本测量方法
- zread.ai: virgiliojr94/book-to-skill - 架构概览和详细说明
- Claude Code Skills - Claude Code 的 Skill 机制文档
试过了？评论区说说你的体验。还没试？收藏起来周末折腾。
作者: itech001 来源: 公众号：AI人工智能时代 网站: https://www.theaiera.cn/ 每日分享最前沿的AI新闻资讯和技术研究。
本文首发于 AI人工智能时代，转载请注明出处。
