How to use the A-Evolve Agent Improvement skill (a-evolve)

What the a-evolve skill makes the agent do

A skill is a folder containing a SKILL.md file with instructions that an agent reads when a request matches the skill's description. The a-evolve skill is instructions only: it has no external dependencies and no harness changes. It tells the agent how to analyse agent runs and write proposed artifacts.

The skill follows the Solve → Observe → Evolve → Gate → Reload methodology from the A-Evolve project. The agent collects evidence, diagnoses failures by category, proposes mutations, checks them against a gate, and then presents accepted changes for you to place in your project.

• Solve: gather run logs, error traces, pass/fail results and metric values.
• Observe: group failures by category, root cause, frequency and severity.
• Evolve: propose a new SKILL.md, a short system prompt patch, a JSON knowledge entry, or nothing.
• Gate: check specificity, testability, blast radius and consistency with existing guidance.
• Reload: present accepted changes with suggested file locations and keep a running evolution log.

Install the a-evolve skill

Download the ZIP containing SKILL.md from the directory page and unzip it. For a personal install, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into your project's .claude/skills/
• Claude apps: Settings → Capabilities → Skills, then upload

Trigger the skill with natural requests

The skill's description lists trigger phrases, so you usually do not need a special command. Describe the problem in plain language. Phrases that match the description include "evolve", "self-improve", "diagnose failures", "generate skills from errors", "what went wrong and how to fix it", or any mention of A-Evolve.

Give the agent the evidence it needs. Pointing it at a log file or results folder works better than a vague complaint.

• "Diagnose the failures in this run log and tell me what went wrong and how to fix it."
• "Evolve the system prompt based on the errors in these experiment outputs."
• "Generate skills from the recurring errors in last night's agent batch."
• "Self-improve my agent using these pass/fail results."

What the output looks like

The skill asks the agent to write observations as a structured list with an ID, error category, affected tasks, root cause, frequency and severity. Proposed mutations follow from those observations. A generated skill should target one specific failure category, be under 100 lines, and include a "when to apply" trigger.

The skill also sets limits: no more than three skills per evolution cycle, surgical prompt patches rather than rewrites, and no tool code changes unless you explicitly ask.

• Skill files: a SKILL.md for a specific recurring pattern (frequency of 3 or more).
• Prompt patches: one short paragraph per issue, appended to the system prompt.
• Knowledge entries: a JSON record with id, category, insight, source and confidence.
• Do nothing: for one-off or cosmetic issues, or fixes that are too broad or risky.

Use it with AutoResearchClaw

If you run the AutoResearchClaw (ARC) pipeline, the skill maps its loop onto specific stages. Stage 12 (EXPERIMENT_RUN) provides the Solve artifacts, stage 13 (ITERATIVE_REFINE) is the main Observe and Evolve trigger, stage 15 (RESEARCH_DECISION) works as a natural gate where PROCEED means accept and REFINE means retry, and stage 18 (PEER_REVIEW) adds signal about writing quality.

For ARC projects, the skill recommends locations for each artifact: evolved skills go in .claude/skills/evolved/<skill-name>/SKILL.md, knowledge entries in docs/kb/evolved_knowledge/<id>.json, and observation logs in evolution/observations/<batch>.md.

• Say "evolve my research pipeline" and the agent will ask which run to analyse, or find the latest artifacts/rc-*/ folder.
• Look for evolve.log, stage logs, reviews.md and sentinel watchdog reports.
• Prompt patches are appended to prompts.default.yaml or a custom prompts file.

Optional: MetaClaw integration

If AutoResearchClaw has MetaClaw enabled with metaclaw_bridge.enabled set to true, evolved skills can be placed in ~/.metaclaw/skills/arc-*/ so MetaClaw injects them into future runs automatically. The skill describes the two systems as complementary: a-evolve produces higher-precision targeted skills, while MetaClaw lessons capture broader patterns from pipeline warnings and errors.

Safety notes and tips

The skill runs no scripts and uses no network access. It works by reading the files you supply and writing proposed artifacts. Nothing is applied automatically: the gate step is a judgment check made by the agent, so you should review each change before it reaches a production prompt or skill set.

Keep a running evolution log, as the skill recommends, so you can trace which change came from which observation. Compare results after each change by re-running the failed tasks.

• Review every proposed artifact before placing it in a live project.
• Do not use the skill's output unchecked in production systems, where a mistaken edit could cause regressions.
• Give it real run data; a vague description produces vague skills.
• Ask for one batch at a time so observations stay tied to specific evidence.