skill-audit

Was macht skill-audit?

Statische Analyse von SKILL.md gegen den V3-Standard (LLM-kompatibel). Führt 10 QA-Prüfungen durch, erkennt mechanische und semantische Probleme und liefert einen priorisierten Bericht. Besonders nützlich für Nutzer, die von Claude vor Version 4.5 migriert haben – ältere Skills funktionieren oft nur im Kontext des Autors, nicht in externen Agenten.

---

Wann verwenden

Auslösen bei:

• Nutzer hat eine Skill, die „nicht auslöst“ oder „nicht richtig funktioniert“
• Migration von Claude 3.x / 4.0 auf 4.6+ und fehlerhaftes Verhalten festgestellt
• Skill soll auf GPT-5, Gemini oder einem anderen LLM als Claude ausgeführt werden
• Erstellung von Skills in großen Mengen (z. B. für Schüler, Team, Community)
• Priorisierung der zu reparierenden Skills in einer Sammlung

Beispiele für auslösende Nachrichten:

• „führe skill-audit auf skills/my-skill/SKILL.md aus“
• „meine Skill löst auf GPT nicht aus“
• „prüfe diesen Ordner mit Skills für mich“
• „skill-audit ./skills“
• „warum funktioniert diese Skill auf Claude, aber nicht auf Gemini?“

Wann NICHT verwenden

NICHT auslösen, wenn:

• Nutzer eine NEUE Skill ERSTELLEN möchte → createskill oder skill-creator verwenden
• Nutzer die geprüfte Skill AUSFÜHREN möchte → Skill direkt ausführen
• Nutzer eine Sicherheitsüberprüfung (OWASP, Secrets in Produktion) wünscht → anderes Tool
• Ziel-Datei nicht SKILL.md ist (z. B. Python-Skript, README) → generische Refaktorierung

---

Eingaben

Parameter	Typ	Erforderlich	Beschreibung
path	string	✅	Pfad zu einer SKILL.md ODER zu einem Ordner mit Unterordnern, die SKILL.md enthalten (rekursiv)
format	string	❌	markdown (Standard) oder json – Format des Berichts

Ausgaben

Feld	Typ	Beschreibung
score	int 0-10	Anzahl der bestandenen QA-Prüfungen
issues	array	Priorisierte Liste von Problemen (z. B. desc_no_triggers, examples_too_few)
by_category	object	Durchschnittliche Bewertung und Bestehensquote pro Skill-Kategorie
report	markdown	Vollständiger Bericht mit Rangliste und Detailangaben pro Skill

Ausgabeformat: Markdown-Datei unter ./audit-results.md + Zusammenfassung im Terminal.

---

Workflow

1. Eingabe validieren – Existiert der Pfad? Ist es eine .md-Datei oder ein Verzeichnis?
2. SKILL.md-Dateien sammeln
   • Wenn der Pfad auf eine .md-Datei zeigt → einzelne Liste
   • SONST → Rekursive glob-Suche nach **/SKILL.md im Verzeichnis
3. Für jede SKILL.md:
   • YAML-Frontmatter parsen (--- ... ---)
   • Aufteilen des Bodies in H2-Abschnitte (H2 innerhalb von Code-Fences ``` oder ~~~ ignorieren)
   • Die 10 QA-Prüfungen ausführen
   • Score + Issues + Zählungen erfassen
4. Ergebnisse aggregieren – Durchschnittliche Bewertung, Verteilung, häufigste Issues
5. Markdown-Bericht erstellen unter ./audit-results.md mit:
   • Gesamtzusammenfassung
   • Score-Verteilung
   • Issues nach Häufigkeit
   • Top 30 Skills mit dem größten Reparaturbedarf
   • Detailangaben pro Skill
6. Zusammenfassung im Terminal ausgeben – Gesamtzahl, Durchschnittsbewertung, Bestehensquote ≥7

Die 10 QA-Prüfungen

1. Name in kebab-case und stimmt mit dem Ordnernamen überein
2. Beschreibung: 50+ Wörter, dritte Person, 5+ Trigger-Phrasen, negative Abgrenzungen
3. Jeder Schritt des Workflows ist eine einzelne, imperative, eindeutige Aktion
4. 2+ konkrete Beispiele (echte Eingabe → echte Ausgabe)
5. Edge Cases abgedeckt (3+ Bedingungen)
6. Ausgabeformat explizit definiert
7. Keine vage Sprache (Liste verbotener Wörter in references/qa-checklist.md)
8. Negative Abgrenzungen im Abschnitt „## When NOT to Use“
9. Keine hartcodierten Anmeldedaten (Secrets, API-Keys, Tokens)
10. Ordner evals/evals.json existiert mit 2+ Fällen

---

Edge Cases

• Wenn der Pfad nicht existiert → Exit 1 mit Meldung „Pfad nicht gefunden: {path}"
• Wenn das Verzeichnis leer ist (0 SKILL.md) → Exit 0 mit Meldung „Keine SKILL.md gefunden in {path}"
• Wenn SKILL.md kein YAML-Frontmatter enthält → Score 0, Issue missing_frontmatter
• Wenn YAML ungültig ist → Score 0, Issue yaml_parse_error
• Wenn der Ordner evals/ existiert, aber kein evals.json enthält → Issue no_evals_folder
• Wenn SKILL.md zu groß ist (>350 Zeilen) → Warning long, empfiehlt Auslagerung von Inhalten nach references/
• Wenn in Markdown-Links ein Platzhalter (link, url, path) verwendet wird → ignoriert (gilt nicht als defekter Verweis)

---

Beispiele

Beispiel 1 – Einzelne Skill prüfen

Echte Eingabe: skill-audit ./my-skill/SKILL.md

Ausgeführter Workflow:

1. Überprüfung, ob ./my-skill/SKILL.md existiert
2. YAML parsen – findet name: my-skill, Beschreibung mit 32 Wörtern
3. Body aufgeteilt: Hat ## When to Use, fehlt ## When NOT to Use
4. 10 Prüfungen ausführen: Beschreibung zu kurz (32w<50), keine Negativbeispiele, kein evals-Ordner, nur 1 Beispiel
5. Bericht erstellen

Echte Ausgabe:

skill-audit: 1 Skill analysiert
  my-skill — 6/10 (232L, 32w desc, 4 triggers, 1 ex, 4 edge, evals ✗)
  Issues: desc_too_short(32w), desc_no_negatives, examples_too_few(1), no_evals_folder

Bericht: ./audit-results.md

Beispiel 2 – Ganzen Ordner prüfen (Edge Case: mehrere Skills)

Echte Eingabe: skill-audit ~/my-claude-skills/

Ausgeführter Workflow:

1. Überprüfung, ob ~/my-claude-skills/ ein Verzeichnis ist
2. Glob findet 12 SKILL.md
3. Für jede: Parsen + Prüfungen + Score
4. Aggregieren: Durchschnittsbewertung 7.1, 4/12 bestanden (≥7)
5. Priorisierter Bericht: Schlechteste zuerst

Echte Ausgabe:

skill-audit: 12 Skills analysiert
  Durchschnittsbewertung: 7.1/10
  Bestanden (≥7): 4/12 (33%)

Top 3 häufigste Issues:
  desc_no_negatives (12, 100%)
  no_evals_folder (9, 75%)
  desc_too_short (7, 58%)

Schlechteste Skills:
  1. legacy-skill-x — 3/10
  2. migrated-from-gpt — 4/10
  3. old-claude35-skill — 5/10

Bericht: ./audit-results.md

---

Abhängigkeiten

• Laufzeit: Python 3.8+
• Bibliotheken: Nur Stdlib (re, json, pathlib, argparse, collections)
• APIs: Keine – 100% statisch/offline
• Dateien: templates/SKILL-TEMPLATE.md + references/qa-checklist.md (schreibgeschützt)
• Andere Skills: Keine – eigenständiges Tool

---

Fehler & Behebung

Fehler	Ursache	Lösung
Pfad nicht gefunden	Ungültiger oder falsch geschriebener Pfad	Absoluten Pfad überprüfen; mit ls {path} bestätigen
yaml.YAMLError	Fehlerhaftes Frontmatter	SKILL.md öffnen, Einrückung und schließendes --- prüfen
UnicodeDecodeError	SKILL.md in nicht-UTF8-Kodierung	Im Editor als UTF-8 speichern
ModuleNotFoundError: yaml	PyYAML fehlt	pip3 install pyyaml ausführen
Bericht nicht erstellt	Fehlende Schreibberechtigung für ./audit-results.md	Von einem Verzeichnis mit Schreibberechtigung aus ausführen

---

Hinweise

Zum Score: 7/10 ist das Minimum, um eine Skill als „trigger-zuverlässig“ auf externen LLMs zu betrachten. 10/10 ist ideal. Unter 7 bedeutet dies in der Regel, dass die Skill in freier Prosa und nicht als ausführbarer Vertrag geschrieben wurde – ein häufiges Format bei Skills vor V3.

Zu evals.json: Prüfung 10 validiert nicht den Inhalt der Evals, sondern nur das Vorhandensein der Datei und die Mindeststruktur (2+ Fälle mit prompt und expected_output). Die Qualität der Evals obliegt dem Autor der Skill, nicht dem Audit.

Bekannte Einschränkungen:

• Keine Überprüfung der semantischen Qualität des Workflows (ob die Schritte für die Domäne sinnvoll sind)
• Keine Ausführung der Skill (nur statische Analyse)
• Heuristiken für Trigger-Phrasen können bei dichten technischen Beschreibungen zu falsch positiven Ergebnissen führen – Issues bei grenzwertigen Scores (6-7) manuell überprüfen

---

Änderungsprotokoll

• v1.0 (2026-04-19): Erste Version. 10 QA-Prüfungen basierend auf dem V3-Standard. Abgeleitet aus einem Audit von 119 Skills des Amora-Arbeitsbereichs (Durchschnittsbewertung 5,9 → 10,0).