Je gère une équipe de devs qui vit avec Claude Code depuis près d'un an. Et non, je ne parle pas d'un "on l'a testé pendant un sprint" de vie. Je parle d'un "notre CI s'exécute dessus et nos templates de pull request sont en fait des prompts Claude" de vie. Au cours de ce parcours, j'ai eu une idée ambitieuse. J'ai construit un ensemble de compétences personnalisées pour l'équipe : `code-review`, `debug-protocol`, et `team-conventions`. Elles vivent dans `.claude/skills/`, sont bien présentées, avec tout le frontmatter YAML dont on peut rêver. Et pendant les premières semaines, elles sont restées là. Surtout. Ignorées. Comme une alarme incendie qui ne sonne que quand le feu est déjà là.
Ce qui est le plus frustrant ? Les fichiers de compétences étaient corrects. Les chemins étaient bons. Le markdown était propre et superbement documenté. La compétence ne se déclenchait juste jamais. Et après des mois de têtes grattées, j'ai enfin appris la vérité : ce n'était jamais la faute de la compétence. C'était la mienne.
Le Piège des "Compétences qui Ne Se Déclenchent Pas"
Pour tous ceux qui n'ont pas encore plongé dans l'abîme de la configuration des compétences Claude Code, voici la version courte : les compétences sont des dossiers situés dans `.claude/skills/
```markdown
---
name: code-reivew
description: Use when the user asks for a code review.
---
```
Ça semble anodin. Mais la façon dont Claude Code décide réellement de déclencher une compétence est de lire *toutes* les descriptions, de les mélanger dans son prompt système, et de faire correspondre votre requête actuelle avec celles-ci. En d'autres termes, l'activation de compétence est essentiellement un jeu de correspondance d'intention. Et si votre description est rédigée comme un déclencheur littéral par mots-clés, le jeu est truqué dès le départ.
Nous avons passé trois semaines à blâmer Claude, l'API, et la phase de la lune. Puis nous avons enfin lu la documentation officielle sur les compétences à [docs.anthropic.com/en/docs/claude-code/skills](https://docs.anthropic.com/en/docs/claude-code/skills) et avons réalisé quelque chose de gênant : le modèle n'est pas paresseux, il est juste littéral. Il ne peut déclencher qu'une compétence qu'il *reconnaît* comme pertinente via la description. Et nos descriptions étaient atroces.
Le Vrai Problème : Un Décalage entre les Descriptions
Voici ce que nous avons mis beaucoup trop de temps à comprendre : **la compétence n'existe pas dans le vide.** Elle existe dans une soupe d'autres compétences, de comportements intégrés, et de tout ce qui se trouve dans le contexte de Claude. Quand un développeur tape quelque chose, Claude effectue un rapide calcul mental : *"Est-ce que ça correspond à une description de compétence ? Si plusieurs correspondent, laquelle est la plus proche ? Est-ce que je devrais plutôt répondre directement ?"*
Si votre description de compétence est trop étroite, trop vague, ou trop focalisée sur les mots-clés, Claude la ratera. Et si votre description entre en collision avec une autre compétence ou une commande intégrée, Claude choisira la mauvaise. Le code dans votre SKILL.md n'est jamais le problème. C'est la métadonnée.
Voici les trois plus grandes façons dont cela affecte les véritables équipes.
Scénario 1 : La Compétence "Code Review" qui Restait Endormie
J'ai rédigé notre compétence `code-review` avec la description la plus évidente du monde : *"À utiliser lorsque l'utilisateur demande une revue de code."* Simple, non ? Faux.
Nos développeurs n'ont jamais dit "revue de code". Ils disaient :
- "Tu peux vérifier mon PR ?"
- "Regarde ce diff, quelque chose ne va pas."
- "Relis ça avant que je pousse."
- "C'est pas trop over-engineered ?"
Devinz laquelle déclenchait la compétence ? Aucune. Claude répondait directement sans jamais invoquer la compétence parce que la phrase "revue de code" n'apparaissait jamais. La solution était gênante de simplicité. Nous avons réécrit la description pour qu'elle soit sémantique, pas littérale :
```yaml
description: >-
Pour reviewer des changements de code, des pull requests, des diffs ou des merge requests.
Se déclenche sur des phrases comme "review ce PR", "check mon diff", "vérifie ce code",
"c'est bon pour merge", ou "regarde ces changements".
Pas pour le debugging général ou l'explication de code.
```
Nous avons aussi ajouté une clause "Pas pour". Ce simple changement a fait déclencher la compétence environ 80% plus souvent. Les compétences Claude Code sont fondamentalement de l'ingénierie de prompts — et le prompt, c'est la description.
Scénario 2 : Le Protocole de Debug qui Nous a Ghostés
Notre compétence `debug-protocol` devait être le héros de l'équipe. Un processus structuré, étape par étape, pour reproduire les bugs, vérifier les logs, inspecter l'état et proposer des correctifs. C'était beau. Ça ne s'est jamais non plus déclenché.
Pourquoi ? Parce que la description commençait par le mot "debug". Et "debug" est partout dans Claude Code. Il y a un flag de débogage intégré, des comportements de débogage au niveau système, et probablement trois autres compétences dans le même dossier utilisant un langage similaire. Quand nos développeurs disaient "aide-moi à débug ce test qui échoue", Claude avait quatre correspondances plausibles et choisissait celle qui avait la pertinence *globale* la plus forte — généralement le comportement intégré, pas notre compétence personnalisée.
Nous avons appris deux leçons :
1. **Donnez aux compétences des noms uniques et spécifiques.** `debug-protocol` est générique. `sentry-repro-protocol` ou `memory-leak-hunt` auraient été meilleurs. Les noms génériques sont écrasés par les intentions génériques.
2. **Utilisez le contrôle manuel.** Dans Claude Code, vous pouvez toujours taper `/debug-protocol` pour forcer le déclenchement. Nous avons ajouté cela aux conventions de notre équipe, et soudain la compétence n'était plus morte — elle avait juste besoin d'une invitation directe.
Mais voici l'insight plus profond : le modèle a choisi la mauvaise compétence parce que *nous* avons créé une collision. Si vous avez deux compétences qui se ressemblent, Claude devinera. Faites en sorte que les descriptions s'annulent mutuellement. Dites explicitement à Claude : "utilise celle-ci au lieu du comportement de débogage général quand le problème concerne les logs serveur."
Scénario 3 : La Compétence "Team Conventions" qui a Tout Oublié
L'échec le plus bizarre est venu de notre compétence `team-conventions`. Elle contenait les règles pour les messages de commit, la nomenclature des branches et les descriptions de PR. Elle a parfaitement fonctionné au début d'une session, puis s'est arrêtée vers le message 20. Nous avons supposé que le modèle "oubliait". Ce n'était pas un bug mémoire — c'était une question de contexte.
Claude Code injecte toutes les descriptions de compétences dans le prompt système. Des descriptions longues mangent du contexte. Et quand la conversation se charge, le système commence à compresser ou tronquer le prompt système pour faire de la place. Notre description pour `team-conventions' était un mur de texte — trois paragraphes de jargon d'entreprise. C'était la première chose à être jetée par-dessus bord quand la fenêtre de contexte se rétrécissait.
La solution a été d'alléger la description à deux ou trois phrases et de déplacer les règles réelles dans un fichier référencé à l'intérieur du dossier de la compétence. Maintenant, la description n'est plus qu'un panneau indicateur : *"Pour les messages de commit, la nomenclature des branches et les conventions de PR. Règles complètes dans convention.md."* Le modèle peut retenir ça, et quand la compétence se déclenche, il lit le fichier complet. Nous avons aussi déplacé les règles non-compétences dans notre fichier mémoire projet `CLAUDE.md`, qui est chargé de manière plus fiable pour les instructions s'appliquant à toute l'équipe.
Solutions Pratiques à Appliquer Dès Aujourd'hui
Après des semaines de souffrance, voici la checklist que j'aurais aimé qu'on me remette dès le premier jour.
Traitez la Description comme une Requête de Recherche
Si quelqu'un recherchait la description de votre compétence, correspondrait-elle à ce que vous voulez vraiment ? Rédigez la description comme une requête de recherche sémantique. Incluez des synonymes, des phrases réelles que votre équipe utilise, et des exclusions explicites. Ne présumez pas que le modèle "sait ce que vous vouliez dire". Il ne sait que ce que vous avez écrit.
Gardez les Fichiers de Compétences Légers
Un fichier de compétence de 500 lignes est un passif. Il mange du contexte, est tronqué et devient peu fiable. Gardez le SKILL.md centré sur la *décision* de quand se déclencher. Poussez les détails lourds dans des fichiers auxiliaires — `prompt.md`, `criteria.md`, `checklist.md` — que Claude ne lit qu'après activation de la compétence.
Ajoutez des Exemples Négatifs
Ça paraît contre-intuitif, mais ça marche. Dans la description, indiquez explicitement à quoi la compétence *ne sert pas*. Écrivez : *"Pas pour les discussions d'architecture générale. Pas pour les questions de syntaxe."* Cela réduit les faux positifs et aide aussi le modèle à distinguer entre des compétences similaires. Les exemples négatifs sont l'outil le plus tranchant de la boîte.
Utilisez la Commande `/` pour le Contrôle Manuel
Peu importe la qualité de vos métadonnées, il viendra un moment où la détection automatique échouera. Formez votre équipe à taper `/nom-compétence` quand ils doivent forcer le déclenchement. Ce n'est pas un échec — c'est un filet de sécurité. Les équipes les plus malines traitent le déclenchement automatique comme une commodité, pas comme une dépendance.
Déboguez-le Comme N'importe Quel Autre Code
Claude Code a un flag `--debug`. Utilisez-le. Inspectez le prompt système assemblé au début d'une session et confirmez que vos descriptions de compétences y figurent bien. Ça paraît évident, mais nous avons découvert qu'une virgule en fin de bloc dans un de nos frontmatter YAML invalidait silencieusement tout le fichier. La compétence ne se chargeait jamais. Pas à cause de la correspondance d'intention — à cause d'une erreur de syntaxe. La sortie de débogage l'a attrapée en dix secondes.
Testez avec Différentes Formulations
Ne testez pas uniquement la phrase exacte de votre documentation. Ouvrez une session fraîche et tapez la façon désordonnée, humaine et ambiguë dont votre équipe parle réellement. "Ce PR-là, ça va pas péter ?" devrait déclencher votre compétence de revue si vos descriptions sont bonnes. Si ce n'est pas le cas, votre description n'est pas encore assez bonne.
FAQ
Pourquoi ma compétence fonctionne dans une nouvelle session mais cesse de se déclencher plus tard ?
C'est presque toujours une troncature de contexte. Les descriptions de compétences longues sont supprimées du prompt système à mesure que la conversation grandit. Allégez la description, ou restructurez avec un fichier référencé. Ce n'est pas un problème de mémoire — c'est un problème d'espace.
Est-il préférable d'utiliser des mots-clés ou du langage naturel dans les descriptions ?
Les deux, dans le bon ratio. Commencez par une description sémantique en une phrase de *l'intention* ("pour reviewer des changements de code"), puis ajoutez une liste de phrases de déclenchement courantes. Ne comptez pas uniquement sur les mots-clés, mais ne soyez pas si abstrait que rien ne corresponde non plus.
Une compétence personnaliselle peut-elle remplacer un comportement intégré de Claude Code ?
Pas directement. Les comportements intégrés sont câblés à un niveau que votre compétence ne peut pas remplacer. Mais vous pouvez gagner la correspondance en rendant votre description plus spécifique et pertinente par rapport à la situation réelle de votre équipe. Si vous êtes bloqué, utilisez `/nom-compétence` pour forcer, ou reformulez la demande pour que le chemin intégré ne convienne plus.
Comment savoir si mon fichier de compétence se charge même ?
Lancez `claude --debug` et inspectez la sortie. Vous devriez voir vos compétences listées dans l'assemblage du prompt système. Si votre compétence n'est pas listée, vérifiez le frontmatter YAML, la structure de dossiers, et le nom du fichier. Un dossier de compétence sans un `SKILL.md` valide n'est juste qu'une décoration.
En Résumé
Voici la vérité gênante : quand une compétence ne se déclenche pas, le fichier de compétence n'est presque jamais le problème. Le problème est la qualité de la traduction que vous avez faite de l'intention humaine — "relis mon travail, suis nos règles, corrige ce bug de la façon dont on en a convenu" — en métadonnées que Claude lit réellement. Il ne s'agit pas d'écrire un meilleur code. Il s'agit d'écrire de meilleurs *panneaux indicateurs*.
Si vous êtes frustré par des compétences silencieuses, ne réécrivez pas votre markdown de zéro. Réécrivez vos descriptions. Ajoutez de vrais exemples. Ajoutez des exclusions. Gardez le fichier léger. Et quand tout le reste échoue, tapez simplement `/nom-compétence` et continuez votre journée.
La compétence n'est pas cassée. Et croyez-le ou non, Claude non plus. Nous avons juste oublié que le modèle doit être invité à la fête avec plus qu'un vague signe de la main à travers la pièce.
Comments (0)
No comments yet. Be the first to comment!
Leave a Comment