skill-forge-eval

Skill-Evaluierungs-Pipeline

Führe strukturierte Evaluierungen gegen Claude Code Skills durch, um Auslösung, Korrektheit und Qualität mittels einer Multi-Agent-Pipeline zu verifizieren.

Ablauf

Schritt 1: Evaluierungssatz definieren

Akzeptiere Evaluierungsdefinitionen aus:

• Pfad zur Evaluierungs-JSON: evals/evals.json oder benutzerdefinierte Datei
• Inline-Eingabeaufforderungen: Benutzer gibt Evaluierungsabfragen direkt ein
• Automatisch generiert: Aus Skill-Beschreibung generieren (siehe Schritt 1b)

JSON-Schema für Evaluierungssatz:

{
  "skill_name": "mein-skill",
  "skill_path": "./mein-skill",
  "evals": [
    {
      "eval_id": 0,
      "eval_name": "beschreibender-name",
      "prompt": "Die Aufgabenaufforderung des Benutzers",
      "input_files": [],
      "assertions": [
        {
          "name": "ausgabe-hat-punktzahl",
          "check": "Die Ausgabe enthält eine numerische Punktzahl zwischen 0-100",
          "weight": 1.0
        }
      ],
      "should_trigger": true
    }
  ]
}

Schritt 1b: Evaluierungssatz automatisch generieren

Falls kein Evaluierungssatz vorhanden ist, generiere einen:

1. Lies die SKILL.md-Beschreibung und -Anweisungen des Skills
2. Führe python scripts/generate_eval_set.py <skill-pfad> aus, um einen Startsatz zu erstellen
3. Präsentiere den generierten Satz dem Benutzer zur Überprüfung und Bearbeitung
4. Benutzer genehmigt oder ändert vor dem Fortfahren

Schritt 2: Arbeitsbereich einrichten

Erstelle den Evaluierungs-Arbeitsbereich außerhalb des Skill-Verzeichnisses, um Verwechslungen von Evaluierungs-Artefakten mit Skill-Dateien zu vermeiden. Verwende ein benachbartes Verzeichnis oder einen dedizierten Ort:

eval-workspace/
  iteration-1/
    eval-0/
      eval_metadata.json        # Assertions und Konfiguration für diese Evaluierung
      with_skill/
        outputs/                # Ausgaben der Skill-Ausführung
        timing.json             # Token-Anzahl + Dauer
        grading.json            # Assertions-Ergebnisse + Belege
      baseline/
        outputs/
        timing.json
        grading.json
    eval-1/
      eval_metadata.json
      with_skill/
        outputs/
        timing.json
        grading.json
      baseline/
        outputs/
        timing.json
        grading.json
    benchmark.json              # Aggregierte Metriken
    benchmark.md                # Lesbarer Bericht

Erstelle für jedes Evaluierungsverzeichnis eval_metadata.json aus dem Eintrag des Evaluierungssatzes:

{
  "eval_id": 0,
  "eval_name": "beschreibender-name",
  "prompt": "Die Aufgabenaufforderung des Benutzers",
  "assertions": [...],
  "should_trigger": true
}

Schritt 3: Evaluierungsläufe ausführen

Für jede Evaluierung im Satz starte zwei parallele Läufe:

Lauf mit Skill (delegiere an agents/skill-forge-executor.md):

Führe diese Aufgabe aus:
- Skill-Pfad: <pfad-zum-skill>
- Aufgabe: <Evaluierungsaufforderung>
- Eingabedateien: <Evaluierungsdateien falls vorhanden, oder "keine">
- Speichere Ausgaben nach: <arbeitsbereich>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Zu speichernde Ausgaben: <worauf die Assertions prüfen>

Basislinien-Lauf (delegiere an agents/skill-forge-executor.md):

• Für neue Skills: Lauf ohne geladenen Skill
• Für verbesserte Skills: Lauf mit der vorherigen Version (erstelle zuerst einen Schnappschuss)

Speichere Zeitdaten in timing.json in jedem Laufverzeichnis:

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

Schritt 4: Ergebnisse benoten

Delegiere für jeden abgeschlossenen Lauf an agents/skill-forge-grader.md:

1. Benote gemäß den Assertions in eval_metadata.json
2. Speichere Ergebnisse in grading.json pro Lauf:

{
  "eval_id": 0,
  "run_type": "with_skill",
  "assertions": [
    {
      "name": "ausgabe-hat-punktzahl",
      "passed": true,
      "evidence": "Punktzahl gefunden: 87/100 in Zeile 14"
    }
  ],
  "pass_rate": 1.0
}

Schritt 5: Aggregieren und Analysieren

1. Führe python scripts/aggregate_benchmark.py <arbeitsbereich>/iteration-<N> --skill-name <name> aus

2. Dies erzeugt benchmark.json und benchmark.md mit:

   • Bestehensquote pro Evaluierung (mit Skill vs. Baseline)
   • Durchschnittliche Zeit und Token-Nutzung
   • Verbesserungsverhältnis (mit Skill / Baseline)

3. Delegiere an agents/skill-forge-analyzer.md um:

   • Muster aufzudecken, die aggregierte Statistiken verbergen könnten
   • Konsistent fehlschlagende Assertionstypen zu identifizieren
   • Regressionen aus vorherigen Iterationen zu kennzeichnen

Schritt 6: Ergebnisse präsentieren

Erstelle einen Zusammenfassungsbericht:

# Evaluierungsbericht: [skill-name] — Iteration [N]

## Gesamt
| Metrik | Mit Skill | Baseline | Differenz |
|--------|-----------|----------|-----------|
| Bestehensquote | X% | Y% | +Z% |
| Durchschnittszeit | Xs | Ys | -Zs |
| Durchschnitts-Token | X | Y | -Z |

## Ergebnisse pro Evaluierung
| Evaluierung | Mit Skill | Baseline | Status |
|-------------|-----------|----------|--------|
| eval-0 | BESTANDEN | FEHLGESCHLAGEN | Verbessert |
| eval-1 | BESTANDEN | BESTANDEN | Beibehalten |

## Muster & Erkenntnisse
[Vom Analyse-Agent]

## Empfehlungen
[Spezifische Verbesserungen basierend auf Fehlschlägen]

Schritt 7: Feedback sammeln

Speichere Benutzerfeedback in feedback.json:

{
  "reviews": [
    {
      "run_id": "eval-0-with_skill",
      "feedback": "dem Diagramm fehlen Achsenbeschriftungen",
      "timestamp": "2026-03-06T12:00:00Z"
    }
  ],
  "status": "complete"
}

Leite Feedback an /skill-forge evolve für die nächste Iteration weiter.

Erweitert: Blinder Vergleich

Für rigorose A/B-Tests zwischen Skill-Versionen:

1. Delegiere an agents/skill-forge-comparator.md
2. Übergib zwei Verzeichnisse: eval-<ID>/with_skill/outputs/ und eval-<ID>/baseline/outputs/
3. Der Vergleicher weist zufällige Bezeichnungen zu (Version A / Version B), sodass er nicht wissen kann, welche neu ist
4. Bewertet jede Ausgabe anhand der Assertions-Kriterien aus eval_metadata.json
5. Gibt Präferenzwerte zurück, ohne zu wissen, welche "neu" oder "alt" ist

Fehlerbehandlung

• Executor-Zeitüberschreitung: Überschreitet ein Lauf 5 Minuten, beende ihn und markiere als "timed_out": true in timing.json
• Executor-Fehler: Stürzt ein Lauf ab, speichere den Fehler in error.txt im Laufverzeichnis und fahre mit den verbleibenden Evaluierungen fort
• Bewertungsfehler: Kann die Bewertung Bestehen/Fehlschlagen nicht ermitteln, markiere Assertion als "passed": null mit Begründung
• Fehlende Dateien: Fehlt timing.json oder grading.json nach einem Lauf, kennzeichne die Evaluierung im Bericht als unvollständig
• Teilweise Fertigstellung: Aggregiere und berichte immer über die verfügbaren Ergebnisse — blockiere nicht wegen einer fehlgeschlagenen Evaluierung

Qualitätstore

Bevor ein Evaluierungslauf als abgeschlossen markiert wird:

• Alle Evaluierungen ausgeführt (mit Skill + Baseline)
• Zeitdaten für jeden Lauf erfasst
• Alle Assertions mit Beleg benotet
• Benchmark mit Bestehensquote, Zeit, Token aggregiert
• Analyse-Muster dokumentiert
• Ergebnisse dem Benutzer präsentiert