Book-to-Skill 图书技能转换器
把任何技术书 PDF、文档或资料集转换成结构化 Agent 技能，随时查阅、边干活边用，比把整本书塞进上下文省 24–51 倍 token。
SKILL.md 本身体现最低权限与用户确认：写入位置需向用户确认而非静默默认，依赖安装默认 ask，成本预估在生成前请求确认，处理完全本地且 README/SECURITY 明确不联网上传，无隐蔽外传迹象。扣分点：生成的 skill 会写入用户文件系统多个位置，覆盖现有 skill 需用户选择但流程较长易误操作；rollback/删除机制未在 SKILL.md 中说明；权限声明（allowed-tools）被有意省略，依赖宿主首用提示。
指令自洽、步骤编号清晰、异常路径（无参数、无支持文件、找不到 extract.py、扫描版 PDF）有明确报错与退出；工作目录按 PID 隔离避免并发冲突。扣分点：静态审查无法执行关键路径，extract.py 本体未在证据中；SKILL.md 文本在 cheatsheet 一节被截断（'The '处中断），Step 9 及后续不完整，长书 REPL 流程与脚本实际行为无法核对。
触发条件定义精确（四种模式各有 Trigger），输入格式、输出结构、非适用范围（扫描 PDF 需 OCR、无章节标题的书不自动分段）都有披露；多宿主（Claude Code/Copilot/Amp/Hermes）环境适配详尽，含 CJK 令牌估算与中日韩目录检测，中文文档有 README.zh-CN。扣分点：技术模式依赖 docling、部分格式依赖 pip/Calibre，大陆网络下安装这些依赖可能不可达或不稳定，未提供镜像指引。
文档分层良好（SKILL.md 精简、README/FAQ/architecture 分层），MIT 许可明确，CHANGELOG 由 git-cliff 生成且语义化版本，维护责任与更新路径（issues、 sponsors 支持的维护模式）清楚，CI 含 SKILL.md 一致性校验工具 validate_skill.py。扣分点：AGENTS.md 要求 SKILL.md 保持精简，但该文件较长且本证据中尾部截断，无法确认完整性与最新一致性；生成产物的版本/治理规则依赖生成时行为，静态不可核。
核心任务路径（提取→结构化→生成按需加载的章节文件）设计合理，相对手工整理或直接读 PDF 的边际价值有明确论证（24×–51× token 节省、Discovery Loop Tax），成本预估透明。扣分点：静态审查未执行，生成产物质量（章节摘要准确性、cheatsheet 完整性）无法验证；SKILL.md 截断使 Step 9/10 与质量规则不可见；价值声明主要来自仓库自述文档，代表性输出未在本证据中出现。
有较强的一手材料：CI 工作流（pytest 矩阵、smoke、bandit、CodeQL、dependency-review）、测试目录、CHANGELOG 中的可复核测量（韩文章节检测 precision 0.999/recall 1.000、Gutenberg 基准）、use-cases 仓库模式。扣分点：静态审查不可执行；所示测试文件仅覆盖 eval manifest 而非生成关键路径；基准数字与声称结果未经独立复核，达到 5 分上限但不可再高。
- 静态审查未执行任何代码；SKILL.md 在 cheatsheet 一节被截断，Step 9 及后续指令不可见，实际行为可能与文档不符。
- 技术模式需安装 docling，部分格式依赖 pip 或 Calibre；中国大陆网络下载这些依赖可能失败或缓慢，建议预先用 extract.py --check 并自备镜像。
- 生成的 skill 会写入多个候选目录并可能覆盖已有 skill；使用前注意确认目标路径，删除/回滚需手动进行。
- 转换受版权保护书籍产生的 skill 应保持私有，勿公开分发；项目自身不含任何书籍内容。
这个 Skill 能做什么，适合哪些场景？
book-to-skill 是一个开源（MIT）的 Agent 技能，可把 PDF、EPUB、DOCX、HTML、Markdown、RTF 乃至 MOBI/AZW 图书或文档文件夹转换成结构化技能。它提取的不是摘要，而是作者命名的框架、原则、技巧、反模式和思维模型，按章节生成为按需加载的文件。生成结果可在 GitHub Copilot CLI、Amp、Claude Code、Hermes Agent 等兼容 Agent Skills 标准的主机中使用。处理全程在本地进行，工具本身不包含任何书籍内容。
安装后，在支持的 Agent 中运行 /book-to-skill <路径或通配符> [技能名]。工作流程：先询问输入是技术类还是文本类；调用 scripts/extract.py 抽取文本（技术类用 Docling 保留表格和代码块，约 1.5 秒/页；文本类用 pdftotext/pypdf/pdfminer，即时完成），并给出 token 成本预估；分析书的标题、作者和章节结构；为每章生成摘要文件（含框架、代码示例、参考表、决策要点），外加 glossary.md、patterns.md、cheatsheet.md 和主 SKILL.md（约 4000 token）；写入 ~/.copilot/skills/、~/.agents/skills/ 或 ~/.claude/skills/ 等目录；最后运行安全扫描并清理临时工作目录。还支持把新资料合并进已有技能（Update/Fold-in），以及可选地用 gh CLI 发布到 GitHub。
- 工程师买了《Pro Git》《Think Python》这类技术书，读过后想边写代码边按章节查阅准确内容，而不是翻 PDF
- 团队把内部架构决策记录、runbook 或入职文档文件夹合并成一个可查询的技能
- 把品牌手册或设计规范变成团队可随时提问的技能，替代翻阅几十页 PDF
- 研究员把一批论文加自己的笔记合并成统一知识库，新资料到了可以增量并入
- 需要反复应用某本书方法论（如影响力、系统思考框架）的从业者，想让 Agent 按"Use X when Y"的方式调用这些框架
这个 Skill 有哪些优点和局限？
- 实测比整本塞进上下文省 24–51 倍 token，比每次问答的探索循环也省 2.4–15.6 倍（tools/discovery_tax.py 可自行复现）
- 提取结构而非摘要：保留作者命名的框架、决策规则、反模式，回答基于你的实际文本而非训练数据
- 章节文件按需加载，技能常驻成本仅约 5000 token；一本书转换成本约 1 美元量级
- 跨主机：一个 SKILL.md 同时适配 Copilot CLI、Amp、Claude Code、Hermes Agent 等标准兼容主机
- 本地处理，不包含也不上传书籍内容；支持增量更新已有技能；MIT 许可
- 章节自动检测依赖显式的 Chapter N / Capítulo N 标题；Pro Git、Moby-Dick 等用小节或罗马数字的书无法自动分段
- 技术类 PDF 的 Docling 抽取较慢（约 1.5 秒/页），长书需要等待几分钟
- 基准测试只覆盖三本书和特定模型定价；对其他书和模型的实际成本需自行验证
- 生成技能的内容源自第三方版权书籍时必须保持私有，不能公开分发（README 明确了版权红线）
- EPUB 图片不读取（仅计数丢弃）；MOBI 依赖外部安装的 Calibre，非 pip 包
如何安装这个 Skill？
作为 Agent 技能安装（提供 /book-to-skill 命令）：
- GitHub Copilot CLI：git clone https://github.com/virgiliojr94/book-to-skill.git ~/.copilot/skills/book-to-skill，然后在会话中运行 /skills reload
- 跨主机路径（Copilot CLI 和 Amp 均可发现）：克隆到 ~/.agents/skills/book-to-skill
- Claude Code：克隆到 ~/.claude/skills/book-to-skill，或在会话中粘贴安装提示词
纯文本/Markdown/reStructuredText/AsciiDoc 无需额外依赖；PDF、EPUB、DOCX、RTF 等格式的可选抽取器可用 python3 scripts/extract.py --check 检查并按提示安装。
如何使用这个 Skill？
在 Agent 会话中运行：/book-to-skill ~/books/my-book.pdf（也支持文件夹、glob 或多文件列表，可加自定义技能名）。生成后即可像普通技能一样使用：/your-book-skill 加载核心框架；/your-book-skill replication 查找并讲解某主题；/your-book-skill ch05 深入某章；/your-book-skill "what chapters do you have?" 浏览目录。Copilot CLI 中新技能可能需要 /skills reload 才会出现；Claude Code 和 Amp 在下次会话中自动加载。
这个 Skill 与同类方案有什么区别？
README 对比了几种替代方案：直接把 PDF 塞进上下文（每回合重复付费，大窗口也不便宜）；RAG 工具（如 CandleKeep，适合几十本书的宽而浅的检索）；NotebookLM（适合跨大量书籍搜索）。book-to-skill 定位是"窄而深"——把一本书或一组相关资料变成可反复应用的推理结构，与 RAG 互补而非竞争。