Compare two outputs WITHOUT knowing which skill produced them.
## Role
The Blind Comparator judges which output better accomplishes the eval task. You receive two outputs labeled A and B, but you do NOT know which skill produced which. This prevents bias toward a particular skill or approach.
Your judgment is based purely on output quality and task completion.
## Inputs
You receive these parameters in your prompt:
-**output_a_path**: Path to the first output file or directory
-**output_b_path**: Path to the second output file or directory
-**eval_prompt**: The original task/prompt that was executed
-**expectations**: List of expectations to check (optional - may be empty)
## Process
### Step 1: Read Both Outputs
1. Examine output A (file or directory)
2. Examine output B (file or directory)
3. Note the type, structure, and content of each
4. If outputs are directories, examine all relevant files inside
### Step 2: Understand the Task
1. Read the eval_prompt carefully
2. Identify what the task requires:
- What should be produced?
- What qualities matter (accuracy, completeness, format)?
- What would distinguish a good output from a poor one?
### Step 3: Generate Evaluation Rubric
Based on the task, generate a rubric with two dimensions:
Be decisive - ties should be rare. One output is usually better, even if marginally.
### Step 7: Write Comparison Results
Save results to a JSON file at the path specified (or `comparison.json` if not specified).
## Output Format
Write a JSON file with this structure:
```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.",
Evaluate expectations against an execution transcript and outputs.
## Role
The Grader reviews a transcript and output files, then determines whether each expectation passes or fails. Provide clear evidence for each judgment.
You have two jobs: grade the outputs, and critique the evals themselves. A passing grade on a weak assertion is worse than useless — it creates false confidence. When you notice an assertion that's trivially satisfied, or an important outcome that no assertion checks, say so.
## Inputs
You receive these parameters in your prompt:
-**expectations**: List of expectations to evaluate (strings)
-**transcript_path**: Path to the execution transcript (markdown file)
-**outputs_dir**: Directory containing output files from execution
## Process
### Step 1: Read the Transcript
1. Read the transcript file completely
2. Note the eval prompt, execution steps, and final result
3. Identify any issues or errors documented
### Step 2: Examine Output Files
1. List files in outputs_dir
2. Read/examine each file relevant to the expectations. If outputs aren't plain text, use the inspection tools provided in your prompt — don't rely solely on what the transcript says the executor produced.
3. Note contents, structure, and quality
### Step 3: Evaluate Each Assertion
For each expectation:
1.**Search for evidence** in the transcript and outputs
2.**Determine verdict**:
-**PASS**: Clear evidence the expectation is true AND the evidence reflects genuine task completion, not just surface-level compliance
-**FAIL**: No evidence, or evidence contradicts the expectation, or the evidence is superficial (e.g., correct filename but empty/wrong content)
3.**Cite the evidence**: Quote the specific text or describe what you found
### Step 4: Extract and Verify Claims
Beyond the predefined expectations, extract implicit claims from the outputs and verify them:
1.**Extract claims** from the transcript and outputs:
- Factual statements ("The form has 12 fields")
- Process claims ("Used pypdf to fill the form")
- Quality claims ("All fields were filled correctly")
2.**Verify each claim**:
-**Factual claims**: Can be checked against the outputs or external sources
-**Process claims**: Can be verified from the transcript
-**Quality claims**: Evaluate whether the claim is justified
3.**Flag unverifiable claims**: Note claims that cannot be verified with available information
This catches issues that predefined expectations might miss.
### Step 5: Read User Notes
If `{outputs_dir}/user_notes.md` exists:
1. Read it and note any uncertainties or issues flagged by the executor
2. Include relevant concerns in the grading output
3. These may reveal problems even when expectations pass
### Step 6: Critique the Evals
After grading, consider whether the evals themselves could be improved. Only surface suggestions when there's a clear gap.
Good suggestions test meaningful outcomes — assertions that are hard to satisfy without actually doing the work correctly. Think about what makes an assertion *discriminating*: it passes when the skill genuinely succeeds and fails when it doesn't.
Suggestions worth raising:
- An assertion that passed but would also pass for a clearly wrong output (e.g., checking filename existence but not file content)
- An important outcome you observed — good or bad — that no assertion covers at all
- An assertion that can't actually be verified from the available outputs
Keep the bar high. The goal is to flag things the eval author would say "good catch" about, not to nitpick every assertion.
### Step 7: Write Grading Results
Save results to `{outputs_dir}/../grading.json` (sibling to outputs_dir).
## Grading Criteria
**PASS when**:
- The transcript or outputs clearly demonstrate the expectation is true
- Specific evidence can be cited
- The evidence reflects genuine substance, not just surface compliance (e.g., a file exists AND contains correct content, not just the right filename)
**FAIL when**:
- No evidence found for the expectation
- Evidence contradicts the expectation
- The expectation cannot be verified from available information
- The evidence is superficial — the assertion is technically satisfied but the underlying task outcome is wrong or incomplete
- The output appears to meet the assertion by coincidence rather than by actually doing the work
**When uncertain**: The burden of proof to pass is on the expectation.
### Step 8: Read Executor Metrics and Timing
1. If `{outputs_dir}/metrics.json` exists, read it and include in grading output
2. If `{outputs_dir}/../timing.json` exists, read it and include timing data
## Output Format
Write a JSON file with this structure:
```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."
},
{
"text":"The assistant used the skill's OCR script",
"evidence":"Reference section was left blank despite data being available"
}
],
"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 — consider checking it appears as the primary contact with matching phone and email from the input"
},
{
"reason":"No assertion checks whether the extracted phone numbers match the input — I observed incorrect numbers in the output that went uncaught"
}
],
"overall":"Assertions check presence but not correctness. Consider adding content verification."
}
}
```
## Field Descriptions
-**expectations**: Array of graded expectations
-**text**: The original expectation text
-**passed**: Boolean - true if expectation passes
-**evidence**: Specific quote or description supporting the verdict
-**summary**: Aggregate statistics
-**passed**: Count of passed expectations
-**failed**: Count of failed expectations
-**total**: Total expectations evaluated
-**pass_rate**: Fraction passed (0.0 to 1.0)
-**execution_metrics**: Copied from executor's metrics.json (if available)
-**output_chars**: Total character count of output files (proxy for tokens)
-**transcript_chars**: Character count of transcript
-**timing**: Wall clock timing from timing.json (if available)
-**executor_duration_seconds**: Time spent in executor subagent
-**total_duration_seconds**: Total elapsed time for the run
-**claims**: Extracted and verified claims from the output
-**claim**: The statement being verified
-**type**: "factual", "process", or "quality"
-**verified**: Boolean - whether the claim holds
-**evidence**: Supporting or contradicting evidence
-**user_notes_summary**: Issues flagged by the executor
-**uncertainties**: Things the executor wasn't sure about
-**needs_review**: Items requiring human attention
-**workarounds**: Places where the skill didn't work as expected
-**eval_feedback**: Improvement suggestions for the evals (only when warranted)
-**suggestions**: List of concrete suggestions, each with a `reason` and optionally an `assertion` it relates to
-**overall**: Brief assessment — can be "No suggestions, evals look solid" if nothing to flag
## Guidelines
-**Be objective**: Base verdicts on evidence, not assumptions
-**Be specific**: Quote the exact text that supports your verdict
-**Be thorough**: Check both transcript and output files
-**Be consistent**: Apply the same standard to each expectation
-**Explain failures**: Make it clear why evidence was insufficient
-**No partial credit**: Each expectation is pass or fail, not partial
<div class="instructions">Review each output and leave feedback below. Navigate with arrow keys or buttons. When done, copy feedback and paste into Claude Code.</div>
</div>
<div class="progress" id="progress"></div>
</div>
<!-- View tabs (only shown when benchmark data exists) -->
-`errors_encountered`: Number of errors during execution
-`output_chars`: Total character count of output files
-`transcript_chars`: Character count of transcript
---
## timing.json
Wall clock timing for a run. Located at `<run-dir>/timing.json`.
**How to capture:** When a subagent task completes, the task notification includes `total_tokens` and `duration_ms`. Save these immediately — they are not persisted anywhere else and cannot be recovered after the fact.
```json
{
"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
}
```
---
## benchmark.json
Output from Benchmark mode. Located at `benchmarks/<timestamp>/benchmark.json`.
```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"
"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%"
]
}
```
**Fields:**
-`metadata`: Information about the benchmark run
-`skill_name`: Name of the skill
-`timestamp`: When the benchmark was run
-`evals_run`: List of eval names or IDs
-`runs_per_configuration`: Number of runs per config (e.g. 3)
-`runs[]`: Individual run results
-`eval_id`: Numeric eval identifier
-`eval_name`: Human-readable eval name (used as section header in the viewer)
-`configuration`: Must be `"with_skill"` or `"without_skill"` (the viewer uses this exact string for grouping and color coding)
-`run_number`: Integer run number (1, 2, 3...)
-`result`: Nested object with `pass_rate`, `passed`, `total`, `time_seconds`, `tokens`, `errors`
-`run_summary`: Statistical aggregates per configuration
-`with_skill` / `without_skill`: Each contains `pass_rate`, `time_seconds`, `tokens` objects with `mean` and `stddev` fields
-`delta`: Difference strings like `"+0.50"`, `"+13.0"`, `"+1700"`
-`notes`: Freeform observations from the analyzer
**Important:** The viewer reads these field names exactly. Using `config` instead of `configuration`, or putting `pass_rate` at the top level of a run instead of nested under `result`, will cause the viewer to show empty/zero values. Always reference this schema when generating benchmark.json manually.
---
## comparison.json
Output from blind comparator. Located at `<grading-dir>/comparison-N.json`.
```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.",
<strong>Optimizing your skill's description.</strong> This page updates automatically as Claude tests different versions of your skill's description. Each row is an iteration — a new description attempt. The columns show test queries: green checkmarks mean the skill triggered correctly (or correctly didn't trigger), red crosses mean it got it wrong. The "Train" score shows performance on queries used to improve the description; the "Test" score shows performance on held-out queries the optimizer hasn't seen. When it's done, Claude will apply the best-performing description to your skill.
prompt=f"""You are optimizing a skill description for a Claude Code skill called "{skill_name}". A "skill" is sort of like a prompt, but with progressive disclosure -- there's a title and description that Claude sees when deciding whether to use the skill, and then if it does use the skill, it reads the .md file which has lots more details and potentially links to other resources in the skill folder like helper files and scripts and additional documentation or examples.
The description appears in Claude's "available_skills" list. When a user sends a query, Claude decides whether to invoke the skill based solely on the title and on this description. Your goal is to write a description that triggers for relevant queries, and doesn't trigger for irrelevant ones.
Here's the current description:
<current_description>
"{current_description}"
</current_description>
Current scores ({scores_summary}):
<scores_summary>
"""
iffailed_triggers:
prompt+="FAILED TO TRIGGER (should have triggered but didn't):\n"
Skill content (for context on what the skill does):
<skill_content>
{skill_content}
</skill_content>
Based on the failures, write a new and improved description that is more likely to trigger correctly. When I say "based on the failures", it's a bit of a tricky line to walk because we don't want to overfit to the specific cases you're seeing. So what I DON'T want you to do is produce an ever-expanding list of specific queries that this skill should or shouldn't trigger for. Instead, try to generalize from the failures to broader categories of user intent and situations where this skill would be useful or not useful. The reason for this is twofold:
1. Avoid overfitting
2. The list might get loooong and it's injected into ALL queries and there might be a lot of skills, so we don't want to blow too much space on any given description.
Concretely, your description should not be more than about 100-200 words, even if that comes at the cost of accuracy. There is a hard limit of 1024 characters — descriptions over that will be truncated, so stay comfortably under it.
Here are some tips that we've found to work well in writing these descriptions:
- The skill should be phrased in the imperative -- "Use this skill for" rather than "this skill does"
- The skill description should focus on the user's intent, what they are trying to achieve, vs. the implementation details of how the skill works.
- The description competes with other skills for Claude's attention — make it distinctive and immediately recognizable.
- If you're getting lots of failures after repeated attempts, change things up. Try different sentence structures or wordings.
I'd encourage you to be creative and mix up the style in different iterations since you'll have multiple opportunities to try different approaches and we'll just grab the highest-scoring one at the end.
Please respond with only the new description text in <new_description> tags, nothing else."""
