📚 book-to-skill：将技术书籍转化为 AI Agent 技能

Booklin——book-to-skill 的魔法向导

---

场景切入：当 AI 助手读完书就"失忆"

你花了两周读完一本《设计模式》，做了满满笔记。三个月后写代码时，你依稀记得"第7章讲了什么来着"——然后打开 PDF，疯狂 Ctrl+F。

更尴尬的是问 AI 助手："这本书里策略模式怎么用？"它要么一本正经地胡编乱造，要么老实交代"我没有这本书的内容"。

这就是 book-to-skill 试图解决的核心痛点：让 AI 助手真正"记住"你看过的每一本书，并且能随时调用。

---

项目背景：一个开发者的"知识管理执念"

book-to-skill 由独立开发者 virgiliojr94 创建，GitHub 仓库地址为 virgiliojr94/book-to-skill。

作者在项目 README 中分享了自己的经历：买了很多技术书籍，读完一遍就忘，再想用时找不到重点。传统的笔记工具（Notion、Obsidian）需要大量手工整理，最终沦为"积灰仓库"。他想要的是：把书籍变成 AI 助手可以随时调用的知识模块，就像请了一个读过所有书的私人导师。

这个需求在 2025 年 Claude Code 和 GitHub Copilot CLI 普及后变得尤为迫切。AI 助手可以处理复杂任务，但前提是它得知道那本书讲了什么——而把 PDF 直接塞进上下文窗口，动辄消耗数十万 token，成本高、速度慢，还容易"迷失"（Discovery Loop Tax）。

项目于 2026 年 5 月上线，迅速在 GitHub Trending 拿下第 3 名，不到半年突破 30,000 stars，成为 Agent Skills 生态中最受欢迎的工具之一。

---

核心功能：不是摘要，是"可操作的知识模块"

book-to-skill 远不止把 PDF 转成 Markdown 那么简单。它的工作流程分为两个阶段：

阶段一：Python 提取器（确定性）

支持格式：

格式	推荐工具	说明
PDF（文字型）	pdftotext（poppler）	即时提取
PDF（技术型，含代码/表格）	docling	~1.5秒/页，保留代码块和表格
EPUB	ebooklib + beautifulsoup4	最佳质量
DOCX	python-docx	Word 文档
HTML	trafilatura	网页内容
RTF/MOBI	striprtf / Calibre	特殊格式
Markdown / 纯文本	内置	无需额外依赖

PDF 类型由工具自动判断：用户只需回答"这本书是技术类还是文字类"，工具自动选择最佳解析器。

阶段二：AI Agent 生成器（SKILL.md 规范）

提取后的纯文本交给 AI 代理，按照 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

关键设计：按需加载。章节文件不会一次性全部加载，只有当用户问到相关内容时，AI 才会读取对应章节文件。这意味着回答一个问题只需要 24×–51× 更少的 tokens，相比直接往上下文塞整本书，这个优化是实质性的。

---

上手体验：安装只需一条命令

# 最简方式（跨 Agent 通用）
npx skills add virgiliojr94/book-to-skill

# 或手动克隆（Claude Code）
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill

# 或 pip 安装（CLI 独立使用）
pip install book-to-skill
book-to-skill ./my-book.pdf

安装后，在支持 Agent Skills 的环境中（Claude Code、GitHub Copilot CLI、Amp、OpenAI Codex 等），直接调用：

/book-to-skill ./design-patterns.pdf

生成技能后，提问变得极为自然：

/design-patterns 策略模式和工厂模式有什么区别？应该在什么场景下选用？

AI 从章节文件中读取相关内容后回答，不会胡编乱造，引用自书中原文。

---

技术架构：提取器 + 生成器双模块

项目结构清晰，分为两大模块：

scripts/extract.py  →  book_to_skill/   (Python 提取器)
SKILL.md                            (Agent 生成器规范)

• 提取器（Python）：完全确定性，根据格式自动选择解析器，处理异常优雅（单个文件失败不影响整批处理）
• 生成器（SKILL.md 规范）：定义 AI Agent 的行为准则，告诉它如何分析书籍结构、如何分配深度预算、如何生成 glossary/patterns/cheatsheet

这种"确定性提取 + AI 生成"的分层设计非常巧妙：提取过程稳定可复现，生成过程灵活可迭代。

依赖管理采用 Python 标准 pyproject.toml，支持按需安装：

pip install book-to-skill[pdf]          # PDF 支持
pip install book-to-skill[technical]    # Docling（技术书籍）
pip install book-to-skill[all]           # 全部格式

代码质量方面：使用 ruff 进行 lint（仅开启 E9/F 高价值规则，不做过度风格约束），pytest 测试覆盖提取、检测和 Discovery Tax 测量。

---

争议与局限

1. 扫描版 PDF 需要 OCR。没有文字层的扫描书籍无法直接处理，需要先 ocrmypdf 转换
2. 版权问题需自行负责。项目明确声明不处理版权，但生成的技能包含原书知识框架，是否构成版权争议取决于使用方式
3. 生成质量依赖 AI 模型能力。SKILL.md 生成质量取决于调用的模型（Claude Sonnet 4.5 / GPT-4 等），不同模型生成的技能可能有差异
4. 跨 Agent 兼容但非完美。SKILL.md 是 Agent Skills 开放规范，但不同 Agent 对它的解析方式存在细微差异（如 Hermes Agent 的 skills 目录结构和 Claude Code 不同）

---

行业意义：Agent Skills 生态的基础设施

book-to-skill 的成功折射出一个更大的趋势：Agent Skills 作为跨 Agent 的知识共享标准正在形成。

2026 年，Claude Skills 的 SKILL.md 格式已被 Claude Code、Cursor、Gemini CLI、Codex CLI 等多个主流 Agent 采纳。GitHub 上出现了社区技能库（如 agentskills/agentskills），非开发者也能贡献自己的领域知识。

book-to-skill 在这个生态中扮演了内容生产工具的角色：它把被动积累的书籍知识，转化为主动可复用的 Agent 技能。从"买了书 → 读完忘"到"买了书 → AI 记住 → 随时调用"，这是一个工作流的根本性改变。

目前项目仍在活跃维护中（最新更新 2026 年 9 月），支持 Claude Code 最新版本，已在 Reddit r/claudeskills 社区引发广泛讨论，被评价为"最实用的 Claude Skill 之一"。