Create Custom Grader

Create Custom Grader

Convert team-owned benchmark definitions into runnable SkillEvaluator custom graders and, when needed, native Harbor tasks.

Purpose

Help an agent author valid SkillEvaluator BYOG/BYOT files from a user's benchmark instead of leaving the user with empty grader templates.

When To Use

Use this skill when the user wants to:

• bring an existing benchmark into SkillEvaluator
• turn a rubric into evals/grader.py or evals/grader.sh
• add custom metrics beside the default evaluator metrics
• convert task files such as task.yaml, task.json, pytest checks, or shell verifiers into BYOG or BYOT
• prove a team can run its own benchmark through SkillEvaluator

Do not use this skill for ordinary evals/evals.json authoring when no custom grading logic is needed. Use the normal dataset authoring workflow for that.

Instructions

1. Read the target skill, existing evals/, benchmark prompts, fixtures, and any verifier code.
2. Choose default_plus_custom when custom metrics should complement default evaluator scoring.
3. Choose custom_only only when the user wants the custom grader to own pass/fail semantics.
4. Write or update evals/grader.py or evals/grader.sh, then validate the Harbor contract.

Examples

skillevaluator init-custom-grader <skill-dir> --language python --mode default_plus_custom
skillevaluator tier3 validate <skill-dir>

Prerequisites

• The target skill directory should contain SKILL.md.
• The SkillEvaluator CLI should be available as skillevaluator.
• Full E2E evaluation may need agent credentials, sandbox access, GPU access, or service credentials depending on the benchmark.

Core Choice

Choose one path before writing files:

Default to default_plus_custom unless the user explicitly wants the custom grader to replace the default evaluator metrics.

Workflow

1. Resolve the target skill and benchmark source. Read the target SKILL.md, existing evals/, benchmark prompts, fixtures, rubric, reference solution, tags, and any expected trigger/non-trigger metadata.

2. Map benchmark fields into evaluator inputs. Use benchmark prompts or prompt variants as question entries. Use the target skill as expected_skill. Put each case's required starter files under evals/files/<case-id>/, and declare files: ["evals/files/<case-id>"] on every corresponding eval entry. Do not omit files in a multi-case dataset, because omission intentionally stages the entire shared directory for legacy compatibility. Preserve benchmark-specific rubric text in the entry only when the grader needs to read it.

3. Scaffold the evaluator contract. For generated tasks:

   skillevaluator init-custom-grader <skill-dir> --language python --mode default_plus_custom

   For shell checks:

   skillevaluator init-custom-grader <skill-dir> --language shell --mode default_plus_custom

   For native Harbor tasks:

   skillevaluator init-harbor-task <skill-dir> --case-id <case-id> --with-config

4. Replace scaffold placeholders. The custom grader is real executable logic, not metadata. It must read available evidence, compute numeric scores, and write the evaluator reward contract.

5. Validate before running.

   skillevaluator validate <skill-dir> --harbor-contract

   Fix missing files, invalid Python, missing reward output, and native Harbor ID mismatches before evaluation.

6. Run the deepest practical proof. Prefer a real with-skill/baseline run. If services, credentials, GPU, or cost block full E2E, state exactly what was validated and what was not.

Grader Contract

Python and shell graders run inside the Harbor verifier context. They may read:

• /logs/agent/trajectory.json for agent actions and final answer evidence
• /tests/entry.json for the eval case metadata
• /workspace/input/ for the entry's declared committed fixtures from evals/files/
• /solution/ or other task outputs only when the task environment produces them

They must write:

• /logs/verifier/reward.json
• /logs/verifier/reward.txt with a numeric score from 0.0 to 1.0

Use this reward shape:

{
  "overall": 0.92,
  "custom_metrics": {
    "domain_repair": 1.0,
    "domain_verification": 0.8
  },
  "details": {
    "domain_repair": {
      "score": 1.0,
      "reason": "The solution repaired the required files."
    }
  }
}

In default_plus_custom, default evaluator scoring keeps its overall authoritative and adds the grader's custom_metrics into reports. In custom_only, the grader's overall is the pass/fail reward.

Never emit custom metric names that collide with reserved evaluator fields: security, skill_execution, skill_efficiency, accuracy, goal_accuracy, behavior_check, overall, details, metrics, metric_set, or entry_id.