book-to-skill 项目摘要

项目定位

book-to-skill 是一个本地化的转换工具，能将任意技术书籍、文档目录或资料集合转化为符合开放 Agent Skills 标准的结构化技能（skill）。生成的 skill 可在 GitHub Copilot CLI、Amp、Claude Code 等支持该标准的代理中按需加载，让用户在编码或学习时直接通过斜杠命令调用书中的内容。

相比把整本书塞进上下文再让代理阅读，使用该工具后查询时的 token 消耗可减少 24 倍到 51 倍（基于真实书籍的基准测试），因为结构化成本只在转换时支付一次。

工作流程

三步即可完成转换：

1. 指定输入：指向一个文件、文件夹或 glob 模式，例如 /book-to-skill ./my-book.pdf。
2. 蒸馏成 skill：工具将书籍提炼为框架、决策规则、反模式以及按章节切分的文件，输出的是结构而非摘要。
3. 按需加载：输入 /my-book replication 时，代理会读取对应章节并基于真实内容回答，避免凭空编造。

生成产物

执行 /book-to-skill your-book.pdf（也支持文件夹、glob 或文件列表）后，会在代理的技能目录创建完整 skill：

文件	用途	体量
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

章节文件按需加载，在主动询问相关主题前不会占用技能预算。

不只是书

虽然名称带有 "book"，但输入可以是任何结构化文本，例如：内部架构决策记录、运维手册、新人指南组成的 docs/ 目录；品牌语调指南、组件设计原则；论文加个人笔记的混合资料；RFC、API 契约、合规文档等。只要是反复查阅却记不住的资料，都是合适的候选。

技术架构

工具分为两半：

• Python 抽取器（确定性）：从文档中提取干净的文本与元数据。
• 生成器（由代理遵循规格执行）：读取 SKILL.md 中的步骤说明，将抽取结果组织为结构化 skill。

按需加载的章节文件保证了运行时技能体积保持在较小范围。

用法

命令格式为 /book-to-skill <path|folder|glob> [skill-name]，并支持仅分析、从分析结果生成、更新/合并等模式。转换完成后还可以将 skill 发布到 GitHub（默认私有），通过 npx skills add 安装到任意代理。

安装

# 推荐方式：跨代理 skills CLI 一键安装
npx skills add virgiliojr94/book-to-skill

# 手动方式：克隆到技能目录
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill
# Copilot CLI 用 ~/.copilot/skills/，Amp 或跨代理用 ~/.agents/skills/

抽取器依赖

工具按格式依次尝试可用的抽取库，使用首个可选项。可执行 python3 scripts/extract.py --check 查看当前环境中各格式对应的抽取器是否齐全。

格式	推荐工具	安装命令	备注
PDF（纯文本）	pdftotext (poppler)	sudo apt install poppler-utils	速度最快
PDF（技术类，含代码与表格）	docling	pip3 install docling	保留 Markdown 表格与代码块
EPUB	ebooklib + beautifulsoup4	pip3 install ebooklib beautifulsoup4	质量最佳
HTML	beautifulsoup4	pip3 install beautifulsoup4	—
DOCX	python-docx	pip3 install python-docx	—
RTF	striprtf	pip3 install striprtf	—
MOBI/AZW/AZW3	Calibre ebook-convert	需安装 Calibre 桌面应用	外部工具
TXT/Markdown/reST/AsciiDoc	内置	—	无需安装

扫描版 PDF 需要先用 OCR 增加文本层，例如 ocrmypdf input.pdf output.pdf，否则抽取器会在检测后立即停止。

版权与许可

• 项目本身以 MIT 许可证发布，仅覆盖代码与 skill 定义。
• 不随项目附带任何书籍内容，输出是用户基于自有副本生成的笔记式衍生品，不会复制原文段落。
• 处理过程完全本地，文件不会被工具上传。
• 第三方书籍的 skill 应保持私有，不要再分发。

仓库结构

book-to-skill/
├── SKILL.md              # 技能定义与分步说明（生成器规格）
├── scripts/
│   ├── extract.py        # 入口封装
│   └── extractor/        # 模块化抽取包
│       ├── config.py     # 扩展名、路径与依赖常量
│       ├── dependencies.py  # 可选依赖探测 + --check
│       ├── exceptions.py # 抽取异常（支持批量时单源失败）
│       ├── utils.py      # CLI 解析、多源解析、章节检测
│       └── parsers/      # 各格式解析器（pdf、epub、docx、html、rtf、calibre、text）
├── tools/
│   ├── discovery_tax.py  # 测量 token 成本
│   └── validate_skill.py # 按主机规则校验生成的 SKILL.md
├── tests/                # pytest 测试集
└── docs/                 # 性能、架构、用法、安装、FAQ 等文档