Claude Code a ignoré mon skill 5 fois. 1 ligne l'a réglé

Un skill Claude Code peut marcher parfaitement quand vous tapez son nom et ne jamais se charger quand vous demandez la même chose avec des mots simples. Le nôtre a tourné à chaque fois qu'on a tapé son nom, et il a été ignoré à chaque fois qu'on a demandé la même tâche en langage courant. On l'a vu se faire ignorer, on a lu pourquoi, et on a réécrit la seule ligne qui a tout réglé.

Un skill est un jeu d'instructions enregistré que Claude Code va chercher tout seul quand votre demande correspond. Ce qui décide de la correspondance, c'est une ligne que Claude lit avant de choisir, et ce ne sont pas vos instructions. Les six étapes ci-dessous vous mènent du prompt que vous retapez sans cesse à un skill qui se charge seul, plus un test de vingt demandes qui repère un skill ignoré avant que votre équipe ne le fasse.

Test (même demande, sessions neuves)	Skill chargé
Appelé par son nom (/release-notes)	2 sur 2
Mots simples, description d'origine	0 sur 5
Mots simples, description réécrite	5 sur 5

Un skill est un dossier avec un seul fichier dedans, SKILL.md. Le fichier commence par un court en-tête (un nom et une description d'une phrase), suivi des instructions. Il fonctionne comme une fonction : l'appelant lit la signature et la docstring, et le corps ne s'exécute que lorsqu'on l'appelle. Rangez-le dans votre dossier personnel pour l'avoir dans tous vos projets, ou dans le dépôt pour que tous ceux qui y travaillent l'aient.

Partez de la tâche, pas du fichier. Prenez le prompt que vous retapez sans cesse et écrivez le résultat exact que vous voulez. Le nôtre : les release notes de la semaine, c'est-à-dire les commits depuis lundi, groupés par zone, sans les tâches de maintenance, une ligne par changement avec le numéro de sa pull request. Sur le dépôt open source Hono, ce long prompt a produit des notes propres pour huit corrections de bugs cette semaine-là, et ce résultat est devenu la cible que le skill devait atteindre.

Tous les prompts ne méritent pas un skill. Une question ponctuelle, non, et un skill que vous ne réutilisez jamais n'est qu'une ligne de plus que Claude doit lire. Gardez une courte liste des prompts que vous tapez chaque semaine ; celui qui est en haut devient votre premier skill.

Créez .claude/skills/release-notes/SKILL.md dans votre projet : un dossier skills dans le dossier caché .claude, un dossier portant le nom du skill, et le fichier du skill dedans. Le dossier compte. Un fichier release-notes.md posé à plat ne se charge pas du tout, et la documentation en fait la première chose à vérifier.

L'en-tête est constitué de quelques lignes étiquetées entre deux rangées de tirets, et il doit commencer à la première ligne du fichier, sinon Claude Code l'ignore. Le nôtre avait un nom, release-notes, et la description que la plupart des gens écriraient :

---
name: release-notes
description: Generates changelog documents from repository history.
---

Sous l'en-tête viennent les instructions, en étapes numérotées, celles que vous donneriez à un nouveau coéquipier. Les nôtres en comptent cinq : trouver les commits depuis lundi, écarter les commits chore et docs, grouper par portée de commit conventionnel, écrire une ligne simple par changement, et sortir un bloc titré avec un court résumé en haut. Anthropic recommande de garder cette partie courte. Pas besoin de redémarrer : Claude Code prend en compte un skill nouveau ou modifié dans la session où vous êtes déjà.

Testez-le par son nom : tapez une barre oblique, choisissez le skill dans le menu, appuyez sur entrée. Dans des sessions neuves, le nôtre a lu le journal des commits, groupé les corrections par zone et écrit les notes exactement comme voulu, à chaque fois. Le hic, c'est que vous, et toute votre équipe, devez vous souvenir de son nom.

Un coéquipier ne tapera pas le nom du skill. Il ouvrira une nouvelle session et demandera comme il vous le demanderait à vous. Alors testez ça : ouvrez une session neuve (une nouvelle conversation où rien n'est chargé) et demandez la tâche avec vos propres mots. Elle doit être neuve, parce qu'un skill déjà utilisé reste dans la conversation et qu'un test dans cette session ne prouve rien.

On a tapé « what did we ship this week? ». Claude a lancé lui-même le journal des commits et écrit un résumé à sa façon, sans aucune trace du skill. Les réponses n'étaient pas mauvaises, mais elles variaient d'une exécution à l'autre : l'une comptait depuis lundi, une autre depuis le dernier tag de version et intégrait un changement de documentation que le skill aurait écarté. Sur cinq sessions neuves, le skill a été ignoré cinq fois.

Cinq exécutions, c'est une démonstration, pas une statistique. Mais un skill qui marche par son nom et qui est ignoré à chaque fois en mots simples ne fait pas son travail, et comme il a réussi le test par son nom à l'étape deux, vous n'auriez jamais pensé à regarder.

Avant de changer un seul mot, faites trois vérifications :

1. /skills liste tous les skills que la session voit. Cherchez le vôtre. Le nôtre était listé et activé, mais l'installation comptait 277 skills, et plusieurs skills de plugins correspondaient à « release » avant le nôtre.
2. claude --debug écrit un journal détaillé de ce que Claude Code charge. Cherchez les lignes sur les skills. Le nôtre montrait le skill du projet chargé, et aussi un avertissement indiquant que la liste des skills dépassait le budget, donc que certaines descriptions sont coupées.
3. claude plugin validate .claude/skills vérifie que l'en-tête est bien formé. Celle-ci compte : un en-tête cassé laisse le skill tourner par son nom, mais Claude ne peut plus le faire correspondre tout seul. Le nôtre a passé.

Vérification	Ce qu'elle indique	Notre résultat
/skills	Le skill est-il visible et activé ?	Listé, activé (277 skills)
--debug	A-t-il été chargé ? La liste est-elle coupée ?	Chargé ; avertissement de liste hors budget
plugin validate	L'en-tête est-il lu correctement ?	Réussi

Fichier chargé et en-tête valide, la cause est la description. Tant qu'il n'a pas décidé de charger un skill, Claude ne lit pas vos instructions. Il lit une ligne par skill, le nom et la description, et la compare à vos mots. La nôtre disait « generates changelog documents from repository history » ; la demande disait « what did we ship this week ». Les deux phrases n'ont aucun mot en commun. Claude n'a jamais lu nos instructions ; il a lu une ligne, et cette ligne n'utilisait pas nos mots.

L'avertissement de budget signifie que Claude Code raccourcit les descriptions pour tenir dans la limite, en commençant par les skills les moins utilisés, et un skill tout neuf est le moins utilisé de tous. Vérifiez que le vôtre a survécu : le nôtre, oui, puisque les demandes qui employaient ses propres mots le chargeaient toujours.

Écrivez la description pour le moment où quelqu'un demande, pas pour le fichier. Dites ce que fait le skill, quand l'utiliser, et les mots que les gens tapent vraiment. La nôtre est devenue :

description: Writes this week's release notes from git log, grouped by scope (router, css, jsx). Use when the user asks what we shipped, what changed this week, for release notes, a changelog, or a summary of recent commits.

Le guide de rédaction d'Anthropic ajoute une règle : l'écrire à la troisième personne (« Writes »), jamais « I can help » ni « You can use this ».

Puis prouvez-le dans une session neuve avec la même demande. « What did we ship this week? » a cette fois chargé le skill avant que Claude ne touche à quoi que ce soit, et les notes sont sorties dans notre format, dans cinq sessions neuves sur cinq.

Faites aussi une référence : désactivez le skill avec un réglage skillOverrides dans votre fichier de réglages local (il le masque sans le supprimer). Désactivé, Claude est revenu à son propre résumé ; activé, le skill s'est chargé. C'est le skill qui a fait la différence, pas la chance.

La limite : une description qui correspond à trop de choses fait se déclencher le skill là où il ne devrait pas. Ajoutez les mots que vous employez vraiment, pas tous ceux auxquels vous pensez.

Une demande a prouvé la correction ; un skill sur lequel une équipe compte est demandé de bien des façons. Le skill-creator d'Anthropic décrit le test : vingt demandes, un mélange de celles qui doivent charger le skill et de quasi-ratés qui ne le doivent pas. Un quasi-raté ressemble à la tâche mais en est une autre, comme « write a commit message for my staged changes ». Lancez chaque demande dans sa propre session neuve et notez si le skill s'est chargé. Le script du skill-creator ne voyait pas le skill sur notre version de Claude Code, alors on a lancé les mêmes vingt demandes avec un court script à nous.

Description	Demandes à charger qui l'ont chargé	Quasi-ratés qui l'ont chargé
Originale	4 sur 10	0 sur 10
Réécrite	10 sur 10	0 sur 10

Avant la réécriture, le skill ne se chargeait que sur les demandes qui contenaient déjà « release notes », « changelog » ou « release » : la correspondance par mots de l'étape quatre, en pleine lumière. Après la réécriture, il s'est chargé sur toutes les demandes qui devaient le charger, et il est resté à l'écart de tous les quasi-ratés.

Pour un skill qui ne doit jamais rater, forcez-le. Tapez son nom, ou ajoutez un hook (un petit script que Claude Code exécute à un moment fixe, ici à chaque message que vous envoyez) dont la sortie dit à Claude d'utiliser le skill pour cette tâche. Avec le hook en place, même la description d'origine s'est chargée sur la demande en mots simples. La limite : chaque exécution de test consomme de l'usage réel et un hook ajoute une ligne à chaque message, alors gardez-le pour les quelques skills qui doivent vraiment se déclencher. Relancez votre liste à chaque changement de description.

Notre skill de release notes a marché à chaque fois par son nom, a été ignoré dans toutes les sessions neuves en mots simples, et une ligne réécrite l'a fait se charger à chaque fois. La raison : Claude lit une ligne par skill avant de décider, et il compare vos mots, pas vos intentions.

Un skill sert pour une tâche que vous répétez avec un résultat fixe : des notes hebdomadaires, une description de pull request, une checklist de version. Il ne sert pas pour une question ponctuelle, et ce n'est pas l'outil pour une règle qui doit toujours tenir ; c'est le travail d'un hook. Une pile de skills inutilisés coûte aussi, parce qu'avec trop de skills Claude Code se met à couper des descriptions, les moins utilisées d'abord. Une bonne description augmente les chances mais ne fera pas se déclencher un skill pour une tâche qu'il n'a jamais visée, et une poignée d'exécutions est une démonstration, donc votre liste de demandes de test est la vraie vérification.

La règle d'or : écrivez la description avec les mots que vous tapez vraiment quand vous demandez la tâche.