ZeroClaw skill-creator JSON Schema 全解析从 evals 到 benchmark 的完整数据契约【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw导读本文以 ZeroClaw 仓库中 skill-creator 技能的 schema 参考文档.claude/skills/skill-creator/references/schemas.md为核心系统讲解 skill 评测与优化流水线中全部 9 种 JSON 文件的结构、字段语义与存放位置。读完本文你将掌握如何为 skill 编写可执行的 evals、理解 grader/comparator/analyzer 三类 Agent 的产出格式并能手动构造或修复 benchmark.json 等关键数据文件让 eval-viewer 评测查看器 正确渲染结果。一、数据契约全景9 种 JSON 在评测流水线中的角色skill-creator 的评测与迭代流程定义在 SKILL.md围绕起草 skill → 编写测试用例 → 并行运行带 skill 与基线→ 评分 → 聚合基准 → 人工评审 → 改进这一循环展开。整条流水线由 9 种 JSON 文件串接它们分属三个层次JSON 文件生产者存放位置作用evals.json人工/Claudeskill 目录evals/下定义 skill 的测试用例输入与预期eval_metadata.jsonClaude运行前每个 eval 运行目录记录单次 eval 的提示词与断言history.jsonImprove 模式workspace 根目录追踪版本迭代与胜率演进grading.jsongrader 子代理每个运行目录断言逐条打分结果metrics.jsonexecutor 子代理run-dir/outputs/执行过程的工具调用统计timing.jsonClaude收到任务通知时运行目录记录各阶段耗时与 token 数benchmark.jsonaggregate 脚本 / Benchmark 模式benchmarks/timestamp/汇总统计与配置间对比comparison.json盲比较代理grading-dir/comparison-N.json盲评 A/B 输出质量analysis.json事后分析代理grading-dir/剖析胜因并给出改进建议各文件的消费方与字段约束均可在 skill-creator 脚本目录 与 agents 目录 中得到印证。二、evals.jsonskill 测试用例的入口契约2.1 文件位置与结构evals.json定义了一个 skill 的评测集位于 skill 目录下的evals/evals.json。其顶层为skill_name与evals数组{ skill_name: example-skill, evals: [ { id: 1, prompt: Users example prompt, expected_output: Description of expected result, files: [evals/files/sample1.pdf], expectations: [ The output includes X, The skill used script Y ] } ] }2.2 字段语义skill_name必须与 skill 的 frontmatter 中的name字段一致。在 ZeroClaw 仓库中.claude/skills/zeroclaw/evals/evals.json 即为真实示例skill_name为zeroclaw与 .claude/skills/zeroclaw/SKILL.md 的 frontmatter 一致评测内容围绕 store a memory、cron add、SSE 事件监控 等 ZeroClaw 实际 CLI 能力展开。evals[].id唯一整数标识用于在 workspace 中映射eval-ID目录。evals[].prompt要执行的任务提示词。SKILL.md 特别强调测试提示词应当贴近真实用户口吻如how do i make my bot remember my name而不是抽象指令。evals[].expected_output对成功结果的人类可读描述。evals[].files可选输入文件路径列表相对于 skill 根目录。evals[].expectations可验证的断言语句列表。SKILL.md 指出创建 skill 的第一步只写 prompt断言可在运行期间再补——参考 schemas.md 的完整 schema包括后续要添加的 assertions/expectations 字段。需要说明的是实际运行流水线中每个 eval 还会生成独立的eval_metadata.json字段为eval_id、eval_name、prompt、assertions见 SKILL.md 的 Step 1其中eval_name要求用描述性名称如descriptive-name-here而非笼统的 eval-0该名称同时用作目录名。2.3 断言质量原则SKILL.md 与 grader.md 反复强调好的断言必须可客观验证、有区分度。grader 对通过的判定要求证据反映真实任务完成度而非表面合规——例如文件存在且内容正确而不是只有正确文件名。一条检查名字是否出现的断言对一份凭空编造出该名字的文档也会通过属于低质量断言grader 会在eval_feedback中主动指出这类问题。三、history.jsonImprove 模式下的版本迭代档案在 Improve 模式下skill 的改进历史记录在 workspace 根目录的history.json中{ started_at: 2026-01-15T10:30:00Z, skill_name: pdf, current_best: v2, iterations: [ { version: v0, parent: null, expectation_pass_rate: 0.65, grading_result: baseline, is_current_best: false }, { version: v1, parent: v0, expectation_pass_rate: 0.75, grading_result: won, is_current_best: false }, { version: v2, parent: v1, expectation_pass_rate: 0.85, grading_result: won, is_current_best: true } ] }字段含义started_at改进开始时间的 ISO 时间戳。skill_name被改进的 skill 名称。current_best当前最优版本的标识符。iterations[].version版本标识v0,v1, ...。iterations[].parent派生自的父版本。iterations[].expectation_pass_rate评分得到的断言通过率。iterations[].grading_result取值baseline、won、lost或tie表示该版本相对父版本/基线的结果。iterations[].is_current_best是否为当前最优版本。四、grading.jsongrader 代理的评分产物4.1 完整示例grader 子代理工作说明见 agents/grader.md读取执行 transcript 与输出文件对每条断言给出 PASS/FAIL 判定与证据输出到run-dir/grading.json{ expectations: [ { text: The output includes the name John Smith, passed: true, evidence: Found in transcript Step 3: Extracted names: John Smith, Sarah Johnson }, { text: The spreadsheet has a SUM formula in cell B10, passed: false, evidence: No spreadsheet was created. The output was a text file. } ], summary: { passed: 2, failed: 1, total: 3, pass_rate: 0.67 }, execution_metrics: { tool_calls: { Read: 5, Write: 2, Bash: 8 }, total_tool_calls: 15, total_steps: 6, errors_encountered: 0, output_chars: 12450, transcript_chars: 3200 }, timing: { executor_duration_seconds: 165.0, grader_duration_seconds: 26.0, total_duration_seconds: 191.0 }, claims: [ { claim: The form has 12 fillable fields, type: factual, verified: true, evidence: Counted 12 fields in field_info.json } ], user_notes_summary: { uncertainties: [Used 2023 data, may be stale], needs_review: [], workarounds: [Fell back to text overlay for non-fillable fields] }, eval_feedback: { suggestions: [ { assertion: The output includes the name John Smith, reason: A hallucinated document that mentions the name would also pass } ], overall: Assertions check presence but not correctness. } }4.2 字段详解expectations[]逐条评分结果必须使用text、passed、evidence三个字段名。SKILL.md 与 aggregate_benchmark.py第 156–161 行都明确警告若改用name/met/details等变体字段名viewer 将显示空值或零值。aggregate 脚本在发现 expectation 缺少text/passed时还会打印警告。summary聚合统计pass_rate为 0.0–1.0 的小数。execution_metrics从 executor 的 metrics.json 复制若存在其中output_chars与transcript_chars作为 token 消耗的代理指标。timing从 timing.json 复制若存在。claimsgrader 额外从输出中提取并核验的隐含声明事实性factual、过程性process、质量性quality用于捕捉预设断言遗漏的问题。user_notes_summaryexecutor 标记的问题——uncertainties不确定项、needs_review需人工复核、workarounds绕过方案。eval_feedback可选仅当 grader 发现断言本身有明显缺陷时出现包含改进建议与总体评价。grader 的判定标准为有明确证据且证据反映真实任务完成 → PASS无证据、证据矛盾、证据流于表面如仅文件名正确而内容为空→ FAIL举证责任在断言本身burden of proof to pass is on the expectation。五、metrics.json 与 timing.json执行侧的两个轻量数据源5.1 metrics.jsonexecutor 的工具调用统计executor 子代理将执行统计写入run-dir/outputs/metrics.json{ tool_calls: { Read: 5, Write: 2, Bash: 8, Edit: 1, Glob: 2, Grep: 0 }, total_tool_calls: 18, total_steps: 6, files_created: [filled_form.pdf, field_values.json], errors_encountered: 0, output_chars: 12450, transcript_chars: 3200 }字段说明tool_calls按工具类型统计调用次数total_tool_calls为总和total_steps为主要执行步骤数files_created列出产出文件errors_encountered为执行期错误数output_chars/transcript_chars分别为输出文件与 transcript 的字符数。5.2 timing.json必须即时保存的墙钟数据timing.json记录一次运行的墙钟耗时位于run-dir/timing.json。schema 文档给出了一条关键的采集提醒当子代理任务完成时任务通知中携带total_tokens与duration_ms必须立即保存——这两项数据不会持久化到任何其他地方事后无法恢复。SKILL.md 的 Step 3 也强调处理每个通知时立即保存而不是攒批处理。{ total_tokens: 84852, duration_ms: 23332, total_duration_seconds: 23.3, executor_start: 2026-01-15T10:30:00Z, executor_end: 2026-01-15T10:32:45Z, executor_duration_seconds: 165.0, grader_start: 2026-01-15T10:32:46Z, grader_end: 2026-01-15T10:33:12Z, grader_duration_seconds: 26.0 }在聚合阶段aggregate_benchmark.py 会优先读取 grading.json 内嵌的timing.total_duration_seconds若为 0 则回退读取同目录的timing.json第 136–147 行。六、benchmark.jsonBenchmark 模式的统计汇总契约6.1 完整示例与顶层结构benchmark.json是 Benchmark 模式的产出位于benchmarks/timestamp/benchmark.json由 aggregate_benchmark.py 从各 run 的 grading.json 聚合生成{ metadata: { skill_name: pdf, skill_path: /path/to/pdf, executor_model: claude-sonnet-4-20250514, analyzer_model: most-capable-model, timestamp: 2026-01-15T10:30:00Z, evals_run: [1, 2, 3], runs_per_configuration: 3 }, runs: [ { eval_id: 1, eval_name: Ocean, configuration: with_skill, run_number: 1, result: { pass_rate: 0.85, passed: 6, failed: 1, total: 7, time_seconds: 42.5, tokens: 3800, tool_calls: 18, errors: 0 }, expectations: [ {text: ..., passed: true, evidence: ...} ], notes: [ Used 2023 data, may be stale, Fell back to text overlay for non-fillable fields ] } ], run_summary: { with_skill: { pass_rate: {mean: 0.85, stddev: 0.05, min: 0.80, max: 0.90}, time_seconds: {mean: 45.0, stddev: 12.0, min: 32.0, max: 58.0}, tokens: {mean: 3800, stddev: 400, min: 3200, max: 4100} }, without_skill: { pass_rate: {mean: 0.35, stddev: 0.08, min: 0.28, max: 0.45}, time_seconds: {mean: 32.0, stddev: 8.0, min: 24.0, max: 42.0}, tokens: {mean: 2100, stddev: 300, min: 1800, max: 2500} }, delta: { pass_rate: 0.50, time_seconds: 13.0, tokens: 1700 } }, notes: [ Assertion Output is a PDF file passes 100% in both configurations - may not differentiate skill value, Eval 3 shows high variance (50% ± 40%) - may be flaky or model-dependent, Without-skill runs consistently fail on table extraction expectations, Skill adds 13s average execution time but improves pass rate by 50% ] }6.2 字段语义与硬性约束metadata基准运行元信息含skill_name、timestamp、evals_runeval 名称或 ID 列表、runs_per_configuration每配置运行次数如 3。runs[]单次运行结果。eval_id为数值标识eval_name为人类可读名称viewer 用作分区标题configuration必须严格取with_skill或without_skill——viewer 依赖该精确字符串进行分组与配色run_number为整数1, 2, 3...result为嵌套对象含pass_rate、passed、total、time_seconds、tokens、errors。run_summary按配置聚合的统计。with_skill/without_skill各自包含pass_rate、time_seconds、tokens的mean/stddev对象delta为差值字符串如0.50、13.0、1700。notesanalyzer 产出的自由文本观察。关键约束schema 文档原文强调viewer 严格按字段名读取。若将configuration写成config或把pass_rate放到 run 顶层而非result内嵌viewer 会显示空值/零值。手动生成 benchmark.json 时必须逐字对照本 schema。这一约束在 generate_review.py 中也有体现——它把 benchmark 数据整体嵌入生成的 HTML第 270–281 行viewer 模板按约定字段渲染。aggregate 脚本的聚合算法aggregate_benchmark.py 第 176–224 行先按配置收集所有 run 的 pass_rate/time/tokens 列表用样本标准差公式计算mean/stddev/min/max再取前两个配置的均值差生成delta。命令用法为python -m scripts.aggregate_benchmark workspace/iteration-N --skill-name name脚本同时产出benchmark.json与人类可读的benchmark.md含 pass rate、时间、token 的均值 ± 标准差对比表与 delta。七、comparison.json 与 analysis.json盲比较的成对产物7.1 comparison.json盲比较器输出当需要严格验证新版本是否真的更好时可选用盲比较系统见 SKILL.md 的 Advanced: Blind comparison 与 agents/comparator.md把两份输出标为 A/B 交给独立代理不告知哪份来自哪个 skill让其按内容质量与任务完成度判定优劣。结果写入grading-dir/comparison-N.json{ winner: A, reasoning: Output A provides a complete solution with proper formatting and all required fields. Output B is missing the date field and has formatting inconsistencies., rubric: { A: { content: { correctness: 5, completeness: 5, accuracy: 4 }, structure: { organization: 4, formatting: 5, usability: 4 }, content_score: 4.7, structure_score: 4.3, overall_score: 9.0 }, B: { content: { correctness: 3, completeness: 2, accuracy: 3 }, structure: { organization: 3, formatting: 2, usability: 3 }, content_score: 2.7, structure_score: 2.7, overall_score: 5.4 } }, output_quality: { A: { score: 9, strengths: [Complete solution, Well-formatted, All fields present], weaknesses: [Minor style inconsistency in header] }, B: { score: 5, strengths: [Readable output, Correct basic structure], weaknesses: [Missing date field, Formatting inconsistencies, Partial data extraction] } }, expectation_results: { A: { passed: 4, total: 5, pass_rate: 0.80, details: [ {text: Output includes name, passed: true} ] }, B: { passed: 3, total: 5, pass_rate: 0.60, details: [ {text: Output includes name, passed: true} ] } } }字段说明winnerA、B或TIE。比较器要求果断判定——真正等价才允许平局双方都失败时选败得没那么惨的一方。reasoning选择胜者的清晰理由。rubric两维度评分。内容维度correctness/completeness/accuracy与结构维度organization/formatting/usability各 1–5 分content_score/structure_score为维度均分overall_score换算到 1–10 分。output_quality概要质量评估score应与rubric.overall_score一致。expectation_results仅在提供断言时存在无断言则整体省略该字段。断言通过率是次要证据不主导胜负判定。7.2 analysis.json事后剖析胜因比较器定出胜负后agents/analyzer.md 定义的事后分析代理读取双方 skill 与 transcript揭盲并解释为什么赢、输方如何改进输出grading-dir/analysis.json{ comparison_summary: { winner: A, winner_skill: path/to/winner/skill, loser_skill: path/to/loser/skill, comparator_reasoning: Brief summary of why comparator chose winner }, winner_strengths: [ Clear step-by-step instructions for handling multi-page documents, Included validation script that caught formatting errors ], loser_weaknesses: [ Vague instruction process the document appropriately led to inconsistent behavior, No script for validation, agent had to improvise ], instruction_following: { winner: { score: 9, issues: [Minor: skipped optional logging step] }, loser: { score: 6, issues: [ Did not use the skills formatting template, Invented own approach instead of following step 3 ] } }, improvement_suggestions: [ { priority: high, category: instructions, suggestion: Replace process the document appropriately with explicit steps, expected_impact: Would eliminate ambiguity that caused inconsistent behavior } ], transcript_insights: { winner_execution_pattern: Read skill - Followed 5-step process - Used validation script, loser_execution_pattern: Read skill - Unclear on approach - Tried 3 different methods } }字段要点improvement_suggestions中的priority分high/medium/low三级high 表示很可能改变本次比较结果category使用固定枚举instructions指令措辞、tools脚本/模板、examples示例、error_handling失败处理、structure内容重组、references外部文档。instruction_following对双方各给 1–10 分并列出具体偏差。7.3 Benchmark 场景下的 analyzer 变体analyzer.md 还定义了另一种角色分析 benchmark 结果而非比较两版 skill。此时其产出是JSON 字符串数组notes聚焦聚合统计无法呈现的模式——如某断言在两种配置下都 100% 通过可能无法区分 skill 价值某个 eval 方差极高可能不稳定skill 增加 13 秒平均耗时但提升 50% 通过率等。这些 notes 正是 benchmark.json 顶层notes数组的内容来源。八、Schema 的代码级印证与工作流串联8.1 消费方代码印证以上 Schema 并非纸面约定均可从仓库代码得到印证evals.json 触发评测scripts/run_eval.py 读取--eval-set指定的 JSON结构为[{ query: ..., should_trigger: ... }]通过ProcessPoolExecutor并行调用claude -p检测 skill 描述是否触发统计trigger_rate输出含results与summary的 JSON——这是 Description Optimization 阶段SKILL.md 的run_loop.py流程的核心数据源。grading.json 聚合scripts/aggregate_benchmark.py 逐目录读取eval-*/config/run-*/grading.json提取summary.pass_rate、内嵌timing、execution_metrics、expectations校验text/passed字段存在与user_notes_summary再聚合为benchmark.json与benchmark.md。grading.json / benchmark.json 渲染eval-viewer/generate_review.py 递归扫描 workspace 中带outputs/的目录构建 run 列表加载同目录或父目录的eval_metadata.json取其prompt/eval_id与grading.json并将--benchmark指向的 benchmark.json 一并嵌入自包含 HTML供 viewer.html 渲染Outputs与Benchmark两个标签页用户提交的评审意见通过/api/feedback写入feedback.json。SKILL.md frontmatter 解析scripts/utils.py 的parse_skill_md()负责解析name/description含 YAML 多行块标量|/等run_eval.py 正是用解析出的描述作为被测对象。8.2 端到端工作流中 JSON 的出现顺序综合 SKILL.md 的步骤说明一个典型迭代中这些 JSON 的诞生顺序为起草 skill 后编写evals/evals.json仅 prompt断言后补为每个测试用例建立 workspace 目录并写eval_metadata.json含eval_name、assertions可暂空同一轮次并行 spawn 带 skill 与基线新 skill 基线为without_skill改进型为旧版本快照skill-snapshot/的子代理运行期间补写断言到eval_metadata.json与evals.json每个子代理完成通知到达时立即写timing.jsonexecutor 自行写outputs/metrics.jsongrader 子代理产出grading.json运行python -m scripts.aggregate_benchmark workspace/iteration-N --skill-name name生成benchmark.json与benchmark.mdanalyzer 阅读 benchmark 数据产出notes启动 eval-viewer/generate_review.py 供用户评审--previous-workspace指向上一迭代以展示旧输出与反馈评审结果落盘feedback.json下一迭代按iteration-N1/继续history.json记录 Improve 模式下的版本演进。九、实操注意事项与常见陷阱字段名零容忍grading.json的 expectations 必须用text/passed/evidencebenchmark.json的配置字段必须叫configuration且取值为with_skill/without_skillpass_rate必须嵌套在result内。违反任一约定都会导致 viewer 显示空值。timing 数据不可再生total_tokens与duration_ms只存在于子代理任务通知中错过即永久丢失务必在通知到达时立即落盘。eval_name 要有语义使用描述性名称并同步作为目录名便于多人协作与多迭代对照新迭代的eval_metadata.json需要重新生成不要假设会从上一迭代继承。断言要能区分 skill 价值始终检查断言是否无 skill 也会通过grader 的eval_feedback与 analyzer 的 notes 专门用于揪出这类无效断言与高方差 eval。盲比较的约束expectation_results仅在提供断言时出现比较器必须保持盲态只依据输出质量判定避免对 skill 来源作任何推断。无显示环境的处理Cowork/headless 环境下用--static output_path生成独立 HTML 文件替代浏览器服务评审反馈通过下载的feedback.json回传再复制进 workspace 供下一迭代使用。以上约定共同构成了 skill-creator 的可复现评测体系所有评判都有结构化 JSON 落盘、所有聚合都有脚本保证一致性、所有字段都有 viewer 消费方强制校验。在 ZeroClaw 仓库中.claude/skills/zeroclaw/evals/evals.json 正是这套契约在真实 skill 上的落地范例——为 ZeroClaw 自身的 CLI 技能记忆存储、定时任务、SSE 监控编写评测集时可直接参照本文的字段语义与质量原则。【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考