Evolve Agent

Bestehenden Agenten weiterentwickeln

Einen Agenten verbessern, erweitern oder eine fortgeschrittene Variante eines Agenten erstellen, der urspruenglich mit create-agent verfasst wurde. Dieses Verfahren behandelt die Wartungsseite des Agenten-Lebenszyklus: Luecken anhand von Best Practices bewerten, gezielte Verbesserungen an der Persona-Definition anwenden, Versionen erhoehen und Registry sowie Querverweise synchron halten.

Wann verwenden

• Die Skills-Liste eines Agenten ist veraltet, nachdem neue Skills der Bibliothek hinzugefuegt wurden
• Nutzer-Feedback zeigt fehlende Faehigkeiten, unklaren Zweck oder schwache Beispiele
• Werkzeuganforderungen haben sich geaendert (neuer MCP-Server, Werkzeug entfernt, Rechteeinschraenkung erforderlich)
• Der Umfang eines Agenten muss geschaerft werden -- er ueberschneidet sich mit einem anderen Agenten oder ist zu breit
• Eine fortgeschrittene Variante wird neben dem Original benoetigt (z.B. r-developer und r-developer-advanced)
• Verwandte Agenten oder Teams wurden hinzugefuegt und Querverweise in Siehe-auch sind veraltet

Eingaben

• Erforderlich: Pfad zur bestehenden Agentendatei zur Weiterentwicklung (z.B. agents/r-developer.md)
• Erforderlich: Weiterentwicklungsausloser (Feedback, neue Skills, Werkzeugaenderung, Umfangsueberschneidung, Teamintegration, entdeckte Einschraenkungen)
• Optional: Ziel-Versions-Bump-Groesse (patch, minor, major)
• Optional: Ob stattdessen eine fortgeschrittene Variante erstellt werden soll (Standard: direkt verfeinern)

Vorgehensweise

Schritt 1: Den aktuellen Agenten bewerten

Die bestehende Agentendatei lesen und jeden Abschnitt gegen die Qualitaetscheckliste aus guides/agent-best-practices.md bewerten:

# 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

Erwartet: Eine Liste spezifischer Luecken, Schwachstellen oder Verbesserungsmoeglichkeiten, nach Abschnitt geordnet.

Bei Fehler: Falls die Agentendatei nicht existiert oder kein Frontmatter hat, ist dieser Skill nicht anwendbar — stattdessen create-agent verwenden, um sie von Grund auf zu erstellen.

Schritt 2: Weiterentwicklungsanforderungen sammeln

Identifizieren und kategorisieren, was die Weiterentwicklung ausgeloest hat:

Die spezifischen Aenderungen vor der Bearbeitung dokumentieren:

- Frontmatter: `new-skill-id` zur Skills-Liste hinzufuegen
- Faehigkeiten: Faehigkeit "API-Sicherheitsanalyse" hinzufuegen
- Verfuegbare Skills: `new-skill-id` mit Beschreibung hinzufuegen
- Einschraenkungen: veraltete Einschraenkung ueber fehlenden Skill entfernen
- Siehe auch: Link zu neuem Team hinzufuegen, das diesen Agenten beinhaltet

Erwartet: Eine konkrete Liste von Aenderungen, jede einem spezifischen Abschnitt der Agentendatei zugeordnet.

Bei Fehler: Falls die Aenderungen unklar sind, den Benutzer um Klaerung bitten, bevor fortgefahren wird. Vage Weiterentwicklungsziele erzeugen vage Verbesserungen.

Schritt 3: Weiterentwicklungsumfang waehlen

Diese Entscheidungsmatrix verwenden, um zu bestimmen, ob direkt verfeinert oder eine Variante erstellt werden soll:

Verfeinerung: Waehlen beim Aktualisieren von Skills, Beheben von Dokumentation, Schaerfen des Umfangs oder Anpassen von Werkzeugen. Der Agent behaelt seine Identitaet.

Variante: Waehlen wenn die weiterentwickelte Version einer wesentlich anderen Zielgruppe dient, ein anderes Modell erfordert oder Faehigkeiten hinzufuegt, die das Original zu breit machen wuerden. Das Original bleibt fuer einfachere Anwendungsfaelle unveraendert.

Erwartet: Eine klare Entscheidung — Verfeinerung oder Variante — mit Begruendung.

Bei Fehler: Im Zweifel Verfeinerung verwenden. Eine Variante kann spaeter immer extrahiert werden; es ist schwieriger, eine wieder zusammenzufuehren.

Schritt 4: Aenderungen an der Agentendatei anwenden

Fuer Verfeinerungen

Die bestehende Agentendatei direkt bearbeiten:

• Frontmatter: skills, tools, tags, model, priority, mcp_servers nach Bedarf aktualisieren
• Zweck/Faehigkeiten: Ueberarbeiten, um neuen Umfang oder hinzugefuegte Funktionalitaet widerzuspiegeln
• Verfuegbare Skills: Neue Skills mit Beschreibungen hinzufuegen, veraltete entfernen
• Verwendungsszenarien: Hinzufuegen oder ueberarbeiten, um neue Faehigkeiten zu demonstrieren
• Einschraenkungen: Nicht mehr geltende entfernen, neue ehrliche hinzufuegen
• Siehe auch: Querverweise aktualisieren, um aktuelle Agenten-/Team-/Leitfaden-Landschaft widerzuspiegeln

Diese Bearbeitungsregeln befolgen:

• Alle bestehenden Abschnitte erhalten — Inhalte hinzufuegen, keine Abschnitte entfernen
• Abschnitt "Verfuegbare Skills" mit Frontmatter-skills-Liste synchron halten
• Standard-Skills (meditate, heal) nicht zum Frontmatter hinzufuegen, es sei denn sie sind Kern der Agentenmethodik
• Jede Skill-ID pruefen: grep "id: skill-name" skills/_registry.yml

Fuer Varianten

# 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

Erwartet: Die Agentendatei (verfeinert oder neue Variante) besteht die Bewertungscheckliste aus Schritt 1.

Bei Fehler: Falls eine Bearbeitung die Dokumentstruktur beschaedigt, git diff verwenden, um Aenderungen zu ueberpruefen und partielle Bearbeitungen mit git checkout -- <file> rueckgaengig zu machen.

Schritt 4.5: Uebersetzte Varianten synchronisieren

Erforderlich, wenn Uebersetzungen existieren. Dieser Schritt gilt sowohl fuer menschliche Autoren als auch fuer KI-Agenten, die dieser Vorgehensweise folgen. Nicht ueberspringen — veraltete source_commit-Werte fuehren dazu, dass npm run validate:translations falsche Stale-Warnungen ueber alle Locales hinweg meldet.

Pruefen, ob Uebersetzungen fuer den weiterentwickelten Agenten existieren, und sie auf den neuen Stand der Quelle aktualisieren:

# Check for existing translations
ls i18n/*/agents/<agent-name>.md 2>/dev/null

Falls Uebersetzungen existieren

1. Aktuellen Quell-Commit-Hash ermitteln:

SOURCE_COMMIT=$(git rev-parse HEAD)

2. source_commit im Frontmatter jeder uebersetzten Datei aktualisieren:

for locale_file in i18n/*/agents/<agent-name>.md; do
  sed -i "s/^source_commit: .*/source_commit: $SOURCE_COMMIT/" "$locale_file"
done

3. Dateien zur Neu-Uebersetzung markieren, indem betroffene Locales in der Commit-Nachricht aufgefuehrt werden:

evolve-agent(<agent-name>): <Beschreibung der Aenderungen>

Translations flagged for re-sync: de, zh-CN, ja, es
Changed sections: <Liste der geaenderten Abschnitte>

4. Uebersetzungs-Statusdateien neu generieren:

npm run translation:status

Falls keine Uebersetzungen existieren

Keine Aktion noetig. Mit Schritt 5 fortfahren.

Fuer Varianten

Die Uebersetzung neuer Varianten aufschieben, bis sich die Variante stabilisiert hat (1-2 Versionen). Eine v1.0-Variante zu uebersetzen, die sich bis v1.2 erheblich aendern kann, verschwendet Aufwand. Uebersetzungen hinzufuegen, nachdem die Variante mindestens einmal verfeinert wurde.

Erwartet: Alle uebersetzten Dateien haben source_commit auf den aktuellen Commit aktualisiert. Die Commit-Nachricht vermerkt, welche Locales neu uebersetzt werden muessen und welche Abschnitte sich geaendert haben. npm run translation:status beendet mit 0.

Bei Fehler: Falls sed das Frontmatter-Feld nicht matcht, hat die uebersetzte Datei moeglicherweise eine nicht standardisierte Formatierung. Manuell oeffnen und pruefen, ob source_commit in ihrem YAML-Frontmatter vorhanden ist. Falls das Feld fehlt, wurde die Datei nicht korrekt angelegt — mit npm run translate:scaffold -- agents neu anlegen.

Schritt 5: Version und Metadaten aktualisieren

Das Feld version im Frontmatter gemaess semantischer Versionierung erhoehen:

Auch aktualisieren:

• updated-Datum auf das aktuelle Datum
• tags falls sich der Domain-Abdeckungsbereich des Agenten geaendert hat
• description falls der Zweck wesentlich anders ist
• priority falls sich die Wichtigkeit des Agenten relativ zu anderen geaendert hat

Erwartet: Frontmatter-version und updated spiegeln Groesse und Datum der Aenderungen wider. Neue Varianten beginnen bei "1.0.0".

Bei Fehler: Falls die Version vergessen wird zu erhoehen, gibt es keine Moeglichkeit, den aktuellen Stand vom vorherigen zu unterscheiden. Immer vor dem Committen erhoehen.

Schritt 6: Registry und Querverweise aktualisieren

Fuer Verfeinerungen

Den bestehenden Eintrag in agents/_registry.yml aktualisieren, um das ueberarbeitete Frontmatter widerzuspiegeln:

# Find the agent's registry entry
grep -A 10 "id: <agent-name>" agents/_registry.yml

Felder description, tags, tools und skills aktualisieren, um der Agentendatei zu entsprechen. Keine Zaehleraenderung erforderlich.

Querverweise in anderen Dateien aktualisieren, falls sich Faehigkeiten oder Name des Agenten geaendert haben:

# 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

Fuer Varianten

Den neuen Agenten in agents/_registry.yml in alphabetischer Position hinzufuegen:

  - 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

Dann:

1. total_agents am Anfang der Registry hochzaehlen
2. Querverweis in Siehe-auch des urspruenglichen Agenten hinzufuegen, der auf die Variante zeigt
3. Querverweis in Siehe-auch der Variante hinzufuegen, der auf das Original zeigt
4. Der Symlink .claude/agents/ zu agents/ bedeutet, dass die Variante automatisch erkennbar ist

Erwartet: Registry-Eintrag stimmt mit Agentendatei-Frontmatter ueberein. Fuer Varianten entspricht total_agents der tatsaechlichen Anzahl der Agenteneintraege.

Bei Fehler: Eintraege zaehlen mit grep -c "^ - id:" agents/_registry.yml und pruefen ob es total_agents entspricht.

Schritt 7: Den weiterentwickelten Agenten validieren

Die vollstaendige Validierungscheckliste durchfuehren:

• Agentendatei existiert am erwarteten Pfad
• YAML-Frontmatter wird fehlerfrei geparst
• version wurde erhoehen (Verfeinerung) oder auf "1.0.0" gesetzt (Variante)
• updated-Datum spiegelt heute wider
• Alle Pflichtabschnitte vorhanden: Purpose, Capabilities, Available Skills, Usage Scenarios, Examples, Limitations, See Also
• Skills im Frontmatter stimmen mit dem Abschnitt "Verfuegbare Skills" ueberein
• Alle Skill-IDs existieren in skills/_registry.yml
• Standard-Skills (meditate, heal) sind nicht aufgefuehrt, es sei denn sie sind Kern der Methodik
• Werkzeugliste folgt dem Prinzip der minimalen Berechtigungen
• Registry-Eintrag existiert und stimmt mit Frontmatter ueberein
• Fuer Varianten: total_agents-Zaehler stimmt mit tatsaechlicher Anzahl auf der Festplatte ueberein
• Querverweise sind bidirektional (Original <-> Variante)
• git diff zeigt keine versehentlichen Loeschungen aus dem urspruenglichen Inhalt

# 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

Erwartet: Alle Checklistenelemente bestanden. Der weiterentwickelte Agent ist bereit zum Committen.

Bei Fehler: Jeden fehlschlagenden Punkt einzeln adressieren. Die haeufigsten Post-Weiterentwicklungs-Probleme sind veraltete Skill-IDs im Abschnitt "Verfuegbare Skills" und ein vergessenes updated-Datum.

Validierung

• Agentendatei existiert und hat gueltiges YAML-Frontmatter
• version-Feld spiegelt die vorgenommenen Aenderungen wider
• updated-Datum ist aktuell
• Alle Abschnitte vorhanden und intern konsistent
• Frontmatter-skills-Array stimmt mit dem Abschnitt "Verfuegbare Skills" ueberein
• Alle Skill-IDs existieren in skills/_registry.yml
• Standard-Skills nicht unnoetig aufgefuehrt
• Registry-Eintrag stimmt mit der Agentendatei ueberein
• Fuer Varianten: neuer Eintrag in agents/_registry.yml mit korrektem Pfad
• Fuer Varianten: total_agents-Zaehler aktualisiert
• Querverweise sind gueltig (keine fehlerhaften Links in Siehe-auch)
• git diff bestaetigt keine versehentliche Inhaltsentfernung

Haeufige Stolperfallen

• Version zu erhoehen vergessen: Ohne Versions-Bumps gibt es keine Moeglichkeit zu verfolgen, was sich wann geaendert hat. version und updated immer im Frontmatter vor dem Committen aktualisieren.
• Skills-Listen-Abweichung: Das Frontmatter-skills-Array und der Abschnitt ## Available Skills muessen synchron bleiben. Eines zu aktualisieren ohne das andere schafft Verwirrung fuer Menschen und Werkzeuge.
• Standard-Skills unnoetig aufzaehlen: meditate oder heal zum Frontmatter hinzufuegen, obwohl sie bereits aus der Registry geerbt werden. Nur auflisten wenn sie Kern der Agentenmethodik sind.
• Werkzeug-Ueberversorgung bei der Weiterentwicklung: Bash oder WebFetch waehrend einer Weiterentwicklung "nur fuer den Fall" hinzufuegen. Jede Werkzeugergaenzung sollte durch eine spezifische neue Faehigkeit gerechtfertigt sein.
• Veraltete Siehe-auch nach Variantenerstellung: Beim Erstellen einer Variante muessen sowohl das Original als auch die Variante aufeinander verweisen. Einseitige Verweise lassen den Graphen unvollstaendig.
• Registry-Eintrag nicht aktualisiert: Nach der Aenderung von Skills, Werkzeugen oder Beschreibung eines Agenten muss der agents/_registry.yml-Eintrag aktualisiert werden. Veraltete Registry-Eintraege verursachen Erkennungs- und Werkzeugfehler.

Verwandte Skills

• create-agent — Grundlage fuer das Verfassen neuer Agenten; evolve-agent setzt voraus, dass dies urspruenglich befolgt wurde
• evolve-skill — das Parallelverfahren fuer das Weiterentwickeln von SKILL.md-Dateien
• commit-changes — den weiterentwickelten Agenten mit einer beschreibenden Nachricht committen