README

book-to-skill


  English ·
  Русский ·
  简体中文


 翻译说明。 以英文 README 为准。本翻译可能落后于 master。  
 与英文版同步于 commit 907be50（2026-08-31）。  
 查看差异：git log 907be50..master -- README.md


将任意技术书籍、文档文件夹或资料集合，转换为统一的 Agent Skill——可在 GitHub Copilot CLI、Amp、Claude Code、Hermes Agent 或 OpenCode, OpenClaw 中随时学习、查阅并在工作中使用。


  
  
  
  
  



  
  



  为什么 ·
  生成内容 ·
  不止于书籍 ·
  工作原理 ·
  用法 ·
  安装 ·
  FAQ ·
  性能 ·
  架构 ·
  更新日志



  回答一个问题时，比把整本书丢进上下文少消耗 24×–51× 的 token，基于真实书籍测量（测量方法）。


三步上手：

1. 指定文件、文件夹或 glob —— /book-to-skill ./my-book.pdf
2. 提炼成 skill —— 框架、决策规则、反模式，以及按章节拆分的文件。提取的是结构，不是摘要。
3. Agent 按需加载 —— 输入 /my-book replication，它会读取对应章节，基于真实内容回答，避免幻觉。

---

 🤔 为什么



你买了一本很好的技术书，读了一遍。三个月后，你忘了第 7 章的存在。

常见的变通办法都不管用：
- 📄 「我搜一下 PDF」→ 得到的是页码列表，不是答案
- 🧠 「我问 Agent 这本书的内容」→ 要么幻觉，要么说没有内容
- 📝 「边读边做笔记」→ 最后得到一份 200 行的文档，再也不会打开

book-to-skill 把书变成结构化 skill，Agent 按需加载。

安装后，输入 /your-book-slug replication，Agent 会读取对应章节，基于实际内容回答。没有幻觉，不用翻 PDF。书成为你工作流的一部分。

兼容任何支持开放 Agent Skills 标准的宿主 —— GitHub Copilot CLI、Amp、Claude Code、Hermes Agent 和 OpenCode, OpenClaw 都读取相同的 SKILL.md 格式。
---

 📦 生成内容

运行 /book-to-skill your-book.pdf（或文件夹、glob、文件列表）后，默认会在用户级跨 Agent 目录 ~/.agents/skills// 生成一份完整 skill，供 Copilot CLI、Amp、Codex、OpenCode 和使用默认状态目录的 OpenClaw 直接发现。OpenCode 也会读取其托管目录 ~/.config/opencode/skills//；若设置了非默认 OPENCLAW_STATE_DIR，OpenClaw 则需使用当前状态目录下的 skills/。在 Claude Code 中运行时，转换器还会尝试在 ~/.claude/skills// 创建符号链接；只有回读验证通过，才会报告 Claude Code 已发现该 skill，否则运行报告会说明链接未建立。Hermes Agent 不扫描跨 Agent 目录，其个人 skill 按类别安装在 ${HERMES_HOME:-$HOME/.hermes}/skills///。也可以按需显式选择 OpenClaw 或 OpenCode 托管目录，以及项目本地目录：

| 文件 | 用途 | 大小 |
|------|------|------|
| 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 |

章节文件按需加载 —— 在你问到相关主题之前，不会占用 skill 预算。

---

 🏢 不止于书籍

名字里是「book」，但输入可以是任意结构化 prose。同一套提取流程适用于你拥有并反复查阅的知识：

- 内部文档 —— 架构决策记录、运行手册、入职指南。把整个 docs/ 文件夹折叠成一个 skill，编码时随时提问。
- 品牌与设计系统 —— 语调指南、语气文档、组件原则。把品牌手册变成 skill，团队查询代替翻阅 60 页 PDF。
- 研究资料簇 —— 一叠论文加自己的笔记，合并为统一 skill，新资料到来时可更新（见更新 / 折叠合并）。
- 规范与标准 —— RFC、API 合约、合规文档——常查但从没背下来。

如果你经常重新打开某份文档，希望自己已经背下来，它就是候选。

---

 🧾 Discovery Loop Tax（发现循环税）

读 PDF 的 Agent 不只是读 —— 它还要导航：反复获取目录、回溯、每一轮重新处理。book-to-skill 在转换时一次性支付结构化成本，查询时 token 与答案规模成正比 —— 比把书丢进上下文少 24×–51×，基于真实书籍测量。

📊 完整方法论、数据与逐书表格 → docs/performance.md

---

 ⚙️ 工作原理

两部分：确定性的 Python 提取器（文档 → 干净文本 + 元数据）和 spec 驱动的 生成器（Agent 按 SKILL.md 生成结构化 skill）。按需加载的章节文件保持已加载 skill 体积小巧。

🔧 完整流程（Step 0–10、提取模式、token 预算）→ docs/how-it-works.md

---

 🚀 用法

/book-to-skill  [skill-name] —— 另有仅分析、从分析结果生成、更新/折叠合并等模式。转换完成后，converter 可将 skill 发布到 GitHub（默认私有），任意宿主可通过 npx skills add 安装。

▶️ 所有模式与示例 → docs/usage.md

💬 实践案例 → use cases —— 一本 DevEx 书变成 300+ 工程师调研；一本扫描 PDF 卡住后成为 130。欢迎添加你的案例：账号在你自己的 Gist，索引只需一行 PR。

---

 📥 安装

bash
 一条命令，任意宿主 —— 通过跨 Agent skills CLI：
npx skills add virgiliojr94/book-to-skill

 或手动 —— 克隆到 skills 文件夹（注册 /book-to-skill）：
gi

Top issues

Latest release

Extraction reliability release: six fixes for silent content loss or silent wrong answers, plus the first changelog generated from commit messages.

Highlights

- Scanned PDFs fail fast. An image-only PDF used to run the whole extraction chain — Docling across every page in technical mode — before failing with a message about Unicode sanitization. It now stops on the first pages in ~0.01s and tells you to run ocrmypdf (130), and the docs finally state the limit (132).
- Real words stopped being deleted. Page-edge cleanup treated any short word built from ivxlcdm as a page number, so "MIX", "CI