skill-forge-evolve

Skill-Evolution & Verbesserung

Prozess

Schritt 1: Problem diagnostizieren

Fragen Sie den Benutzer oder analysieren Sie Logs, um die Problemkategorie zu identifizieren:

Kategorie A: Auslöseprobleme

• Zu schwache Auslösung: Skill aktiviert sich nicht, wenn er sollte
• Zu starke Auslösung: Skill aktiviert sich, wenn er nicht sollte
• Fehlauslösung: Falscher Sub-Skill wird aktiviert

Kategorie B: Ausführungsprobleme

• Unvollständige Workflows: Skill stoppt vor der Fertigstellung
• Falsche Ausgabe: Ergebnisse entsprechen nicht den Erwartungen
• Fehlende Fehlerbehandlung: Fehler werden nicht elegant behandelt
• Performance: Zu langsam oder zu viele Token verbraucht

Kategorie C: Architekturprobleme

• Fehlende Fähigkeit: Neuer Anwendungsfall nicht abgedeckt
• Skalierungsprobleme: Skill zu groß, benötigt Zerlegung
• Querverweisprobleme: Links zu nicht existierenden Dateien

Kategorie D: Qualitätsprobleme

• Inkonsistente Ergebnisse: Unterschiedliche Ausgaben für gleiche Eingabe
• Vage Anweisungen: Claude interpretiert jedes Mal anders
• Fehlende Beispiele: Keine konkrete Anleitung

Schritt 2: Fehlerbehebung nach Kategorie

Fehlerbehebung: Zu schwache Auslösung

1. Aktuelle Beschreibung lesen
2. Fehlende Triggerphrasen identifizieren
3. Domänenschlüsselwörter und Paraphrasen hinzufügen
4. Dateityperwähnungen hinzufügen, falls relevant
5. Mit 5 Abfragen testen, die jetzt auslösen sollten

Häufige Ursachen:

• Beschreibung zu generisch
• Fehlende gängige Paraphrasen
• Fachjargon ohne Laiensprache

Vorlage zur Fehlerbehebung:

# Vorher (zu schwache Auslösung)
beschreibung: Analysiert Codequalität

# Nachher (spezifische Trigger)
beschreibung: >
  Statische Code-Analyse und Qualitätsbewertung. Überprüft Codestil,
  Komplexität, Sicherheitslücken und Testabdeckung. Verwenden, wenn
  der Benutzer „Code-Review“, „Code-Qualität“, „Lint“, „Statische Analyse“,
  „Code Smell“, „Code-Audit“ oder „Überprüfe meinen Code“ sagt.

Fehlerbehebung: Zu starke Auslösung

1. Aktuelle Beschreibung lesen
2. Identifizieren, warum nicht verwandte Abfragen sie auslösen
3. Negative Trigger hinzufügen („NICHT verwenden für...“)
4. Beschreibung spezifischer machen
5. Mit 5 Abfragen testen, die NICHT auslösen sollten

Vorlage zur Fehlerbehebung:

# Vorher (zu starke Auslösung)
beschreibung: Verarbeitet Dokumente zur Überprüfung

# Nachher (spezifische + negative Trigger)
beschreibung: >
  Verarbeitet PDF-Rechtsdokumente zur Vertragsklausel-Extraktion und
  Compliance-Überprüfung. Verwenden für rechtliche Verträge, NDAs,
  AGBs. NICHT verwenden für allgemeine Dokumentenbearbeitung,
  Formatierung oder nicht-rechtliche PDFs.

Fehlerbehebung: Ausführungsprobleme

1. Den fehlschlagenden Schritt im Workflow identifizieren
2. Explizite Validierungsgates zwischen Schritten hinzufügen
3. Fehlerbehandlung mit klaren Wiederherstellungsanweisungen hinzufügen
4. „Wenn X fehlschlägt, dann Y“-Fallbackpfade hinzufügen
5. Ein Skript für fragile Operationen in Betracht ziehen

Fehlerbehebung: Qualitätsprobleme

1. Vage Anweisungen durch spezifische ersetzen
2. Konkrete Beispiele für erwartete Eingabe/Ausgabe hinzufügen
3. Explizite „Mach dies, nicht das“-Vergleiche hinzufügen
4. Qualitätsprüfschritte vor der endgültigen Ausgabe hinzufügen
5. Ein Validierungsskript in Betracht ziehen

Schritt 3: Iterations-Workspace-Protokoll

Verwenden Sie strukturierte Workspaces, um Verbesserungen über Iterationen hinweg zu verfolgen:

eval-workspace/
  iteration-1/          # Erste Version
    eval-0/with_skill/  # Eval-Ergebnisse
    eval-0/baseline/
    benchmark.json      # Aggregierte Metriken
    benchmark.md        # Lesbarer Bericht
    feedback.json       # Benutzerfeedback
  iteration-2/          # Nach erster Verbesserung
    eval-0/with_skill/
    eval-0/baseline/
    benchmark.json
    benchmark.md
    feedback.json

Die Iterationsschleife:

1. Wenden Sie die Fehlerbehebung auf den Skill an
2. Führen Sie /skill-forge eval <pfad> in iteration-<N+1>/ aus
3. Führen Sie /skill-forge benchmark <pfad> mit --previous iteration-<N>/ aus
4. Überprüfen Sie den Benchmark-Vergleich auf Regressionen
5. Sammeln Sie Benutzerfeedback in feedback.json
6. Lesen Sie das Feedback und iterieren Sie (zurück zu Schritt 2)

Hören Sie auf zu iterieren, wenn:

• Der Benutzer sagt, dass er zufrieden ist
• Alles Feedback leer ist (alles sieht gut aus)
• Der Benchmark zeigt keine sinnvollen Fortschritte zwischen Iterationen
• Die Bestehensquote die definierten Schwellenwerte erreicht

Schritt 3b: Selbstheilungsschleife

Für schnelle Fehlerbehebungen ohne vollständige Eval-Pipeline:

1. Wenden Sie die Fehlerbehebung an
2. Testen Sie mit dem ursprünglichen Fehlerfall
3. Testen Sie mit 3 anderen Fällen (Regressionstest)
4. Wenn die Fehlerbehebung funktioniert:
   -> Aktualisieren Sie die Anweisung/SKILL.md
   -> Dokumentieren Sie die Erkenntnis in Referenzen oder SKILL.md
5. Wenn die Fehlerbehebung fehlschlägt:
   -> Diagnostizieren Sie warum
   -> Versuchen Sie einen alternativen Ansatz
   -> Wiederholen

Schritt 3c: Beschreibungsoptimierungsschleife

Für Auslöseprobleme (Kategorie A) verwenden Sie die automatisierte Optimierungsschleife:

1. Eval-Set für Trigger generieren: python scripts/generate_eval_set.py <pfad>
2. Eval-Set mit dem Benutzer überprüfen und verfeinern
3. Optimierung ausführen: python scripts/optimize_description.py <pfad> --eval-set evals.json
4. Train/Test-Split-Ergebnisse und Verbesserungsvorschläge überprüfen
5. Vorgeschlagene Beschreibungsänderungen anwenden
6. Optimierung erneut ausführen, um die Verbesserung zu messen
7. Die Beschreibung mit der höchsten Testpunktzahl auswählen (nicht Train – vermeidet Overfitting)
8. Bis zu 5 Mal iterieren oder bis sich die Testpunktzahl einpendelt

Schritt 4: Architekturentwicklung

Wenn ein Skill seine Stufe überwächst:

Stufe 1 -> Stufe 2 (benötigt Skripte):

1. Identifizieren Sie die fragile/deterministische Operation
2. Erstellen Sie ein Skript in scripts/
3. Aktualisieren Sie SKILL.md, um auf das Skript zu verweisen
4. Testen Sie das Skript unabhängig

Stufe 2 -> Stufe 3 (benötigt Sub-Skills):

1. Identifizieren Sie unterschiedliche Workflows, die getrennt werden können
2. Extrahieren Sie jeden in ein eigenes skills/{parent}-{child}/SKILL.md
3. Aktualisieren Sie die Haupt-SKILL.md mit einer Routing-Tabelle
4. Verschieben Sie gemeinsames Wissen nach references/
5. Aktualisieren Sie install.sh

Stufe 3 -> Stufe 4 (benötigt Agenten):

1. Identifizieren Sie Workflows, die parallel ausgeführt werden können
2. Erstellen Sie Agentendefinitionen in agents/
3. Aktualisieren Sie den Audit/Full-Analysis-Sub-Skill, um an Agenten zu delegieren
4. Testen Sie die parallele Ausführung

Schritt 5: Versionsmanagement

Nach der Entwicklung:

1. Aktualisieren Sie metadata.version im Frontmatter (falls vorhanden)
2. Fügen Sie Erkenntnisse in SKILL.md oder einer Referenzdatei hinzu
3. Aktualisieren Sie alle betroffenen Querverweise
4. Führen Sie die Validierung erneut aus: python scripts/validate_skill.py <pfad>
5. Testen Sie den vollständigen Workflow Ende-zu-Ende

Häufige Entwicklungsmuster

Muster: Hinzufügen von Branchenerkennung

Wenn ein Skill das Verhalten je nach Benutzertyp anpassen muss:

## Branchenerkennung
Benutzertyp aus dem Kontext erkennen:
- **Typ A**: [Signale] -> [Verhalten]
- **Typ B**: [Signale] -> [Verhalten]

Muster: Hinzufügen von Qualitätsgates

Wenn die Ausgabequalität inkonsistent ist:

## Qualitätsgates
Vor der Ausgabe:
- [ ] [Prüfung 1]
- [ ] [Prüfung 2]
- [ ] [Prüfung 3]

Muster: Hinzufügen von Bewertung

Wenn Benutzer messbare Ausgaben benötigen:

## Bewertung (0-100)
| Kategorie | Gewichtung |
|-----------|------------|
| Kategorie A | 30 % |
| Kategorie B | 30 % |
| Kategorie C | 20 % |
| Kategorie D | 20 % |