Dépannage des skills

Un skill qui ne se comporte pas comme prévu vous met aussitôt sur la piste de son contenu : vous relisez vos instructions, vous reformulez, vous testez trois variantes. Le problème se situe souvent ailleurs, dans la structure, l’emplacement, le nom, ou la place qu’il reste dans la liste. Cette leçon suit l’ordre d’un diagnostic, du plus mécanique au plus subtil, et se termine par la question que la documentation pose désormais à tout auteur de skill : comment savoir qu’il fonctionne vraiment ?

Commencer par le validateur

Avant toute autre investigation, faites vérifier la structure. Dans Claude Code, claude plugin validate .claude/skills (ou ~/.claude/skills) repère les fichiers SKILL.md dont l’en-tête YAML ne s’analyse pas ; pour un plugin, claude plugin validate ./mon-plugin contrôle aussi le manifeste. La bibliothèque de référence du standard fournit l’équivalent indépendant du produit : skills-ref validate ./mon-skill. Un en-tête mal formé est le défaut le plus sournois : Claude Code charge quand même le corps du skill, mais sans ses champs, si bien que /nom fonctionne tandis que Claude ne peut plus reconnaître la description. claude --debug journalise l’erreur d’analyse.

Le skill ne se déclenche pas

Le scénario le plus fréquent : le skill existe, il passe la validation, et Claude ne l’utilise pas au moment attendu. La documentation donne l’ordre de vérification :

1. La description contient-elle les mots que vous employez vraiment ? Comparez-la à vos demandes réelles et ajoutez les tournures manquantes.
2. Le skill apparaît-il quand vous demandez « Quels skills sont disponibles ? »
3. Reformulez la demande pour qu’elle colle à la description.
4. Appelez-le directement avec /nom ; s’il est réservé à l’utilisateur (disable-model-invocation: true), c’est d’ailleurs le seul moyen.
5. Si /nom n’est pas reconnu non plus, le nom contient peut-être un caractère refusé (voir plus bas).
6. Si le skill déclare des paths, les fichiers sur lesquels Claude travaille doivent être dans le répertoire courant : un fichier d’un worktree voisin, même ajouté avec /add-dir, ne compte pas.

Souvenez-vous aussi que Claude ne consulte un skill que si la tâche dépasse ce qu’il sait faire seul : une demande d’une étape peut ne pas déclencher un skill pourtant bien décrit. Variante du problème : Claude charge un skill, mais pas celui que vous visiez. Des descriptions trop proches se concurrencent ; rendez-les plus distinctes, chacune décrivant son territoire. À l’inverse, un skill qui se déclenche trop souvent demande une description plus précise, ou disable-model-invocation: true.

La liste est coupée

Quand vous avez beaucoup de skills, un autre mécanisme entre en jeu. Claude Code met en contexte la liste des noms et descriptions, dans un budget qui vaut 1 % de la fenêtre du modèle. Au-delà, il conserve tous les noms mais abandonne des descriptions, en commençant par les skills que vous invoquez le moins, ce qui retire précisément les mots-clés dont Claude a besoin. /doctor estime le coût de la liste et ses plus gros contributeurs ; /skill-doctor indique ce que chaque skill coûte et combien de fois il a servi, pour décider lesquels couper. Vous pouvez aussi relever le budget (skillListingBudgetFraction), réduire un skill à son nom (skillOverrides: "name-only") ou raccourcir les descriptions, le cas d’usage principal en premier, chaque entrée étant plafonnée à 1 536 caractères.

Le skill n’apparaît même pas

Quand le skill n’est pas listé du tout, ce n’est plus une question de formulation mais d’emplacement et de nom. Vérifiez dans l’ordre :

• le fichier s’appelle exactement SKILL.md, dans un dossier au nom du skill, lui-même dans un dossier skills/ ; un skill.md parfaitement rédigé reste invisible ;
• le nom du dossier n’est ni synced ni anthropic-skills (réservés aux skills synchronisés depuis claude.ai) et ne contient ni <, ni >, ni espace insécable ou double, ni caractère invisible ; Claude Code refuse ces noms et le signale dans le journal de claude --debug ;
• un dossier .claude/skills/ créé après le démarrage de la session est pris en compte avec /reload-skills ; un skill dans un sous-dossier du projet ne se charge que lorsque Claude y travaille, ou après /add-dir ;
• pour un skill de plugin, le plugin est-il installé et activé ? /plugin (onglet Installed) affiche les erreurs de chargement, et /reload-plugins applique un changement sans redémarrer ;
• en Cowork ou dans une session cloud, seuls les skills activés sur votre compte claude.ai (ou commités dans le dépôt, hors projets) sont présents : ~/.claude/skills/ de votre machine n’y est pas lu.

Quand la priorité joue contre vous

Un skill personnel systématiquement ignoré alors que tout semble correct signale une collision de noms avec un skill de priorité supérieure : un skill déployé par votre organisation nommé code-review l’emporte sur le vôtre, silencieusement. À nom égal : organisation, puis personnel, puis projet ; votre skill remplace un skill fourni avec Claude Code (code-review), mais pas ses alias (/review reste l’original). Deux issues : renommer votre skill de façon plus distinctive, ou en discuter avec votre administrateur. Dans un dépôt partagé, un skill de projet que vous ne voulez pas chez vous se coupe depuis /skills (touche Espace), qui écrit skillOverrides dans .claude/settings.local.json.

Claude cesse de suivre le skill

Claude suit le skill dans sa première réponse, puis l’oublie. Trois cas, chacun avec son remède. Si Claude a sauté une règle qui doit tenir à chaque fois, déplacez-la dans un hook : Claude Code l’exécute à chaque événement, quoi que Claude décide ; pour la garder avec le skill, déclarez le hook dans son en-tête. Si Claude a sauté une consigne qu’il doit appliquer avec jugement, formulez-la pour toute la tâche (« lance les tests après chaque modification » plutôt que « lance les tests ») : le contenu du skill est ajouté une fois à la conversation, et Claude Code ne relit pas le fichier aux tours suivants. Si la conversation a été compactée, réinvoquez le skill : après compaction, seuls ses 5 000 premiers tokens sont conservés, d’où l’importance de mettre l’essentiel en haut de SKILL.md.

Les échecs à l’exécution

Reste le cas où le skill se charge puis échoue en route. Un skill qui s’appuie sur des paquets externes suppose ces dépendances installées : déclarez-les dans compatibility, ou passez par une commande ponctuelle épinglée (uvx, npx) qui les résout seule. Un script doit être exécutable (chmod +x) et appelé par ${CLAUDE_SKILL_DIR}/scripts/…, jamais par un chemin relatif au répertoire courant ni par un chemin Windows à barres inverses. Une commande !`…` ne s’exécute pas dans un skill synchronisé depuis claude.ai. Et un skill de projet dans un dossier que vous n’avez pas encore approuvé peut voir ses hooks retenus jusqu’au dialogue de confiance, alors que ses allowed-tools s’appliquent déjà.

Savoir qu’un skill fonctionne

Voir un skill se déclencher prouve que Claude l’a trouvé, pas qu’il a fait ce que vous vouliez. La documentation recommande une comparaison de référence : rassemblez quelques demandes réalistes, exécutez chacune dans une session neuve avec le skill, puis sans (réglé sur off dans skillOverrides), et comparez. La session neuve compte, car le contexte accumulé en écrivant le skill masque les trous de ses instructions. Deux outils automatisent la boucle : le plugin skill-creator d’Anthropic (/plugin install skill-creator@claude-plugins-official), qui écrit des cas de test, lance un sous-agent par cas, note les réponses et compare avec et sans skill ; et claude plugin eval pour un skill livré dans un plugin, qui répète chaque cas sans le plugin et peut bloquer une CI sous un seuil.

Pour le déclenchement seul, agentskills.io propose une méthode simple : une vingtaine de demandes, moitié qui doivent déclencher, moitié qui ne doivent pas (surtout des « presque » : même vocabulaire, besoin différent), chacune lancée trois fois avec claude -p … --output-format json pour mesurer un taux de déclenchement. Le script d’exemple tient en vingt lignes de shell.

À vous de jouer

1. Cassez volontairement l’en-tête d’un skill (un --- manquant), lancez claude plugin validate .claude/skills, puis claude --debug et retrouvez l’erreur dans le journal.
2. Renommez un skill code-review : vérifiez que /code-review lance le vôtre et que /review lance toujours celui de Claude Code.
3. Écrivez dix demandes pour votre skill pr-description, cinq qui doivent le déclencher et cinq « presque » qui ne doivent pas, et testez-les avec claude -p en mode JSON.
4. Installez skill-creator et demandez « évalue mon skill pr-description avec skill-creator » ; lisez le benchmark.json produit.

Sources officielles : Extend Claude with skills · Test plugins with evals · Optimizing skill descriptions · Evaluating skill output quality · Spécification Agent Skills

Points clés à retenir

• Validez d’abord (claude plugin validate, skills-ref validate) : un YAML cassé charge le corps sans la description
• Déclenchement : mots réels dans la description, « Quels skills sont disponibles ? », /nom, paths dans le répertoire courant ; la liste est plafonnée à 1 % du contexte (/doctor, /skill-doctor)
• Invisible : SKILL.md exact, noms réservés et caractères refusés, /reload-skills, /reload-plugins, et pas de ~/.claude/skills/ dans le cloud
• Oublié en route : hook pour les règles strictes, consignes formulées pour toute la tâche, réinvoquer après compaction
• Mesurez avec une comparaison avec et sans skill : skill-creator, claude plugin eval, taux de déclenchement sur vingt demandes

Testez vos connaissances