Skills : le savoir-faire versionné

Le problème que les skills résolvent

Chaque équipe a ses gestes rituels : « ajouter une route » implique CHEZ VOUS le router du bon module, un schéma Pydantic, la session RLS, un test cross-tenant. Un agent générique en fera 60 % ; le nouveau collègue aussi. Ce savoir-faire vivait dans la tête des anciens — les skills le mettent dans le repo.

Une skill = un fichier markdown versionné (.claude/skills/add-route/SKILL.md) : quand demander (le déclencheur), la procédure pas à pas, les pièges, les fichiers de référence à imiter. L'agent la charge quand la tâche correspond — et suit VOTRE procédure au lieu d'improviser la sienne.

Le catalogue du projet étudié (10 skills)

Trois familles instructives :

• les gestes de code : add-route, add-chat-tool, add-langgraph-node, add-extractor, add-connector, add-migration, add-page — un par point d'extension de l'architecture. Remarque : la liste des skills DESSINE l'architecture (si un geste fréquent n'a pas de skill, soit il manque, soit l'architecture a un problème) ;
• les enquêtes : debug-matching — la procédure de diagnostic (quelles tables regarder, quels scores tracer, quels cas d'éval rejouer) ;
• les workflows : plan-feature, ship-feature — les enchaînements complets (de la spec au ticket, du code à la MR verte).

S'y ajoutent les slash commands (/ship, /status, /retro, /new-adr) : les mêmes idées, déclenchées explicitement.

Écrire une bonne skill

1. Un déclencheur net : « utiliser quand on expose une nouvelle ressource REST » — l'agent doit savoir QUAND la charger ;
2. La procédure qui pointe vers l'exemplaire : « imite modules/catalog/router.py » vaut mieux que 50 lignes d'explications — le code de référence est la vraie spec ;
3. Les pièges en négatif : « n'oublie PAS le test d'isolation cross-tenant » — les skills capturent les erreurs déjà commises ;
4. Testée en vrai : une skill qui produit du code refusé en revue est un bug de skill — on la corrige comme du code.