Skill Doctor – Skill-Diagnose-Tool
Ablauf
- Das angegebene Skill-Verzeichnis einlesen
- Auf das Vorhandensein der Kerndateien prüfen (SKILL.md, gotchas.md usw.)
- Skript aufrufen, um einen strukturierten Bericht zu erhalten:
python scripts/analyze_skill.py <skill_path> --output json– liefert Punktzahlen, Probleme und Vorschläge für jeden Prüfpunkt - Für jede niedrig bewertete Kategorie (<70 Punkte) werden zusätzlich konkrete Optimierungsvorschläge, erwartete Verbesserung und Aufwandsabschätzung ergänzt
- Alle optimierbaren Punkte auflisten und den Benutzer auswählen lassen, welche akzeptiert werden
- Akzeptierte Punkte einzeln optimieren (Dateien direkt ändern)
- Nach der Optimierung das Skript erneut ausführen, um einen Vorher-Nachher-Vergleich zu erstellen
Der Agent übernimmt die intelligente Schicht (Optimierungsvorschläge, Benutzerinteraktion, Änderungen), das Skript die stabile Schicht (Bewertungsberechnung, strukturierte Ausgabe). Siehe scripts/analyze_skill.py zur Verwendung.
Neun Prüfbereiche
| Prüfbereich | Prüfinhalt | Bestehenskriterium |
|---|---|---|
| description-Prüfung | Ist es als Auslösebedingung geschrieben, nicht als Funktionsbeschreibung? | Enthält Auslöse-Keywords, Länge < 100 Zeichen |
| gotchas-Prüfung | Gibt es eine Aufzeichnung von Fallstricken? | gotchas.md existiert und ist nicht leer |
| Dateiorganisations-Prüfung | Ist es nach der Dreiklassifikation organisiert? | Stammverzeichnis nur SKILL.md + gotchas.md + examples.md, Referenzmaterial in reference/, Skripte in scripts/, Konfiguration in config/ |
| Überrestriktions-Prüfung | Sind die Pfade übermäßig eingeschränkt? | Keine starren Abläufe wie „Schritt 1, Schritt 2“ |
| Bekanntes-Wissen-Prüfung | Werden dem Agenten bereits bekannte Inhalte wiederholt? | Keine Tutorials wie „Was ist X“, „Wie verwendet man Y“ |
| Speicherkonfigurations-Prüfung | Gibt es eine config.json? | config.json existiert mit sinnvoller Konfiguration |
| Skript-Prüfung | Wird ein Skript benötigt, fehlt aber? | Bei Bedarf an stabilen Fähigkeiten: scripts-Verzeichnis vorhanden |
| hooks-Prüfung | Sind die hooks korrekt konfiguriert? | PreToolUse/PostToolUse im richtigen Format |
| Markdown-Format-Prüfung | Ist das Format korrekt? | YAML, Tabellen, Codeblöcke korrekt formatiert |
Berichtsformat
{
"skill_name": "xxx",
"overall_score": 55,
"grade": "D",
"check_results": {
"description": {"score": 50, "issues": ["Als Funktionsbeschreibung geschrieben"], "suggestions": ["In Auslösebedingung umformulieren"], "expected_gain": 40},
"gotchas": {"score": 40, "issues": ["gotchas.md ist leer"], "suggestions": [["Mindestens 3 echte Fallstricke ergänzen"], "expected_gain": 50}
},
"optimization_options": [
{"id": 1, "item": "description", "current_score": 50, "expected_score": 90, "gain": 40,
"effort": "niedrig", "action": "Beschreibung in Auslösebedingung umschreiben",
"token_saved_per_call": 50, "time_saved_per_call_sec": 0},
{"id": 2, "item": "gotchas", "current_score": 40, "expected_score": 90, "gain": 50,
"effort": "mittel", "action": "Echte Fallstricke ergänzen",
"token_saved_per_call": 0, "time_saved_per_call_sec": 180}
],
"overall_after_accept_all": 85,
"total_benefits": {
"token_saved_per_call": 200,
"time_saved_per_call_sec": 300
}
}
Regeln zur Nutzenabschätzung
| Optimierungstyp | Token-Ersparnis (pro Aufruf) | Zeitersparnis (pro Aufruf) | Erläuterung |
|---|---|---|---|
| description kürzen | Pro überflüssigem Zeichen × 1 Token | — | Reduziert Context-Ladung |
| gotchas ergänzen | — | 2–5 Minuten pro Fallstrick | Vermeidet wiederholtes Debuggen von Fallstricken |
| Dateien aufteilen | (Ursprungszeilen - neue Zeilen) × 3 Tokens | — | Referenzmaterial in reference/ verschieben, nur bei Bedarf laden, nicht im Context |
| Überrestriktionen → Entscheidungsrahmen | Pro starrem Schritt × 20 Tokens | 10–30 Sekunden pro Schritt | Reduziert Ausführung unnötiger Schritte |
| Bekanntes Wissen löschen | Länge des Tutorial-Abschnitts in Tokens | — | Vermeidet Wiederholung von Agenten-bekannten Inhalten |
| Skript-Kapselung | — | 1–3 Minuten pro Durchlauf | Vermeidet, dass der Agent jedes Mal denselben Code neu schreibt |
Die Nutzenangaben sind Schätzwerte pro Aufruf; die tatsächlichen Werte variieren je nach Skill-Inhalt und Nutzungsweise.
Hinweis zur „Zeitverschwendung“: Die im Bericht genannte „Zeit“ bezieht sich auf zusätzliche Verluste durch Designfehler, nicht auf die Gesamtausführungszeit des Skills. Im Einzelnen:
- Fehlende gotchas → Agent fällt wiederholt in Fallstricke und debuggt (2–5 Minuten pro Durchlauf)
- Überrestriktionen → Agent führt sinnlose starre Schritte aus (10–30 Sekunden pro Schritt)
- Fehlende Skripte → Agent schreibt denselben Code jedes Mal neu (1–3 Minuten pro Durchlauf)
Vergleichslogik: Wert vor Optimierung = Summe dieser Verluste; nach Optimierung Verluste auf null → ~0; „Ersparnis“ = eliminierte Verlustmenge. Nach der Optimierung benötigt die Skill-Ausführung selbst noch Zeit, aber diese zusätzlichen Verluste treten nicht mehr auf.
Darstellung der Optimierungsvorschläge
Nach der Berichterstellung werden die optimierbaren Punkte als Liste dem Benutzer präsentiert, jeder Punkt enthält:
### 🔧 Optimierbare Punkte
| # | Prüfbereich | Aktuell | Erwartet | Steigerung | Aufwand | Token/Aufruf | Zeit/Aufruf | Aktion |
|---|------------|--------|----------|------------|--------|-------------|-------------|--------|
| 1 | description | 50 | 90 | +40 | niedrig | ~50 | — | In Auslösebedingung umschreiben |
| 2 | gotchas | 40 | 90 | +50 | mittel | — | ~3min | Echte Fallstricke ergänzen |
| ... | ... | ... | ... | ... | ... | ... | ... | ... |
**Nach Akzeptieren aller Optimierungen**: 55 Punkte (D) → 85 Punkte (B), Steigerung um 30 Punkte
### 📈 Gesamtnutzen (pro Aufruf)
- Token-Ersparnis: ~200/Aufruf
- Zeitersparnis: ~5 Minuten/Aufruf
- Fallstrickvermeidung: Nach Ergänzung der gotchas häufige Fehler vermeidbar
> **Hinweis zur Zeitstatistik**: Die hier genannte „Zeitersparnis“ bezieht sich auf **zusätzliche Verluste durch Designfehler**, nicht auf die Gesamtausführungszeit des Skills:
> - Fehlende gotchas → Agent fällt wiederholt in Fallstricke und debuggt (2–5 Minuten pro Durchlauf)
> - Überrestriktionen → Agent führt sinnlose starre Schritte aus (10–30 Sekunden pro Schritt)
> - Fehlende Skripte → Agent schreibt denselben Code jedes Mal neu (1–3 Minuten pro Durchlauf)
> - Wert vor Optimierung = Summe der Verluste, nach Optimierung Verluste auf null, „Ersparnis“ = eliminierte Verlustmenge
Bitte wählen Sie:
- **„Alle akzeptieren“** – Optimiert alle Punkte auf einmal
- **„Akzeptiere 1,3“** – Optimiert nur die ausgewählten Punkte
- **„Überspringen“** – Nur Bericht ansehen, keine Optimierung
Ausführung nach Benutzerbestätigung
- Nach Auswahl durch den Benutzer werden die entsprechenden Dateien Punkt für Punkt geändert
- Nach jedem abgeschlossenen Punkt wird der Status markiert
- Nach Abschluss aller Änderungen wird der Gesundheitscheck erneut ausgeführt, um einen Vergleichsbericht zu erstellen
Format des Vorher-Nachher-Vergleichsberichts
## 📊 Vergleich vor und nach der Optimierung
| Prüfbereich | Vorher | Nachher | Änderung |
|------------|--------|---------|----------|
| description | 50 (Funktionsbeschreibung) | 90 (Auslösebedingung) | +40 ⬆️ |
| gotchas | 40 (leer) | 90 (gefüllt) | +50 ⬆️ |
| ... | ... | ... | ... |
| **Gesamt** | **55 (D)** | **85 (B)** | **+30 ⬆️** |
### 📈 Gesamtnutzen (pro Aufruf)
| Dimension | Vorher | Nachher | Ersparnis |
|-----------|--------|---------|-----------|
| Token | ~800/Aufruf | ~600/Aufruf | ~200/Aufruf |
| Zeitverschwendung | ~5min | ~0 | ~5min |
| Hauptdatei | 466 Zeilen | 75 Zeilen | -84% |
> Zeitverschwendung = Zusätzlicher Aufwand durch Designfehler (Fallstrick-Debugging, redundante Schritte usw.), nicht die Gesamtausführungszeit des Skills. Siehe [Regeln zur Nutzenabschätzung](#regeln-zur-nutzenabschätzung).
### Geänderte Dateien
- `SKILL.md` – Beschreibung umgeschrieben
- `gotchas.md` – 5 echte Fallstricke ergänzt
Vollständiges Interaktionsbeispiel
Siehe examples.md, Beispiel 9
Bewertungsstufen
- A (90–100 Punkte) – Ausgezeichnet, alle Best Practices eingehalten
- B (75–89 Punkte) – Gut, geringer Optimierungsspielraum
- C (60–74 Punkte) – Ausreichend, deutliche Verbesserungspunkte
- D (<60 Punkte) – Nicht bestanden, Überarbeitung erforderlich
Detaillierte Checkliste
Siehe checklists.md
Häufige Fallstricke
Siehe gotchas.md
Optimierungsbeispiele
Siehe examples.md
Skript
Die Kernlogik des Gesundheitschecks ist in scripts/analyze_skill.py gekapselt. Der Agent ruft es auf, um strukturierte Bewertungen zu erhalten:
python scripts/analyze_skill.py <skill_path> --output json # Schritt 3: Bewertungsbericht abrufen
python scripts/analyze_skill.py <skill_path> --output markdown # Optional: menschenlesbarer Bericht
Das Skript übernimmt: Bewertungsberechnung, Problemprüfung, Stufenbestimmung (stabile Schicht) Der Agent übernimmt: Optimierungsvorschläge generieren, Benutzerinteraktion, Dateiänderungen ausführen (intelligente Schicht)