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

章节文件按需加载 —— 在你问到相关主题之前，不会占用 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 <path|folder|glob> [skill-name] —— 另有仅分析、从分析结果生成、更新/折叠合并等模式。转换完成后，converter 可将 skill 发布到 GitHub（默认私有），任意宿主可通过 npx skills add 安装。

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

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

📥 安装

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

# 或手动 —— 克隆到 skills 文件夹（注册 /book-to-skill）：
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill
# （Copilot CLI：~/.copilot/skills/ · Amp/跨 Agent：~/.agents/skills/）
# （Hermes Agent：${HERMES_HOME:-$HOME/.hermes}/skills/<category>/）
# （OpenClaw：${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/skills/；~/.agents/skills/ 仅限默认状态）
# （OpenCode：~/.agents/skills/ —— 同时也读取 ~/.config/opencode/skills/）

📥 所有宿主、可选提取器与独立 CLI → docs/install.md

❓ FAQ

常见问题 —— 「为什么不直接把 PDF 丢进去？」、成本、隐私、非书籍输入、多文件书籍等。

❓ 答案 → docs/faq.md

book-to-skill/
├── SKILL.md              # Skill 定义 + 逐步说明（生成器 spec）
├── scripts/
│   ├── extract.py        # 薄入口包装
│   └── extractor/        # 模块化提取包
│       ├── config.py     # 扩展名、路径、依赖常量
│       ├── dependencies.py  # 可选依赖探测 + --check
│       ├── exceptions.py # ExtractionError（单源失败，批处理安全）
│       ├── utils.py      # CLI 解析、多源解析、章节检测、runner
│       └── parsers/      # 各格式解析器（pdf、epub、docx、html、rtf、calibre、text）
├── tools/
│   ├── discovery_tax.py  # 测量 token 成本 vs 上下文 dump / discovery loop
│   └── validate_skill.py # 按宿主规则校验生成的 SKILL.md（--lens claude|copilot|amp）
├── tests/                # pytest 套件（提取、检测、discovery tax）
├── docs/
│   ├── performance.md    # 实测基准、discovery tax、成本
│   └── architecture.md   # 流水线 + 组件图
├── CHANGELOG.md          # 发布历史（semver）
├── CONTRIBUTING.md       # 开发环境、PR 规范、发布流程
├── SECURITY.md           # 漏洞报告
└── README.md             # 英文 README

⚖️ 版权与合理使用

book-to-skill 不包含任何书籍内容 —— 一页都没有。它是你指向已有文件的转换器。

• 本地处理。 提取与分析在你的机器上运行。本工具不会上传你的文件。（若 Agent 的模型在云端运行，你喂给它的文本遵循该提供商的正常数据条款 —— 与任何 prompt 相同。）
• 使用你自己的副本。 带上你购买的书、公司拥有的文档，或你有权阅读的论文。
• 输出是你的笔记。 生成的 skill 是结构化、综合的衍生内容 —— 框架名、定义、要点 —— 不是原文再现。skill 明确从不复制原始段落（见 Quality Rule #7）。把它当作手写学习笔记：属于你，供个人使用。
• 不要重新分发。 发布或分享受版权保护作品所生成的 skill 可能侵犯权利人权益。第三方书籍的 skill 请保持私有。内部文档、自己的写作和开放许可材料可在其许可证范围内分享。

如有疑问，请遵循源文档的许可证或条款。本项目是工具；如何使用由你负责。

💖 赞助

book-to-skill 免费且 MIT 许可，由维护者在业余时间维护。若它为你节省了 token 或学习时间，欢迎赞助日常维护：PR 审查、多语言修复、发布与文档。

成为赞助者 → github.com/sponsors/virgiliojr94

每位赞助者列在 BACKERS.md。感谢支持开放、隐私优先的工具。✨

许可证

MIT —— 适用于本仓库中的转换器（代码 + skill 定义），不适用于你用其处理的任何书籍或文档。

_{目录策略与英文 README 的 commit c108d25 同步 · 英文版为准}