调试 skill¶
本页最后更新于 ，内容可能过时
用一个子 agent 真实跑一遍待调试的 skill
把它的歧义与绕弯收集起来, 据此改 skill
适用前提: 待调试的 skill 已经写完, 需要找的是它在真实任务里暴露的问题
给子 agent 的约束¶
启动前把这些写进提示词, 缺一条结果就不可用
- 只跑指定的任务, 不读仓库里已有的成品作参考
- 不用
git log,git show,git checkout取历史里的旧产物 - 不改
.claude/skills/下的文件, 发现问题只上报 - 输出目录另建, 不写进正式目录
- 中间产物放
%TEMP%下 - 外部服务的写操作 (例如图床上传) 允许真做, 便于验证
再给一份参考范例
范例是同类的已完成产物, 不是本次的输出
范例让子 agent 在 skill 没覆盖的地方有参考, 也让它的选择有可比的对象
流程¶
- 起一个子 agent, 把任务与上面的约束写进提示词
- 子 agent 报告它遇到的歧义与错误
- 主线程核对它报的问题
- 汇总成记录, 写进仓库根的
skill-bug.md - 抽子 agent 的思考过程, 也写进
skill-bug.md - 按记录逐条修 skill
- 复查全部 skill 的文风与做法
- 清理测试产物
第 3 步不能省
子 agent 报的问题里有相当一部分是它自己的操作失误, 例如路径拼错, 变量拼错
先自己复现一次, 复现得到的才写进记录
误判写进记录, 后面的修改会照着错的改
抽取思考过程¶
子 agent 的记录落在会话目录里
<仓库路径键> 由仓库绝对路径生成, 本仓库是 C--Users-16770-Desktop-Mind-City
<会话 id> 取时间最新的一个, 就是当前这次会话的目录
两处容易出错的细节
- 文件很大, 因为渲染过的图片按 base64 内联在里面, 可达数十 MB
%TEMP%\claude\<会话>\tasks\*.output是 0 字节的占位文件, 不是记录, 不要去那里找
抽取做法
- 先打印一两条记录看结构, 字段名随版本会变
- 再写脚本按结构抽, 每条 thinking 与说明取开头约 120 到 150 字
- 工具调用只记工具名与参数开头, 带图片的结果整条跳过, 否则会把 base64 写进上下文
- 结果写进
%TEMP%\subagent-<分段>.txt, 再 Read 这个文件 - 不要直接把 jsonl 读进上下文, 也不要指望控制台能打印中文
按条目区间分段, 一次抽一段, 分多次抽完
覆盖情况要写进记录
哪部分抽了, 哪部分没抽, 结论的可信度取决于这个
记录文件的格式¶
固定写在仓库根 skill-bug.md, 收尾时删
- 测试环境: 输入的源文件, 输出目录, 参考范例, 临时目录, 给子 agent 的约束
- 覆盖说明: 思考过程抽了多少, 有多少工具结果与图片没看
- 过程重建: 产物的时间线, 以及子 agent 自述的关键决策点
- 绕弯清单: 逐环节对照
照 skill 就能做的与它自己想的 - 问题清单: 按严重程度分组, 每条写清涉及哪个文件的哪一行
- 主线程的误判: 核对后被推翻的判断, 单独记一节, 不要留在问题清单里
- 已修: 编号, 改在哪, 做法
- 清理清单: 收尾要删的东西
修 bug 的取舍¶
改之前先分类
- 不同 agent 会给出不同答案, 且答案本身无优劣的: 写死一个
- 有客观判据的: 写判据, 参数留给 agent 自己选
- skill 的默认做法本身是错的: 优先改, 这类影响最大, 子 agent 要先失败再推翻
收尾¶
复查全部 skill, 两项一起过
- 文风: 全角标点, 术语是否统一, 口语化用词, 行尾终止符
- 做法: 各处写的方法是否互相矛盾, 有没有与本次结论冲突的旧描述
清理这些
- 测试用的输出目录
%TEMP%下的中间产物与抽取文件- 图床上传过的对象
skill-bug.md本身
注意事项¶
- 核对环节要假定子 agent 会犯错, 它的自述可信, 它得出的结论不一定可信
- 抽取是分段的, 一次抽完上下文会超限
- 涉及的路径含
[ ] ( )和中文时加引号