1. 为什么要把技术书编译成 Agent Skill如果你正在用 Claude Code 写一个分布式存储模块脑子里想的是「按 DDIA 里那套复制模型来设计」但 Agent 给你的回答永远是教科书式的泛泛而谈——问题不在模型在于它根本没见过你手里那本书。传统做法是把 PDF 丢给 AI让它总结然后把相关段落复制进对话。每换一个问题这套动作就要重来一遍。一本 500 页的技术书大概 20 万 Token全塞进上下文不仅贵还会让模型在无关章节里「迷路」。book-to-skill 这个项目换了个思路它不把书做成摘要而是把书编译成 Agent 能长期复用的结构化知识目录也就是 SKILL.md 加章节文件。具体来说转换完成后你会得到这样一个结构~/.claude/skills/ddia/ ├── SKILL.md ├── chapters/ │ ├── ch01-tradeoffs.md │ ├── ch02-data-models.md │ ├── ch05-replication.md │ └── ch07-transactions.md ├── glossary.md ├── patterns.md └── cheatsheet.mdSKILL.md 是入口大约 4K Token里面存核心框架、关键思维模型和章节索引。Agent 启动这个 Skill 时只读这一份需要细节时再按索引去读对应章节文件。项目自己的基准测试显示针对单个章节提问的场景输入 Token 相比整本书塞上下文能减少 24 到 51 倍具体取决于书的结构和问题类型。它和 RAG、NotebookLM 的区别在于定位。如果你有 500 本书要全文检索那 RAG 更合适。book-to-skill 面向的是「我正在真正用这一本书希望 Agent 长期按它的方法工作」。比如把 DDIA 里的 Replication、Partitioning、Consistency、Storage Engine 变成 Agent 随时能引用的方法论而不是每次重新搜索。名字虽然叫 book-to-skill但现在它已经支持单个文件、文件夹、Glob 和多来源集合。你完全可以把~/company-docs/整个目录——architecture.md、api.md、deployment.md、security.md——编译成一个统一的 Skill。这样它实际能覆盖企业技术文档、项目架构说明、开发规范、API 文档、运维手册这些场景。支持格式包括 PDF、EPUB、DOCX、TXT、Markdown、reStructuredText、AsciiDoc、HTML、RTF、MOBI、AZW/AZW3其中 MOBI 和 AZW 需要额外装 Calibre。部署层面book-to-skill 是纯本地转换工具读取你指定的文件把 Skill 写到对应目录不上传文件、不联网、不启动服务。个人电脑直接跑没问题。但如果你日常已经在用 Claude Code、Codex、Copilot CLI 这套远程开发环境把它一起放到 Linux 服务器上会更顺——多设备共享同一套 SkillsAgent 和资料在同一环境批量转换也不占个人电脑。下面就从环境准备开始一步步走完从文档到 Agent 调用的完整流程。2. TaoToken 前置统一 Key 与 API 通道book-to-skill 本身只负责「文档 → SKILL.md」的编译它不碰模型调用。真正让 Agent 读起这些 Skill 来回答问题的是 Claude Code 背后的模型通道。这里有个容易被忽略的坑很多人装完 book-to-skillSkill 也生成了但 Claude Code 那边模型请求一直 401最后发现是 Key 和 Base URL 没配对。我建议在部署 book-to-skill 之前先把模型侧的接入通道理顺。TaoToken 在这里的作用是提供一个统一的 Key 和 API 入口让 Claude Code、Codex、Cline 这些工具走同一条通道不用每个工具单独配一套凭证。官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。你需要提前准备三样东西我把它叫做「接入三件套」项目说明获取位置Base URL模型请求的入口地址https://taotoken.net/apiAPI Key身份凭证形如 sk-xxx控制台 API Keys 页面Model ID具体调用的模型标识模型列表或文档这三件套在 Claude Code、Cline、Codex 里的填法不一样但缺一不可。很多人只填了 Key 忘了 Base URL或者 Base URL 末尾多加了/v1导致路径重复都会报错。先去控制台创建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 然后在 API Keys 页面生成一个。生成后立刻复制保存页面刷新后就看不到了。如果你还没决定用哪个模型可以先到模型对话页面试一下https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 确认模型能正常响应再往下走。对于长期跑 Agent 的场景比如你打算让 Claude Code 持续读 Skill 写代码可以考虑 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它更适合高频调用不用每次担心额度。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各工具的具体配置示例。这里要强调一点TaoToken 是模型 API 通道不是编辑器替代品也不是 book-to-skill 的替代。它解决的是「Agent 怎么调到模型」这一层book-to-skill 解决的是「Agent 读什么知识」这一层两者是配合关系。把 Key 和 Base URL 准备好后面配置 Claude Code 时直接填进去就行。3. 可复制配置目录结构与 SKILL.md 模板这一节给你可以直接抄的配置。先规划目录再写 SKILL.md 模板最后配 Claude Code 的 settings。3.1 服务器目录规划假设你在一台 Linux 开发机上建议这样组织/data/ ├── books/ │ ├── ddia.pdf │ ├── clean-code.epub │ └── system-design.pdf ├── documents/ │ ├── api/ │ │ ├── auth.md │ │ └── endpoints.md │ └── architecture/ │ ├── overview.md │ └── database.md └── projects/ └── backend/ ~/.claude/skills/ ├── book-to-skill/ ├── ddia/ ├── clean-code/ └── company-architecture//data/books放电子书/data/documents放项目文档~/.claude/skills放编译产物。这样备份和迁移都清晰。3.2 安装 book-to-skill先更新系统并装依赖apt update apt upgrade -y apt install -y git curl python3 python3-pip python3-venv poppler-utils验证 PDF 提取工具python3 --version pdftotext -v然后克隆到 Skills 目录这是注册 Agent Skill 的方式和 pip 安装是两条路mkdir -p ~/.claude/skills cd ~/.claude/skills git clone https://github.com/virgiliojr94/book-to-skill.git完成后~/.claude/skills/book-to-skill/就存在了。如果你只想用独立 CLI 提取文档可以另建虚拟环境python3 -m venv ~/book-to-skill-env source ~/book-to-skill-env/bin/activate pip install book-to-skill注意pip install book-to-skill不会自动把/book-to-skill注册到 Claude Code它只装独立提取 CLI。这个差异项目 Changelog 专门说明过。3.3 SKILL.md 模板编译产物里的 SKILL.md 是 Agent 的入口结构建议如下# DDIA Skill ## 核心框架 - 可靠性、可扩展性、可维护性三大目标 - 数据模型关系型、文档型、图型 - 存储引擎B-Tree vs LSM-Tree ## 关键思维模型 - 复制单主、多主、无主 - 分区按 Key 范围、按 Hash - 事务ACID、隔离级别、并发控制 ## 章节索引 - ch01: 可靠性、可扩展性、可维护性 - ch02: 数据模型与查询语言 - ch05: 复制 - ch07: 事务 ## Topic Index - replication - ch05 - partitioning - ch06 - consistency - ch05, ch09 - storage-engine - ch03Agent 启动时只读这份约 4K Token。需要细节时按 Topic Index 去读对应章节。3.4 Claude Code settings 配置Claude Code 的配置放在~/.claude/settings.json把接入三件套填进去{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }如果你用 Cline 的 MCP 模式配置在 Cline 的 settings 里同样是 Base URL、Key、Model ID 三件套。Codex 的话看~/.codex/auth.json{ OPENAI_API_KEY: sk-你的Key, OPENAI_BASE_URL: https://taotoken.net/api }Model ID 要和你实际调用的模型一致填错会报 model not found。填完后重启 Claude Code 让配置生效。4. 验证请求从文档导入到 Agent 调用配置写完跑一遍完整流程验证。假设你要把/data/books/ddia.pdf编译成 Skill。4.1 执行转换在 Claude Code 里执行/book-to-skill /data/books/ddia.pdf ddia第一个参数是源文件第二个是 Skill 名。等它跑完检查产物ls -la ~/.claude/skills/ddia/你应该看到 SKILL.md、chapters/、glossary.md、patterns.md、cheatsheet.md。如果 chapters 是空的说明 PDF 提取失败回去检查 poppler-utils 是否装好。4.2 处理整个文档目录项目文档更适合整目录编译/book-to-skill /data/documents/architecture/ company-architecture这样overview.md、database.md会被合并成一个 SkillAgent 写代码时能直接引用你公司的架构约定。4.3 验证 Agent 调用Skill 生成后直接问/ddia replicationAgent 会先读 SKILL.md 找到 replication 对应的章节再读 ch05-replication.md然后回答。你可以对比一下不加载 Skill 时问同样的问题回答明显更泛加载后它会引用书里的具体模型和权衡。再验证一次模型通道是否正常。如果 Claude Code 能正常返回说明 Base URL 和 Key 配对成功。如果报 401说明 Key 有问题如果报连接失败说明 Base URL 写错了。4.4 检查 Token 消耗在 Claude Code 里观察一次问答的 Token 用量。加载 Skill 后输入 Token 应该稳定在 5K 左右SKILL.md 4K 相关章节 1K而不是整本书的 20 万。这就是按需加载的价值项目性能文档把它叫做降低「Discovery Loop Tax」。5. 本篇常见错排查部署过程中最容易卡在几个地方我按报错类型整理。401 Unauthorized这是模型通道问题不是 book-to-skill 的问题。检查~/.claude/settings.json里的ANTHROPIC_API_KEY是否填对Key 有没有多余空格。如果 Key 是从控制台复制的确认没漏字符。Base URL 必须是https://taotoken.net/api末尾不要加/v1否则路径会变成/api/v1/v1。local proxy failed / connection refused说明 Claude Code 连不上 Base URL。先确认服务器能出网curl -I https://taotoken.net/api如果 curl 也失败是网络层问题如果 curl 成功但 Claude Code 失败检查 settings.json 的 JSON 格式有没有语法错误比如多了逗号。reading choices / model not foundModel ID 填错了。去模型对话页面确认可用的模型标识然后更新 settings.json 里的ANTHROPIC_MODEL。不同工具的 Model ID 字段名不一样Claude Code 用ANTHROPIC_MODELCline 在界面里选Codex 看 auth.json。OAuth 相关报错如果你之前用官方登录方式配过 Claude Code可能残留了 OAuth 凭证和 API Key 模式冲突。清掉旧的凭证缓存确保走的是 Key 模式。Skill 生成了但 Agent 不读检查 Skill 目录名和调用名是否一致。/book-to-skill /data/books/ddia.pdf ddia生成的是~/.claude/skills/ddia/调用时用/ddia。如果目录名是ddia-skill但调用/ddia就找不到。另外确认 SKILL.md 在目录根下不在子目录里。PDF 提取出乱码扫描版 PDF 没有文字层poppler 提取不出来。这种需要先做 OCR或者换 EPUB 版本。技术书尽量用文字版 PDF。转换速度极慢复杂 PDF 解析本来就慢尤其是带表格和多栏排版的。如果只是普通文字书别开最高成本的解析模式。批量转换放服务器上跑别占个人电脑。6. 把 Skill 接入你的日常开发流走到这里你已经有了一个能用的 book-to-skill 环境文档编译成 SkillClaude Code 通过 TaoToken 通道调用模型Agent 按需读取章节。接下来是把它变成日常习惯。我的做法是给每本常用技术书建一个 Skill放在~/.claude/skills/下项目文档按团队维度建 Skill。写代码时直接/ddia replication或/company-architecture apiAgent 就会带着书里的方法论回答而不是泛泛而谈。如果你要长期跑这套环境建议把模型通道固定下来。Coding Plan 适合高频编码场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。Key 管理在控制台https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。接入细节看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。最后提醒两点。一是安全book-to-skill 解析 PDF、EPUB、DOCX 这些格式本质上属于处理不可信文档别用 root 跑别让它读到 SSH 私钥陌生文件放隔离环境处理。二是版权只处理你自己写的、依法购买的、公司授权的或开源许可的文档生成的 Skill 别公开传播受版权保护书籍的大段原文。环境搭好后真正花时间的不是部署而是资料整理和 Skill 的目录设计。把章节切分和 Topic Index 做细Agent 的命中率会明显提升。