e9tgldr/skill-router

Skill Router

Derzeit sind hier etwa 170 Skills installiert, die in Qualität und Umfang stark variieren, mehrere davon nahezu Duplikate voneinander (drei separate Design-Skills für „mach es nicht generisch", zwei Kopien von impeccable, xlsx neben xlsx-dsh). Eine schlechte Wahl ist der teuerste verfügbare Fehler: Ein falscher Skill kostet seinen gesamten Kontext und zieht die Antwort vom Ziel weg, während gar kein Skill meist besser ist als der falsche Skill.

Also: Zuerst routen, dann arbeiten. Diese Datei ist das Routing-Verfahren. Es ist günstig – ein Dateidurchlauf, ein oder zwei Tool-Aufrufe – und ersetzt das Raten aus der Skill-Liste. Das Verfahren ist installationsunabhängig: Die unten stehenden Anzahlen, Namen und Familien beschreiben den Katalog, gegen den es geschrieben wurde, und die Suche normalisiert auf den jeweils vorgefundenen Katalog.

1. Aufgabe lesen, bevor irgendetwas angefasst wird

Beantworte diese Punkte still, jeweils in einer Zeile. Sie bestimmen die Route, nicht das Ergebnis.

• Was wird produziert? Eine Datei (docx/xlsx/pdf/pptx/png), laufender Code, eine Entscheidung, eine Nachricht, ein Plan.
• Welche Domäne? Web-Frontend, Backend, Daten, Dokumente, Design, Video/Animation, VR, Ops.
• Gibt es ein bestehendes Artefakt? Neuanfang vs. Änderung an fremdem Code – das kippt die Route von Build-Skills zu Audit-/Review- und Verstehen-zuerst-Skills.
• Wer liest die Ausgabe? Investor, Lehrer, Teammitglied, Compiler. Die Zielgruppe ändert den Schreib-Skill, nicht den technischen.

Wenn die Anfrage ein einziger Satz purer Absicht ist („mach mir was Cooles"), ist das auch ein Routing-Signal: Es bedeutet, dass noch kein Skill ausgewählt werden kann und zuerst Fragen kommen (Schritt 6).

2. Schneller Pfad – Routingtabelle prüfen

Lies references/task-types.md (relativ zu diesem Skill-Verzeichnis). Die erste Tabelle bildet ~40 gängige Aufgabenformen auf eine geprüfte Skill-Kette in einem Bildschirm ab; die zweite listet spezielle Werkzeuge mit unerwartbaren Namen (animation-vocabulary, cdn-caching, vercel-connect) ach denen niemand sucht, also prüfe sie, bevor du zu dem Schluss kommst, dass nichts passt.

• Treffer gefunden → gehe mit dieser Kette zu Schritt 4. Suche nicht zusätzlich; die Tabelle ist die Antwort und erneutes Suchen verbrennt nur Tokens.
• Kein Treffer oder der Treffer ist unvollständig → Schritt 3.
• Die Tabelle nennt Skills, die du nicht hast (eine andere Installation, eine andere Umgebung, ein frischer Rechner) → überspringe die Tabelle vollständig und gehe zu Schritt 3. Die Tabelle ist die Abbildung einer Installation; die Suche funktioniert mit jedem Katalog. Verifiziere mit --doctor.

3. Katalog durchsuchen

Ein Befehl, kein Modell nötig:

# Pfad ist relativ zum Verzeichnis dieses Skills
node scripts/find_skills.mjs "Landingpage wirkt generisch" -n 8
node scripts/find_skills.mjs --doctor      # welche Wurzelverzeichnisse wurden gescannt, was wurde gefunden

Es bewertet alle installierten Skills nach Name + Beschreibung (IDF-gewichtet, sodass seltene Wörter über user/code/when gewinnen) plus einer kuratierten Konzeptebene für Formulierungen, die keine Vokabeln mit dem benötigten Skill teilen. Gibt die besten Treffer mit ihren SKILL.md-Pfaden aus oder NO GOOD MATCH, wenn nichts passt.

So fragst du gut ab:

• Verwende die Substantive der Aufgabe, nicht den Satz des Benutzers: tabellenkalkulation diagramme csv, nicht "kannst du das irgendwie in was mit einem Diagramm verwandeln".
• Führe 2–3 verschiedene Blickwinkel aus, anstatt einer langen Abfrage – den Artefakt-Winkel (Pitch-Deck), den Domänen-Winkel (Investor-Fundraising), den Problem-Winkel (Text wirkt wie eine Vorlage). Bündele sie in einem bash-Aufruf, wenn du magst.
• --explain gibt aus, warum jedes Ergebnis wie bewertet wurde, Token für Token – verwende es, wenn ein Ergebnis falsch aussieht, anstatt über die Ursache zu raten.
• Jedes Ergebnis ist als [strong], [likely] oder [weak] gekennzeichnet. [weak] bedeutet, dass der Router aufgrund eines einzigen beiläufigen Wortes rät – behandle es als Vorschlag, nicht als Antwort, und ziehe dein eigenes Urteil vor. Wenn alle Ergebnisse schwach sind, sagt das Skript das.
• --all gibt den vollständigen Katalog aus, --name pdf löst einen Namen in einen Pfad auf, --json gibt maschinenlesbare Ausgabe, -n 20 erweitert die Liste, wenn du die Zweitplatzierten sehen willst (oft ist die richtige Antwort bei #4 für eine schlecht formulierte Abfrage).
• Ergebnisse sind bewertet, nicht autoritativ. Du wählst immer noch.
• Das Skript lebt im scripts/-Verzeichnis dieses Skills. Wenn die Umgebung einen absoluten Pfad bereitstellt, verwende ihn; andernfalls wechsle zuerst mit cd in das Skill-Verzeichnis.
• Es indiziert, was existiert, keine feste Liste: Es scannt die üblichen benutzer- und projektspezifischen Skill-Verzeichnisse in verschiedenen Umgebungen (~/.pi, ~/.claude, ~/.codex, ~/.agents, ~/.cursor, plus <cwd>/skills und Plugin-node_modules). Leite es mit SKILL_ROUTER_ROOTS=/a/skills:/b/skills oder --root /a/skills woandershin. Auf einem unbekannten Rechner führe zuerst --doctor aus: Es listet jedes Wurzelverzeichnis auf, ob es existiert, wie viele Skills es beigesteuert hat, doppelte Namen und SKILL.md-Dateien, die es nicht parsen konnte. Für einen neuen Katalog sind keine Konzepte oder Tore erforderlich – sie sind optionale Verstärkungen zusätzlich zum lexikalischen Ranking; ohne sie bewertet die Suche dennoch nach Name und Beschreibung.

Wenn das Skript selbst nicht verfügbar ist oder eine Suche zweimal nichts Plausibles ergibt, falle zurück darauf, die ~/.pi/agent/skills/-Beschreibungen aus der Systemaufforderungsliste zu lesen. Gib nicht auf und öffne nicht fünf SKILL.md-Dateien in der Hoffnung, dass eine passt.

4. Auswahl – Regeln, die die Kette kurz halten

1. Prozess vor Implementierung. Skills, die festlegen, wie die Arbeit läuft (Brainstorming, Pläne schreiben, systematisches Debuggen, testgetriebene Entwicklung, Skills schreiben) werden geladen, bevor Skills geladen werden, die festlegen, was die Ausgabe ist (Design, docx, nextjs). Prozess- Skills sagen dir oft, dass du als nächstes einen Implementierungs-Skill laden sollst – tu das.

2. Maximal drei Skills. Eins ist normal, zwei üblich, drei die Obergrenze. Ein vierter bedeutet, dass du sammelst, anstatt zu entscheiden.

3. Einer pro Familie. Lade niemals zwei Mitglieder derselben Familie – nimm die erste Spalte:

   Familie	Wähle einen
   Frontend-Geschmack / Anti-Generisch	design-taste-frontend, ui-craft, impeccable, frontend-design, craft
   Duplizierte Kopien	impeccable (agents/) über impeccable-dsh; xlsx über xlsx-dsh; kimi/* über dsh/*, es sei denn, der dsh-Skill ist eindeutig spezifischer
   Dokumentformat	genau der, der zur Datei passt: docx, pdf, pptx, xlsx
   Bewegung	animate (Web), animate-expo (React Native) – nicht beide
   Backend	backend-patterns, create-a-backend, api-design – maximal zwei
   Quest / VR	hz-*-Familie + metavr-cli; beginne immer mit hz-quest-verify-first

4. Plattform-Tore respektieren. hz-*, portal, metavr-cli benötigen einen Quest/VR-Kontext; cloudbase benötigt CloudBase; kimi-webbridge / kimi-cu benötigen einen echten Browser oder eine Desktop-GUI. Wenn die Aufgabe die Plattform nicht nennt, ist der Skill nicht anwendbar, egal wie gut die Wörter passen.

5. Begründe oder lehne ab. Für jeden Kandidaten: ein Satz: warum dieser. Wenn der Satz "er erwähnt die gleichen Wörter" ist, lehne ihn ab. Zwei Skills können denselben Wortschatz teilen und trotzdem für verschiedene Maschinen sein.

6. Keiner ist eine gültige Antwort. Wenn nichts die Hürde nimmt, sage das in wenigen Worten und erledige die Aufgabe mit deinem eigenen Urteil. Ein fehlender Skill ist kein Grund, einen halbwegs relevanten zu starten.

7. Nur bei Richtungswechseln neu routen. Eine neue Teilaufgabe innerhalb desselben Workflows löst keine neue Suche aus. Ein Wechsel der Domäne (der Benutzer sagt „mach daraus doch lieber ein Deck") schon.

5. In einer Zeile ankündigen, dann weitermachen

Sage vor der Arbeit die Route einmal:

Verwende design-taste-frontend (Anti-Vorlagen-Landingpage) → animate für den Hero. Kein Skill passt für den Texterstellungsteil; das schreibe ich selbst.

Regeln für diese Zeile: ein oder zwei Sätze, nur Namen + Gründe. Keine Aufsätze über das Skill-Inventar, kein „Ich habe die folgenden Skills für diese Aufgabe ausgewählt, weil …". Der Benutzer möchte die Entscheidung sehen, nicht die Überlegungen. Wenn die Route ungewöhnlich ist oder du wissentlich von der Tabelle abweichst, ist das der eine zusätzliche Satz, der es wert ist.

6. Nur fragen, was die Arbeit blockiert

Hier zeigt das Routing seinen Wert: Ein ausgewählter Skill sagt dir, was er wissen muss, also stelle diese Fragen – und nur diese.

Stelle Fragen, wenn und nur wenn:

• die Aufgabe zwei oder mehr wirklich unterschiedliche Ergebnisse hat („ein Poster" könnte PNG oder eine Präsentationsfolie sein, und die Dateien unterscheiden sich),
• die Zielgruppe oder das Format unbekannt und aus dem Kontext nicht zu erraten ist,
• die eigenen Anweisungen des ausgewählten Skills eine Entscheidung erfordern, die der Benutzer treffen muss (Marke, Budget, Zugangsdaten, echte vs. Testdaten),
• eine Route echtes Geld kosten oder die Produktion berühren würde.

Frage nicht:

• welchen Skill zu verwenden – das ist die Aufgabe dieses Skills. Frage nach dem Ergebnis, lass das Routing aus der Antwort folgen,
• irgendetwas, das die Anfrage bereits beantwortet, irgendetwas, das die Codebasis oder die Dateien beantworten,
• irgendetwas, das eine sinnvolle Voreinstellung abdeckt. Wähle die Voreinstellung, sage, welche Voreinstellung du in der Ankündigungszeile gewählt hast, und mach weiter. Dieser Benutzer bevorzugt lange unbeaufsichtigte Läufe gegenüber Schritt-für-Schritt-Bestätigung.

Form: ein ask_user_question-Aufruf, höchstens 3 Fragen, jeweils 2–4 Optionen, empfohlene Option zuerst mit "(Empfohlen)" auf dem Label, ein kurzer Satz pro Option, der sagt, wozu sie sich verpflichtet. Staple niemals einen zweiten Fragebogen direkt nach dem ersten; wenn eine Antwort eine neue Frage aufwirft, ziehe eine sinnvolle Voreinstellung einer weiteren Runde vor.

Wenn der geladene Skill eine eigene Entdeckungs- oder Fragephase hat (die meisten Design- und Planungs-Skills haben das), führe diese durch, anstatt deine eigene zu erfinden. Zwei Frage-Runden hintereinander wirkt wie Hinhaltetaktik.

7. Laden und ausführen

• Lies die SKILL.md mit dem read-Werkzeug, vollständig, unter dem von der Suche zurückgegebenen Pfad. Überflogene Skills erzeugen überflogene Ausgabe.

• Löse alle references/-, scripts/-, assets/-Pfade relativ zum Verzeichnis dieses Skills auf – die Suche gibt die Datei aus, also ist das übergeordnete Verzeichnis das Skill-Stammverzeichnis.

• Führe Skripte wie geschrieben aus. Wenn ein Skript ein Argument benötigt, das es nicht dokumentiert, sage das, anstatt deine eigene Implementierung zu ersetzen.

• Der Skill gewinnt bei Gleichstand. Sobald geladen, überschreiben seine Anweisungen die Meinungen dieser Datei darüber, wie die Arbeit zu erledigen ist, und überschreiben die allgemeine bewährte Praxis. Diese Datei hat ihn nur ausgewählt.

• Wenn ein geladener Skill mit „frage zuerst den Benutzer" oder „plane, bevor du Code schreibst" beginnt, tu das – das Routen zu einem Prozess-Skill und dann das Überspringen seines Prozesses ist schlimmer, als gar nicht zu routen.

• Wenn du während der Arbeit feststellst, dass der Skill falsch war, sage das deutlich und route neu (Schritt 4). Still um einen schlechten Skill herumzuarbeiten, ist der Fehlermodus.

• Zeichne die Korrektur auf, damit derselbe Fehler nicht zweimal gemacht wird:

  node scripts/find_skills.mjs --learn "<die fehlgeschlagene Formulierung>" <richtiger-skill>
  node scripts/find_skills.mjs --wrong "<die fehlgeschlagene Formulierung>" <falscher-skill>
  

  Tue dies immer dann, wenn der Benutzer eine Route ablehnt, ein geladener Skill sich als das falsche Werkzeug herausstellt oder du manuell routen musstest, weil die Suche danebengelegen hat. Gelernte Korrekturen überstimmen die lexikalische Bewertung bei ähnlichen zukünftigen Abfragen und sie reisen mit der Installation – so wird dieser Router in einer Umgebung besser, die er noch nie gesehen hat.

8. Abschluss

Eine Zeile am Ende: welche Skills verwendet wurden und wo das Artefakt gelandet ist. Dann aufhören – keine Zusammenfassung des Skill-Inhalts, kein Angebot, das Routing zu erklären.

Wartung – Den Router ändern, ohne ihn zu beschädigen

Der Router wird gemessen, nicht geschätzt. scripts/eval_routing.mjs enthält 80 realistische Abfragen, jeweils mit der Menge der Skills, die akzeptable Antworten sind, plus einem Dutzend Tor-Fällen (eine generische React-Abfrage darf niemals einen Quest-Skill anzeigen). Führe es vor und nach jeder Änderung aus:

node scripts/eval_routing.mjs
# score: 80/80 (100.0%)  gate leaks: 0
node ... --verbose      # Rangfolge pro Fall
node ... quest          # nur passende Fälle

node scripts/smoke_portable.mjs   # Fremdkatalog + Lernen + 600-Skill-Maßstab

smoke_portable.mjs ist der Portabilitätstest: Es erfindet 16 Skills in Domänen, die dieser Router noch nie gesehen hat (Kubernetes, Rust, Salesforce, Terraform…), überprüft die Rangfolge, die Robustheit von Paraphrasen, das portable Tor, das Lernen, doppelte Namen, leere Kataloge, Pfade mit Leerzeichen, SKILL_ROUTER_ROOTS und einen Lauf mit 600 Skills. Wenn du die Bewertung änderst, müssen beide Testkits grün bleiben – die Auswertung schützt die Qualität auf einem bekannten Katalog, der Rauchtest schützt das Verhalten auf einem unbekannten.

Eine Änderung, die die Punktzahl erhöht, ist eine Verbesserung; eine Änderung, die sie senkt, ist ein Rückschritt, egal wie viel sauberer der Code liest. Fälle, deren erwartete Skills nicht installiert sind, werden übersprungen, nicht als fehlgeschlagen gemeldet, sodass die Testkit auf jedem Rechner läuft.

Wenn eine reale Aufgabe schlecht geroutet wird, behebe sie auf der billigsten Ebene, die sie erklärt:

1. Falsche Wörter für dieselbe Idee → füge eine kuratierte CONCEPTS-Regel in find_skills.mjs hinzu (when-Regex → boost-Punktzahl, optional unless-Veto und demote). Dies ist die Ebene für Absichten, die keine Vokabeln mit dem Skill teilen: "vage Idee, kein Pflichtenheft" → brainstorming. Einzelfall? Greife nicht dazu – zeichne es stattdessen auf (--learn). CONCEPTS ist für allgemeines Verhalten; der Speicher ist für „diese Formulierung, dieser Skill".
2. Eine wiederkehrende Aufgabenform → füge eine Zeile in references/task-types.md hinzu. Kostet zur Abfragezeit nichts und der schnelle Pfad überspringt die Suche vollständig.
3. Ein Skill, der immer gegen laute Nachbarn verliert → füge ihn zu DEMOTE hinzu oder gib dem lauten Nachbarn ein demote in einem Konzept (z. B. Dashboard allein darf ui-craft nicht mit ui-craft-dense-dashboard schlagen).
4. Ein Plattform-Skill, der in generische Abfragen durchsickert → erweitere GATES um die Wörter, die vorhanden sein müssen, damit er in Frage kommt.
5. Eine Route, die der Benutzer korrigiert hat → --learn / --wrong, dann weitermachen. Überprüfe --memory gelegentlich: Wenn derselbe Skill immer wieder für dieselbe Art von Formulierung korrigiert wird, befördere das Muster in CONCEPTS und --forget die Einträge.

Füge die fehlschlagende Abfrage zuerst zu CASES hinzu, warte, bis sie fehlschlägt, dann repariere. Stimme die Bewertung nicht auf Abfragen ab, die du nicht notiert hast – so wird der Router am Ende gut für deine Beispiele und schlecht für die des Benutzers.

Rote Flaggen – Du rationalisierst, hör auf

Gedanke	Realität
"Das ist einfach, kein Routing nötig"	Route schnell, implementiere schnell. Der schnelle Pfad