book-to-skill
将任何技术书籍、文档文件夹或资料集合转化为统一的代理技能（Skill）——在GitHub Copilot CLI、Amp或Claude Code中边工作边学习、参考和使用。
为什么 · 生成内容 · 超越书籍 · 工作原理 · 使用方法 · 安装 · 常见问题 · 性能 · 架构 · 更新日志
与将整本书倒入上下文相比，Token消耗减少24倍至51倍，针对真实书籍测量（测量方法）。
工作原理，只需3步：
- 指定文件、文件夹或通配符——
/book-to-skill ./my-book.pdf - 提炼——工具将书籍提炼为技能——框架、决策规则、反模式以及按章节拆分文件。提取结构，而非摘要。
- 按需加载——输入
/my-book replication，代理读取相应章节，基于真实内容回答，不会产生幻觉。
🤔 为什么
你买了一本很棒的技术书。读了一遍。三个月后，你已经不记得第7章的存在。
常见的变通方法并不能解决问题：
- 📄 “让我搜一下PDF” → 得到的是一堆页码，而不是答案
- 🧠 “我会问代理关于这本书的事” → 要么幻觉，要么说没有内容
- 📝 “我边读边做笔记” → 最终得到一个200行的文档，再也不打开
book-to-skill通过将书籍转化为结构化技能，让代理按需加载来解决这个问题。
安装后，只要输入/your-book-slug replication，代理就会读取正确章节并从真实内容中回答。没有幻觉，无需翻阅PDF。书籍成为你工作流程的一部分。
支持任何遵循开放Agent Skills标准的主机——GitHub Copilot CLI、Amp和Claude Code都读取相同的SKILL.md格式。
📦 生成内容
运行/book-to-skill your-book.pdf（或文件夹、通配符或文件列表）会在代理的技能目录中创建一个完整技能（Copilot CLI为~/.copilot/skills/<slug>/，Amp或跨代理为~/.agents/skills/<slug>/，Claude Code为~/.claude/skills/<slug>/）：
| 文件 | 用途 | 大小 |
|---|---|---|
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 |
章节文件按需加载——在你询问该主题之前，它们不计入技能预算。
🏢 超越书籍
名字说的是“书”，但输入可以是任何结构化文字。同样适用于你拥有并经常重读的知识：
- 内部文档——架构决策记录、操作手册、入职指南。将整个
docs/文件夹折叠进一个技能，编码时随时提问。 - 品牌与设计系统——语音指南、语气文档、组件原理。将品牌手册转化为团队查询的技能，而不是翻阅60页PDF。
- 研究集群——一堆论文加上你自己的笔记，合并成一个统一技能，并随着新材料出现而更新（参见更新/融入）。
- 规范与标准——RFC、API契约、合规文档，你参考但从不背诵。
如果你经常重看某个文档，以至于希望自己能记住它，那它就是合适的候选对象。
🧾 发现循环税（Discovery Loop Tax）
一个PDF阅读代理不只是阅读——它还要导航：每一轮都要重新获取目录、回溯、重新处理所有内容。book-to-skill只在转换时支付一次这种结构化成本，因此查询会与答案成正比——与将整本书倒入上下文相比，Token消耗减少24倍至51倍，基于真实书籍实测。
📊 完整方法、数字和每本书的表格 → docs/PERFORMANCE.md
⚙️ 工作原理
两个部分：一个确定性的Python提取器（文档 → 干净文本 + 元数据）和一个规范驱动的生成器（你的代理遵循SKILL.md将其转化为结构化技能）。按需加载章节文件可保持已加载技能精简。
🔧 完整指南（步骤0-10，提取模式，Token预算）→ docs/HOW_IT_WORKS.md
🚀 使用方法
/book-to-skill <路径|文件夹|通配符> [技能名称]——另有仅分析、从分析生成、以及更新/融入模式。
▶️ 所有模式和示例 → docs/USAGE.md
📥 安装
# 代理技能（注册 /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/）
📥 所有主机、可选提取器以及独立CLI → docs/INSTALL.md
❓ 常见问题
常见问题——“为什么不直接倾倒PDF？”，成本、隐私、非书籍输入、多文件书籍。
❓ 答案 → docs/FAQ.md
🔧 系统要求
提取器按格式依次尝试工具，并使用第一个可用的。如果什么都没安装，会告诉你需要运行哪条命令。纯文本、Markdown、reStructuredText和AsciiDoc不需要额外依赖。
一条命令检查你的环境：
python3 scripts/extract.py --check会打印每种格式已安装的提取器，以及安装缺失项的确切命令——无需文件。
PDF——根据书籍类型选择：
| 书籍类型 | 工具 | 安装 | 速度 |
|---|---|---|---|
| 文本为主（散文，少表格） | pdftotext (poppler) | sudo apt install poppler-utils | ⚡ 即时 |
| 文本为主后备 | pypdf | pip3 install pypdf | ⚡ 即时 |
| 文本为主后备 | pdfminer.six | pip3 install pdfminer.six | ⚡ 即时 |
| 技术类（代码、表格、公式） | docling | pip3 install docling | 约1.5秒/页 |
在提取开始前，技能会询问书籍是技术类还是文本为主，并自动选择正确的工具。Docling保留Markdown表格和代码块；pdftotext对于纯散文类书籍更快。
EPUB：
| 工具 | 安装 | 质量 |
|---|---|---|
ebooklib + beautifulsoup4 | pip3 install ebooklib beautifulsoup4 | ⭐⭐⭐ 最佳 |
标准库 zipfile | 内置——无需安装 | ⭐⭐ 始终可用 |
其他格式：
| 格式 | 工具 | 安装 |
|---|---|---|
| DOCX | python-docx（后备：标准库ZIP/XML） | pip3 install python-docx |
| HTML | beautifulsoup4（后备：标准库html.parser） | pip3 install beautifulsoup4 |
| RTF | striprtf（后备：正则） | pip3 install striprtf |
| MOBI / AZW / AZW3 | Calibre ebook-convert（外部应用，非pip） | https://calibre-ebook.com/download |
| TXT / Markdown / reStructuredText / AsciiDoc | 内置 | — |
📁 仓库结构
book-to-skill/
├── SKILL.md # 技能定义 + 逐步指令（生成器规范）
├── scripts/
│ ├── extract.py # 精简入口包装器
│ └── extractor/ # 模块化提取包
│ ├── config.py # 扩展名、路径、依赖常量
│ ├── dependencies.py # 可选依赖探测 + --check
│ ├── exceptions.py # ExtractionError（单源失败，批量安全）
│ ├── utils.py # CLI解析、多源解析、章节检测、运行器
│ └── parsers/ # 格式专用解析器（pdf、epub、docx、html、rtf、calibre、text）
├── tools/
│ ├── discovery_tax.py # 测量Token成本 vs 上下文倾倒/发现循环
│ └── validate_skill.py # 根据主机规则检查生成的SKILL.md（--lens claude|copilot|amp）
├── tests/ # pytest测试套件（提取、检测、发现税）
├── docs/
│ ├── PERFORMANCE.md # 实测基准、发现税、成本
│ └── ARCHITECTURE.md # 流水线 + 组件图
├── CHANGELOG.md # 发布历史（语义化版本）
├── CONTRIBUTING.md # 开发设置、PR约定、发布流程
├── SECURITY.md # 漏洞报告
└── README.md # 本文件
⚖️ 版权与合理使用
book-to-skill不包含任何书籍内容——连一页都没有。它只是一个转换器，指向你已拥有的文件。
- 处理在本机进行。 提取和分析在你的机器上运行。本工具绝不会上传你的文件。（如果你的代理模型在云端运行，你输入的文本遵循该提供商正常的数据条款——与任何提示相同。）
- 使用你自己的副本。 携带你购买的书、你公司拥有的文档，或你有权阅读的论文。
- 输出就是你的笔记。 生成的技能是结构化、综合的衍生内容——框架名称、定义、要点——而非文本的复制。该技能明确从不复制原始段落（见质量规则#7）。将其视为手写学习笔记：属于你，供个人使用。
- 不要重新分发。 发布或分享受版权保护作品的生成技能可能侵犯权利持有人的权益。保持第三方书籍的技能私密。内部文档、你自己的写作和开放许可材料在许可范围内可以分享。
如有疑问，请遵循源文档的许可证或条款。这个项目是一个工具；如何使用由你自己负责。
💖 赞助者
book-to-skill是免费且MIT许可的，在个人时间维护。如果它为你节省了Token或学习时间，请考虑赞助其维护：PR审查、多语言修复、发布和文档。
成为赞助者 → github.com/sponsors/virgiliojr94
每位赞助者都会列在BACKERS.md中。感谢你让开放、隐私至上的工具保持活力。✨
许可证
MIT——适用于本仓库中的转换器（代码 + 技能定义），不适用于你用它处理的任何书籍或文档。