Instruction Eval 是一个围绕智能体运行条件做 A/B 对照实验的技能，用于回答一个常被忽略的问题：给 instruction 加几行、往目录里放一份参考文档，真的会改变智能体的行为吗？这些条件通常缺乏验证，即使写下它们的人也不清楚效果。该技能用一次观察替代猜测。
用途 该技能用于验证或证伪关于智能体运行条件是否产生影响的说法。可对比的轴包括 instruction 文本、instruction 指向的参考材料、MCP 工具与权限、hooks、skill 文件等。脚本只看到两个目录，因此所有这些条件都以相同方式处理。实验方向取决于目的：验证新增内容时，baseline 是不含该轴的状态，variant 是含该轴的状态；为删除辩护时则相反，baseline 含轴、variant 不含轴。删除场景更为常见，因为 instruction 只会单向增长，而无效的 instruction 仍会在每次请求中消耗上下文并稀释有效指令的信号。但删除的判断标准是不对称的：不是“没有效果证据就删除”，而是“只有确认删除后不产生失败才删除”，否则小样本下会因噪声误删规则。
主要能力 技能提供运行 A/B 的脚本 run_ab.py 与生成报告的脚本 render_report.py。实验以 claude -p 子进程执行，需要 Claude Code CLI 可用。报告分为脚本自动生成部分与 LLM 撰写部分（insights.json），并在 HTML 中视觉分隔：自动部分包含实验设置（n、模型、两个目录路径）、每个 arm 每次重复的答案文本、指标中位数与差值、运行异常（错误、权限拒绝）；LLM 部分包含你改了什么、关于变化的说法、每个提示词观察到的差异、指标解读、结论。技能强调不要手写脚本产出的内容，因为转录只会引入错误。
使用方式 流程分为四步。第一步设计与构建条件：先选轴，只以用户提到的内容为候选，即使看起来显然也要在第二步确认；根据情境用 git worktree、复制文件到 worktree 或创建临时文件来构建，构建后用 diff -rq <baseline> <variant> 验证，若除目标轴外还有差异则 A/B 不成立；注意 git worktree 只带受版本控制的文件，构建产物或本地获取的参考材料不会跟随；会话启动 hook 若做网络或构建工作会把延迟计入时长，建议两臂统一禁用；“文件不存在”条件不能用空文件伪造，必须真正删除；一次只改一个轴，因为条件之间会相互干扰。接着构建提示词集，JSON 数组包含 id、kind、prompt，至少包含一个 off-target 提示词，提示词要写成真实用户会发出的具体句子，避免“检查配置”这类抽象表述。最后选 n，最少 3，用于决策时 5 以上，绝不用 n=1，因为智能体运行即使在相同条件下变异系数也达数十个百分点。
第二步运行前展示全部内容并取得批准：展示轴（baseline 缺什么、variant 有什么，路径或 file:line）、刻意保持相等的因素、diff -rq 原始输出、完整提示词文本及 on/off-target 标签、n、模型、总运行次数、用户原话中的说法（没有则写“none”）。未经批准不要运行。
第三步运行：使用 python <skill-path>/scripts/run_ab.py --baseline <目录> --variant <目录> --prompts <prompts.json> --work <结果目录> --n <N> --model <当前会话模型 ID>。必须传入当前会话模型 ID，否则子进程会使用用户默认模型，导致结果偏离用户实际体验。运行耗时较长，应在后台执行。
第四步构建报告：先不带 insights 渲染并阅读 HTML 中的答案（python <skill-path>/scripts/render_report.py --work <结果目录>），也可直接读 runs/*.json，但 HTML 将两臂并列更便于对比。阅读后写 insights.json，键均为可选，缺失的会显示为“not written”。arms 必须填写，因为哪一侧持有轴会随目的翻转，没有标签读者无法分辨。最后带 insights 重新渲染。
评分方法按此顺序选择：能用代码计数的用代码（格式合规、特定字符串存在、引用数量、lint 通过等）；需要判断时人工阅读答案（提示词数量少，成本不高，报告本来就为并列阅读设计）；只有在内容多到读不过来时才用 LLM 评分，且应给逐项评分标准而非散文式标准，并以两种呈现顺序各运行一次，因为评分模型偏好第一个答案和更长的答案。人工阅读时要警惕奖励自信错误答案的倾向，看证据而非语气。需要关注的观察点包括：无轴的一臂是说“不知道”还是给出错误答案（这是完全不同的失败）；有轴的一臂是否引用来源；在 off-target 提示词上，有轴的一臂是否做了不必要的搜索；应按哪一侧持有轴来阅读，而不是按 baseline 和 variant 的槽位名。如果观察与原始说法矛盾，应记录下来，有时最大的产出就是发现说法是错的。
指标解读规则 只有三个指标可用于比较：duration、turn count、output tokens。input tokens 和 cost 受 prompt caching 主导，可能与实际工作量反向变动，报告已排除。当范围重叠时不要解读差值，报告会显示每个 arm 的观察最小值和最大值并标记重叠行，重叠意味着差异可能是运行间方差而非效应。不要单独解读某个指标，时长和输出增加是意味着成本更高还是答案更完整，无法仅从数字判断，每行只有结合答案才有意义。不要跨提示词求平均，同一条 instruction 在不同提示词上可能产生相反方向，平均会抵消成虚假的“无差异”。不要预先决定指标应该往哪个方向移动，如果方向与预期矛盾，应作为观察记录。注意“运行异常”警告，当错误或权限拒绝集中在一个 arm 时，这些时间已计入其指标，两臂并不等价。
适用场景与限制 适用于需要验证 instruction、参考材料、MCP 工具权限、hooks 或 skill 文件是否真正改变智能体行为的场景，尤其是为删除无效 instruction 提供依据。限制包括：运行环境需要 Claude Code CLI，若不可用则无法使用；脚本会产生方向性估计而非确定的效应量；n=5 也达不到统计显著性；不在无法使用 Claude Code CLI 的环境运行。