book-to-skill 的 AGENTS.md 执行契约解析为 Coding Agent 定义证据驱动的协作流程【免费下载链接】book-to-skillTurn any technical book PDF into a Claude Code skill — ready to study, reference, and use while you work.项目地址: https://gitcode.com/GitHub_Trending/bo/book-to-skill本篇技术指南围绕 AGENTS.md 展开它是 book-to-skill 仓库面向编程 Agentcoding agent的仓库级执行契约repository-wide execution contract规定了项目边界、真理来源、不可协商规则、执行循环、验证门与评估成本纪律。读完本文你将理解如何为「确定性 Python 提取器 规格驱动的 Agent 生成器」这类双半结构项目设计一套可被 Agent 自动执行的开发契约并掌握pytest -q、ruff check .、python3 tools/validate_skill.py SKILL.md等验证门在 pyproject.toml 与 tools/validate_skill.py 中的实际落地方式。一、为什么一个仓库需要执行契约双半结构的协作难题book-to-skill 的使命是把任何技术书籍或文档转换为结构化的、按需加载的 Agent Skill。这个目标决定了它天然由两个截然不同的一半组成见 AGENTS.md 的 Project intent 一节确定性的 Python 提取器入口为 scripts/extract.py其内部只是向后兼容的薄封装shim真正实现位于book_to_skill/包中book_to_skill/cli.py → book_to_skill/utils.py负责把 PDF、EPUB、DOCX、HTML、RTF、纯文本乃至通过 Calibre 转换的 MOBI/AZW 统一抽取为干净的全文文本与元数据规格驱动的生成器即 SKILL.md由 Agent 作为指令执行——按 Step 0 到 Step 11 逐步完成提取 → 成本预估 → 结构分析 → 章节摘要 → 支撑文件 → 主 SKILL.md → 安全扫描 → 发布的完整转换流程。当参与开发的协作者不仅有人类还有可自动读写文件、运行命令、提交 PR 的编码 Agent 时项目方必须用一份明确、紧凑、可执行的文档告诉 Agent项目边界在哪里、先读什么、什么绝对不能做、做完怎么证明。这正是 AGENTS.md 存在的意义。契约第一条就划出红线——不要在没有充分理由的情况下混淆这两半的职责提取器只做确定性文本抽取生成器只做基于规格的结构化生成。二、Sources of truth为改动代码指定最小证据集AGENTS.md 要求 Agent 在改动代码前先读取与改动相关的最小文件集避免在巨大代码库中迷失或凭印象改动文件何时必读在本仓库中的角色CONTRIBUTING.md任何贡献贡献规则与必须通过的检查项docs/architecture.md任何改动当前架构与组件所有权说明SKILL.md涉及生成行为或生成技能结构生成器规格Steps 0–11 Fold-in 工作流SECURITY.md / SECURITY-NOTICE.md涉及解析、文件、子进程、生成内容或依赖安全边界与供应链风险声明距离改动最近的既有测试任何改动行为回归基准其中特别值得注意的是 docs/research/progressive-disclosure-evals.md——这是渐进式披露progressive disclosure研究/评估计划的执行台账execution ledger。它定义了任务顺序、证据门evidence gate并明确区分了论文衍生的想法hypotheses与产品需求product requirements。AGENTS.md 据此规定凡是属于该计划的改动Agent 必须先定位状态为READY且依赖已完成的首个任务而不是自由发挥。三、Non-negotiable rules八条不可协商规则的源码级印证AGENTS.md 用加粗列出的八条规则是契约的宪法其中每一条都能在仓库源码与测试中找到对应实现Measure, do not assert测量而非断言任何声称的质量、token、路由、准确率或成本改进都必须附上可复现的证据。这对应 tools/discovery_tax.py用真实抽取的章节大小建模上下文成本以及 docs/research/progressive-disclosure-evals.md 第 10 节 Claims guardrail 中对尚未证实的说法的封禁清单。不要把论文假设变成生产行为在证据门通过之前禁止仅因为听起来合理就添加KEY_ELEMENTS风格的元数据、库模式library mode、更深层路由或新的 SKILL.md 内容。这一条直接映射到研究计划中的 PD-07路由元数据消融与 PD-12证据评审与生产决策门任何候选生产想法都必须先给出ADOPT / KEEP EXPERIMENTAL / REJECT / INSUFFICIENT EVIDENCE之一的最小证据才能进入产品。保持 SKILL.md 精简它是每次运行都会加载的转换器上下文always-loaded converter context任何净增长都必须用新增上下文是否值回成本的证据来背书。CONTRIBUTING.md 的 Ground rules 也重申了这一点而 docs/architecture.md 则从设计原则上给出理由SKILL.md 体量小、内容前置compaction 从末尾截断章节文件按需加载、只在被读取时才消耗 token。永不提交受版权保护的原始书籍文本必须使用合成、公有领域或明确授权的夹具fixture。仓库中的 evals/fixtures/ 目录只包含pd00-synthetic-book.txt、pd03-book.txt等合成/公有领域样例私有评估语料与原始在线轨迹live trajectories则被明确要求留在 git 之外这正是该规则的落地实例。评估工作避免新增运行时依赖评估专用依赖必须位于核心运行时之外并给出理由。这一点在 pyproject.toml 中清晰可见——核心可选依赖只有html/epub/pdf/docx/rtf/technical/all几组提取器依赖评估相关代码tools/evals/下的 manifest、score、replay、paper_flat完全独立不进入打包入口。不手改 CHANGELOG.mdCONTRIBUTING.md 的 Releases 一节说明它由 Conventional Commit 消息经 git-cliff 在发版时自动生成PR 标题必须是合法的 Conventional Commitfix:、feat:、docs:等CI 会检查标题。除非任务明确授权否则保持向后兼容例如 scripts/extract.py 作为薄 shim 保留正是为了让旧调用方式持续可用book_to_skill/cli.py 中对 stdout/stderr 强制 UTF-8 的reconfigure处理也体现了对旧环境Windows 传统代码页的兼容考量。不削弱安全检查、路径加固、净化或生成技能扫描来让实验通过docs/architecture.md 的 Security 一节列出了分层加固——book_to_skill/sanitize.py剥离零宽字符U200B/200C/200D/2060/FEFF与 Unicode 标签块UE0000–E007FDOCX 解析器拒绝含 DTD/实体的 XML 部件以防范 XXE 与 Billion-Laughs子进程参数注入防护路径在传入pdftotext/pdfinfo/ebook-convert前绝对化以及 tools/scan_generated_skill.py 对生成技能中指令覆盖短语、模型控制标签、残留不可见 Unicode、权限扩张型 frontmatter 与数据外泄形态内容的告警扫描。四、Execution loop六步执行循环禁止从想法直接跳到实现AGENTS.md 明确警告任何非平凡任务都不得从想法直接跳到实现必须遵循六步循环Orient定向——读本文件与相关真理来源在提出新模块或抽象之前先检查现有代码/测试对研究计划类工作先定位状态为READY且依赖已完成的首个任务。研究计划中的任务台账使用READY / BLOCKED / IN_PROGRESS / DONE / REJECTED五种状态PD-04 至 PD-12 目前均因依赖未完成而处于BLOCKEDAgent 必须尊重这一依赖链而非绕行。Plan the smallest coherent change规划最小自洽改动——陈述要解决的假设或缺陷声明什么将保持不变优先复用既有工具而非平行实现在写代码之前先定义验收命令。Implement one task一次实现一个任务——保持 diff 聚焦与实现一同添加确定性测试不顺手重构无关代码。Prove it证明它——运行任务专属检查与仓库验证门必须捕获真实命令输出或机器可读的结果产物——看起来没问题这类散文不是证据。这与工具 tools/evals/ 中离线可重放的 scorer/replay 设计理念一致在消耗模型 token 之前先用确定性夹具证明正确性。Record state记录状态——在研究计划涉及范围内更新任务状态/证据区阻塞项记为阻塞项绝不因为代码写了就标记任务完成。Continue only after the gate is green门变绿才继续——仅在当前任务被证明后才移动到下一个依赖就绪的任务尊重计划中定义的 PR 边界改变生产行为的任务不得与无关的研究基础设施悄悄捆绑。五、Validation gates代码变更的最小本地检查AGENTS.md 规定的代码变更最小本地检查只有两条pytest -q ruff check .它们在 pyproject.toml 中有精确对应testpaths [tests]指定测试发现目录[tool.ruff.lint] select [E9, F]把 lint 门限定为语法错误E9 pyflakes 未定义名/未使用导入F风格类规则刻意不设门。CONTRIBUTING.md 进一步说明 CI 在 PR 上会跑 lint、py3.10–3.13 测试矩阵、smoke、SKILL.md 校验与 PR 标题检查。若SKILL.md 变更还必须追加python3 tools/validate_skill.py SKILL.mdtools/validate_skill.py 是一个多视角校验器它按宿主 lens--lens claude|copilot|amp|hermes审计 SKILL.md 是否符合对应 Agent 平台的技能规则。从源码可见其工具表差异——Claude Code 识别Bash/Read/Write/Glob/Grep等内置工具Copilot CLI 识别shell/bash/write且未知 token 被当作 MCP 服务器名软提示而非报错Amp 接受 Claude 工具集外加shell_command。错误ERROR级问题会使 CI 失败警告WARN级则仅提示。除此之外提取行为变更时还要运行相应的提取器 smoke/复现命令及其针对性测试例如 tests/ 下按格式细分的test_epub_image_reporting.py、test_pdf_page_number_detection.py、test_html_block_boundaries.py等生成技能行为变更时必须提供改动前后的生成产物generated artifact或基准结果且不得提交受版权保护的源文本一条硬性结论是只要要求的检查被跳过、失败或被未经证实的说法替代任务就不能标记为DONE。六、Evaluation-work cost discipline在线模型实验的成本纪律AGENTS.md 单独为评估工作立了一章成本纪律核心前提是在线模型实验昂贵永远不是第一步验证手段。具体顺序被固定为先跑单元/夹具测试先跑少量有判别力的小样本再做大扫描以 source/config/model/prompt 身份为键缓存并复用已生成的技能包在线运行前预先登记条件、语料、问题、模型/测试框架、重复次数与 token/成本上限在更小规模的证据门证明其价值之前不要跳到 10/20 本书的扫描如果更便宜的测试就能证伪假设先跑它。这条纪律在 docs/research/progressive-disclosure-evals.md 第 4 节被细化为可执行规则每次在线运行都必须有一份 pre-run config/manifest至少包含 source/corpus ID 与哈希、condition 名、question set ID 与哈希、模型与 harness、prompt/config 哈希、重复/种子信息、max_calls、max_input_tokens、max_output_tokens、可选max_cost_usd以及这次运行为何必要、能改变什么决策的说明runner 必须在其配置的硬性上限被静默超过时停止而非继续。已完成的 PD-01确定性 manifest 与哈希、PD-02离线轨迹评分器正是为这条纪律提供基础设施证据分别落在 tests/evals/test_manifest.py、tests/evals/test_score.py 与 tests/evals/test_replay.py。七、Instruction scope指令作用域与优先级规则AGENTS.md 最后明确了指令的生效范围与冲突裁决根级AGENTS.md应用于整个仓库更深层嵌套的AGENTS.md可为其子树添加更窄的指令指令冲突时更具体的文件胜出直接的用户/系统指令优先于仓库指引。这一优先级设计在仓库中有完整落地CLAUDE.md 全文只有一行AGENTS.md导入语句用引用而非复制的方式把根契约接入 Claude Code 的项目记忆机制避免规则重复漂移——这与 docs/research/progressive-disclosure-evals.md 第 11 节Agent 指令兼容性中根指令文件保持紧凑详细计划状态放在专门文档里而不是塞进每个 Agent 的常驻上下文的原则完全一致。八、给其他项目作者的借鉴如何复刻这份执行契约从 AGENTS.md 可以提炼出一套可移植的Agent 协作契约模板要素任何由 Agent 参与开发的开源仓库都可参考先声明项目意图与边界一句话说清项目是什么、由哪几部分组成、各自职责是什么、什么情况下不要跨界建立真理来源清单按何时必读组织文件让 Agent 用最小阅读集定位上下文把红线写成不可协商规则证据优先、预算约束、版权约束、安全约束等逐条给出一句话理由固定执行循环定向 → 规划 → 实现 → 证明 → 记录 → 继续阻断直接跳到实现的路径量化验证门给出可复现的命令如pytest -q、ruff check .并规定DONE 的定义——检查被跳过/失败/被替代都不算完成为昂贵资源单列成本纪律凡是消耗模型 token、云资源或时间的操作都要小样本先行、预登记上限、缓存复用明确指令优先级根级 vs 嵌套 vs 用户指令的裁决规则。从源码结构看book-to-skill 甚至为契约的每个环节都配备了独立工具与测试tools/validate_skill.py守护生成规格、tools/discovery_tax.py建模上下文成本、tools/scan_generated_skill.py守护生成内容安全、tests/evals/守护评估基础设施。契约不是写在文档里的口号而是被工具与测试固化下来的可执行流程——这正是这份 AGENTS.md 最值得借鉴的设计取向。【免费下载链接】book-to-skillTurn any technical book PDF into a Claude Code skill — ready to study, reference, and use while you work.项目地址: https://gitcode.com/GitHub_Trending/bo/book-to-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考