技能介绍

要解决什么问题

Agent 技能通常需要把长文档里的可检索知识和原始材料一起打包，而不是把整本书塞进 SKILL.md。Book2Skill 面向「多格式源文件 → 单一可移植技能包」这条流水线：输入放在任务目录的 input/，输出是带 JSONL 索引、规范化 Markdown 与资源的 zip，供后续 Agent 通过文件操作按需读取。

工作方式

技能在创建与更新两种模式间切换。创建模式处理全部上传文档；更新模式在系统明确给出既有 zip 与不可改名的技能名时，只转换新文档，并从已校验包中复用既有 Markdown 与资源，再重建完整索引。

核心步骤由 bundled 脚本驱动，模型侧按顺序配合：

准备与分块：prepare 将 .txt / .md / .docx / .pdf 转为规范化 Markdown；PDF 可提取文本，无文本页在本地路径下按页落成图片。分块保留标题上下文，单块上限 5000 Unicode 字符；纯图且无可用证据文本的段落单独成块，不进入模型批处理。
分批 grounded 索引：迭代器按批暴露 u001、u002 等源单元 ID；模型只写基于证据的索引片段，不得臆造正文。校验失败时在同一 pending 批次上重写 part_path。
合并与元数据：merge 产出 doc-index.jsonl；再依据有界的 outline 写 skill-metadata.json（见 references/metadata.md），避免把全量 chunk 重新载入上下文。
打包：build 校验 zip 内须含 SKILL.md、agents/openai.yaml、索引、源 Markdown、检索脚本及引用资源。

系统提示启用在线 OCR 时，准备阶段追加 --online-ocr，且仅对新上传 PDF 走 API；更新模式下历史 PDF 不会重复提交。

边界与注意点

不安装依赖包、不调用视觉模型、不依赖应用框架代码；脚本用 python3 在技能目录内原路径执行 /scripts/...，勿复制或猜测绝对路径。
工作流产物（如 chunks/、chunks.jsonl）为私有中间态；除迭代器与脚本报错诊断外，不要用文件工具逐块「翻仓库」。
图像页在生成阶段不做内容解读，只 deterministic 合并进索引结构，留给生成后的技能自行打开查看。