Was macht skill-doctor?
Diagnostiziere eine Skill-Bibliothek. Finde Skills, deren Beschreibungen um dieselben Prompts konkurrieren, und behebe dann das Routing.
Wann ausführen
- Du hast viele Skills installiert und „der falsche wird ständig ausgelöst“
- Vor der Veröffentlichung eines Skill-Pakets (Kollisionen abfangen, die Prüfer treffen würden)
- Nach dem Hinzufügen eines neuen Skills (kollidiert er mit einem vorhandenen?)
- Regelmäßige Gesundheitsprüfung einer wachsenden Bibliothek
Eingabe
Gib dem Engine ENTWEDER:
- Ein Verzeichnis mit Skills (
<root>/<name>/SKILL.md) oder - Eine Claude Code manifest.json (
skills-plugin/.../manifest.json)
Ausführung
Der Engine befindet sich in scripts/ neben dieser Datei. Null Abhängigkeiten (Python 3.8+ stdlib).
# Vom Verzeichnis, das diese SKILL.md enthält:
python3 -m scripts <pfad-zu-skills-oder-manifest> # Markdown-Bericht
python3 -m scripts <pfad> --format json --out report.json # Maschinenausgabe
python3 -m scripts <pfad> --fail-on critical # CI-Gate (exit 1)
Häufige Optionen:
--merge-at 0.55– Kollisionswert, der eine ZUSAMMENFÜHRUNGS-Empfehlung auslöst--disambig-at 0.30– Wert, der eine DISAMBIGUIERUNGS-Empfehlung auslöst--vague-threshold 0.5– kennzeichne vage Beschreibungen über diesem Wert--top 12– wie viele Top-Kollisionen aufgelistet werden--format md|json|both
Erkannte Probleme (Issue-Codes)
| Code | Schweregrad | Bedeutung |
|---|---|---|
DUPLICATE_TRIGGER | 🔴 | Dieselbe Auslösephrase wird von 2+ Skills beansprucht (häufigste Ursache für Fehlrouting) |
DUPLICATE_NAME | 🔴 | Zwei Skills haben denselben Namen |
MISSING_DESCRIPTION | 🔴 | Skill kann nie zuverlässig ausgelöst werden |
HIGH_OVERLAP | 🔴/🟠 | Zwei Beschreibungen sind semantisch zu ähnlich |
VAGUE_DESCRIPTION | 🟠 | Füllwort-lastig, kein „verwende wenn“, keine Auslöser |
NAME_DIR_MISMATCH | 🟠 | Name ≠ Verzeichnis (verletzt die Spezifikation) |
BAD_NAME_FORMAT | 🟠 | Name entspricht nicht den Kleinbuchstaben/Bindestrich-Regeln |
DESC_TOO_SHORT / DESC_TOO_LONG | 🟠/🟡 | Außerhalb von 40–1024 Zeichen |
NO_BOUNDARY | 🟡 | Kein Querverweis „Für X siehe “ |
BODY_TOO_LONG | 🔵 | SKILL.md-Körper > 500 Zeilen |
Wie die Bewertung funktioniert (eine Zeile)
kollision = 0,50 · Kosinus(TF-IDF der Beschreibungen)
+ 0,35 · Jaccard(Auslösephrasen)
+ 0,15 · Jaccard(Domänenschlüsselwörter)
Bänder: <0,22 NIEDRIG · 0,22 MITTEL · 0,38 HOCH · 0,55 KRITISCH.
Siehe references/scoring.md für die vollständige Begründung.
Arbeitsablauf für den Agenten
- Führe den Engine auf dem Skills-Pfad des Benutzers aus → lies den Markdown-Bericht.
- Fasse den Gesundheitswert, die schlimmsten Cluster und doppelte Auslöser zusammen.
- Schlage für jede Top-Empfehlung die konkrete Änderung vor:
MERGE→ entwirf eine kombinierte Beschreibung, schlage den überlebenden Namen vor.ABSORB→ nenne den zu löschenden Skill und wohin seine Auslöser wandern.DISAMBIGUATE→ schreibe die beiden spiegelnden Grenzlinien („Für X siehe Y.“).
- Biete an, die Beschreibungsänderungen anzuwenden (bearbeite das Frontmatter jeder SKILL.md).
- Führe erneut aus, um zu bestätigen, dass sich der Gesundheitswert verbessert hat.
Ausgabe
- Ein Markdown-Bericht: Gesundheitswert, Top-Kollisionen, verwechselbare Cluster, Tabelle der doppelten Auslöser, Empfehlungen, vollständige Issue-Liste, ASCII-Heatmap.
- Optional JSON (
--format json) für CI-Gates oder andere Werkzeuge.
Regeln
- Der Engine ist schreibgeschützt – er bearbeitet niemals Skills. Die Umschreibungen werden vom Agenten (dir) nur nach Zustimmung des Benutzers angewendet.
- Lösche niemals einen Skill ohne explizite Bestätigung.
- Bewahre beim Umschreiben von Beschreibungen jede echte Auslösephrase, auf die der Benutzer angewiesen ist; verschiebe/unterscheide sie nur – lösche sie nicht.
Siehe references/methodology.md für den Algorithmus und references/issue-catalog.md
für die Behebung jedes Problemtyps.