Skip to main content
Agent skill

Agent Self Evaluation

Use after completing any non-trivial task. The agent self-rates its output on 5 axes — accuracy, completeness, clarity, actionability, conciseness — with concrete evidence per criterion. Produces a structured 1-5 scorecard with specific improvement suggestions.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Agent Self Evaluation when an AI agent needs a reusable SKILL.md workflow for this job: Use after completing any non-trivial task. The agent self-rates its output on 5 axes — accuracy, completeness, clarity, actionability, conciseness — with concrete evidence per criterion. Produces a structured 1-5 scorecard with specific improvement suggestions.

When not to use it

Skip Agent Self Evaluation when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/agent-self-evaluation
# Save SKILL.md to ~/.claude/skills/agent-self-evaluation/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/agent-self-evaluation/SKILL.md. For a shared project, commit the folder at .claude/skills/agent-self-evaluation/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Agent Self Evaluation skill for this task: Use Agent Self Evaluation when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

76/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
85/100
Practical detail
76/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Agent Self-Evaluation

After completing a complex task, the agent pauses to rate its own output against a structured 5-axis rubric. This is NOT a pass/fail gate — it's a deliberate reflection step that catches omissions, flags overconfidence, and surface areas for improvement before the user has to.

## When to Activate

- After writing code that spans 3+ files or 50+ lines - After completing a multi-step workflow (implement → test → review) - After a debugging session that involved 3+ attempts - After producing a design document, architecture decision, or written analysis - When the user asks "how good was that?" or "rate yourself" - At the end of any session Stop hook (if configured — see `references/hook-integration.md`)

## Core Concepts

### The 5 Evaluation Axes

| Axis | Question | What it catches | |---|---|---| | **Accuracy** | Are the facts, claims, and outputs correct? | Hallucinations, wrong API names, incorrect syntax, false statements | | **Completeness** | Did it cover everything the user asked for? | Missed edge cases, unhandled error paths, forgotten requirements, skipped subtasks | | **Clarity** | Is the explanation understandable and well-structured? | Confusing explanations, jargon without definition, missing context, rambling | | **Actionability** | Can the user act on the output immediately? | Vague suggestions, missing steps, "you should X" without showing how, no verification path | | **Conciseness** | Did it use the minimum words/tokens needed? | Redundancy, over-explanation, repeating the user's question verbatim, filler content |

### Scoring Scale

``` 5 — Exceptional: no reasonable improvement possible 4 — Good: minor nits only, no substantive gaps 3 — Adequate: meets the request but has a notable weakness on at least one axis 2 — Weak: has a clear gap that affects usability or correctness 1 — Poor: fundamentally misses the request or contains significant errors ```

### The Evidence Rule

Every score below 5 MUST cite specific evidence. A score of 3 cannot just say "could be better" — it must say exactly what is missing or wrong. The mantra: **"Show the gap, don't just name it."**

## Workflow

### Step 1: Collect the Raw Material

Gather what you'll evaluate:

``` - The original user request (read back from conversation) - Your final response/output (the deliverable) - Any tool outputs that verify correctness (test results, exit codes, lint output) - Any user feedback received during the task (corrections, "try again", "that's not right") ```

### Step 2: Score Each Axis Independently

Work through the 5 axes one at a time. For each:

1. Read the axis question 2. Find evidence (or lack of evidence) in the output 3. Assign a score 1-5 4. If score < 5, write a one-sentence improvement note citing the gap

Do NOT average the scores in your head first and then work backwards. Score each axis fresh.

### Step 3: Produce the Evaluation Report

Use the template from `templates/evaluation-report.md`. The report must include:

``` - One-line summary - 5-axis scorecard (score + evidence per axis) - Overall score (simple average, rounded to 1 decimal) - 1-3 specific improvements ranked by impact - Self-check: "Would the user agree with this assessment?" ```

### Step 4: Apply the Improvement

If any axis scored 3 or below:

1. State what you would do differently 2. If the gap is fixable in < 30 seconds (missing link, unclear phrasing), fix it now 3. If the gap requires rework, flag it explicitly: "This axis scored [reason] because [evidence]. Re-running with [specific fix] would likely raise it to [score]."

## Code Examples

### Example: Good Evaluation (Score 4+)

``` Task: Add retry logic to HTTP client

Scorecard: Accuracy: 5 — All API calls correct. Verified: retries use exponential backoff. No hallucinated methods. Completeness: 4 — Covered happy path + 3 error cases. Missing: timeout handling for hung connections. Clarity: 5 — Code comments explain backoff formula. PR description links to incident that motivated this. Actionability:5 — Single merge. No follow-up tasks. Tests pass. Conciseness: 4 — 47 lines total. The retry loop could be extracted into a helper to drop ~8 lines.

Overall: 4.6 — One gap (timeout handling). Fix before merging. ```

### Example: Weak Evaluation (Score 2-3)

``` Task: Add retry logic to HTTP client

Scorecard: Accuracy: 2 — Used urllib3 which doesn't match our httpx-based codebase. Wrong library. Completeness: 3 — Works for GET. POST/PUT not handled (user said "all HTTP requests"). Clarity: 4 — Code is readable. Good variable names. Actionability:2 — "Add tests" mentioned but no test file created. User has to write tests before merging. Conciseness: 3 — 120 lines. The retry config is duplicated in 3 places instead of one shared RetryConfig object.

Overall: 2.8 — Wrong library used. Needs httpx rewrite. Fix accuracy first (switch to httpx), then extend to all HTTP methods, then consolidate config. ```

## Anti-Patterns

### "Everything is a 5"

``` FAIL: Accuracy: 5 — All good. Completeness: 5 — Everything covered. Clarity: 5 — Clear. ```

No evidence cited. This is self-congratulation, not evaluation. A real 5 requires proving there's nothing to improve.

### Over-penalizing for scope creep

``` FAIL: Completeness: 2 — Didn't handle WebSocket connections or gRPC streaming (user didn't ask for these) ```

Only evaluate against what the user actually requested, not what you could have additionally built.

### Using the evaluation to re-litigate

``` FAIL: "As I said earlier, this approach is wrong. Score: 1" ```

The evaluation is about the delivered output, not about re-arguing design decisions that were already made. If the approach was wrong, that should have been caught before delivery.

### Mixing personal preference with objective gaps

``` FAIL: "Score: 3. I don't like Python decorators." ```

"Don't like" is not evidence. Cite a concrete readability, testability, or correctness concern, or leave the score at 4+.

## Best Practices

- **Evaluate the output, not the process.** The user cares about what you delivered, not how many iterations you took. - **One improvement per weak axis.** Don't list 5 things for one axis — pick the highest-impact gap. - **Tie improvements to user impact.** "Missing error handling means the user's API call will crash silently" beats "add error handling." - **Be specific about what 'fixed' looks like.** "Re-run with httpx transport configured for retries" beats "fix the library issue." - **Use tool outputs as evidence.** If tests passed, cite them. If lint is clean, cite it. Don't guess — grep for the proof. - **If you can't find any gaps, try harder.** A perfect score across all 5 axes is rare. Ask: "If I were the user, what would annoy me about this output?"

## Related Skills

- `agent-eval` — Head-to-head comparison of different coding agents on benchmark tasks - `verification-loop` — Systematic verification of outputs against expected results - `security-review` — Security-focused code review checklist

Intended uses

  • Use Agent Self Evaluation when this documented workflow matches the task.

Implementation notes

  • Evaluate the output, not the process. The user cares about what you delivered, not how many iterations you took.
  • One improvement per weak axis. Don't list 5 things for one axis — pick the highest-impact gap.
  • Tie improvements to user impact. "Missing error handling means the user's API call will crash silently" beats "add error handling."
  • Be specific about what 'fixed' looks like. "Re-run with httpx transport configured for retries" beats "fix the library issue."
  • Use tool outputs as evidence. If tests passed, cite them. If lint is clean, cite it. Don't guess — grep for the proof.
  • If you can't find any gaps, try harder. A perfect score across all 5 axes is rare. Ask: "If I were the user, what would annoy me about this output?"

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.