Bestehenden Agenten weiterentwickeln

Einen Agenten verbessern, erweitern oder eine fortgeschrittene Variante eines Agenten erstellen, der urspruenglich mit

create-agent

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

name

description

tools

model

version

author

tags

version

priority

skills

# 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

Schritt 2: Weiterentwicklungsanforderungen sammeln

Identifizieren und kategorisieren, was die Weiterentwicklung ausgeloest hat:

analyze-api-security

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:

<agent>-advanced

<agent>-<specialty>

.md

agents/

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

git checkout -- <file>

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

npm run translation:status

Bei Fehler: Falls

sed

source_commit

npm run translate:scaffold -- agents

Schritt 5: Version und Metadaten aktualisieren

Das Feld

version

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

updated

"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

# Registry-Eintrag des Agenten finden
grep -A 10 "id: <agent-name>" agents/_registry.yml

Felder

description

tags

tools

skills

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

  - 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

Bei Fehler: Eintraege zaehlen mit

grep -c "^  - id:" agents/_registry.yml

total_agents

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

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