Compétences de dépannage

Ce que vous apprendrez

Durée estimée : 15 minutes

À la fin de cette leçon, vous serez capable de :

• Utiliser le validateur de compétences pour détecter les problèmes structurels avant le débogage
• Diagnostiquer et corriger les problèmes courants de déclenchement et de chargement des compétences
• Résoudre les conflits de priorité des compétences entre les compétences d'entreprise, personnelles, de projet et de plugin
• Déboguer les erreurs d'exécution, notamment les dépendances manquantes, les problèmes de permissions et les problèmes de chemin

Dépannage des compétences

(4 minutes)

Quand les compétences ne fonctionnent pas comme prévu, le problème tombe généralement dans quelques catégories prévisibles. Cette vidéo vous guide à travers chacune d'elles — des compétences qui ne se déclenchent pas aux conflits de priorité en passant par les défaillances d'exécution — et vous donne une approche systématique du dépannage. Vous apprendrez également à utiliser l'outil de validateur de compétences et comment utiliser claude --debug pour diagnostiquer les problèmes de chargement.

Points clés à retenir

• Commencez par l'outil de validateur de compétences — il détecte les problèmes structurels avant que vous ne passiez du temps à déboguer d'autres choses
• Si une compétence ne se déclenche pas, la cause est presque toujours la description — ajoutez des phrases de déclenchement qui correspondent à la façon dont vous formulez réellement les demandes
• Si une compétence ne se charge pas, vérifiez que SKILL. md se trouve dans un répertoire nommé (pas à la racine des compétences) et que le nom du fichier est exactement SKILL. md
• Si la mauvaise compétence est utilisée, vos descriptions sont trop similaires — rendez-les plus distinctes
• Pour les erreurs d'exécution, vérifiez les dépendances, les permissions de fichier (chmod +x) et les séparateurs de chemin (utilisez des barres obliques partout)

Quand les compétences ne fonctionnent pas, le problème tombe généralement dans l'une de quelques catégories : la compétence ne se déclenche pas, ne se charge pas, a des conflits ou échoue à l'exécution. La bonne nouvelle, c'est que la plupart des corrections sont assez simples.

Utiliser le validateur de compétences

La première chose à essayer est la commande de vérificateur de compétences de l'agent. Les étapes d'installation varient selon le système d'exploitation, mais utiliser uv est le moyen le plus facile de le configurer rapidement.

Une fois installé, accédez à votre répertoire de compétences ou exécutez la commande de n'importe où. Le validateur détectera les problèmes structurels avant que vous ne passiez du temps à déboguer d'autres choses.

La compétence ne se déclenche pas

Votre compétence 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 la correspondance sémantique, donc votre demande doit chevaucher le sens de la description. S'il n'y a pas assez de chevauchement, pas de correspondance. Voici ce qu'il faut faire :

• Vérifiez votre description par rapport à la façon dont vous formulez réellement les demandes
• Ajoutez des phrases de déclenchement que les utilisateurs diraient réellement
• Testez avec des variations comme « aide-moi à profiler ceci », « pourquoi c'est lent ? », « rends ceci plus rapide »
• Si une variation ne se déclenche pas, ajoutez ces mots-clés à votre description

La compétence ne se charge pas

Si votre compétence n'apparaît pas quand vous demandez à Claude « quelles compétences sont disponibles », vérifiez ces exigences structurels :

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

Exécutez claude --debug pour voir les erreurs de chargement. Recherchez les messages mentionnant le nom de votre compétence. Parfois, cela seul vous pointera directement vers le problème.

La mauvaise compétence est utilisée

Si Claude utilise la mauvaise compétence ou semble confus entre les compétences, vos descriptions sont probablement trop similaires. Rendez-les distinctes. Être aussi spécifique que possible n'aide pas seulement Claude à décider quand utiliser votre compétence — cela prévient également les conflits avec d'autres compétences aux noms similaires.

Conflits de priorité des compétences

Si votre compétence personnelle est ignorée, une compétence d'entreprise ou de priorité plus élevée pourrait avoir le même nom.

Par exemple, s'il y a une compétence d'entreprise « code-review » et que vous avez également une compétence personnelle « code-review », celle de l'entreprise gagne à chaque fois. Vos options :

• Renommez votre compétence en quelque chose de plus distinct (c'est généralement le chemin le plus facile)
• Parlez à votre administrateur de la compétence d'entreprise

Les compétences de plugin n'apparaissent pas

Vous avez installé un plugin mais vous ne voyez pas ses compétences ? Videz le cache, redémarrez Claude Code et réinstallez.

Si les compétences n'apparaissent toujours pas après cela, la structure du plugin pourrait être incorrecte. C'est quand l'outil de validateur gagne vraiment ses galons.

Erreurs d'exécution

La compétence se charge mais échoue pendant l'exécution. Quelques causes courantes :

• Dépendances manquantes : Si votre compétence utilise des packages externes, ils doivent être installés. Ajoutez des informations de dépendance à la description de votre compétence pour que Claude sache ce qui est nécessaire.
• Problèmes de permissions : Les scripts ont besoin de permission d'exécution. Exécutez chmod +x sur tous les scripts que votre compétence référence.
• Séparateurs de chemin : Utilisez des barres obliques partout, même sous Windows.

Liste de contrôle de dépannage rapide

• **Ne se déclenche pas ? ** Améliorez votre description et ajoutez des phrases de déclenchement.
• **Ne se charge pas ? ** Vérifiez votre chemin, le nom du fichier et la syntaxe YAML.
• **Mauvaise compétence utilisée ? ** Rendez les descriptions plus distinctes les unes des autres.
• **Être éclipsé ? ** Vérifiez la hiérarchie des priorités et renommez si nécessaire.
• **Compétences de plugin manquantes ? ** Videz le cache et réinstallez.
• **Défaillance d'exécution ? ** Vérifiez les dépendances, les permissions et les chemins.

Réflexion sur la leçon

• Avez-vous 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 compétences avant de les partager avec votre équipe ?

Conclusion du cours

Félicitations pour avoir terminé Introduction aux compétences d'agent ! Vous avez appris à créer, configurer, partager et dépanner les compétences dans Claude Code. Alors que vous commencez à créer des compétences pour vos propres flux de travail, rappelez-vous que les meilleures compétences proviennent de véritables points de douleur — commencez par les instructions que vous vous trouvez à répéter le plus souvent.

Retours

Nous aimerions entendre comment vous utilisez les compétences dans votre travail, ainsi que tout retour sur ce cours. Partagez vos retours ici.