Depannage des skills

Objectifs

A l’issue de cette lecon, vous serez capable de :

• Utiliser le validateur de skills pour detecter les problemes structurels
• Diagnostiquer et corriger les problemes courants de declenchement et de chargement
• Resoudre les conflits de priorite entre skills enterprise, personnels, projet et plugins
• Deboguer les erreurs d’execution : dependances manquantes, permissions et chemins

Le validateur de skills

Le premier reflexe est d’utiliser la commande de verification des skills d’agent. L’installation varie selon le systeme d’exploitation, mais utiliser uv est le moyen le plus rapide de le configurer.

Le validateur detecte les problemes structurels avant que vous ne perdiez du temps a deboguer autre chose.

Le skill ne se declenche pas

Votre skill existe et passe la validation, mais Claude ne l’utilise pas quand vous l’attendez. La cause est presque toujours la description.

Claude utilise la correspondance semantique : votre requete doit recouvrir le sens de la description. S’il n’y a pas assez de recouvrement, pas de correspondance.

A faire :

• Verifiez votre description par rapport a la facon dont vous formulez vos requetes
• Ajoutez des phrases de declenchement que les utilisateurs diraient naturellement
• Testez avec des variantes comme “aide-moi a profiler ca”, “pourquoi c’est lent ?”, “rends ca plus rapide”
• Si une variante ne declenche pas le skill, ajoutez ces mots-cles a la description

Le skill ne se charge pas

Si votre skill n’apparait pas quand vous demandez “quels skills sont disponibles”, verifiez :

• Le fichier SKILL.md doit etre dans un repertoire nomme, pas a la racine du dossier skills
• Le nom de fichier doit etre exactement SKILL.md — tout en majuscules pour “SKILL”, minuscules pour “md”

Lancez claude --debug pour voir les erreurs de chargement.

Le mauvais skill est utilise

Si Claude utilise le mauvais skill ou semble confus entre plusieurs skills, vos descriptions sont probablement trop similaires. Rendez-les plus distinctes.

Conflits de priorite

Si votre skill personnel est ignore, un skill enterprise ou de priorite superieure porte peut-etre le meme nom.

Par exemple, s’il existe un skill enterprise “code-review” et que vous avez aussi un skill personnel “code-review”, la version enterprise l’emporte systematiquement. Vos options :

• Renommez votre skill avec un nom plus distinctif
• Discutez avec votre admin du skill enterprise

Skills de plugins qui n’apparaissent pas

Un plugin installe mais ses skills sont invisibles ? Videz le cache, redemarrez Claude Code, et reinstallez.

Si les skills n’apparaissent toujours pas, la structure du plugin est peut-etre incorrecte. C’est la que le validateur prend toute sa valeur.

Erreurs d’execution

Le skill se charge mais echoue pendant l’execution. Causes courantes :

• Dependances manquantes : si votre skill utilise des packages externes, ils doivent etre installes. Ajoutez les informations de dependances a la description.
• Problemes de permissions : les scripts ont besoin de la permission d’execution. Lancez chmod +x sur les scripts references.
• Separateurs de chemins : utilisez des barres obliques (forward slashes) partout, meme sous Windows.

Checklist rapide de depannage

---

Felicitations ! Vous avez termine le cours Introduction aux Skills d’agent. Vous savez maintenant creer, configurer, partager et depanner des skills dans Claude Code. Les meilleurs skills naissent de vrais points de friction — commencez par les instructions que vous repetez le plus souvent.

Questions de reflexion

• Avez-vous deja rencontre l’un de ces scenarios dans votre travail ? Quel correctif vous aurait fait gagner le plus de temps ?
• Comment mettriez-vous en place un processus de validation des skills avant de les partager avec votre equipe ?