Bien écrire la description d’un Skill : le champ qui décide de tout

À la fin de cet article, tu auras une liste de quatre vérifications à faire sur la description de n’importe quelle compétence (Skill) avant de la considérer terminée. Tu sauras aussi repérer le moment où deux de tes Skills perso se battent pour être choisis en même temps.

L’article précédent t’a fait écrire deux Skills à la main : relecture-avant-publication (qui relit un texte) et synthese-reunion (qui résume une réunion). Avec un seul Skill, tout va bien. Avec deux, un problème peut apparaître que le premier Skill seul ne pose jamais : leurs descriptions se ressemblent au point que Claude Code hésite entre les deux.

Ce qu’il te faut

Claude Code installé, et au moins deux Skills perso existants. Si tu as suivi la série, tu as déjà relecture-avant-publication et synthese-reunion dans ~/.claude/skills/. Sinon, n’importe quelle paire de Skills que tu as créés fera l’affaire, l’exercice porte sur leurs descriptions, pas sur leur contenu.

Étape 1 — Comprendre ce que la description fait vraiment (2 minutes)

Une compétence (Skill), c’est un peu comme un dossier de procédure rangé dans une armoire de bureau : à l’intérieur, des instructions précises pour faire une tâche (relire un texte, résumer une réunion). La description, c’est l’étiquette collée sur ce dossier, écrite dans l’en-tête de métadonnées (frontmatter) en haut du fichier SKILL.md. Claude Code a potentiellement des dizaines de dossiers dans son armoire (~/.claude/skills/). Avant chaque message que tu envoies, il ne lit que les étiquettes, jamais le contenu des dossiers, pour décider lequel ouvrir (Claude Code — Extend Claude with skills). Le contenu du dossier, le corps du fichier, n’est lu qu’une fois le dossier choisi.

Ça change deux choses concrètes. D’abord, une étiquette floue ne se rattrape pas en soignant l’intérieur du dossier : si Claude ne l’a jamais lue comme pertinente, le contenu, même parfait, ne sert à rien. Ensuite, une étiquette trop générale ne se contente pas de mal fonctionner : elle attire aussi des demandes qui appartiennent à un autre dossier, ou à aucun.

Étape 2 — Réécrire une description trop vague, en trois passes (5 minutes)

Prends une version volontairement faible de relecture-avant-publication :

description: Aide à la relecture de textes.

Passe 1 : nommer exactement ce que fait le Skill. Pas une formule vague comme « aide à la relecture », mais la phrase que tu dirais vraiment quand tu veux ce Skill :

description: Relit un texte avant publication et signale les affirmations non sourcées,
  les tournures commerciales et les anglicismes évitables.

Passe 2 : ajouter le moment où ça doit se déclencher. À quel moment cette demande arrive-t-elle, avec quels mots :

description: Relit un texte avant publication et signale les affirmations non sourcées,
  les tournures commerciales et les anglicismes évitables. À utiliser quand l'utilisateur
  demande une relecture, une passe finale, ou dit qu'un texte est prêt à publier.

Passe 3 : écrire un contre-exemple. Une phrase qui ressemble à une bonne raison de déclencher le Skill, mais qui ne doit pas en déclencher un :

description: [...] Ne pas utiliser pour rédiger un texte de zéro, ni pour corriger du code.

Chaque passe répond à une question différente : quoi, quand, et quand pas. Une description qui répond seulement à la première question tient sur une ligne, et elle rate la moitié des occasions où elle devrait se déclencher.

Étape 3 — Détecter un conflit entre deux Skills (4 minutes)

Avec deux Skills installés, une même phrase peut, en théorie, coller aux deux étiquettes en même temps. Vérifie-le directement, avec une phrase volontairement ambiguë :

Peux-tu me faire une passe sur ce texte avant que je l'envoie à l'équipe ?

Cette phrase pourrait correspondre à relecture-avant-publication (une relecture avant envoi), ou semer le doute avec synthese-reunion si le mot « équipe » fait penser à une réunion. Si Claude Code hésite ou choisit le mauvais Skill, ne devine pas la raison au hasard : demande-lui directement.

Entre relecture-avant-publication et synthese-reunion, lequel correspondait le mieux
à ma dernière demande, et pourquoi as-tu choisi celui-là ?

La réponse te montre quel mot a fait pencher la décision d’un côté. C’est souvent un mot générique présent dans les deux étiquettes : « texte », « passe », « vérifier ». La correction n’est pas de tout réécrire, c’est de retirer ce mot générique d’une des deux descriptions et de le remplacer par un mot propre à ce Skill précis. Un Skill de relecture parle de « publication », un Skill de réunion parle de « notes » ou de « compte-rendu », jamais des deux en même temps.

Étape 4 — La checklist avant de publier un Skill (2 minutes)

Applique ces quatre tests à toute nouvelle description, avant même de tester le Skill dans une vraie conversation :

1. Le test du quoi : une personne qui ne connaît pas ce Skill comprend-elle ce qu’il fait à la lecture de la description seule ?
2. Le test du quand : la description nomme-t-elle une situation concrète, ou seulement une catégorie abstraite (« aide à », « permet de ») ?
3. Le test du contre-exemple : y a-t-il une phrase explicite sur ce que ce Skill ne doit pas couvrir ?
4. Le test du voisin : si tu as d’autres Skills, partagent-ils un mot générique qui pourrait faire pencher un déclenchement du mauvais côté ?

Un Skill qui réussit ces quatre tests est prêt à être essayé en conditions réelles. Un Skill qui échoue au test du voisin fonctionnera très bien tout seul, mais se comportera bizarrement dès que tu auras plus de deux ou trois Skills perso.

Ce qui vient de se passer

Tes deux Skills perso ont maintenant une description révisée selon les quatre passes (quoi, quand, contre-exemple, voisin). Tu as aussi une méthode que tu peux répéter pour repérer un conflit avant qu’il ne se manifeste par un déclenchement bizarre en pleine session de travail.

En résumé

• La description est le seul texte que Claude Code garde toujours sous la main. Un Skill parfait à l’intérieur ne compense pas une étiquette floue à l’extérieur.
• Écris-la en trois passes : le quoi (ce que fait le Skill exactement), le quand (le moment et les mots réels qui doivent le déclencher), le contre-exemple (une phrase piège qui ne doit pas le déclencher).
• Avec plusieurs Skills perso, teste une phrase ambiguë et demande directement à Claude lequel il choisirait et pourquoi, plutôt que de deviner.
• Un mot générique partagé entre deux descriptions (« texte », « passe », « vérifier ») est la cause la plus fréquente de conflit entre Skills.
• Liste de quatre vérifications (quoi, quand, contre-exemple, voisin) avant de considérer une description terminée.

Prochaine étape : que faire quand un Skill qui a pourtant passé cette checklist refuse quand même de se déclencher, ou se déclenche trop souvent.

---

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.