Evolve Skill

Bestehenden Skill weiterentwickeln

Einen Skill verbessern, erweitern oder eine fortgeschrittene Variante eines Skills erstellen, der urspruenglich mit create-skill verfasst wurde. Dieses Verfahren behandelt die Wartungsseite des Skill-Lebenszyklus: Luecken bewerten, gezielte Verbesserungen anwenden, Versionen erhoehen und Registry sowie Querverweise synchron halten.

Wann verwenden

• Verfahrensschritte eines Skills sind nach Werkzeugaenderungen veraltet oder unvollstaendig
• Nutzer-Feedback zeigt fehlende Fallstricke, unklare Schritte oder schwache Validierung
• Ein Skill muss von basic zu intermediate (oder intermediate zu advanced) wachsen
• Eine fortgeschrittene Variante wird neben dem Original benoetigt (z.B. create-r-package und create-r-package-advanced)
• Verwandte Skills wurden hinzugefuegt oder entfernt und Querverweise sind veraltet

Eingaben

• Erforderlich: Pfad zur bestehenden SKILL.md zur Weiterentwicklung
• Erforderlich: Weiterentwicklungsausloser (Feedback, Werkzeugaenderung, Komplexitaets-Upgrade, neue verwandte Skills, entdeckte Fallstricke)
• Optional: Ziel-Komplexitaetsstufe bei Aenderung (basic, intermediate, advanced)
• Optional: Ob stattdessen eine fortgeschrittene Variante erstellt werden soll (Standard: direkt verfeinern)

Vorgehensweise

Schritt 1: Den aktuellen Skill bewerten

Die bestehende SKILL.md lesen und jeden Abschnitt gegen die Qualitaetscheckliste bewerten:

# Read the skill
cat skills/<skill-name>/SKILL.md

# Check frontmatter parses
head -20 skills/<skill-name>/SKILL.md

# Verify related skills still exist
grep -oP '`[\w-]+`' skills/<skill-name>/SKILL.md | sort -u

Erwartet: Eine Liste spezifischer Luecken, Schwachstellen oder Verbesserungsmoeglichkeiten.

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

Schritt 2: Weiterentwicklungsanforderungen sammeln

Identifizieren und kategorisieren, was die Weiterentwicklung ausgeloest hat:

Die spezifischen Aenderungen vor der Bearbeitung dokumentieren. Jede Aenderung mit ihrem Zielabschnitt auflisten.

Erwartet: Eine konkrete Liste von Aenderungen (z.B. "On failure zu Schritt 4 hinzufuegen", "Neuen Schritt 6 fuer Randfaell X hinzufuegen", "Related Skills um new-skill erweitern").

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 wenn Qualitaet verbessert, Luecken behoben oder bescheidene neue Inhalte hinzugefuegt werden. Der Skill behaelt seine Identitaet.

Variante: Waehlen wenn die weiterentwickelte Version doppelt so lang waere, die Zielgruppe aendern oder wesentlich andere Eingaben erfordern wuerde. Das Original bleibt fuer einfachere Anwendungsfaelle unveraendert.

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

Bei Fehler: Falls unsicher, Standard-Verfeinerung verwenden. Eine Variante kann spaeter immer extrahiert werden; es ist schwieriger, eine wieder zusammenzufuehren.

Schritt 4: Inhaltliche Aenderungen anwenden

Fuer Verfeinerungen

Die bestehende SKILL.md direkt bearbeiten:

• Zur Bearbeitung oeffnen
• Verfahrensschritte hinzufuegen/ueberarbeiten
• Expected/On-failure-Paare staerken
• Tabellen oder Beispiele hinzufuegen
• Ausloser fuer "When to Use" aktualisieren
• Inputs ueberarbeiten, falls sich Umfang geaendert hat

Diese Bearbeitungsregeln befolgen:

• Alle bestehenden Abschnitte erhalten — Inhalte hinzufuegen, keine Abschnitte entfernen
• Schritt-Nummerierung nach Einfuegungen fortlaufend halten
• Jeder neue oder geaenderte Schritt muss sowohl Expected als auch On failure haben
• Neue Fallstricke ans Ende des Abschnitts Common Pitfalls
• Neue verwandte Skills ans Ende des Abschnitts Related Skills

Fuer Varianten

# Create the variant directory
mkdir -p skills/<skill-name>-advanced/

# Copy the original as a starting point
cp skills/<skill-name>/SKILL.md skills/<skill-name>-advanced/SKILL.md

# Edit the variant:
# - Change `name` to `<skill-name>-advanced`
# - Update `description` to reflect the advanced scope
# - Raise `complexity` (e.g., intermediate → advanced)
# - Reset `version` to "1.0"
# - Add/expand procedure steps for the advanced use case
# - Reference the original in Related Skills as a prerequisite

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

Bei Fehler: Falls eine Schrittbearbeitung 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 Skill existieren, und sie auf den neuen Stand der Quelle aktualisieren:

# Check for existing translations
ls i18n/*/skills/<skill-name>/SKILL.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/*/skills/<skill-name>/SKILL.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(<skill-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 neu anlegen.

Schritt 5: Version und Metadaten aktualisieren

Das Feld version im Frontmatter gemaess Semver-Konventionen erhoehen:

Auch aktualisieren:

• complexity falls der Umfang erweitert wurde (z.B. basic -> intermediate)
• tags falls sich der Abdeckungsbereich geaendert hat
• description falls sich der Skill-Umfang wesentlich geaendert hat

Erwartet: Frontmatter-version spiegelt die Groesse der Aenderungen wider. Neue Varianten beginnen bei "1.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

Keine Registry-Aenderungen erforderlich (Pfad unveraendert). Querverweise nur aktualisieren, wenn sich Related Skills in anderen Skills geaendert haben:

# Check if any skill references the evolved skill
grep -r "<skill-name>" skills/*/SKILL.md

Fuer Varianten

Den neuen Skill zu skills/_registry.yml hinzufuegen:

- id: <skill-name>-advanced
  path: <skill-name>-advanced/SKILL.md
  complexity: advanced
  language: multi
  description: One-line description of the advanced variant

Dann:

1. total_skills am Anfang der Registry hochzaehlen
2. Querverweis zu Related Skills im urspruenglichen Skill hinzufuegen, der auf die Variante zeigt
3. Querverweis zu Related Skills in der Variante hinzufuegen, der auf das Original zeigt
4. Symlinks fuer Slash-Command-Entdeckung erstellen:

# Project-level
ln -s ../../skills/<skill-name>-advanced .claude/skills/<skill-name>-advanced

# Global
ln -s /mnt/d/dev/p/agent-almanac/skills/<skill-name>-advanced ~/.claude/skills/<skill-name>-advanced

Erwartet: Registry-total_skills stimmt mit find skills -name SKILL.md | wc -l ueberein. Querverweise sind bidirektional.

Bei Fehler: Falls die Registry-Zaehlung falsch ist, find skills -name SKILL.md | wc -l ausfuehren, um die wahre Zaehlung zu ermitteln und die Registry zu korrigieren.

Schritt 7: Den weiterentwickelten Skill validieren

Die vollstaendige Validierungscheckliste durchfuehren:

• SKILL.md existiert am erwarteten Pfad
• YAML-Frontmatter wird fehlerfrei geparst
• version wurde erhoehen (Verfeinerung) oder auf "1.0" gesetzt (Variante)
• Alle Abschnitte vorhanden: When to Use, Inputs, Procedure, Validation, Common Pitfalls, Related Skills
• Jeder Verfahrensschritt hat Expected- und On-failure-Bloecke
• Related Skills verweisen auf gueltige, existierende Skill-Namen
• Registry-Eintrag existiert mit korrektem Pfad (nur Varianten)
• total_skills-Zaehlung stimmt mit tatsaechlicher Skill-Anzahl auf der Festplatte ueberein
• Symlinks loesen sich korrekt auf (nur Varianten)
• git diff zeigt keine versehentlichen Loeschungen aus dem urspruenglichen Inhalt

# Verify frontmatter
head -20 skills/<skill-name>/SKILL.md

# Count skills on disk vs registry
find skills -name SKILL.md | wc -l
grep total_skills skills/_registry.yml

# Check symlinks (for variants)
ls -la .claude/skills/<skill-name>-advanced
readlink -f .claude/skills/<skill-name>-advanced/SKILL.md

# Review all changes
git diff

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

Bei Fehler: Jeden fehlschlagenden Punkt einzeln adressieren. Das haeufigste Post-Weiterentwicklungs-Problem ist ein veralteter total_skills-Zaehler — immer zuletzt pruefen.

Validierung

• SKILL.md existiert und hat gueltiges YAML-Frontmatter
• version-Feld spiegelt die vorgenommenen Aenderungen wider
• Alle Verfahrensschritte haben Expected- und On-failure-Bloecke
• Related-Skills-Referenzen sind gueltig (keine fehlerhaften Querverweise)
• Registry-total_skills stimmt mit tatsaechlicher Zaehlung auf der Festplatte ueberein
• Fuer Varianten: neuer Eintrag in _registry.yml mit korrektem Pfad
• Fuer Varianten: Symlinks erstellt unter .claude/skills/ und ~/.claude/skills/
• 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 immer im Frontmatter vor dem Committen aktualisieren.
• Versehentliche Inhaltsloesch: Beim Umstrukturieren von Schritten ist es leicht, einen On-failure-Block oder eine Tabellenzeile zu verlieren. Immer git diff vor dem Committen ueberpruefen.
• Veraltete Querverweise: Beim Erstellen einer Variante muessen sowohl das Original als auch die Variante aufeinander verweisen. Einseitige Verweise lassen den Graphen unvollstaendig.
• Registry-Zaehlerabweichung: Nach dem Erstellen einer Variante muss der total_skills-Zaehler hochgezaehlt werden. Dieses Vergessen verursacht Validierungsfehler in anderen Skills.
• Umfangs-Creep bei der Verfeinerung: Eine Verfeinerung, die die Laenge des Skills verdoppelt, sollte wahrscheinlich eine Variante sein. Falls mehr als 3 neue Verfahrensschritte hinzugefuegt werden, die Umfangsentscheidung aus Schritt 3 nochmals ueberdenken.
• git mv auf NTFS-gemounteten Pfaden vermeiden (WSL): Auf /mnt/-Pfaden kann git mv fuer Verzeichnisse fehlerhafte Berechtigungen erstellen. Stattdessen mkdir -p + Dateien kopieren + git rm des alten Pfades verwenden.

Verwandte Skills

• create-skill — Grundlage fuer das Verfassen neuer Skills; evolve-skill setzt voraus, dass dies urspruenglich befolgt wurde
• commit-changes — den weiterentwickelten Skill mit einer beschreibenden Nachricht committen
• configure-git-repository — versionskontrollierte Skill-Aenderungen
• security-audit-codebase — weiterentwickelte Skills auf versehentlich enthaltene Geheimnisse pruefen