Écrire un skill Claude Code qui se déclenche vraiment

Si vous recollez les mêmes trois paragraphes d'instructions à chaque nouvelle session, vous avez déjà écrit un skill et vous le rangez simplement mal. Un skill est ce texte dans un fichier que l'agent peut charger seul, au moment où il est pertinent, plutôt que quand vous pensez à le fournir. La mécanique s'apprend en un après-midi, et ce qui décide de son efficacité n'est pas la mécanique.

L'emplacement du fichier décide qui l'obtient

Un skill est un dossier contenant un fichier markdown nommé SKILL.md, et l'emplacement du dossier est toute l'histoire du contrôle d'accès. Sous votre répertoire personnel, il se charge dans tous les projets de votre machine. Dans le dépôt, il se charge pour tous ceux qui y travaillent, une fois committé. La documentation des skills donne le tableau complet, y compris le cas imbriqué pour les monorepos et le cas plugin pour le diffuser dans une équipe.

Pour le travail client, l'emplacement dépôt est presque toujours le bon, car un skill qui encode la façon dont ce site est construit doit voyager avec le site. L'emplacement personnel sert à vos habitudes: comment vous aimez rédiger les commits, quels contrôles vous voulez toujours lancer.

C'est là que la plupart des skills échouent, et cela ne se voit pas en lisant. Le champ description n'est pas un résumé pour un humain qui parcourt une liste. C'est le texte que l'agent lit pour décider si ce skill s'applique à ce que vous venez de demander, et rien d'autre du skill n'est chargé avant cette décision. Une description qui dit ce que le skill est ne se déclenchera pas. Une description qui dit quand l'utiliser, si.

Deux détails en découlent. Mettez le cas d'usage principal en premier, car le texte de description combiné est tronqué dans la liste à 1 536 caractères pour limiter le coût en contexte. Et incluez les formulations que vous tapez réellement, pas le nom formel de la tâche: si vous dites vérifie le crawl, la description doit contenir vérifie le crawl.

Les champs d'en-tête qui changent le comportement

L'un d'eux mérite insistance. Tout ce qui déploie, supprime, publie ou envoie doit porter disable-model-invocation, pour ne tourner que lorsque vous tapez son nom. Nous verrouillons ainsi chaque skill que nous installons, en règle permanente, car le coût d'un skill de déploiement qui part de son propre chef n'est pas symétrique avec celui de taper six caractères.

Gardez le corps court, car il reste en contexte

Une fois chargé, le contenu d'un skill reste en contexte d'un tour à l'autre: chaque ligne est un coût récurrent pour le reste de la session. La documentation dit d'énoncer quoi faire plutôt que de narrer comment ou pourquoi, et c'est le bon instinct. Un skill qui explique son propre raisonnement sur quatre cents mots vous facture ce raisonnement à chaque requête suivante.

Ce qui rend cela supportable, ce sont les fichiers d'appui. Gardez SKILL.md pour les règles de décision et placez la documentation longue dans un fichier séparé à côté, mentionné par son nom. L'agent le lit quand il en a besoin, pas avant. Tout ce qui est déterministe relève d'un script et non de la prose: un contrôle dont la réponse est réussi ou échoué doit être une commande, pas un paragraphe demandant à l'agent de bien regarder.

Testez-le en cherchant à le déclencher

Le seul test qui compte: le skill se charge-t-il quand il devrait. Ouvrez une session neuve, formulez la demande comme vous le feriez naturellement, et voyez si le skill arrive. Puis formulez-la de trois autres façons. La plupart des skills cassés sont des fichiers corrects avec des descriptions qui ne rencontrent jamais le langage réel, et vous ne le découvrirez pas en relisant votre propre description, puisque vous savez déjà ce qu'elle veut dire.

Trois à écrire pour un dépôt de site

Commencez par le skill de vérification: la séquence exacte de commandes qui prouve qu'un changement fonctionne sur ce site, puisque cette séquence diffère pour chaque projet et que personne ne la retient. Puis le skill de contenu: les règles que suit votre copie, qui chez nous incluent de ne jamais utiliser de tiret cadratin et de savoir quelles pages restent en anglais seul. Puis le skill de release, réservé à l'invocation manuelle, portant la liste d'avant-déploiement de l'article sur la mise en production.

C'est le jeu complet pour un site vitrine, et il est délibérément petit. L'article compagnon sur les skills qui valent la peine couvre ceux que vous installez plutôt que d'écrire, et l'article sur CLAUDE.md couvre ce qui relève des instructions. Un skill répond à comment nous faisons ce travail précis; les instructions répondent à ce qui est toujours vrai ici. Confondre les deux, c'est ainsi que les deux fichiers deviennent trop longs.

Le nommage, et les deux façons d'invoquer un skill

Un skill peut arriver de deux façons, et la distinction décide du nommage. Soit l'agent le charge seul, en appariant votre demande à la description, soit vous tapez son nom comme une commande. Le nom reprend par défaut celui du dossier, et comme le même texte apparaît dans le menu des commandes, un skill appelé release se lit correctement quand on le tape et mal quand on l'apparie. La référence des commandes slash couvre l'ancien format de fichier de commande, toujours fonctionnel et partageant l'essentiel du même en-tête.

La règle pratique: nommez pour le cas tapé et rédigez la description pour le cas apparié, car les deux publics diffèrent réellement. Un verbe et un nom conviennent aux deux: check-crawl, write-post, run-release. Évitez les noms qui entrent en collision avec une commande que vous utilisez déjà, car la résolution entre skills homonymes devient une règle à retenir.

Le reste de la surface de configuration est couvert par les articles compagnons: les skills à installer plutôt qu'à écrire, les serveurs MCP qui résolvent le problème d'accès qu'un skill ne peut pas résoudre, et les hooks qui imposent ce qu'un skill se contente de demander.