Dépannage des Skills

Dépannage des Skills

Points clés à retenir

• Commencez par l'outil de validation des Skills — il détecte les problèmes structurels avant que vous ne passiez du temps à déboguer autre chose
• Si un Skill ne se déclenche pas, la cause est presque toujours la description — ajoutez des expressions déclencheuses qui correspondent à la façon dont vous formulez réellement vos requêtes
• Si un Skill ne se charge pas, vérifiez que SKILL.md se trouve dans un répertoire nommé (et non à la racine des Skills) et que le nom du fichier est exactement SKILL.md
• Si le mauvais Skill est utilisé, vos descriptions sont trop similaires — rendez-les plus distinctes
• Pour les erreurs d'exécution, vérifiez les dépendances, les autorisations de fichiers (chmod +x) et les séparateurs de chemin (utilisez des barres obliques partout)

Lorsque les Skills ne fonctionnent pas, le problème se situe généralement dans l'une de quelques catégories : le Skill ne se déclenche pas, ne se charge pas, présente des conflits, ou échoue à l'exécution. La bonne nouvelle, c'est que la plupart des corrections sont assez simples.

Utiliser l'outil de validation des Skills

La première chose à essayer est la commande claude plugin validate. Dans votre shell, exécutez claude plugin validate ~/.claude/skills pour les Skills personnels ou claude plugin validate .claude/skills pour les Skills de projet. Cela nécessite Claude Code v2.1.233 ou une version ultérieure.

Le validateur détecte les fichiers SKILL.md dont le frontmatter ne s'analyse pas correctement, ce qui vous permet de repérer ce problème avant de passer du temps à déboguer autre chose. La vidéo ci-dessus présente un vérificateur distinct que vous installez avec uv.

Le Skill ne se déclenche pas

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

Claude utilise une correspondance sémantique, donc votre requête doit recouper le sens de la description. S'il n'y a pas assez de recoupement, il n'y a pas de correspondance. Voici ce qu'il faut faire :

• Comparez votre description à la façon dont vous formulez réellement vos requêtes
• Ajoutez des expressions déclencheuses que les utilisateurs diraient réellement
• Testez avec des variantes telles que « aide-moi à profiler ceci », « pourquoi est-ce lent ? », « rends ceci plus rapide »
• Si une variante ne déclenche pas le Skill, ajoutez ces mots-clés à votre description

Le Skill ne se charge pas

Si votre Skill n'apparaît pas lorsque vous demandez à Claude « quels Skills sont disponibles », vérifiez ces exigences structurelles :

• Le fichier SKILL.md doit se trouver dans un répertoire nommé, et non à la racine des Skills
• Le nom du fichier doit être exactement SKILL.md — « SKILL » tout en majuscules, « md » en minuscules

Exécutez claude --debug pour voir les erreurs de chargement. Recherchez les messages mentionnant le nom de votre Skill. Parfois, cela seul vous mènera directement au problème.

Le mauvais Skill est utilisé

Si Claude utilise le mauvais Skill ou semble confondre les Skills, vos descriptions sont probablement trop similaires. Rendez-les distinctes. Être aussi précis que possible n'aide pas seulement Claude à décider quand utiliser votre Skill — cela évite aussi les conflits avec d'autres Skills aux noms similaires.

Conflits de priorité entre Skills

Si votre Skill personnel est ignoré, un Skill d'entreprise ou de priorité supérieure porte peut-être le même nom.



Par exemple, s'il existe un Skill d'entreprise « code-review » et que vous avez également un Skill personnel « code-review », celui de l'entreprise l'emporte à chaque fois. Vos options :

1. Renommez votre Skill en quelque chose de plus distinct (c'est généralement la solution la plus simple)
2. Parlez à votre administrateur du Skill d'entreprise

Les Skills de plug-in n'apparaissent pas

Vous avez installé un plug-in mais vous ne voyez pas ses Skills ? Exécutez /plugin et vérifiez que le plug-in est répertorié et activé sous Installés, puis consultez l'onglet Erreurs. Si vous l'avez installé au cours de cette session, exécutez /reload-plugins.

Si les Skills n'apparaissent toujours pas après cela, la structure du plug-in est peut-être incorrecte. Les Skills se chargent à partir d'un répertoire skills/ à la racine du plug-in, et non depuis l'intérieur de .claude-plugin/. Dans votre shell, exécutez claude plugin validate sur le répertoire du plug-in pour vérifier son manifeste et le frontmatter de chaque Skill.

Erreurs d'exécution

Le Skill se charge mais échoue pendant l'exécution. Quelques causes courantes :

• Dépendances manquantes : Si votre Skill utilise des packages externes, ceux-ci doivent être installés. Ajoutez des informations sur les dépendances à la description de votre Skill afin que Claude sache ce qui est nécessaire.
• Problèmes d'autorisation : Les scripts ont besoin de l'autorisation d'exécution. Exécutez chmod +x sur tous les scripts référencés par votre Skill.
• Séparateurs de chemin : Utilisez des barres obliques partout, même sous Windows.

Liste de contrôle rapide pour le dépannage

• Ne se déclenche pas ? Améliorez votre description et ajoutez des expressions déclencheuses.
• Ne se charge pas ? Vérifiez votre chemin, le nom du fichier et la syntaxe YAML.
• Mauvais Skill utilisé ? Rendez les descriptions plus distinctes les unes des autres.
• Masqué par un autre Skill ? Vérifiez la hiérarchie de priorité et renommez si nécessaire.
• Skills de plug-in manquants ? Vérifiez /plugin pour détecter les erreurs, puis exécutez /reload-plugins.
• Échec à l'exécution ? Vérifiez les dépendances, les autorisations et les chemins.

Réflexion sur la leçon

• Avez-vous déjà rencontré l'un de ces scénarios de dépannage dans votre propre travail ? Quelle correction vous aurait fait gagner le plus de temps ?
• Comment mettriez-vous en place un processus pour valider les Skills avant de les partager avec votre équipe ?

Conclusion du cours

Félicitations pour avoir terminé Introduction aux Skills d'agent ! Vous avez appris à créer, configurer, partager et dépanner des Skills dans Claude Code. Lorsque vous commencerez à créer des Skills pour vos propres flux de travail, rappelez-vous que les meilleurs Skills naissent de véritables points de friction — commencez par les instructions que vous vous surprenez à répéter le plus souvent.