Pourquoi une skill ne se déclenche pas, et comment corriger sa description

Une skill ne sert que si votre agent la charge. Il ne lit pas toutes vos skills à chaque demande : il décide à partir d'une courte description. La plupart des skills « qui ne marchent pas » ont en réalité une description qui ne correspond pas à la façon dont vous formulez vos demandes.

Comment l'agent choisit une skill

Les agents chargent les skills par étapes, pour ne pas encombrer leur contexte.

1. Au démarrage, l'agent lit uniquement le nom et la description de chaque skill installée. La spécification Agent Skills estime ce coût à une centaine de tokens par skill.
2. Quand votre demande correspond à une description, il lit le fichier SKILL.md complet et suit ses instructions.
3. Pendant le travail, il ouvre les fichiers annexes (références, modèles, scripts) seulement s'il en a besoin.

La description porte donc tout le poids du déclenchement. Si elle n'indique pas quand la skill est utile, l'agent n'a aucune raison d'aller la chercher. Une conséquence moins connue : un agent consulte surtout les skills pour les tâches qui demandent un savoir-faire qu'il n'a pas seul. Une demande simple en une étape, comme « lis ce PDF », peut ne rien déclencher même avec une description parfaite, parce que l'agent s'en sort avec ses outils de base.

Pourquoi elle ne se déclenche pas

Quatre points propres à Claude Code, d'après sa documentation :

• La description et le champ facultatif when_to_use sont tronqués ensemble à 1 536 caractères dans la liste des skills. Placez le cas d'usage principal au début.
• Cette liste a un budget de caractères, égal à 1 % de la fenêtre de contexte du modèle. Quand il est dépassé, Claude Code retire d'abord les descriptions des skills que vous invoquez le moins. Les noms restent, mais plus les mots-clés qui permettaient de les reconnaître.
• Si le frontmatter YAML est mal formé, la skill se charge avec des métadonnées vides : /nom-de-la-skill fonctionne encore, mais l'agent ne peut plus la reconnaître d'après sa description. Le frontmatter n'est lu que si la ligne --- est la toute première du fichier. Lancez Claude Code avec --debug pour voir l'erreur d'analyse.
• Une skill dont disable-model-invocation vaut true ne se déclenche jamais seule : sa description n'est même pas dans le contexte.

Pour savoir quelles skills Claude voit, demandez-lui « What skills are available? ». Si une skill y manque, le problème est l'installation, pas la description. La page de Claude Code donne les dossiers à vérifier.

Écrire une description qui se déclenche

Voici l'en-tête d'une skill dont la description est trop vague :

---
name: pdf-tools
description: Aide pour les PDF.
---

Et une version qui indique à la fois ce que fait la skill et quand l'utiliser :

---
name: pdf-tools
description: Extrait le texte et les tableaux de fichiers PDF, remplit des formulaires PDF et fusionne plusieurs PDF. À utiliser quand l'utilisateur parle de PDF, de formulaires ou d'extraction de documents, même s'il ne cite pas le mot « PDF » explicitement.
---

Les règles à retenir, tirées de la spécification et du guide d'optimisation Agent Skills :

• Dites ce que fait la skill et quand l'utiliser. La description fait de 1 à 1 024 caractères.
• Adressez-vous à l'agent. « À utiliser quand… » vaut mieux que « Cette skill fait… » : l'agent décide d'agir, dites-lui quand.
• Partez de l'intention de l'utilisateur, pas du fonctionnement interne de la skill. L'agent compare la description à ce que vous demandez.
• Listez les situations, y compris indirectes. Ajoutez les cas où vous ne nommez pas le domaine, par exemple une demande de « marge » pour une skill de tableurs.
• Restez bref. Quelques phrases suffisent, et chaque description occupe du contexte pour toutes vos conversations.

Évitez les chevrons dans la description : Claude Code les affiche sous forme de < et >. Utilisez des crochets pour un paramètre, par exemple [branche].

Tester et ajuster

Ne jugez pas une description sur un seul essai. Le guide Agent Skills recommande de préparer des demandes réalistes, certaines qui doivent déclencher la skill, d'autres qui ne le doivent pas, puis de relever le résultat après chaque modification.

1. Écrivez une dizaine de demandes telles que vous les formulez vraiment, avec fautes, raccourcis et contexte.
2. Ajoutez quelques demandes voisines qui ne doivent pas déclencher la skill, pour repérer une description trop large.
3. Lancez chaque demande dans une nouvelle session et notez si l'agent charge la skill.
4. Modifiez la description, puis recommencez. Si la skill se déclenche trop souvent, précisez la description. Dans Claude Code, vous pouvez aussi ajouter disable-model-invocation: true et ne la lancer qu'à la main, ce qui convient aux actions avec effet de bord comme un déploiement.

Une fois la skill chargée, elle peut être oubliée en cours de route. Claude Code ajoute son contenu à la conversation au moment de l'appel, et après un résumé automatique du contexte il ne conserve que le début de chaque skill appelée. Mettez donc les consignes essentielles en haut de SKILL.md, et rappelez la skill si l'agent s'en écarte.

Pour installer une première ressource, voir Installer votre première ressource. Pour comprendre ce qu'une skill apporte par rapport à un prompt, voir Ressource ou simple prompt ?. Les skills du catalogue se parcourent sur la page des skills.