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:

Abschnitt	Was pruefen	Haeufige Probleme
Frontmatter	Alle Pflichtfelder vorhanden (name, description, tools, model, version, author)	Fehlende tags, veraltete version, falsche priority
Zweck	Spezifische Problemformulierung, nicht generisch "hilft bei X"	Vage oder ueberlappend mit einem anderen Agenten
Faehigkeiten	Konkrete, pruefbare Faehigkeiten mit fettgedruckten Vorsaetzen	Generisch ("behandelt Entwicklung"), keine Gruppierung
Verfuegbare Skills	Stimmt mit Frontmatter-skills-Liste ueberein, alle IDs existieren in der Registry	Veraltete IDs, fehlende neue Skills, Standard-Skills unnoetig aufgelistet
Verwendungsszenarien	2-3 realistische Szenarien mit Aufrufmustern	Platzhaltertext, unrealistische Beispiele
Beispiele	Zeigt Benutzeranfrage und Agentenverhalten	Fehlend oder trivial
Einschraenkungen	3-5 ehrliche Beschraenkungen	Zu wenige, zu vage oder voellig fehlend
Siehe auch	Gueltige Querverweise auf Agenten, Leitfaeden, Teams	Veraltete Links zu umbenannten oder entfernten Dateien

# Agentendatei lesen
cat agents/<agent-name>.md

# Frontmatter-Parsing pruefen
head -20 agents/<agent-name>.md

# Skills im Frontmatter auf Registry-Existenz pruefen
grep "skills:" -A 20 agents/<agent-name>.md

# Pruefen ob der Agent von einem Team referenziert wird
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:

Ausloser	Beispiel	Typischer Umfang
Nutzer-Feedback	"Agent hat XSS im Review uebersehen"	Skill oder Faehigkeit hinzufuegen
Neue Skills verfuegbar	Bibliothek hat analyze-api-security gewonnen	Skills-Liste aktualisieren
Werkzeugaenderung	Neuer MCP-Server verfuegbar	Zu tools/mcp_servers hinzufuegen
Umfangsueberschneidung	Zwei Agenten beanspruchen beide "Code-Review"	Zweck und Einschraenkungen schaerfen
Teamintegration	Agent zu einem neuen Team hinzugefuegt	Siehe-auch aktualisieren, Faehigkeiten pruefen
Modell-Upgrade	Aufgabe benoetigt tieferes Reasoning	Modellfeld aendern
Rechteeinschraenkung	Agent hat Bash, liest aber nur Dateien	Unnoetige Werkzeuge entfernen

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:

Kriterium	Verfeinerung (direkt)	Fortgeschrittene Variante (neuer Agent)
Agenten-ID	Unveraendert	Neue ID: <agent>-advanced oder <agent>-<specialty>
Dateipfad	Dieselbe .md-Datei	Neue Datei in agents/
Versions-Bump	Patch oder Minor	Beginnt bei 1.0.0
Modell	Kann sich aendern	Oft hoeher (z.B. sonnet -> opus)
Registry	Bestehenden Eintrag aktualisieren	Neuer Eintrag hinzugefuegt
Urspruenglicher Agent	Direkt modifiziert	Unveraendert, erhaelt Querverweise in Siehe-auch

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

# Original als Ausgangspunkt kopieren
cp agents/<agent-name>.md agents/<agent-name>-advanced.md

# Variante bearbeiten:
# - `name` in `<agent-name>-advanced` aendern
# - `description` aktualisieren um fortgeschrittenen Umfang widerzuspiegeln
# - `model` bei Bedarf erhoehen (z.B. sonnet -> opus)
# - `version` auf "1.0.0" zuruecksetzen
# - Skills, Faehigkeiten und Beispiele fuer fortgeschrittenen Anwendungsfall erweitern
# - Original in Siehe-auch als einfachere Alternative referenzieren

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:

# Auf vorhandene Uebersetzungen pruefen
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:

Aenderungstyp	Versions-Bump	Beispiel
Tippfehler, Formulierungspraezisierung	Patch: 1.0.0 -> 1.0.1	Unklare Einschraenkung korrigiert
Neue Skills hinzugefuegt, Faehigkeit erweitert	Minor: 1.0.0 -> 1.1.0	3 neue Skills aus Bibliothek hinzugefuegt
Zweck umstrukturiert, Modell geaendert	Major: 1.0.0 -> 2.0.0	Umfang eingegrenzt, auf opus upgraded

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:

# Registry-Eintrag des Agenten finden
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:

# Pruefen ob ein Team diesen Agenten referenziert
grep -r "<agent-name>" teams/*.md

# Pruefen ob ein Leitfaden diesen Agenten referenziert
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: Einzeilige Beschreibung der fortgeschrittenen Variante
    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

# Frontmatter pruefen
head -20 agents/<agent-name>.md

# Skills auf Existenz pruefen
for skill in skill-a skill-b; do
  grep "id: $skill" skills/_registry.yml
done

# Agenten auf Festplatte vs. Registry zaehlen
ls agents/*.md | grep -v template | wc -l
grep total_agents agents/_registry.yml

# Alle Aenderungen ueberpruefen
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