Skill-Benchmarking & Performance-Tracking

Was macht Skill-Benchmarking & Performance-Tracking?

Misst und vergleicht die Performance von Skills über mehrere Iterationen hinweg mit statistischer Genauigkeit durch Mehrfachdurchläufe, Varianzanalyse und Trendverfolgung.

Ablauf

Schritt 1: Benchmark-Konfiguration definieren

Die Konfiguration wird akzeptiert als:

• Vorhandener Evaluierungssatz: Pfad zu evals/evals.json (aus /skill-forge eval)
• Benchmark-Konfiguration: Benutzerdefinierte Konfiguration mit Anzahl der Durchläufe und Schwellwerten

Benchmark-Konfigurationsschema:

{
  "skill_name": "my-skill",
  "skill_path": "./my-skill",
  "eval_set_path": "./evals/evals.json",
  "trials_per_eval": 3,
  "baseline_type": "no_skill",
  "previous_benchmark": null,
  "thresholds": {
    "min_pass_rate": 0.8,
    "max_avg_tokens": 100000,
    "max_avg_duration_seconds": 120,
    "min_improvement_ratio": 1.0
  }
}

Schritt 2: Benchmark-Durchläufe ausführen

Für jede Evaluierung wird trials_per_eval Mal (Standard: 3) ausgeführt, um zuverlässige Metriken zu erhalten:

1. Durchläufe mit Skill ausführen (3x pro Evaluierung)
2. Basislinien-Durchläufe ausführen (3x pro Evaluierung)
3. Pro Durchlauf erfassen: Bestanden/Fehlgeschlagen, Token-Anzahl, Dauer
4. Jedes timing.json und grading.json des Durchlaufs speichern

Verwende agents/skill-forge-executor.md für parallele Ausführung, wo möglich.

Schritt 3: Ergebnisse aggregieren

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

Ausgabe benchmark.json Schema:

{
  "skill_name": "my-skill",
  "iteration": 1,
  "timestamp": "2026-03-06T12:00:00Z",
  "summary": {
    "total_evals": 10,
    "with_skill": {
      "pass_rate": 0.87,
      "pass_rate_std": 0.05,
      "avg_tokens": 45000,
      "avg_duration_seconds": 34.2
    },
    "baseline": {
      "pass_rate": 0.60,
      "pass_rate_std": 0.08,
      "avg_tokens": 62000,
      "avg_duration_seconds": 52.1
    },
    "improvement_ratio": 1.45,
    "token_savings_ratio": 0.73,
    "time_savings_ratio": 0.66
  },
  "per_eval": [
    {
      "eval_id": 0,
      "eval_name": "basic-trigger",
      "with_skill": {"pass_rate": 1.0, "avg_tokens": 30000, "avg_duration_seconds": 20.1},
      "baseline": {"pass_rate": 0.67, "avg_tokens": 50000, "avg_duration_seconds": 45.0},
      "trials": 3
    }
  ],
  "thresholds_met": {
    "min_pass_rate": true,
    "max_avg_tokens": true,
    "max_avg_duration_seconds": true,
    "min_improvement_ratio": true
  }
}

Schritt 4: Mit vorherigen Iterationen vergleichen

Falls previous_benchmark angegeben ist oder eine vorherige iteration-<N-1> existiert:

1. Vorherige benchmark.json laden
2. Delta pro Metrik berechnen:
   • Änderung der Bestehensrate
   • Änderung der Token-Nutzung
   • Änderung der Dauer
   • Neue Regressionen (Evaluierungen, die vorher bestanden wurden, jetzt aber fehlschlagen)
   • Neue Verbesserungen (Evaluierungen, die vorher fehlschlugen, jetzt aber bestanden werden)

Schritt 5: Benchmark-Bericht generieren

# Benchmark-Bericht: [skill-name]

## Iteration [N] vs [N-1]

### Zusammenfassung
| Metrik | Aktuell | Vorher | Delta | Schwellwert | Status |
|--------|---------|--------|-------|-------------|--------|
| Bestehensrate | 87% | 78% | +9% | >= 80% | BESTANDEN |
| Durchschn. Tokens | 45K | 52K | -13% | <= 100K | BESTANDEN |
| Durchschn. Zeit | 34s | 41s | -17% | <= 120s | BESTANDEN |
| Verbesserung | 1,45x | 1,30x | +0,15x | >= 1,0x | BESTANDEN |

### Regressionen (Handlungsbedarf)
| Evaluierung | Vorher | Aktuell | Hinweise |
|-------------|--------|---------|----------|
| eval-5 | BESTANDEN | FEHLGESCHLAGEN | Ausgabe fehlt erforderlicher Abschnitt |

### Verbesserungen
| Evaluierung | Vorher | Aktuell | Hinweise |
|-------------|--------|---------|----------|
| eval-3 | FEHLGESCHLAGEN | BESTANDEN | Fehlerbehandlung funktioniert jetzt |

### Details pro Evaluierung
[Detaillierte Aufschlüsselungstabelle]

### Varianzanalyse
| Evaluierung | Bestehensrate | Std.-Abw. | Durchläufe | Zuverlässigkeit |
|-------------|---------------|-----------|------------|-----------------|
| eval-0 | 100% | 0,00 | 3 | Hoch |
| eval-1 | 67% | 0,47 | 3 | Niedrig (untersuchen) |

### Empfehlungen
[Basiert auf Regressionen, Evaluierungen mit geringer Zuverlässigkeit und Schwellwertverletzungen]

Schritt 6: Schwellwertprüfung

Falls ein Schwellwert nicht erfüllt wird:

1. Als FEHLGESCHLAGEN markieren mit Angabe der spezifischen Schwellwertdetails
2. Auflisten, welche Evaluierungen den Fehler verursacht haben
3. Empfehlen, /skill-forge evolve auszuführen, um die Probleme zu beheben
4. Nicht zur Veröffentlichung freigeben, bis Schwellwerte erfüllt sind

Fehlerbehandlung

• Unbeständige Durchläufe: Falls ein Durchlauf ausfällt oder abstürzt, wird er von der Varianzberechnung ausgeschlossen und "trials_completed" vs "trials_requested" in den Ergebnissen pro Evaluierung vermerkt
• Unzureichende Durchläufe: Falls weniger als 2 Durchläufe für eine Evaluierung abgeschlossen werden, wird die Varianz im Bericht als "unreliable" markiert
• Fehlende Basislinie: Falls Basislinien-Durchläufe vollständig fehlschlagen, werden nur Ergebnisse mit Skill ausgegeben und improvement_ratio übersprungen
• Schwellwert-Grenzfälle: Falls die Bestehensrate exakt dem Schwellwert entspricht, wird sie als BESTANDEN behandelt

Integration mit anderen Sub-Skills

• skill-forge-eval: Stellt den Evaluierungssatz und die Bewertungsinfrastruktur bereit
• skill-forge-evolve: Erhält Benchmark-Fehlschläge als Verbesserungsziele
• skill-forge-publish: Erfordert bestandenen Benchmark (Punktzahl >= Schwellwerte) vor der Veröffentlichung
• skill-forge-review: Kann Benchmark-Zusammenfassung in den Überprüfungsbericht aufnehmen