Skip to main content
skill CX Codex

grill-skill — Claude Code skill: eval design

The grill-skill Claude Code skill helps design an eval for another skill and refine it based on run results. It starts when someone is creating an eval or looking for gaps in an existing one.

MIT ★ 237 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add edonadei/caliper --skill grill-skill -a claude-code
Open on GitHub

What grill-skill does

The skill interviews the user to define what an eval should test, then helps write the spec and refine it through runs. The checks cover whether the skill activates when expected, completes its task, outperforms an agent without it, and holds up after edits.

caliper is required; install it with pipx install caliper-eval if needed. The entry point is /grill-skill [path]: pass a SKILL.md path or let the skill look in the current directory. It asks one question at a time and waits for an answer before moving on.

What it helps with

  • design an eval for a new skill
  • find gaps in an existing eval
  • test whether a skill activates on the right request
  • compare results with a run that excludes the skill

Example prompts for the agent

  • Create an eval for the skill in skills/translator/SKILL.md
  • Find missing tasks in the eval beside SKILL.md
  • Check which failures the current skill eval does not catch

How to install grill-skill

1Skills CLI (Vercel)

npx skills add edonadei/caliper --skill grill-skill -a claude-code

2Manually: put the files in place

~/.claude/skills/grill-skill/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/grill-skill/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about grill-skill

How do I install grill-skill in Claude Code?

Run npx skills add edonadei/caliper --skill grill-skill -a claude-code. The skill file is at ~/.claude/skills/grill-skill/SKILL.md.

What does grill-skill do?

It helps define eval tasks for a skill, write the spec, and refine it using run results. Its checks cover activation, task performance, comparison with a control agent, and behavior after edits.

What does grill-skill need to run?

It requires caliper. Install it with pipx install caliper-eval if it is missing.

Source text

SKILL.md · MIT
---
name: grill-skill
description: Interview the user to decide what a skill's eval should test, then build the spec and iterate until the skill ships. Use when the user wants help designing a skill's eval, has a skill with no eval, or wants to find what an existing eval misses.
allowed-tools: Bash, Read, Write, Edit
---

# Grill Skill

Interview the user to design a skill's eval, then loop run → diagnose → improve until it ships. Requires `caliper` (`pipx install caliper-eval` if missing). Commands, spec skeleton, and task-writing rules: [REFERENCE.md](REFERENCE.md).

An eval answers four questions, and the interview covers each:

- **Fires**: does the agent reach for the skill when it should, and only then? Tested with `activates:` and trigger probes. Fixed in the `description`.
- **Works**: once it fires, does it do the job? Tested with `expect:` / `assert:`. Fixed in the body.
- **Earns**: does it beat the agent without it? Tested against the control: the declared neighbourhood with this skill removed. A task the control passes too is fixed in the task.
- **Holds**: does it stay good across edits? Tested by comparing each new full run against the previous one.

## Entry point

`/grill-skill [path]`: optional path to a `SKILL.md`.

- **Path given**: use it.
- **No path**: look for `SKILL.md` in the cwd; if found, confirm before proceeding, else ask where it is.

## Phase 1 — Understand

Read the `SKILL.md`. Summarize what it does, when it triggers, and what a successful run looks like. Ask the user to confirm your reading. **Wait for confirmation before continuing.**

## Phase 2 — Detect eval mode

Look for `*.eval.yaml` beside the `SKILL.md` (try `<dir-name>.eval.yaml` first).

- **None** → New eval. **Found** → Gap-fill.

Interview one question at a time and wait for each answer. Build every task from the user's answers, and write the spec only after the interview.

### New eval

First offer to mine the user's past sessions for real cases ([REFERENCE.md → Mining past sessions](REFERENCE.md#mining-past-sessions)). They are the user's private history, so read them only after a yes. Each candidate the user keeps opens its question below as a proposed answer to confirm or correct. With a no, or no hits, interview from scratch.

Elicit, one question at a time:

1. **Happy path**: the most common successful use. What did the agent do, and what would confirm it worked?
2. **Edge case**: a tricky-but-valid input that might trip the bare agent.
3. **Adversarial**: what the skill should refuse or avoid.
4. **Neighbours**: which other skills could an agent confuse with this one? For each one the user can point to (a path or a git repo), declare it in `skills:` and add a neighbour probe: a prompt that belongs to the neighbour, with `activates: [<neighbour>]`.

Always propose a silence probe as well: unrelated work, `activates: []`.

Turn each answer into a task: a realistic `prompt` that never names the skill, an observable `expect`, an `assert` when the outcome is checkable, and `activates:` on execution tasks, naming the skill plus any declared skill it delegates to on that task, so the run can tell a `description` failure from a body failure. The harness is single-shot: nobody answers the agent's questions. If the skill asks before acting, the task judges that first turn: `expect:` the question, `assert:` nothing was done yet. Show the proposed YAML and confirm before writing.

Write the spec beside `SKILL.md`, named `<dir-name>.eval.yaml`, with `skills: [./SKILL.md]` and no engine: the backend and model are picked at run time with `--model` / `--judge-model`, so if the SKILL.md targets a non-default agent, tell the user which flag to pass. Then tell the user to commit the spec now, beside `SKILL.md`.

### Gap-fill

Read the existing spec and report its tasks, grouped by the question each answers. Name any question with no task: execution tasks without `activates:`, no trigger probe, no deterministic `assert:`. **Ask what behaviors are missing or under-tested before proposing or writing anything**, even if the user only asked you to inspect it. Past sessions can answer that too: offer to mine them, as in New eval. Sharpen each gap into a task, show it, and confirm before writing it in.

## Whose setup is measured

Runs load the user's own customizations by default (user skills, plugins, rules, settings and connectors; see REFERENCE.md for backend exceptions), which answers "does my skill work in *my* agent?". **Isolate** (`--no-user-customizations`, or `user_customizations: false` in the spec) when comparing backends or models, when the number leaves this machine (shared, published, compared with someone else's run), or when measuring the bare agent: each setup is different, so otherwise part of the delta is the setups. `--ablate` of the user's own skill needs no isolation, since both runs load the same setup.

**Always tell the user which mode ran** and what it loaded, from the report header's `user customizations:` line (absent means isolated), and relay any fix `caliper compare` suggests about it.

## Phase 3 — First run

Validate the spec, then run at `k=1` (commands in [REFERENCE.md](REFERENCE.md)). Show the results. Fix any harness or config error (not a task failure) before moving on. If a run stops with `Not logged in`, ask the user whether to run the login command the error names. With their consent, run it (it opens a browser for them to finish) and rerun; never run it without consent. `hermes model` is an interactive picker, so ask the user to run it in their own terminal instead.

## Phase 4 — Check the tasks need the skill

Before anyone edits the skill, check that the tasks can tell it apart from the control: the declared neighbourhood with this skill removed. Run the control (`--ablate <skill-name>`, or `skill:<skill-name>` if an `mcp:` server shares the name) and a full run, both at `k=3`, then `caliper compare` them. Check activation first: if the skill never fired in the full run, both runs measure the same agent, and the fix is its `description` (Phase 5), not the tasks.

- **The skill fired, and the control scores about as well as the full run**: the task doesn't need the skill, so iterating on the skill against it measures nothing. Sharpen the task with the user (a harder input, the specific rule the skill adds), then re-run both.
- **Full run clearly ahead**: the task measures the skill. Keep it.

Keep the control's results path: in `caliper list <spec-name> --format json`, it's the `path` of the run whose `ablated` names the skill. The skill isn't installed in that run, so editing `SKILL.md` can't move its number: re-diff against it instead of re-running it. Re-run it only when the tasks or the declared skills change.

## Phase 5 — Diagnose and iterate

Read each failing task before suggesting a fix, and say where the fix belongs:

| Signal | Where the fix belongs |
|---|---|
| Run exits `2` (backend misconfigured, unavailable model, failed hook or MCP server, or every attempt unusable) | The environment or the task's hooks, not the skill. Fix and re-run |
| `⊘` unusable attempts (`infra_error`, `timeout`, `judge_error`) | Not the skill: rate limits, auth, or the judge. Fix and re-run |
| `cheat` outcome | The task: it leaks its answer. Tighten the task or `sandbox:` |
| Activation fails: an expected skill didn't fire | That skill's `description` |
| Activation fails: an unexpected skill fired too | The extra skill's `description`, or the overlap between the two |
| Activation fails because one of the user's own skills fired (`skill:` in the report header) | Not the `description` alone: that skill is real competition in their setup. Decide with the user whether to sharpen the description or isolate the run |
| Activation passes, score low | The skill's body |
| The judge's reasoning shows `expect:` was ambiguous | The task's grading: make the criterion observable, or add an `assert:` |
| Full run ≈ control, and the skill fired in the full run | The task (see Phase 4). If it never fired, the `description` |

Suggest one fix at a time, for the cause shared by the most failing tasks, written as a general rule in the skill's own terms.

Then ask whether to iterate or finish.

- **Iterate**: after the user edits their `SKILL.md`, re-run at `k=3` and `caliper compare` it twice: against the previous full run (did the edit hold?) and against the kept control (does it still earn its place?). A skill that got worse can still beat the control. Diagnose again. At k=3 one attempt is a 33-point swing, so confirm a surprising win or loss at k≥5 before acting on it. Loop. If the user would rather have the agent do the editing, and the spec has 8 tasks or more, suggest `hillclimb-skill`.
- **Done**: confirm the full run beats the control on its execution tasks and holds against the previous full run, then remind the user to commit `SKILL.md` and the `.eval.yaml` together.

© edonadei · MIT · edonadei/caliper

Similar skills

SKILL.md skills catalog →
grill-me Matt Pocock grill-me interviews you about a plan or design to expose gaps and sharpen decisions. Use it before implementation starts. CX Codex +1 1,424,476installs grill-with-docs Matt Pocock The grill-with-docs skill interviews you about a plan or design and creates ADRs and a glossary along the way. Use it when decisions need sharper definition. CX Codex +1 1,219,756installs grill JuliusBrussee grill is a Claude Code skill that stress-tests vague feature ideas one question at a time before specification begins. CX Codex +1 816installs w-grill blockmatic-icebox The w-grill Claude Code skill stress-tests a plan or decision by mapping its dependent choices. It asks about decisions whose prerequisites are settled, then waits for confirmation. CX Codex +1 543installs grill-mel gasserane grill-mel — a skill that stress-tests MEL designs before drafting: theories of change, indicator sets, results frameworks. Asks one question at a time, recommends an answer, and pushes back on every untested assumption. CX Codex +1 491installs find-skills vercel-labs find-skills is a Claude Code skill that locates agent skills for a task and helps assess the results. It activates when someone asks for a capability that may already be installable. CX Codex +1 4,400,000installs frontend-design official anthropics The frontend-design skill guides intentional visual design for new interfaces and redesigns. Use it when a generic generated UI is not enough. CX Codex +1 1,025,790installs agent-browser vercel-labs This Claude Code skill automates browser interaction for tasks like navigating sites, filling forms, and testing web apps. It also supports exploratory QA and Electron app automation. CX Codex +1 1,600,000installs

From the same set3

Project sponsors

Companies that keep this analytics open