TL;DR
A self-improving agent does not retrain itself. It is a loop of three Claude Code subagents: a generator that does the job, a read-only verifier that grades it against an answer key of real cases, and a coach that proposes one change at a time in a separate file. A slash command runs one round and shows you the scores. You decide what gets promoted. This post gives every file, prompt and setting you need to build it.
There are two ways to make an AI agent better over time. You can retrain the model, which needs training data, GPUs and an evaluation pipeline. Or you can improve what the model reads: its instructions, its context and its tools. The second way needs none of that infrastructure, and in Claude Code everything the model reads is a file you can diff, review and roll back.
This guide builds the second kind. The example is an agent that answers your team’s recurring questions the way you would. The same structure works for any agent whose output you can check: proposal drafts, support replies, data extraction, code review comments.
What you need: Claude Code, a project folder under git, and about twenty real questions with the answers you actually gave. Plan an afternoon for the first version.
How the loop works#
Three agents, each with one job and only the permissions that job needs:
- The generator does the work. It is the agent you actually want to improve.
- The verifier grades the generator’s answers against an answer key. It can read, but cannot change anything.
- The coach reads the verifier’s report and writes a candidate: a copy of the generator with exactly one change. It never touches the live generator, the answer key or the verifier.
A slash command runs them in order, then runs the candidate against the same cases. If the candidate scores higher without breaking anything that used to pass, you promote it with a copy and a commit.
Why three agents and not one? A model grading its own work tends to be overconfident about it. If the verifier could also fix things, it would learn to pass the test instead of doing the job, and its score would stop meaning anything. If the generator edited itself, you would be changing the thing under test while testing it. Separate roles keep each signal honest.
The files you will create#
your-project/
├── .claude/
│ ├── agents/
│ │ ├── clone.md # generator (the live version)
│ │ ├── clone-verifier.md # grades answers, read-only
│ │ └── clone-coach.md # writes candidates
│ ├── commands/
│ │ └── improve-clone.md # runs one improvement round
│ └── settings.json # locks the files that must not change
├── evals/
│ └── answer-key.md # real inputs and approved answers
├── knowledge/ # whatever the generator needs to know
├── candidates/ # proposed versions and their history
└── runs/ # answers and reports from each round
Start Claude Code from the project root. The permission rules in step 5 resolve paths from the folder the session was started in.
Step 1: write the generator#
The generator is a normal Claude Code subagent. The narrower its job, the better it performs and the easier it is to grade. Do not write it from scratch. Let Claude interview you:
Interview me to write a Claude Code subagent at .claude/agents/clone.md.
The agent answers recurring questions from my team the way I would.
Ask one question at a time. Cover: who asks, what they usually ask, where
the answers live (files in knowledge/), my tone and typical length, what I
never say, and when I send people to someone else.
For every rule you write, add a one-line reason. Stop after about fifteen
questions, show me the draft, and write the file only after I approve it.
The reasons matter. A rule with a reason gives the coach something to weigh later. A bare rule only gives it something to delete. A first version might look like this:
---
name: clone
description: Answers recurring team questions about our tools and processes in my voice.
tools: Read, Grep, Glob
model: sonnet
---
You answer questions from my team the way I would. Look things up in
knowledge/ before answering. Never open evals/, runs/ or candidates/.
## Rules
- Answer in at most three sentences.
Reason: people ask in chat between other tasks.
- Point to the exact place in a tool, not to a person.
Reason: the goal is fewer questions sent to me, not more.
- If knowledge/ does not cover it, say so and name who owns the topic.
Reason: a confident wrong answer costs more than "I don't know".
- No greetings or sign-offs.
Reason: I don't use them in internal chat.
The line about evals/ keeps the generator from reading the expected answers. The slash command in step 6 only ever passes it the questions.
Step 2: build the answer key#
The answer key is the most valuable file in the project. Agents and models will change; a set of real inputs with approved outputs keeps telling you whether a change helped. Each case gets an ID, the input, the expected answer, and two short lists that make grading concrete:
# Answer key
## case-001
**Input:** Where do I find the checkout link for a customer?
**Expected:** Admin portal, Customers, open the customer, Billing tab. The
link is at the top under "Payment link".
**Must include:** admin portal; Billing tab
**Must not:** tell them to ask me
## case-002
**Input:** Can we give a client a 20% discount?
**Expected:** Not without approval from sales leadership. Anything above
10% goes through the discount request form in the CRM.
**Must include:** 10% threshold; discount request form
**Must not:** approve it
Seed it from real history, not from imagination. Export or paste the questions your team asked you, with your replies, into a file, then:
Read sources/team-questions.md. It contains questions my team asked me and
the answers I gave. Pick the 20 most common or most important questions
and write evals/answer-key.md in the format of the example below.
Use my actual replies as Expected. Do not invent answers. If my reply is
missing or unclear, write "TODO" and I will fill it in. Propose Must
include and Must not for each case.
<paste the two example cases here>
Then edit every case by hand until each answer reads exactly like you. This is the step people skip, and it is the one that makes everything else work. From now on the key only grows: every time the agent gets something wrong in real use, that question becomes a new case.
Step 3: add the verifier#
The verifier compares answers with the key and explains every failure. It gets read-only tools, so it cannot change anything even by accident. Give it a different, stronger model than the generator, so the two do not share the same blind spots:
---
name: clone-verifier
description: Grades clone answers against evals/answer-key.md. Read-only. Use when asked to grade a run.
tools: Read, Grep, Glob
model: opus
---
You grade answers produced by the clone agent. You never suggest fixes.
You will be given a file with one "## <case ID>" section per answer.
Compare each answer with the matching case in evals/answer-key.md.
A case FAILS if the answer:
- misses anything listed under Must include,
- does anything listed under Must not,
- contradicts the Expected answer, or
- clearly differs from it in tone or length.
Different wording with the same meaning and tone is a PASS.
Return exactly this format:
case-001: PASS
case-002: FAIL | <one sentence: what differs and why it matters>
...
SCORE: <passed>/<total>
The one-sentence reason on each failure is what the coach works from, so ask for it explicitly and keep it short.
Step 4: add the coach#
The coach turns a report into one proposed change. It can read and write files but has no shell, and step 5 blocks it from the files it must not touch:
---
name: clone-coach
description: Proposes one change to the clone agent as a new candidate file. Use after a graded run.
tools: Read, Grep, Glob, Write
model: opus
---
You improve the clone agent by proposing exactly one change.
1. Read the verifier report you are given and candidates/log.md, which
lists every change already tried and its result.
2. Find the most common reason for FAIL. Do not repeat a change the log
shows was already tried and discarded.
3. Copy .claude/agents/clone.md to candidates/clone-<n>.md, where <n> is
the next free number, and make one change: add, edit or remove a
single rule, or one piece of guidance. Keep every rule's reason line.
4. Write candidates/clone-<n>.why.md with three lines: the change, the
failing cases it targets, and what could get worse.
Never edit .claude/agents/, evals/ or runs/.
One change per candidate is the most important rule here. Change eight things at once and you cannot tell which one helped or which one broke a case that used to pass.
Candidates live in candidates/, outside .claude/agents/, so Claude Code never loads an unapproved version as a live agent.
Step 5: lock the boundaries#
Instructions can drift. Permissions do not. Add deny rules to .claude/settings.json so the answer key, the verifier and the live generator cannot be edited by any agent:
{
"permissions": {
"deny": [
"Edit(/evals/answer-key.md)",
"Edit(/.claude/agents/clone-verifier.md)",
"Edit(/.claude/agents/clone.md)"
]
}
}
In project settings a leading / means the folder the session was started in, which is why you start Claude Code from the project root. Edit rules cover all of Claude’s file-editing tools, including Write, and they apply to the main session and to every subagent. That is intended: new answer key cases and promotions are yours to make, in an editor or a terminal.
Know the limit. Deny rules cover Claude’s own file tools, not a script that opens files by itself. That is why the coach has no Bash. Treat these rules as a guard against mistakes, not as a sandbox. I made the same argument about a knowledge base in an earlier post: a rule that matters belongs in a hook or a permission, not in a prompt.
Step 6: write the round command#
A slash command ties the three agents together. Save this as .claude/commands/improve-clone.md:
---
description: Run one improvement round for the clone agent and propose a candidate
---
Run one improvement round for the clone agent. Never edit .claude/agents/
or evals/, and never promote a candidate.
1. Create runs/<YYYY-MM-DD-HHMM>/. Call it RUN.
2. Read evals/answer-key.md and collect each case ID and Input. Ignore
Expected, Must include and Must not.
3. Live run: start a general-purpose subagent. Tell it to read
.claude/agents/clone.md and follow everything below the frontmatter as
its instructions. Give it only the case IDs and inputs. Save its
answers to RUN/live.md, one "## <case ID>" section per case.
4. Ask the clone-verifier subagent to grade RUN/live.md. Save the report
to RUN/live-report.md.
5. If every case passes, stop and report the score.
6. Ask the clone-coach subagent for one candidate, using RUN/live-report.md.
7. Candidate run: repeat steps 3 and 4 with the new candidate file instead
of .claude/agents/clone.md. Save to RUN/candidate.md and
RUN/candidate-report.md.
8. Append one line to candidates/log.md:
date | candidate file | live score | candidate score | change | decision pending
9. Report both scores, the cases the candidate fixed, the cases it broke,
and the change in one sentence. Recommend promote or discard. A
candidate that breaks a case the live version passed is a discard,
even with a higher total.
Running the live file and the candidate the same way, through a general-purpose subagent that follows the file’s instructions, keeps the comparison fair. Both versions see the same inputs and the same harness, and only the instructions differ.
Step 7: run a round and promote#
Type /improve-clone. A round ends with something like:
Live 15/20, candidate 17/20.
Fixed: case-004, case-011. Broke: none.
Change: added "When a question mentions a price, link the current price
list instead of quoting a number."
Recommendation: promote.
Read candidates/clone-<n>.why.md and skim the two answer files. If you agree, promote it yourself:
cp candidates/clone-3.md .claude/agents/clone.md
git add -A && git commit -m "clone: promote candidate 3 (15/20 -> 17/20)"
Then change decision pending to promoted or discarded in the log, so the coach knows next time. With every promotion in git, rolling back a bad improvement is git revert, and the commit history doubles as a record of what changed and why.
Choose how much autonomy the loop gets#
The structure above supports three levels. Pick one on purpose.
Level 1: you notice, Claude fixes the instructions. You need none of the scaffolding. When any skill or agent gets something wrong in a normal session, say:
Based on this conversation, update the skill or agent I used so this
doesn't happen again. Show me the diff before saving.
This works from day one and is enough for most everyday skills. With the loop in place, the equivalent habit is adding the failed question to the answer key.
Level 2: the loop proposes, you approve. This is the setup described in steps 1 to 7, and it is where most knowledge work should stay. The agent improves on evidence, and your judgment stays the final sign-off. My own knowledge base audit works the same way: it finds problems and proposes fixes, and nothing is applied until I approve it.
Level 3: the loop promotes on its own. Remove the Edit(/.claude/agents/clone.md) deny rule and add a second command, .claude/commands/auto-improve-clone.md:
---
description: Run improvement rounds for the clone agent and promote winners automatically
---
Run the round described in .claude/commands/improve-clone.md up to 10
times. After each round, promote the candidate only if it scores higher
and breaks no case the live version passed: copy it over
.claude/agents/clone.md, set its log line to promoted, and commit with
both scores in the message. Otherwise set it to discarded.
Stop when every case passes, when three rounds in a row end in discard,
or after 10 rounds. Report every promotion with its scores.
Always cap the loop. Without a limit it keeps spending tokens on a case it cannot fix. Level 3 earns its place where the check is a hard pass or fail, which in practice means code with tests. If your answer key depends on judgment about tone or completeness, an unattended loop will slowly change the agent in ways you stop understanding, and its behavior gets harder to predict. Stay at level 2 there.
What makes it work#
- The answer key, not the agents. Twenty real cases with approved answers are worth more than a clever coach. Without them the verifier has nothing to grade against and the loop is optimizing for vibes.
- One change per candidate. It is the only way to know what helped.
- Permissions in configuration. The verifier’s tool list and the deny rules do more for trust in the scores than any sentence in a prompt.
- The generator never sees the expected answers. The round command passes inputs only. If the generator can read the key, every score is inflated.
- Every failure becomes a case. The key should grow with real use. A wrong answer in production is not an incident, it is the next test.
Self-improvement here does not mean an agent rewriting itself until it gets smarter. It means a feedback loop you designed, with a clear line between the decisions the agents make and the ones that stay with you.

