---
name: create-custom-grader
description: Use when converting an existing benchmark, rubric, verifier, task YAML/JSON, or domain check into SkillEvaluator BYOG/BYOT custom evaluation.
metadata:
  author: SkillEvaluator Maintainers <maintainers@example.com>
title: create-custom-grader
canonical_url: https://skilld.dev/gh/nvidia/skillevaluator/create-custom-grader
last_updated: 2026-11-17T20:01:40.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [evals/evals.json](https://skilld.dev/api/skills-raw/nvidia/skillevaluator/create-custom-grader/evals/evals.json), [evals/files/create-custom-grader-001/benchmark/code/fixtures/orders.csv](https://skilld.dev/api/skills-raw/nvidia/skillevaluator/create-custom-grader/evals/files/create-custom-grader-001/benchmark/code/fixtures/orders.csv), [evals/files/create-custom-grader-001/benchmark/code/totals.py](https://skilld.dev/api/skills-raw/nvidia/skillevaluator/create-custom-grader/evals/files/create-custom-grader-001/benchmark/code/totals.py), [evals/files/create-custom-grader-001/benchmark/prompts/direct.md](https://skilld.dev/api/skills-raw/nvidia/skillevaluator/create-custom-grader/evals/files/create-custom-grader-001/benchmark/prompts/direct.md), [evals/files/create-custom-grader-001/benchmark/prompts/vague.md](https://skilld.dev/api/skills-raw/nvidia/skillevaluator/create-custom-grader/evals/files/create-custom-grader-001/benchmark/prompts/vague.md), [evals/files/create-custom-grader-001/benchmark/rubric.md](https://skilld.dev/api/skills-raw/nvidia/skillevaluator/create-custom-grader/evals/files/create-custom-grader-001/benchmark/rubric.md), [evals/files/create-custom-grader-001/benchmark/task.yaml](https://skilld.dev/api/skills-raw/nvidia/skillevaluator/create-custom-grader/evals/files/create-custom-grader-001/benchmark/task.yaml), [evals/files/create-custom-grader-002/csv-summary/evals/evals.json](https://skilld.dev/api/skills-raw/nvidia/skillevaluator/create-custom-grader/evals/files/create-custom-grader-002/csv-summary/evals/evals.json), [evals/files/create-custom-grader-002/csv-summary/evals/files/sales.csv](https://skilld.dev/api/skills-raw/nvidia/skillevaluator/create-custom-grader/evals/files/create-custom-grader-002/csv-summary/evals/files/sales.csv), [evals/files/create-custom-grader-002/csv-summary/scripts/summarize.py](https://skilld.dev/api/skills-raw/nvidia/skillevaluator/create-custom-grader/evals/files/create-custom-grader-002/csv-summary/scripts/summarize.py).
>
> If the user asked to install this Skill, run `npx skilld install nvidia/skillevaluator/create-custom-grader`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/create-custom-grader`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/nvidia/skillevaluator/create-custom-grader) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/create-custom-grader`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/create-custom-grader --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/create-custom-grader --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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

```bash
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:

| User need | Evaluator shape |
| --- | --- |
| Existing `evals/evals.json` task plus extra domain checks | Top-level BYOG: `evals/grader.py` or `evals/grader.sh` |
| Existing benchmark prompt/rubric that can run in the generated workspace | Top-level BYOG plus `evals/evals.json` and `evals/files/` |
| Benchmark owns task layout, setup, service lifecycle, or verifier harness | Native BYOT/BYOG: `evals/harbor/<case>/...` |
| User wants only custom reward/pass criteria | `grading.mode: custom_only` |
| User wants default evaluator dimensions plus custom metrics | `grading.mode: default_plus_custom` |

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:
   ```bash
   skillevaluator init-custom-grader <skill-dir> --language python --mode default_plus_custom
   ```
   For shell checks:
   ```bash
   skillevaluator init-custom-grader <skill-dir> --language shell --mode default_plus_custom
   ```
   For native Harbor tasks:
   ```bash
   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.
   ```bash
   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:

```json
{
  "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`.

## Translation Rules

- Convert each rubric item into a deterministic check when possible.
- If a rubric item requires judgment, encode observable proxies and explain the
  limits in `details`.
- Keep metrics stable across baseline and with-skill runs.
- Score only the generated task workspace. Do not accidentally score copied
  skill source files, reference fixtures, or grader templates.
- Keep custom metric values clamped to `0.0` through `1.0`.
- Preserve benchmark prompt variants as separate eval entries only when they
  exercise meaningfully different behavior.
- Convert expected trigger/non-trigger metadata into `expected_skill`,
  `expected_behavior`, negative cases, or custom metrics that inspect
  trajectory evidence.

## RAPIDS-Style Example

For a benchmark task with `task.yaml`, `code/`, prompt variants, coverage, and a
rubric:

1. Copy `code/` into `evals/files/<case-id>/`.
2. Create one or more `evals/evals.json` entries from the prompt variants, and
   set `files: ["evals/files/<case-id>"]` on each corresponding entry.
3. Set `expected_skill` to the benchmark's target skill.
4. Implement `evals/grader.py` to inspect the agent trajectory and changed
   workspace files.
5. Emit custom metrics for each rubric criterion, for example
   `rapids_diagnosis`, `rapids_requirements_repair`,
   `rapids_repair_safety`, and `rapids_verification`.
6. Validate and run SkillEvaluator with and without the target skill, then
   report both default evaluator metrics and custom metric deltas.

## Limitations

- The skill can design and implement deterministic checks, but ambiguous rubric
  judgment still needs explicit observable proxies or a human-approved scoring
  policy.
- `init-custom-grader` creates scaffolding only; the agent must replace the
  placeholder scoring logic.
- Local validation proves file contracts, not live agent behavior. Do not call
  the benchmark proven until an evaluation run has produced real rewards.

## Troubleshooting

| Problem | Fix |
| --- | --- |
| `evals/evals.json` missing | Create entries from the benchmark prompt or run `init-custom-grader` to seed one. |
| Custom metrics do not appear | Ensure `reward.json` has numeric values under `custom_metrics` and no reserved-name collisions. |
| `custom_only` fails | Write numeric `overall` in `reward.json` or numeric `reward.txt`. |
| Grader scores copied fixtures | Restrict file searches to generated workspace/output paths, not the skill package or grader source. |

## Final Response

When finished, report:

- files created or changed
- exact validation and evaluation commands
- default evaluator metric results
- custom metric results
- whether the proof was full E2E or only static/local validation
- any benchmark rubric criteria that remain partly judgment-based
