Skill Auditor

Skill Auditor:skill 一致性审计(loop engineering 实践)

回答一个问题:这个 skill 宣称的能力,与它实际的表现是否一致? 输出一份逐条声称、证据可追溯的审计报告。

核心架构:确定性骨架 + 一处受控自迭代

本 skill 的可信度不依赖 AI 自觉,依赖结构:

• claims.json 是单一事实源(脊柱):驱动循环、累积证据、投影报告,三个职责一份数据。结构契约见 references/claim-schema.md,开工前先读它。
• AI 只做局部判断(拆声称、构场景、跑任务、判单条状态、写归因);转不转、停不停、状态怎么落、报告怎么出,全部由 scripts/ 下的确定性脚本执行。
• 唯一的自迭代发生在循环体内:claim 的灰区触发下一轮针对性场景,直到灰区清零或撞预算。除此之外任何环节都不迭代——不迭代打磨结论(会漂离证据),不迭代改进被测 skill(那是优化不是验证),不为消灭"无法验证"而反复凑(那是诚实结论)。

铁律(全流程有效,任何阶段不得违反)

1. 任何人不得直接编辑 claims.json。 写入只经 scripts/claims.py;状态与判停只经 scripts/update_states.py;报告只经 scripts/render_report.py。你(主 Agent)也不例外。
2. 一切验证产物只落在 /sandbox/ 内,按轮分子目录。报告与 claims.json 在沙箱外。流程结束用 scripts/cleanup.py 收尾——它默认把关键中间产物整理进 review/ 复盘包(供效果展示与 review),只删冗余沙箱;会先校验报告已落地,顺序不可颠倒。用户事后可用 --purge-all 彻底清空(连 claims.json 与报告)。
3. 终态 claim(confirmed/refuted/unverifiable/blocked)永不重测、永不改判。
4. 不修复、不优化被测 skill。 发现的问题进证据,改进建议只能出现在报告交付后的对话里,绝不回流驱动重跑。
5. 两个硬确认点(interactive 模式)必须真正停下等用户回复,见下文 ⛔ 标记。介绍完就继续跑 = 违规。

工作区

/                  # 建议 /tmp/skill-audit-/ 或用户指定
├── claims.json               # 事实源
├── agent-outputs/round-N/    # 各子Agent 的结构化产出(合并进事实源的中转)
├── report-.md          # 最终交付物
├── sandbox/                  # target/ + deps/ + round-N/,清理时删除
└── review/                   # 清理后保留的复盘包(reasoning/ produced/ inputs/),供效果展示与 review

主流程

执行下列命令前，将 SKILL_DIR 设为当前 skill-auditor/SKILL.md 所在目录； 不要假设当前工作目录就是 skill 目录。

Phase 0:初始化(确定性)

python3 "$SKILL_DIR/scripts/init_workspace.py"  --source  \
    [--mode interactive|auto] [--max-rounds 3] [--max-rounds-per-claim 2]

用户给链接就 clone,给路径就 copy,脚本自动处理并列出文档清单。

Phase 1:claim 抽取 → ⛔ 确认点 1

派子 Agent 按 references/claim-extraction.md 抽取原子声称,产出写入 agent-outputs/claims-extracted.json,然后:

python3 "$SKILL_DIR/scripts/claims.py"  import-claims --file agent-outputs/claims-extracted.json
python3 "$SKILL_DIR/scripts/claims.py"  show

⛔ 硬停(interactive 模式)。 向用户完整展示 claim 清单(含依赖边),明确邀请修改:增/删/改声称、修依赖边、标注不关心的条目,以及注入用户自己关心的场景("我希望它在 XX 场景下能 YY"→ 转成新 claim 加入)。这是全流程杠杆率最高的人工介入点——脊柱在这里定型,后面一切围绕它转。在用户明确回复确认之前,禁止执行 Phase 2 的任何动作。 用户的修改同样经 claims.py 落入事实源(新增走 import-claims,删改可指导用户意图后重新生成抽取文件导入)。

Phase 2:并发取证准备 → ⛔ 确认点 2

同一回合并发派出两个子 Agent(它们互不依赖,串行是浪费):

• 依赖分析,按 references/dependency-analysis.md → agent-outputs/deps.json
• 设计解析,按 references/design-analysis.md → agent-outputs/design-evidence.json + agent-outputs/design-summary.md(设计解析全局只做这一次:skill 文本不会因多跑几轮而变化,重复解析纯属浪费)

回收后合并:

python3 "$SKILL_DIR/scripts/claims.py"  import-design --file agent-outputs/design-evidence.json --summary-file agent-outputs/design-summary.md
python3 "$SKILL_DIR/scripts/claims.py"  set-deps --file 

⛔ 硬停(interactive 模式)。 把 deps.json 的 ask_user 清单交给用户,一次性收齐用户能提供的真实依赖(收到的文件放入 sandbox/deps/);用户提供不了的,告知将按构造说明仿真。依赖收齐后循环内不再打断用户——这次停顿把人的参与压缩在循环之外,循环才配叫自主循环。

Phase 3:自主循环(唯一的自迭代区)

每轮执行以下步骤,循环的继续/退出只看 update_states.py 输出的 DECISION,你不做这个判断:

1. 场景构造:派子 Agent 按 references/scenario-builder.md,传入:轮次 N、全部非终态 claim(含 gray_history)、依赖物料位置、设计解析关注点清单、(回流轮)上轮相关观察。产出经

python3 "$SKILL_DIR/scripts/claims.py" import-scenarios --file ... 合并,并 python3 "$SKILL_DIR/scripts/claims.py" mark-testing --ids 。

1. 沙箱准备(确定性):按各场景 setup,用 bash/脚本铺设 sandbox/round-N/ 与所需 deps 物料。不派 AI 做能用命令完成的事。
2. 实跑:每个场景派一个子 Agent,按 references/runtime-executor.md。场景之间无依赖,同一回合并发派出。 每个实跑 Agent 的输入严格限于:target 路径、该场景的 task/setup/observe、产物目录、targets 的 claim id——绝不把 claim statement 或验证意图传给它(防取证偏向,场景构造已保证 task 文本干净,派发时不要自己加话泄底)。产出经 import-evidence 合并。
3. 状态判定:每条 testing 状态的 claim 派一个子 Agent,按 references/status-judge.md,只传该 claim 的 statement + 全部 runtime 证据(不传 design 证据——判定只看实跑,机制归因在 Phase 4,这是防"设计看衰"污染实证判断的隔离)。可并发。将各判定合并为一个建议数组文件。
4. 状态落定与判停(确定性):

``bash python3 "$SKILL_DIR/scripts/update_states.py" --suggestions agent-outputs/round-N/suggestions.json ``

• DECISION = CONTINUE → 回到步骤 1,进入下一轮
• DECISION = STOP_ALL_TERMINAL / STOP_BUDGET → 退出循环,进 Phase 4

blocked 联动、per-claim 预算、全局预算全部由脚本处理,无需你操心;你只需忠实地把 DECISION 当作唯一的循环控制信号。

Phase 4:汇总归因(一次性,不迭代)

派子 Agent 按 references/attribution.md,传入完整 claims.json,产出经 import-attributions 合并。它解释结论、不修改结论;归因写完不回头打磨。

Phase 5:报告与清理(确定性)

python3 "$SKILL_DIR/scripts/render_report.py"     # claims.json → report-.md,机械投影
python3 "$SKILL_DIR/scripts/cleanup.py"           # 校验报告已落地后,整理 review/ 复盘包,删除冗余沙箱

cleanup.py 默认保留可复盘的关键中间产物:整理出 review/ 复盘包(reasoning/ 审计器各环节推理轨迹、produced/ 被测 skill 逐轮实际产出、inputs/ 实跑喂入的物料),并保留 claims.json 与报告;只删掉冗余的 sandbox/(含体积大且可复得的 target 克隆)。这份复盘包正是"效果展示 / review"的素材来源。

两个可选清理档:

• --lean:只留 claims.json 与报告,过程产物全删(旧行为,不需要复盘时用)。
• --purge-all:连 claims.json 与报告一起删除,工作区清零。供用户在交付后明确指示"全部删掉"时使用。

把报告交付给用户(present_files 或给出路径),并告知复盘包位置 review/ 及"如需彻底清空运行 cleanup.py --purge-all"。报告交付后,若用户想聊"这个 skill 怎么改进",可以基于证据讨论——但那是对话,不是流程的一部分。

子 Agent 调度纪律

子 Agent 没有本会话的任何上下文。每次派发必须显式给全:

• 它该读的指令文件路径(references/ 下对应文件,让它自己读)
• 它的全部输入(数据以文件路径或内联 JSON 给出,不要说"如前所述")
• 它的输出文件路径(约定在 agent-outputs/round-N/ 下)

产出必须是结构化 JSON(格式在各指令文件中已定义),经 claims.py 校验合并——子 Agent 的自由文本汇报只用于你了解进展,不作为证据入库。若某子 Agent 产出不符合格式,重派该 Agent,不要手工替它编数据。

无子 Agent 环境(如 Claude.ai)的降级:各环节由你亲自按对应 references/ 指令顺序执行。此时隔离纪律靠自律维持,最关键的两条:实跑时只按场景 task 执行、只记观察(执行前重读 runtime-executor.md 的取证纪律);状态判定时只对照 statement 与 runtime 证据(不掺入你知道的设计信息)。串行会更慢,流程与规则不变。

模式

• interactive(默认):两个硬确认点,适合单个 skill 的深度评估。确认点 1 的价值(用户校准脊柱 + 注入自己的场景)很大,不要轻易放弃。
• auto:跳过两个确认点,依赖全部走构造。仅当用户明确要求批量/免打扰时使用,并在报告开头注明"未经人工校准 claim 清单,依赖均为仿真构造"。

常见失败模式自检

• 循环转完才发现所有证据都是"跑通了"级别的粗观察 → 场景 observe 写得太泛,回流轮必须尖锐化,参照 scenario-builder.md 的针对性策略。
• 想给一条 claim 补测但它已是终态 → 不行,铁律 3。如果用户对某终态结论有异议,如实告知重新审计需新开工作区。
• 报告生成时脚本报"仍有非终态 claim" → 说明你在 DECISION 非 STOP 时试图出报告,回到 Phase 3。
• 用户在循环中途插话想加声称 → 记下,告知将在本次审计报告交付后作为补充轮说明;不在循环中途改脊柱(会使已有轮次的证据基线失效)。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tlzmw001
• Source: tlzmw001/naiyue-skills
• License: MIT

Install and usage instructions live in the source repository linked above.