grader — Claude Code subagent: what it does, how to install
grader assesses agent execution transcripts and generated files against expectations, flags superficial passes, and critiques test assertions.
no license ★ 406 updated 2026-06-25
.claude/agents/grader.mdWhat grader does
The subagent audits task runs by comparing expected outcomes against an execution transcript and generated artifacts. It takes three parameters: a list of assertions, a path to the Markdown log, and an output directory. Instead of trusting what the executor claimed in the transcript, it opens and inspects output files directly. A test fails whenever an artifact exists with hollow or mismatched content, preventing fake passes.
Beyond prewritten checks, grader extracts unstated claims about process, facts, and output quality from the execution log and verifies them against the artifacts. If user_notes.md is present in the output folder, the agent reads executor uncertainties and notes them in the review. All ratings, tool call statistics, and timing benchmarks are saved into grading.json.
The burden of proof stays on the assertion. Absent clear evidence, the verdict defaults to FAIL. The subagent also reviews the eval definitions themselves, pointing out assertions that are too lenient to catch failures.
What it helps with
- score task results against explicit expectations
- catch superficial test passes with invalid contents
- verify implicit factual and process claims from logs
- pinpoint gaps and weak checks in evaluation suites
- generate a structured
grading.jsonreport with timing metrics
Example prompts for the agent
- Review the execution log in
transcript.mdand verify outputs inrun_artifacts/ - Grade this task run against my checklist and write the result to
grading.json - Audit the latest session transcript and suggest improvements for weak eval assertions
How to install grader
Manually: put the files in place
.claude/agents/grader.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/grader.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/grader.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about grader
How do I install grader in Claude Code?
Place the subagent definition into .claude/agents/grader.md within your project repository.
What does grader do?
It checks execution transcripts and generated files against expectations, assigns PASS or FAIL verdicts with evidence, and exports findings to grading.json.
How does grader handle uncertain or superficial results?
The subagent puts the burden of proof on the expectation; if evidence is weak or matches merely by coincidence, it marks the check as FAIL.