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。

本文提纲

  1. book-to-skill 是什么
  2. 核心价值：24-51 倍的 token 节省
  3. 三步工作流
  4. 生成什么：结构化而非摘要
  5. 十种格式支持与优雅降级
  6. 四种运行模式
  7. 安全设计：防注入
  8. 跨 Agent 兼容
  9. 上手体验

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人工智能时代，转载请注明出处。