How to use the Self-Improve Code Loop agent skill

What is an agent skill and what does self-improve do?

An agent skill is a folder containing a SKILL.md file and supporting files that an AI agent reads when a task matches the skill's description. The skill tells the agent how to carry out a specific kind of work.

The self-improve skill is an autonomous evolutionary code improvement engine with tournament selection. The agent acts as a loop controller that manages setup, research, planning, execution, tournament selection, history recording, visualization, and stop-condition evaluation. It delegates work to specialized oh-my-claudecode agents: a researcher, planner, architect, critic, executor, and git-master.

• Sets a goal (objective, target metric, scope) and a benchmark command.
• Runs research and planning rounds, then has agents implement candidate changes.
• Runs the benchmark on each candidate and keeps the best-scoring changes.
• Records iteration history, candidate scores and progress, and generates a progress chart when Python matplotlib is available.

What you need before installing

The skill lists its requirements in its documentation. Check these before you start.

The skill is built for the oh-my-claudecode agent framework and needs its planner, architect, critic, executor and git-master agents. Your target project must be a git repository.

• Python 3, with matplotlib optional for the progress chart (a text summary is used otherwise).
• Node.js, to run resolve-paths.mjs.
• jq, used by validate.sh.
• A git repository for the project you want to improve.
• The oh-my-claudecode framework and its planner, architect, critic, executor and git-master agents.
• Network access: the skill is marked as using the network, and it runs scripts.

Install the self-improve skill

Download the self-improve ZIP from this page and unzip it. You can install it for yourself or for a single project.

For a personal install, unzip the skill into ~/.claude/skills/. For a project-only install, unzip it into the project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

• Personal: place the skill folder in ~/.claude/skills/.
• Project: place the skill folder in the project's .claude/skills/ folder.
• Claude apps: upload the ZIP under Settings → Capabilities → Skills.

Trigger the skill with a natural request

You do not need a special command. Describe the goal in plain language and name the repository. The skill's description covers autonomous, evolutionary code improvement with tournament selection, so requests about automatically tuning a codebase against a metric are the right kind of request.

During setup the agent will ask you for the repository path if it is not configured, and it will ask you to confirm the trust decision and the benchmark command before the loop starts.

• "Use the self-improve skill to speed up the test suite in this repo."
• "Run a self-improvement loop on this project to raise the benchmark score."
• "Start an evolutionary improvement run against my benchmark command."

Walk through setup and the trust confirmation

Setup has a mandatory trust step. The agent displays the target repository path and asks you to confirm that benchmark commands will run inside it, because they execute code in that repository. If you decline, setup stops. The agent also asks you to confirm the benchmark command before it is run repeatedly.

The goal is set through a short interview covering the objective, metric, target and scope. Results are saved to config files inside the resolved self-improve folder, under .omc/self-improve/topics/default/ for new runs or a topic-named folder when you give a topic or slug.

• Confirm the repository path when asked.
• Answer the goal questions: objective, metric, target and scope.
• Confirm the benchmark command when it is shown to you.
• Review the harness rules (H001, H002, H003) or customize them.

Understand what the loop does while it runs

Once the gate check passes, the loop runs without pausing for input until a stop condition is met. It does not ask for confirmation between iterations. If an agent fails, it retries once, then skips that agent and logs the failure. If all plans are rejected or all executors fail, the failure is logged and the next iteration starts.

The loop does not install packages or modify system configuration. The benchmark code is sealed: validate.sh enforces that the loop cannot modify it, so the evaluation cannot be changed to game the score.

• Iteration history is stored per round, and merge reports record tournament results.
• Candidate scores are stored in tracking data alongside a baseline score and config events.
• Stop conditions are defined in the skill's Step 11; check the generated settings before a long run.

Examples of good requests

The skill fits tasks where a number can be measured repeatedly and compared. Good examples are a test-suite runtime, a benchmark score, or another automated metric that you already trust.

• Reduce the runtime of a test suite measured by a timing command.
• Raise a benchmark score produced by an existing evaluation script.
• Explore many small changes to a module and keep only those that score higher.

Safety notes before you run it

The loop executes the benchmark command as-is inside the repository. Untrusted code can run on your machine, so review the repository and the benchmark command first. The skill also uses the network to the extent the benchmark command does.

Do not use the skill where you cannot review the code, where you have no reliable numeric benchmark, or where you want tight manual control between iterations.

• Review the repository and benchmark command before confirming.
• Run it on a branch: setup creates an improve/{goal_slug} branch from your target branch.
• Do not use it for tasks without a reliable numeric benchmark, because the loop picks winners by score alone.