Evolve an Existing Agent
Improve, extend, or create an advanced variant of an agent that was originally authored with create-agent. This procedure covers the maintenance side of the agent lifecycle: assessing gaps against best practices, applying targeted improvements to the persona definition, bumping versions, and keeping the registry and cross-references in sync.
When to Use
- An agent's skills list is outdated after new skills were added to the library
- User feedback reveals missing capabilities, unclear purpose, or weak examples
- Tool requirements have changed (new MCP server, tool removed, privilege reduction needed)
- An agent's scope needs sharpening — it overlaps with another agent or is too broad
- An advanced variant is needed alongside the original (e.g.,
r-developer and r-developer-advanced)
- Related agents or teams were added and cross-references in See Also are stale
Inputs
- Required: Path to the existing agent file to evolve (e.g.,
agents/r-developer.md)
- Required: Evolution trigger (feedback, new skills, tool change, scope overlap, team integration, discovered limitations)
- Optional: Target version bump magnitude (patch, minor, major)
- Optional: Whether to create an advanced variant instead of refining in-place (default: refine in-place)
Procedure
Step 1: Assess the Current Agent
Read the existing agent file and evaluate each section against the quality checklist from guides/agent-best-practices.md:
| Section | What to Check | Common Issues |
|---|
| Frontmatter | All required fields present (name, description, tools, model, version, author) | Missing tags, stale version, wrong priority |
| Purpose | Specific problem statement, not generic "helps with X" | Vague or overlapping with another agent |
| Capabilities | Concrete, verifiable capabilities with bold lead-ins | Generic ("handles development"), no grouping |
| Available Skills | Matches frontmatter skills list, all IDs exist in registry | Stale IDs, missing new skills, lists default skills unnecessarily |
| Usage Scenarios | 2-3 realistic scenarios with invocation patterns | Placeholder text, unrealistic examples |
| Examples | Shows user request and agent behavior | Missing or trivial examples |
| Limitations | 3-5 honest constraints | Too few, too vague, or missing entirely |
| See Also | Valid cross-references to agents, guides, teams | Stale links to renamed or removed files |
# Read the agent file
cat agents/<agent-name>.md
# Check frontmatter parses
head -20 agents/<agent-name>.md
# Verify skills in frontmatter exist in registry
grep "skills:" -A 20 agents/<agent-name>.md
# Check if agent is referenced by any team
grep -r "<agent-name>" teams/*.md
Expected: A list of specific gaps, weaknesses, or improvement opportunities organized by section.
On failure: If the agent file does not exist or has no frontmatter, this skill does not apply — use create-agent instead to author it from scratch.
Step 2: Gather Evolution Requirements
Identify and categorize what triggered the evolution:
| Trigger | Example | Typical Scope |
|---|
| User feedback | "Agent missed XSS in review" | Add skill or capability |
| New skills available | Library gained analyze-api-security | Update skills list |
| Tool change | New MCP server available | Add to tools/mcp_servers |
| Scope overlap | Two agents both claim "code review" | Sharpen purpose and limitations |
| Team integration | Agent added to a new team | Update See Also, verify capabilities |
| Model upgrade | Task requires deeper reasoning | Change model field |
| Privilege reduction | Agent has Bash but only reads files | Remove unnecessary tools |
Document the specific changes needed before editing. List each change with its target section:
- Frontmatter: add `new-skill-id` to skills list
- Capabilities: add "API Security Analysis" capability
- Available Skills: add `new-skill-id` with description
- Limitations: remove outdated limitation about missing skill
- See Also: add link to new team that includes this agent
Expected: A concrete list of changes, each mapped to a specific section of the agent file.
On failure: If the changes are unclear, consult the user for clarification before proceeding. Vague evolution goals produce vague improvements.
Step 3: Choose Evolution Scope
Use this decision matrix to determine whether to refine in-place or create a variant:
| Criteria | Refinement (in-place) | Advanced Variant (new agent) |
|---|
| Agent ID | Unchanged | New ID: <agent>-advanced or <agent>-<specialty> |
| File path | Same .md file | New file in agents/ |
| Version bump | Patch or minor | Starts at 1.0.0 |
| Model | May change | Often higher (e.g., sonnet → opus) |
| Registry | Update existing entry | New entry added |
| Original agent | Modified directly | Left intact, gains See Also cross-reference |
Refinement: Choose when updating skills, fixing documentation, sharpening scope, or adjusting tools. The agent keeps its identity.
Variant: Choose when the evolved version would serve a substantially different audience, require a different model, or add capabilities that would make the original too broad. The original stays as-is for simpler use cases.
Expected: A clear decision — refinement or variant — with rationale.
On failure: If unsure, default to refinement. You can always extract a variant later; it is harder to merge one back.
Step 4: Apply Changes to the Agent File
For Refinements
Edit the existing agent file directly:
- Frontmatter: Update
skills, tools, tags, model, priority, mcp_servers as needed
- Purpose/Capabilities: Revise to reflect new scope or added functionality
- Available Skills: Add new skills with descriptions, remove deprecated ones
- Usage Scenarios: Add or revise scenarios to demonstrate new capabilities
- Limitations: Remove constraints that no longer apply, add new honest ones
- See Also: Update cross-references to reflect current agent/team/guide landscape
Follow these editing rules:
- Preserve all existing sections — add content, do not remove sections
- Keep the Available Skills section in sync with the frontmatter
skills list
- Do not add default skills (
meditate, heal) to frontmatter unless they are core to the agent's methodology
- Verify each skill ID exists:
grep "id: skill-name" skills/_registry.yml
For Variants
# Copy the original as a starting point
cp agents/<agent-name>.md agents/<agent-name>-advanced.md
# Edit the variant:
# - Change `name` to `<agent-name>-advanced`
# - Update `description` to reflect the advanced scope
# - Raise `model` if needed (e.g., sonnet → opus)
# - Reset `version` to "1.0.0"
# - Expand skills, capabilities, and examples for the advanced use case
# - Reference the original in See Also as a simpler alternative
Expected: The agent file (refined or new variant) passes the assessment checklist from Step 1.
On failure: If an edit breaks the document structure, use git diff to review changes and revert partial edits with git checkout -- <file>.
Step 4.5: Sync Translated Variants
Required when translations exist. Applies to human authors and AI agents
alike. Do not bump source_commit — an evolve run that changes English
without retranslating leaves every provenance field untouched, and the staleness
it creates is true rather than noise (#405, #616).
Check which translations exist for the evolved agent. They are about to become stale, and this step is how you leave them honestly stale rather than falsely fresh:
# Check for existing translations
ls i18n/*/agents/<agent-name>.md 2>/dev/null
Which provenance field may move, and by what
scripts/lib/provenance.js is the authority on this; the table is its summary.
| Field | Moves when | Moved by |
|---|
source_commit | a human retranslates against a newer English revision | that human, in the commit carrying the retranslated prose |
fence_basis_commit | frozen-fence bytes are propagated into the mirror and verified | normalize-i18n-fences.js when it does the propagating; tools/provenance-field.mjs when you propagate by hand, after check:fence-propagation passes |
Which of those applies depends on what you edited, and getting this wrong is how a
provenance field becomes a false claim:
- Prose only — neither field moves. The mirror is genuinely stale afterwards,
npm run validate:translations is right to say so, and bumping source_commit would assert a
translation event that never happened, suppressing the one signal that would have
surfaced the drift (#405, #616).
- A frozen fence —
source_commit still does not move, but the mirrors' fence bodies
just changed, so every fence_basis_commit naming the old revision is now false.
Step 2 below restamps them. Leaving them is the failure this table exists to prevent.
- A retranslation of one locale — that locale's
source_commit moves, in the commit
carrying the prose, and the others' do not.
normalize-i18n-fences.js is named above for the case where it does the propagating. It
does not fire on a hand propagation — measured on this skill's own rewrite, where a
preview reported five files to change and not one was a mirror of these skills. Do not wait
for it to restamp what you copied by hand.
Never repair a provenance field in bulk with sed. The form this step used to carry was a
substitution anchored at ^source_commit — column 0 — which silently no-ops on every mirror
that nests provenance under metadata: at two-space indent: wrong and unreliable at once.
Route any bulk field edit through tools/provenance-field.mjs, which is indent-aware and
refuses to move source_commit unless you declare you are the human retranslating.
(That anchored form is deliberately not reproduced here. #616's acceptance criterion is a
grep, and prose quoting the thing it forbids would defeat the check that proves the thing
is gone.)
- Read which mirrors this change made stale, and leave them stale:
npm run validate:translations
- If you edited a frozen fence in English, its bytes must reach all four mirrors in
this same commit, verified by bytes rather than by the fence gate — that gate accepts a
body from any English revision, so it cannot tell you whether your edit landed. Then
restamp the mirrors you touched, because their old
fence_basis_commit now names a
revision whose fences they no longer carry:
npm run check:fence-propagation -- --id <agent-name>
node tools/provenance-field.mjs --field fence_basis_commit --set $(git rev-parse --short HEAD) <mirror paths>
- Flag the affected locales in the commit message, naming what changed:
evolve(<agent-name>): <description of changes>
Translations now stale, source_commit deliberately NOT bumped: de, zh-CN, ja, es
Changed sections: <list sections that changed>
- Regenerate the translation status files:
npm run translation:status
If no translations exist
No action needed. Proceed to Step 5.
For variants
Defer translation of new variants until the variant stabilizes (1-2 versions). Add translations after the variant has been refined at least once.
Expected: source_commit unchanged everywhere. npm run validate:translations reports
more stale mirrors than before — that count rising is the correct outcome of an evolve run,
not a failure to repair. If you edited a frozen fence, fence_basis_commit on the mirrors
you touched names the commit carrying the new bytes; if you edited only prose, no provenance
field moved at all. If a frozen fence was edited, check:fence-propagation shows every
mirror carrying the new bytes. npm run translation:status exits 0.
On failure: If check:fence-propagation reports a mirror whose fence body differs, the
byte-copy did not reach it: copy the English fence body verbatim into that mirror and re-run
— and read its output rather than its exit code, which it shares with the unalignable
case. If a frontmatter field genuinely needs a bulk edit, use tools/provenance-field.mjs; a
substitution anchored at column 0 matches nothing in a mirror that nests provenance under
metadata:, and reports success while changing nothing.
Step 5: Update Version and Metadata
Bump the version field in frontmatter following semantic versioning:
| Change Type | Version Bump | Example |
|---|
| Typo fix, wording clarification | Patch: 1.0.0 → 1.0.1 | Fixed unclear limitation |
| New skills added, capability expanded | Minor: 1.0.0 → 1.1.0 | Added 3 new skills from library |
| Restructured purpose, changed model | Major: 1.0.0 → 2.0.0 | Narrowed scope, upgraded to opus |
Also update:
updated date to the current datetags if the agent's domain coverage changeddescription if the purpose is materially differentpriority if the agent's importance relative to others changed
Expected: Frontmatter version and updated reflect the magnitude and date of changes. New variants start at "1.0.0".
On failure: If you forget to bump the version, the next evolution will have no way to distinguish the current state from the previous one. Always bump before committing.
Step 6: Update Registry and Cross-References
For Refinements
Update the existing entry in agents/_registry.yml to match the revised frontmatter:
# Find the agent's registry entry
grep -A 10 "id: <agent-name>" agents/_registry.yml
Update description, tags, tools, and skills fields to match the agent file. No count change is needed.
Update cross-references in other files if the agent's capabilities or name changed:
# Check if any team references this agent
grep -r "<agent-name>" teams/*.md
# Check if any guide references this agent
grep -r "<agent-name>" guides/*.md
For Variants
Add the new agent to agents/_registry.yml in alphabetical position:
- id: <agent-name>-advanced
path: agents/<agent-name>-advanced.md
description: One-line description of the advanced variant
tags: [domain, specialty, advanced]
priority: normal
tools: [Read, Write, Edit, Bash, Grep, Glob]
skills:
- skill-id-one
- skill-id-two
Then:
- Increment
total_agents at the top of the registry
- Add See Also cross-reference in the original agent pointing to the variant
- Add See Also cross-reference in the variant pointing to the original
- The
.claude/agents/ symlink to agents/ means the variant is automatically discoverable
Expected: Registry entry matches the agent file frontmatter. For variants, total_agents equals the actual number of agent entries.
On failure: Count entries with grep -c "^ - id:" agents/_registry.yml and verify it matches total_agents.
Step 7: Validate the Evolved Agent
Run the full validation checklist:
# Verify frontmatter
head -20 agents/<agent-name>.md
# Check skills exist
for skill in skill-a skill-b; do
grep "id: $skill" skills/_registry.yml
done
# Count agents on disk vs registry
ls agents/*.md | grep -v template | wc -l
grep total_agents agents/_registry.yml
# Review all changes
git diff
Expected: All checklist items pass. The evolved agent is ready to commit.
On failure: Address each failing item individually. The most common post-evolution issues are stale skill IDs in the Available Skills section and a forgotten updated date.
Validation
Common Pitfalls
- Forgetting to bump version: Without version bumps, there is no way to track what changed or when. Always update
version and updated in frontmatter before committing.
- Skills list drift: The frontmatter
skills array and the ## Available Skills section must stay in sync. Updating one without the other creates confusion for both humans and tooling.
- Listing default skills unnecessarily: Adding
meditate or heal to the frontmatter when they are already inherited from the registry. Only list them if they are core to the agent's methodology (e.g., mystic, alchemist).
- Tool over-provisioning during evolution: Adding
Bash or WebFetch during an evolution "just in case." Every tool addition should be justified by a specific new capability.
- Stale See Also after variant creation: When creating a variant, both the original and the variant need to reference each other. One-directional references leave the graph incomplete.
- Registry entry not updated: After changing an agent's skills, tools, or description, the
agents/_registry.yml entry must be updated to match. Stale registry entries cause discovery and tooling failures.
Related Skills
create-agent — foundation for authoring new agents; evolve-agent assumes this was followed originallyevolve-skill — the parallel procedure for evolving SKILL.md filescommit-changes — commit the evolved agent with a descriptive message