Dépannage des skills
Mis à jour le 29 juillet 2026
Objectifs
À l’issue de cette leçon, vous serez capable de :
- Utiliser le validateur de skills pour détecter les problèmes structurels
- Diagnostiquer et corriger les problèmes courants de déclenchement et de chargement
- Résoudre les conflits de priorité entre skills enterprise, personnels, projet et plugins
- Déboguer les erreurs d’exécution : dépendances manquantes, permissions et chemins
Commencer par le validateur
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 votre demande, vous testez trois variantes. Le problème se situe souvent ailleurs, dans la structure du skill plutôt que dans ce qu’il raconte. D’où le premier réflexe : lancer la commande de vérification des skills d’agent avant toute autre investigation. Son installation varie selon le système d’exploitation, et uv reste le moyen le plus rapide de la configurer. Le validateur détecte les problèmes structurels avant que vous ne perdiez du temps à déboguer autre chose.
Le skill ne se déclenche pas
Le scénario le plus fréquent : votre skill existe, il passe la validation, et Claude ne l’utilise pas au moment où vous l’attendiez. La cause est presque toujours la description. Claude procède par correspondance sémantique — votre requête doit recouvrir le sens de la description, et sans recouvrement suffisant, il n’y a pas de correspondance.
Confrontez donc votre description à la façon dont vous formulez réellement vos requêtes, puis intégrez-y les phrases de déclenchement qu’un utilisateur emploierait spontanément. Prenez un skill de profilage de performance et éprouvez-le sur plusieurs formulations : « aide-moi à profiler ça », « pourquoi c’est lent ? », « rends ça plus rapide ». Si l’une d’elles reste sans effet, vous venez d’identifier les mots-clés qui manquent — ajoutez-les et refaites le test.
Variante du même problème : Claude charge un skill, mais pas celui que vous visiez. Cette confusion trahit des descriptions trop proches les unes des autres ; rendez-les plus distinctes, chacune décrivant son territoire sans empiéter sur le voisin.
Le skill n’apparaît même pas
Quand vous demandez quels skills sont disponibles et que le vôtre n’apparaît pas, ce n’est plus une question de formulation mais d’emplacement. Deux exigences se vérifient en quelques secondes : le fichier SKILL.md doit être placé dans un répertoire nommé, jamais à la racine du dossier des skills, et son nom doit être exactement SKILL.md, majuscules pour « SKILL », minuscules pour « md ». Un fichier skill.md parfaitement rédigé reste invisible. Si ces deux points sont bons, lancez claude --debug pour lire les erreurs de chargement.
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. Si votre organisation déploie un skill enterprise nommé code-review et que vous avez créé le vôtre sous le même nom, la version enterprise l’emporte à chaque fois, silencieusement. Deux issues : renommer votre skill de façon plus distinctive, ou discuter du skill enterprise avec votre administrateur.
Les skills apportés par un plugin ont leur propre mode de défaillance. Le plugin est installé, ses skills restent invisibles : videz le cache, redémarrez Claude Code, puis réinstallez. Si l’absence persiste, c’est la structure du plugin qui est en cause — et c’est là que le validateur prend toute sa valeur.
Les échecs à l’exécution
Reste le cas où le skill se charge puis échoue en cours de route. Trois causes couvrent l’essentiel. Un skill qui s’appuie sur des packages externes suppose ces dépendances installées sur la machine ; mentionnez-les dans la description pour que rien ne reste implicite. Les scripts réclament la permission d’exécution : un chmod +x sur les scripts référencés règle la question. Enfin, écrivez vos chemins avec des barres obliques, y compris sous Windows, sous peine de voir un skill valide échouer sur un seul séparateur.
| Problème | Solution |
|---|---|
| Ne se déclenche pas | Améliorez la description, ajoutez des phrases de déclenchement |
| Ne se charge pas | Vérifiez le chemin, le nom de fichier et la syntaxe YAML |
| Mauvais skill utilisé | Rendez les descriptions plus distinctes |
| Masqué par un autre | Vérifiez la hiérarchie de priorité, renommez si nécessaire |
| Skills de plugin absents | Videz le cache et réinstallez |
| Échec à l’exécution | Vérifiez dépendances, permissions et chemins |
Vous voici au terme du cours Introduction aux Skills d’agent : vous savez créer, configurer, partager et dépanner des skills dans Claude Code. Les meilleurs skills naissent de vrais points de friction, alors commencez par les instructions que vous répétez le plus souvent. Repensez à vos dernières semaines de travail : lequel de ces scénarios de panne avez-vous déjà rencontré, et quel correctif vous aurait fait gagner le plus de temps ? Posez ensuite la question à votre équipe — quel processus de validation adopter avant de partager un skill, pour que ces symptômes soient détectés chez son auteur plutôt que chez ses utilisateurs ?
Testez vos connaissances
Cinq questions pour vérifier que vous savez écrire, placer et déboguer un skill.
1. De quoi un skill est-il fait, concrètement ?
Réponse : D’un dossier contenant un fichier SKILL.md : un frontmatter (nom, description, et éventuellement allowed-tools) suivi de vos instructions en Markdown, plus les ressources ou scripts dont il a besoin.
2. Où placer un skill selon qui doit en bénéficier ?
Réponse : Dans ~/.claude/skills pour qu’il vous suive d’un projet à l’autre ; dans le dossier du projet pour qu’il soit versionné et partagé avec toute l’équipe.
3. Qu'est-ce qui déclenche réellement le chargement d'un skill ?
Réponse : Sa description. C’est elle que Claude lit pour décider si le skill correspond à la tâche en cours. Une description vague ne se déclenche jamais ; une description qui nomme explicitement les situations couvertes se déclenche.
4. À quoi sert `allowed-tools` ?
Réponse : À restreindre les outils que le skill peut employer — précieux pour un skill qui ne doit que lire, ou qui ne doit jamais écrire sur le disque.
5. Un skill ne se déclenche pas : par où commencer le diagnostic ?
Réponse : Vérifiez que le fichier s’appelle bien SKILL.md, que le frontmatter est valide, que le dossier est au bon endroit — puis reformulez la description pour qu’elle nomme le cas d’usage avec les mots que vous employez réellement.