Déboguer un Skill qui ne se déclenche pas (ou qui se déclenche trop)

À la fin de cet article, tu sauras classer n’importe quel Skill capricieux dans l’un de trois symptômes précis, et appliquer le correctif qui va avec, sans jamais réécrire un SKILL.md en entier pour un problème qui tient dans une phrase.

L’article précédent t’a donné une checklist à appliquer avant de publier un Skill. Celui-ci s’occupe de l’après : ce que tu fais quand un Skill qui a pourtant passé la checklist se comporte mal une fois en usage réel, sur des phrases que tu n’avais pas anticipées. C’est le dernier article du bloc Skills de cette série.

Ce qu’il te faut

Claude Code installé, et un Skill perso qui ne se comporte pas comme prévu. Si aucun des tiens ne pose problème pour l’instant, note-le quelque part : la panne arrive toujours après plusieurs semaines d’usage, jamais le jour de la création.

Étape 1 — Nommer le symptôme avant de toucher au fichier (2 minutes)

Trois symptômes existent, et chacun a une cause différente. Ne commence jamais à corriger avant d’avoir identifié lequel tu observes :

• Silence : tu formules une demande qui devrait déclencher le Skill, rien ne se passe, Claude répond directement sans passer par le Skill.
• Excès : le Skill se déclenche sur des demandes qui n’ont rien à voir avec sa tâche.
• Confusion : le Skill se déclenche, mais ce n’est pas le bon parmi plusieurs Skills perso disponibles.

Le silence se corrige en élargissant la description. L’excès se corrige en la resserrant. La confusion, elle, ne se corrige presque jamais dans le fichier fautif : elle se corrige dans le fichier voisin qui empiète dessus. Traiter un excès comme un silence, ou l’inverse, fait tourner en rond pendant plusieurs cycles de correction pour rien.

Étape 2 — Silence : reproduire la panne avant de la corriger (4 minutes)

Ne reformule pas ta demande pour qu’elle marche « quand même ». Note la phrase exacte qui aurait dû déclencher le Skill et n’a rien fait, puis demande directement :

Je m'attendais à ce que le Skill relecture-avant-publication se déclenche sur ma dernière
phrase. Pourquoi ne l'as-tu pas fait ?

La réponse tombe presque toujours dans l’un de ces deux cas : soit ta phrase employait un mot que la description ne couvre pas (« peux-tu vérifier ce texte » plutôt que « relecture » ou « passe finale »), soit le contexte de la conversation orientait Claude ailleurs (un fichier de code ouvert juste avant, par exemple). Dans le premier cas, ajoute le mot manquant à la description. Dans le second, c’est le contexte qui a fait pencher la décision, pas un défaut du Skill : reproduis la demande dans une conversation neuve avant de conclure à un vrai silence.

Étape 3 — Excès : identifier le mot qui aimante tout (3 minutes)

Un Skill en excès se déclenche sur des phrases voisines mais pas identiques à sa tâche réelle. Rassemble deux ou trois exemples de déclenchements indésirables, puis cherche le mot qu’ils ont en commun avec la description. C’est presque toujours un verbe générique : « vérifier », « regarder », « faire une passe ».

La correction n’est pas de supprimer le verbe, c’est de l’accoler systématiquement à son objet précis dans la description. « Vérifier » devient « vérifier un texte avant publication », jamais « vérifier » seul. Si l’excès persiste malgré une description resserrée, disable-model-invocation: true dans les informations d’en-tête du fichier (le frontmatter) réserve le Skill à l’appel explicite par son nom (/nom-du-skill) : utile pour tout ce qui déclenche une action structurante, où une bascule non voulue coûte plus cher qu’un appel manuel occasionnel.

Étape 4 — Confusion : comparer les deux descriptions côte à côte (4 minutes)

Le test des phrases ambiguës de l’article précédent t’a fait fabriquer une phrase de test avant de publier. Ici, la phrase n’est pas fabriquée : c’est celle qui vient de mal tourner en usage réel, dans une conversation qui contenait déjà d’autres éléments de contexte (un fichier ouvert, un sujet abordé juste avant). Ce contexte-là compte autant que les deux descriptions elles-mêmes, et il ne se reproduit pas artificiellement.

Avec deux Skills ou plus, une phrase peut activer le mauvais. Ouvre les deux fichiers SKILL.md en cause et pose la question directement à Claude Code, dans le contexte de la conversation qui a mal tourné :

Tu as déclenché synthese-reunion sur ma dernière phrase, mais je voulais
relecture-avant-publication. Qu'est-ce qui, dans ta description de synthese-reunion,
a capté cette phrase ?

La réponse pointe presque toujours vers le même mot générique repéré à l’étape 3, mais partagé cette fois entre deux fichiers plutôt qu’à l’intérieur d’un seul. Retire ce mot de l’un des deux, celui pour lequel il est le moins spécifique. Un Skill de synthèse de réunion garde « réunion » et « compte-rendu » ; un Skill de relecture garde « publication » et « texte prêt ». Aucun des deux ne garde « vérifier » ou « passe » seul.

Le réflexe qui évite de refaire ce travail dans six mois

Chaque fois qu’un Skill rate un déclenchement, note la phrase exacte dans un coin, même si tu corriges tout de suite. Après trois ou quatre notes sur le même Skill, un motif apparaît presque toujours : un vocabulaire que tu emploies naturellement et que la description n’a jamais couvert. C’est ce motif qu’il faut corriger, pas chaque phrase individuellement au fil de l’eau.

Ce qui vient de se passer

Tu as une méthode en trois branches (silence, excès, confusion) pour diagnostiquer n’importe quel Skill capricieux, sans jamais repartir d’une page blanche. Ça clôt le bloc Skills de cette série : dossier, SKILL.md écrit à la main, description testée et déboguée, plugin skill-creator pour aller plus vite quand utile.

En résumé

• Nomme le symptôme avant de corriger : silence (rien ne se déclenche), excès (se déclenche trop), confusion (le mauvais Skill se déclenche).
• Silence : reproduis la phrase exacte, demande à Claude pourquoi le Skill n’a pas réagi, plutôt que de reformuler ta demande.
• Excès : cherche le verbe générique commun aux déclenchements indésirables, accole-le à son objet précis ; disable-model-invocation: true en dernier recours pour les Skills structurants.
• Confusion : compare les deux descriptions concurrentes côte à côte, retire le mot générique partagé de celle où il est le moins spécifique.
• Note les phrases qui ratent un déclenchement au fil du temps : un motif récurrent vaut mieux qu’une correction isolée à chaque fois.

Prochaine étape : sortir de la mémoire d’une seule session en installant claude-mem, la mémoire persistante entre tes conversations.

---

Cette mise en pratique poursuit la série sur l’installation et la configuration de Claude Code, de zéro jusqu’à un premier programme fonctionnel. La vidéo est ici.

Abonne-toi au blog pour suivre la suite de la série.