grade-iterate

Build bounded grade-iterate loops with rubric-based outcome payloads and verdict-driven next moves.

25.3k|3.6k|Updated Oct 19, 2025
One-click install
npx skills add https://github.com/alirezarezvani/claude-skills --skill grade-iterate
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: grade-iterate
Source: https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/skills/grade-iterate
Command: npx skills add https://github.com/alirezarezvani/claude-skills --skill grade-iterate

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Iterating an AI agent until its output is good enough often becomes an unbounded, subjective loop with no clear stopping criteria. This Skill structures that process for Claude Managed Agents by requiring a markdown rubric, clamping iteration budgets, reading grader verdicts, and validating generalization with held-back eval cases.

Core Features & Use Cases

  • Outcome Payload Builder: Generates a user.define_outcome JSON payload with a required rubric and max_iterations clamped to 1..20, sourced from a build sheet or command-line arguments.
  • Verdict Reader: Parses grader results and recommends the next move — SHIP, SHARPEN, ESCALATE, or RESUME — with budget-aware advice when one iteration remains.
  • Held-Back Eval Scaffold: Creates parallel eval run plans (capped at the 25-thread CMA ceiling) using cases the agent never saw during iteration.
  • Use Case: After launching an email-labeling agent, define a rubric (one label per email, grounded reasons, urgent precision), run up to 5 graded iterations, then validate the passing version against 3 held-back cases before shipping v0.

Quick Start

Run outcome_builder.py against my build sheet with a rubric and 5 max iterations, then use verdict_reader.py on each grader result to decide whether to sharpen, ship, or escalate.

Frequently Asked Questions about grade-iterate

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I grade an AI agent's output against a rubric?

Define a markdown rubric with 3-5 checkable criteria and build a user.define_outcome payload using outcome_builder.py. The CMA outcome primitive grades each attempt in an isolated context and returns a verdict per rubric line.

How many iterations should an agent improvement loop run?

The recommended range is 3 to 5 iterations, with a hard clamp between 1 and 20 enforced by outcome_builder.py. Unbounded loops are not allowed; if the cap is reached without convergence, the run escalates for re-scoping.

What should I do when a grader verdict says needs_revision?

A needs_revision verdict means SHARPEN: fix the failing rubric lines in the prompt, tools, or inputs, then re-run. If only one iteration remains, make the single highest-value fix or escalate rather than waste the budget.

Why use held-back eval cases after an agent passes the rubric?

Held-back cases test generalization on inputs the agent never saw during iteration, preventing overfitting to the training loop. Each case runs as an independent session graded against the same rubric, with concurrency capped at 25 threads.

Does this skill require external Python packages?

No, all three scripts are stdlib-only and make no network calls. They read and write local JSON files such as build sheets, outcome payloads, and verdict results.