e9tgldr/skill-router

Routeur de Compétences

Il y a actuellement environ 170 compétences installées ici et leur qualité et leur portée varient considérablement, plusieurs d'entre elles sont presque des doublons (trois compétences de design distinctes pour "ne pas avoir l'air générique", deux copies d'impeccable, xlsx à côté de xlsx-dsh). Faire un mauvais choix est la seule erreur la plus coûteuse : une mauvaise compétence coûte tout son corps en contexte et fait dévier la réponse, alors qu'aucune compétence ne fait généralement mieux que la mauvaise.

Donc : routez d'abord, puis travaillez. Ce fichier est la procédure de routage. Elle est peu coûteuse — une seule analyse de fichier, un ou deux appels d'outil — et elle remplace les suppositions basées sur la liste des compétences. La procédure est indépendante de l'installation : les nombres, les noms et les familles ci-dessous décrivent le catalogue sur lequel elle a été écrite, et la recherche se normalise en fonction du catalogue qu'elle trouve.

1. Lisez la tâche avant de toucher à quoi que ce soit

Répondez à ces questions en silence, en une ligne chacune. Elles déterminent la route, pas le livrable.

• Qu'est-ce qui est produit ? Un fichier (docx/xlsx/pdf/pptx/png), du code fonctionnel, une décision, un message, un plan.
• Quel domaine ? Frontend web, backend, données, docs, design, vidéo/animation, VR, opérations.
• Existe-t-il un artefact existant ? Greenfield vs. modification du code de quelqu'un — cela fait basculer la route des compétences de construction vers les compétences d'audit/révision et de compréhension d'abord.
• Qui lit le résultat ? Investisseur, enseignant, coéquipier, compilateur. Le public change la compétence d'écriture, pas la compétence technique.

Si la demande est une phrase d'intention pure ("fais-moi quelque chose de cool"), c'est aussi un signal de routage : cela signifie qu'aucune compétence ne peut encore être choisie et que les questions viennent en premier (étape 6).

2. Chemin rapide — vérifiez le tableau de routage

Lisez references/task-types.md (relatif au répertoire de cette compétence). Le premier tableau mappe environ 40 formes de tâches courantes vers une chaîne de compétences vérifiée en un écran ; le second liste les outils étroits avec des noms impossibles à deviner (animation-vocabulary, cdn-caching, vercel-connect) que personne ne recherche, alors vérifiez-le avant de conclure que rien ne correspond.

• Correspondance trouvée → allez à l'étape 4 avec cette chaîne. Ne cherchez pas aussi ; le tableau est la réponse et chercher à nouveau ne fait que brûler des tokens.
• Pas de correspondance, ou la correspondance est partielle → étape 3.
• Le tableau nomme des compétences que vous n'avez pas (une installation différente, un harnais différent, une machine vierge) → ignorez complètement le tableau et allez à l'étape 3. Le tableau est le mappage d'une seule installation ; la recherche fonctionne sur n'importe quel catalogue. Vérifiez avec --doctor.

3. Recherchez dans le catalogue

Une commande, aucun modèle nécessaire :

# le chemin est relatif au répertoire de cette compétence
node scripts/find_skills.mjs "landing page feels generic" -n 8
node scripts/find_skills.mjs --doctor      # quelles racines ont été scannées, ce qui a été trouvé

Il note toutes les compétences installées sur le nom + la description (pondéré par IDF, donc les mots rares l'emportent sur user/code/when) plus une couche conceptuelle organisée pour les formulations qui ne partagent aucun vocabulaire avec la compétence dont elles ont besoin. Affiche les meilleures correspondances avec leurs chemins SKILL.md, ou NO GOOD MATCH quand rien ne correspond.

Comment bien interroger :

• Utilisez les noms de la tâche, pas la phrase de l'utilisateur : spreadsheet charts csv, pas "peux-tu transformer ça en quelque chose avec un graphique".
• Exécutez 2–3 angles différents plutôt qu'une seule longue requête — l'angle de l'artefact (pitch deck), l'angle du domaine (investor fundraising), l'angle du problème (text looks templated). Regroupez-les en un seul appel bash si vous le souhaitez.
• --explain affiche pourquoi chaque résultat a été classé, token par token — utilisez-le lorsqu'un résultat semble faux plutôt que de deviner la cause.
• Chaque résultat est étiqueté [strong], [likely] ou [weak]. [weak] signifie que le routeur devine à partir d'un mot incident — traitez-le comme une suggestion, pas comme une réponse, et préférez votre propre jugement. Si tous les résultats sont faibles, le script le dit.
• --all affiche le catalogue complet, --name pdf résout un nom en chemin, --json donne une sortie lisible par machine, -n 20 élargit la liste lorsque vous voulez voir les suivants (souvent la bonne réponse est #4 pour une requête mal formulée).
• Les résultats sont classés, pas faisant autorité. Vous choisissez toujours.
• Le script vit dans le répertoire scripts/ de cette compétence. Si le harnais expose un chemin absolu, utilisez-le ; sinon, cd d'abord dans le répertoire de la compétence.
• Il indexe tout ce qui existe, pas une liste fixe : il analyse les répertoires de compétences habituels par utilisateur et par projet à travers les harnais (~/.pi, ~/.claude, ~/.codex, ~/.agents, ~/.cursor, plus <cwd>/skills et plugin node_modules). Pointez-le ailleurs avec SKILL_ROUTER_ROOTS=/a/skills:/b/skills ou --root /a/skills. Sur une machine inconnue, exécutez --doctor d'abord : il liste chaque racine, si elle existe, combien de compétences elle a contribuées, les noms en double, et les fichiers SKILL.md qu'il n'a pas pu analyser. Aucun concept ou porte n'est nécessaire pour un nouveau catalogue — ils sont des boosts optionnels au-dessus du classement lexical ; avec zéro d'entre eux, la recherche classe toujours par nom et description.

Si le script lui-même est indisponible ou si une recherche ne retourne rien de plausible deux fois, repliez-vous sur la lecture des descriptions ~/.pi/agent/skills/ à partir de la liste des invites système. Ne vous arrêtez pas, et n'ouvrez pas cinq fichiers SKILL.md en espérant qu'un colle.

4. Choisissez — des règles qui maintiennent la chaîne courte

1. Processus avant mise en œuvre. Les compétences qui définissent comment le travail s'exécute (brainstorming, writing-plans, systematic-debugging, test-driven-development, writing-skills) se chargent avant les compétences qui définissent ce à quoi le résultat ressemble (design, docx, nextjs). Les compétences de processus indiquent fréquemment de charger une compétence de mise en œuvre ensuite — laissez-les faire.

2. Trois compétences maximum. Une est normale, deux est courant, trois est le plafond. Une quatrième signifie que vous collectionnez au lieu de décider.

3. Une par famille. Ne chargez jamais deux membres de la même famille — prenez la première colonne :

   Famille	Choisissez-en une
   Goût frontend / anti-générique	design-taste-frontend, ui-craft, impeccable, frontend-design, craft
   Copies dupliquées	impeccable (agents/) sur impeccable-dsh ; xlsx sur xlsx-dsh ; kimi/* sur dsh/* sauf si le dsh est clairement plus spécifique
   Format de doc	exactement celui correspondant au fichier : docx, pdf, pptx, xlsx
   Animation	animate (web), animate-expo (React Native) — pas les deux
   Backend	backend-patterns, create-a-backend, api-design — au maximum deux
   Quête / VR	famille hz-* + metavr-cli ; commencez toujours par hz-quest-verify-first

4. Respectez les portes de la plateforme. hz-*, portal, metavr-cli ont besoin d'un contexte Quest/VR ; cloudbase a besoin de CloudBase ; kimi-webbridge / kimi-cu ont besoin d'un vrai navigateur ou d'une interface graphique de bureau. Si la tâche ne nomme pas la plateforme, la compétence ne s'applique pas, peu importe à quel point les mots correspondent bien.

5. Justifiez ou rejetez. Pour chaque candidat, une clause : pourquoi celui-ci. Si la clause est "il mentionne les mêmes mots", rejetez-le. Deux compétences peuvent partager du vocabulaire et être néanmoins destinées à des machines différentes.

6. Aucun est une réponse valide. Si rien ne franchit la barre, dites-le en quelques mots et effectuez la tâche avec votre propre jugement. Une compétence manquante n'est pas une raison pour lancer une compétence à moitié pertinente.

7. Ne ré-routez que sur les pivots. Une nouvelle sous-tâche dans le même flux de travail ne déclenche pas une nouvelle recherche. Un changement de domaine (l'utilisateur dit "en fait, fais-en un deck") le fait.

5. Annoncez en une ligne, puis avancez

Avant de faire le travail, énoncez la route une fois :

Utilisation de design-taste-frontend (page d'accueil anti-modèle) → animate pour le héros. Aucune compétence ne convient pour la partie rédaction ; je l'écris moi-même.

Règles pour cette ligne : une ou deux phrases, noms + raisons uniquement. Pas d'essais sur l'inventaire des compétences, pas de "J'ai sélectionné les compétences suivantes pour cette tâche parce que…". L'utilisateur veut voir la décision, pas la délibération. Si la route est inhabituelle ou si vous vous écartez sciemment du tableau, c'est la seule chose qui vaut une clause supplémentaire.

6. Ne demandez que ce qui bloque le travail

C'est là que le routage porte ses fruits : une compétence choisie vous dit ce qu'elle a besoin de savoir, alors posez ces questions — et seulement celles-ci.

Demandez quand, et seulement quand :

• la tâche a deux livrables ou plus vraiment différents ("une affiche" pourrait être un PNG ou un diaporama, et les fichiers diffèrent),
• le public ou le format est inconnu et impossible à deviner à partir du contexte,
• les propres instructions de la compétence choisie nécessitent une décision que l'utilisateur doit posséder (marque, budget, informations d'identification, données réelles vs. fictives),
• une route coûterait de l'argent réel ou toucherait la production.

Ne demandez pas :

• quelle compétence utiliser — c'est le travail de cette compétence. Demandez le résultat, laissez le routage découler de la réponse,
• quoi que ce soit que la demande répond déjà, quoi que ce soit que la base de code ou les fichiers répondent,
• quoi que ce soit qu'un défaut raisonnable couvre. Choisissez le défaut, dites quel défaut vous avez choisi dans la ligne d'annonce, et continuez à avancer. Cet utilisateur préfère les longues exécutions ininterrompues aux confirmations tour par tour.

Forme : un seul appel ask_user_question, au maximum 3 questions, 2–4 options chacune, option recommandée en premier avec "(Recommandé)" sur l'étiquette, une courte phrase par option disant à quoi elle s'engage. N'empilez jamais un deuxième questionnaire juste après le premier ; si une réponse soulève une nouvelle question, préférez un défaut raisonnable à un autre aller-retour.

Si la compétence que vous avez chargée a sa propre phase de découverte ou de questions (la plupart des compétences de design et de planification le font), exécutez celle-ci au lieu d'en inventer une. Deux tours de questions à la suite sont perçus comme une temporisation.

7. Chargez et exécutez

• Lisez le fichier SKILL.md avec l'outil read, entièrement, au chemin que la recherche a retourné. Les compétences survolées produisent un résultat survolé.

• Résolvez tous les chemins references/, scripts/, assets/ relatifs au répertoire de cette compétence — la sortie de recherche imprime le fichier, donc le répertoire parent est la racine de la compétence.

• Exécutez les scripts tels qu'écrits. Si un script a besoin d'un argument qu'il ne documente pas, dites-le plutôt que de substituer votre propre implémentation.

• La compétence l'emporte sur les égalités. Une fois chargée, ses instructions remplacent les opinions de ce fichier sur la façon de faire le travail, et remplacent les bonnes pratiques génériques. Ce fichier ne l'a que choisie.

• Si une compétence chargée commence par "demandez d'abord à l'utilisateur" ou "planifiez avant d'écrire du code", faites cela — router vers une compétence de processus et ensuite sauter son processus est pire que de ne pas router du tout.

• Si en cours de travail vous découvrez que la compétence était fausse, dites-le clairement et ré-routez (étape 4). Contourner tranquillement une mauvaise compétence est le mode d'échec.

• Enregistrez la correction pour que la même erreur ne soit pas commise deux fois :

  node scripts/find_skills.mjs --learn "<la formulation qui a échoué>" <bonne-compétence>
  node scripts/find_skills.mjs --wrong "<la formulation qui a échoué>" <mauvaise-compétence>
  

  Faites-le chaque fois que l'utilisateur rejette une route, qu'une compétence chargée se révèle être le mauvais outil, ou que vous avez dû router manuellement parce que la recherche a manqué. Les corrections apprises l'emportent sur le score lexical sur des requêtes futures similaires, et elles voyagent avec l'installation — c'est ainsi que ce routeur s'améliore dans un environnement qu'il n'a jamais vu.

8. Fermeture

Une ligne à la fin : quelles compétences ont été utilisées et où l'artefact a atterri. Puis arrêtez — pas de résumé du contenu des compétences, pas d'offre d'expliquer le routage.

Maintenance — modifier le routeur sans le casser

Le routeur est noté, pas ressenti. scripts/eval_routing.mjs contient 80 requêtes réalistes, chacune avec l'ensemble des compétences qui sont des réponses véritablement acceptables, plus une douzaine de cas de porte (une requête React générique ne doit jamais faire remonter une compétence Quest). Exécutez-le avant et après tout changement :

node scripts/eval_routing.mjs
# score : 80/80 (100,0 %)  fuites de porte : 0
node ... --verbose      # classement par cas
node ... quest          # seulement les cas correspondants

node scripts/smoke_portable.mjs   # catalogue étranger + apprentissage + échelle de 600 compétences

smoke_portable.mjs est le test de portabilité : il invente 16 compétences dans des domaines que ce routeur n'a jamais vus (Kubernetes, Rust, Salesforce, Terraform…), vérifie le classement, la robustesse aux paraphrases, la porte portable, l'apprentissage, les noms en double, les catalogues vides, les chemins avec des espaces, SKILL_ROUTER_ROOTS, et une exécution à l'échelle de 600 compétences. Si vous changez la notation, les deux suites doivent rester vertes — l'évaluation protège la qualité sur un catalogue connu, le test de fumée protège le comportement sur un catalogue inconnu.

Un changement qui augmente le score est une amélioration ; un changement qui le diminue est une régression, peu importe à quel point le code a l'air plus soigné. Les cas dont les compétences attendues ne sont pas installées sont ignorés, pas échoués, donc la suite s'exécute sur n'importe quelle machine.

Lorsqu'une tâche réelle route mal, corrigez-la au niveau le moins coûteux qui l'explique :

1. Mauvais mots pour la même idée → ajoutez une règle CONCEPTS organisée dans find_skills.mjs (quand regex → boost scores, facultatif sauf si veto et rétrograder). C'est le niveau pour une intention qui ne partage aucun vocabulaire avec la compétence : "idée vague, pas de spécification" → brainstorming. Ponctuel ? N'utilisez pas cela — enregistrez-le plutôt (--learn). CONCEPTS est pour le comportement général ; la mémoire est pour "cette formulation, cette compétence".
2. Une forme de tâche récurrente → ajoutez une ligne à references/task-types.md. Ne coûte rien au moment de la requête et le chemin rapide ignore complètement la recherche.
3. Une compétence qui perd face à des voisins bruyants → ajoutez-la à DEMOTE, ou donnez au voisin bruyant un demote dans un concept (par exemple, dashboard seul ne doit pas battre ui-craft avec ui-craft-dense-dashboard).
4. Une compétence de plateforme qui fuit dans les requêtes génériques → étendez GATES avec les mots qui doivent être présents pour qu'elle soit éligible.
5. Une route que l'utilisateur a corrigée → --learn / --wrong, puis passez à autre chose. Vérifiez --memory occasionnellement : si la même compétence continue d'être corrigée pour le même type de formulation, promouvez le modèle dans CONCEPTS et --forget les entrées.

Ajoutez d'abord la requête défaillante à CASES, regardez-la échouer, puis corrigez. Ne réglez pas la notation sur des requêtes que vous n'avez pas écrites — c'est ainsi que le routeur finit par être bon avec vos exemples et mauvais avec ceux de l'utilisateur.

Drapeaux rouges — vous rationalisez, arrêtez

Pensée	Réalité
"C'est simple, pas besoin de routage"	Routez vite, implémentez vite. Le chemin rapide...

…

[La suite est tronquée pour la traduction]