企业官网建设流程全解析

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 文件串接，它们分属三个层次：

各文件的消费方与字段约束均可在 skill-creator 脚本目录 与 agents 目录 中得到印证。

二、evals.json：skill 测试用例的入口契约

2.1 文件位置与结构

evals.json定义了一个 skill 的评测集，位于 skill 目录下的evals/evals.json。其顶层为skill_name与evals数组：

{ "skill_name": "example-skill", "evals": [ { "id": 1, "prompt": "User's 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.json：Improve 模式下的版本迭代档案

在 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.json：grader 代理的评分产物

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 复制（若存在）。
• claims：grader 额外从输出中提取并核验的隐含声明（事实性factual、过程性process、质量性quality），用于捕捉预设断言遗漏的问题。
• user_notes_summary：executor 标记的问题——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.json：executor 的工具调用统计

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.json：Benchmark 模式的统计汇总契约

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_run（eval 名称或 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"）。
• notes：analyzer 产出的自由文本观察。

关键约束（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} ] } } }

字段说明：

• winner："A"、"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 skill's 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 的诞生顺序为：

1. 起草 skill 后编写evals/evals.json（仅 prompt，断言后补）；
2. 为每个测试用例建立 workspace 目录并写eval_metadata.json（含eval_name、assertions可暂空）；
3. 同一轮次并行 spawn 带 skill 与基线（新 skill 基线为without_skill，改进型为旧版本快照skill-snapshot/）的子代理；
4. 运行期间补写断言到eval_metadata.json与evals.json；
5. 每个子代理完成通知到达时立即写timing.json，executor 自行写outputs/metrics.json；
6. grader 子代理产出grading.json；
7. 运行python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>生成benchmark.json与benchmark.md；
8. analyzer 阅读 benchmark 数据产出notes；
9. 启动 eval-viewer/generate_review.py 供用户评审（--previous-workspace指向上一迭代以展示旧输出与反馈），评审结果落盘feedback.json；
10. 下一迭代按iteration-<N+1>/继续，history.json记录 Improve 模式下的版本演进。

九、实操注意事项与常见陷阱

1. 字段名零容忍：grading.json的 expectations 必须用text/passed/evidence；benchmark.json的配置字段必须叫configuration且取值为with_skill/without_skill，pass_rate必须嵌套在result内。违反任一约定都会导致 viewer 显示空值。
2. timing 数据不可再生：total_tokens与duration_ms只存在于子代理任务通知中，错过即永久丢失，务必在通知到达时立即落盘。
3. eval_name 要有语义：使用描述性名称并同步作为目录名，便于多人协作与多迭代对照；新迭代的eval_metadata.json需要重新生成，不要假设会从上一迭代继承。
4. 断言要能区分 skill 价值：始终检查断言是否"无 skill 也会通过"；grader 的eval_feedback与 analyzer 的 notes 专门用于揪出这类无效断言与高方差 eval。
5. 盲比较的约束：expectation_results仅在提供断言时出现；比较器必须保持盲态，只依据输出质量判定，避免对 skill 来源作任何推断。
6. 无显示环境的处理：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