Pourquoi Agent Skills ne fonctionne pas ? Dépannage du déclenchement et des autorisations de Claude Code en 2026

Agent Skills ne fonctionne pas ? Le meilleur choix consiste à isoler d’abord la découverte, puis le déclenchement et enfin l’exécution, avant de modifier le modèle ou de réinstaller les extensions. Cette méthode convient lorsque Claude Code, Codex ou OpenCode voit un projet mais ne charge pas la compétence, la déclenche sans utiliser ses outils, ou bloque une action à cause des permissions et de la frontière de confiance.

Cette page s’adresse aux développeurs qui cherchent pourquoi une compétence Claude Code ne se déclenche pas et souhaitent vérifier chaque couche avec un exemple minimal. Elle concerne également les équipes qui livrent des compétences dans un dépôt distant, ainsi que les responsables d’environnements AI Coding Agent qui doivent imposer une validation et un retour arrière reproductibles.

Commencer par classer la panne

La première erreur consiste à traiter tous les symptômes comme une installation cassée. Dans la pratique, trois pannes différentes peuvent produire une impression identique : « l’agent ne fait rien ».

• La compétence n’est pas découverte : aucun indice ne montre qu’elle existe dans le projet courant. Le répertoire est mal placé, la racine de travail est incorrecte, le fichier porte un mauvais nom ou les métadonnées ne sont pas lisibles.
• La compétence est découverte mais non déclenchée : son nom ou sa description apparaît, mais la demande formulée ne correspond pas assez clairement à sa fonction, ou une autre compétence semble plus pertinente.
• La compétence est déclenchée mais son exécution échoue : le contenu est chargé, puis Read, Write, Bash ou un outil MCP est refusé, absent, monté dans un autre environnement ou limité par une règle de confiance.

Cette classification change immédiatement la suite du diagnostic. Une panne de découverte se corrige dans l’arborescence et le fichier SKILL.md. Une panne de déclenchement se vérifie avec la description et un jeu de demandes contrôlées. Une panne d’exécution se traite dans les permissions, les chemins montés et les confirmations d’actions.

La spécification officielle d’Agent Skills définit la structure attendue et les métadonnées nécessaires. La documentation officielle des Skills de Claude Code doit ensuite primer sur les habitudes issues d’un ancien dépôt ou d’un exemple communautaire.

Vérifier l’arborescence avant de toucher au modèle

Dans un projet, le point de départ doit être la racine réellement ouverte par l’agent. Une structure typique à contrôler ressemble à ceci :

projet/
└── .claude/
    └── skills/
        └── nom-de-la-competence/
            └── SKILL.md

Cette représentation n’est pas une invitation à recopier aveuglément un chemin : les emplacements pris en charge peuvent évoluer selon l’agent et sa configuration. Elle sert à vérifier quatre éléments concrets :

• le dossier .claude/skills appartient bien au projet chargé ;
• chaque compétence possède son propre répertoire ;
• le fichier s’appelle exactement SKILL.md ;
• aucun niveau supplémentaire ne sépare le fichier de la structure attendue.

Un dossier imbriqué trop profondément peut rester invisible, même si le fichier existe sur le disque. À l’inverse, un fichier placé dans le bon répertoire mais nommé skill.md, SKILL.yaml ou README.md ne constitue pas nécessairement une compétence reconnue. La casse devient particulièrement importante dans un environnement distant ou dans un volume Linux monté depuis un Mac.

Le frontmatter mérite le même contrôle. Dans la spécification actuelle, les champs name et description ont une fonction distincte : le premier identifie la compétence, le second aide l’agent à déterminer dans quels cas elle peut être pertinente. Une syntaxe YAML invalide, des délimiteurs absents ou une valeur structurée de manière inattendue peuvent donc empêcher l’analyse du fichier avant même que le modèle ne reçoive une occasion de l’utiliser.

Le premier test doit rester minimal : un fichier SKILL.md, une description précise, une instruction sans écriture et une sortie facilement vérifiable. Tant que cette version n’est pas découverte, ajouter des scripts, des exemples audio, des outils de design ou des connexions MCP ne fait qu’augmenter le nombre de causes possibles.

Comparer les trois couches de diagnostic

Le tableau suivant permet de choisir la prochaine vérification sans confondre présence, décision du modèle et autorisation d’action.

Symptôme observé	Couche probablement en cause	Vérification prioritaire	Correction à tester
Aucun nom de compétence n’est visible	Découverte	Racine du projet, dossier .claude/skills, nom de SKILL.md	Revenir à une compétence minimale dans le projet local
La compétence est mentionnée mais son contenu n’est pas utilisé	Déclenchement	description, formulation de la demande, conflit avec une autre compétence	Employer une demande explicite et un test de cas limite
La compétence commence puis demande une autorisation	Exécution	Permission de l’outil, chemin du projet, politique de confiance	Autoriser une opération sans effet de bord, puis réévaluer
L’outil est accepté mais agit sur un autre fichier	Contexte	Répertoire courant, montage distant, branche ou espace de travail	Afficher le chemin ciblé et verrouiller le projet de test
Le comportement change après une mise à jour	Maintenance	Version du fichier, configuration de l’agent, journal de chargement	Restaurer la dernière version approuvée et comparer les changements

Cette séparation répond à une confusion fréquente : voir le nom d’une compétence dans une interface ne prouve pas que son contenu a été lu, et voir son contenu ne prouve pas qu’un outil a été autorisé. Chaque étape doit donc produire une preuve différente.

Tester la description avec un jeu de demandes contrôlé

Une description trop large, par exemple « aide au développement », entre en concurrence avec de nombreuses tâches. Elle peut être pertinente partout et donc guider l’agent nulle part avec assez de précision. Une description trop étroite produit l’effet inverse : la compétence fonctionne dans une formulation exacte, mais reste silencieuse dès que la demande utilise un vocabulaire naturel.

Il faut donc préparer un petit jeu de tests comprenant :

• une demande qui doit déclencher la compétence ;
• une demande voisine qui ne doit pas la déclencher ;
• une formulation avec le vocabulaire habituel de l’équipe ;
• une demande explicite qui nomme la compétence ;
• une demande qui ressemble au domaine mais nécessite un autre outil.

Le test doit d’abord répondre à la question « la compétence est-elle sélectionnée ? », puis à la question « son contenu est-il consulté ? ». Une demande explicite peut servir de contrôle, mais elle ne doit pas être considérée comme la preuve que le déclenchement automatique est fiable. Aucun Skill ne doit être présenté comme automatiquement appelé dans toutes les situations.

Les descriptions qui se contredisent sont également problématiques. Deux compétences peuvent viser le même type de tâche en annonçant des conditions presque identiques, alors que l’une modifie du code et l’autre produit une analyse. Dans ce cas, la résolution dépend du contexte fourni au modèle et peut varier avec la formulation. Les équipes doivent donc donner à chaque compétence un domaine, un résultat attendu et des exclusions suffisamment distincts.

Restaurer les permissions sans ouvrir tout l’environnement

Une compétence qui demande Read, Write, Bash ou un outil MCP ne se trouve plus dans le seul domaine de la découverte. Elle agit dans une frontière de confiance. Le refus peut venir de la politique de l’agent, du projet non approuvé, du chemin absent dans le montage distant, d’un serveur MCP non démarré ou d’une confirmation utilisateur non fournie.

La documentation officielle sur les permissions de Claude Code doit être utilisée pour vérifier le comportement exact de l’environnement concerné. Il faut distinguer :

• la permission de lire un fichier ;
• la permission d’écrire ou de remplacer un fichier ;
• la permission d’exécuter une commande ;
• la permission d’accéder à un service externe ;
• la permission de transmettre une action à un serveur MCP.

Une stratégie raisonnable consiste à commencer par une lecture d’un fichier inoffensif, puis à tester une écriture dans un répertoire temporaire, avant d’autoriser une commande ou une modification du dépôt. Si la compétence échoue déjà sur la première lecture, son script d’automatisation n’est pas encore en cause.

MCP ajoute une limite supplémentaire : le serveur peut être disponible dans l’environnement local mais absent du Mac distant, ou démarrer avec un répertoire de travail différent. La documentation du SDK MCP décrit les éléments d’intégration à vérifier ; elle ne garantit pas que chaque configuration distante possède les mêmes variables, sockets ou accès réseau.

Distinguer projet local, dépôt distant et espace cloud

Le même Skill peut fonctionner dans un dossier local et échouer dans un environnement distant, sans que son fichier ait changé. Les différences les plus fréquentes sont la racine réellement montée, l’utilisateur qui lance l’agent, les permissions du volume, la branche livrée et la configuration chargée au démarrage.

Environnement	Risque principal	Preuve à conserver	Réponse recommandée
Projet local	Test réalisé depuis une mauvaise racine	Chemin courant et arborescence	Rejouer depuis la racine contenant .claude
Dépôt distant	Le Skill n’est pas livré avec la branche active	Révision, statut du dépôt et contenu du fichier	Versionner le Skill et vérifier la branche de test
Mac distant	Permissions différentes entre session interactive et agent	Journal de lancement et identité d’exécution	Tester avec un projet isolé et des droits minimaux
Espace cloud	Montage, réseau ou serveur MCP absents	Liste des chemins accessibles et état des outils	Déclarer les dépendances avant le déploiement

Pour une équipe, le fichier de compétence ne doit pas être le seul objet contrôlé. Les scripts appelés, les fichiers de configuration, les variables d’environnement et les accès MCP doivent être examinés comme un ensemble. Une compétence provenant d’un dépôt tiers peut contenir des instructions demandant une exécution privilégiée, une copie de fichiers sensibles ou un appel externe non attendu.

Les recommandations de sécurité relatives aux outils d’agents gérés peuvent être confrontées à la documentation officielle sur les outils contrôlés. Le lien ne remplace pas un audit : chaque équipe doit décider quels chemins, commandes et services sont acceptables pour son propre dépôt.

Utiliser une matrice de décision avant de modifier la configuration

Résultat du test minimal	Décision	Ce qu’il ne faut pas faire
La compétence n’apparaît pas	Corriger le chemin, le nom et le frontmatter	Changer de modèle ou multiplier les plugins
Elle apparaît mais ne se déclenche pas	Réécrire la description et répéter les demandes contrôlées	Conclure que l’installation est cassée
Elle se déclenche sans outil	Vérifier le contenu réellement lu et le contexte	Ajouter immédiatement toutes les permissions
L’outil est refusé	Examiner la politique, le montage et la confirmation	Donner un accès global au dépôt
Le test réussit seulement dans un environnement	Comparer les chemins, l’utilisateur et les services disponibles	Déclarer la compétence prête pour la production

Cette matrice est particulièrement utile lorsqu’un responsable doit arbitrer entre un correctif local et une modification globale. Tant que la cause n’est pas isolée, une réinstallation peut supprimer des indices, tandis qu’un élargissement des permissions peut masquer une mauvaise arborescence.

Appliquer une procédure d’acceptation réutilisable

La validation d’un nouveau Skill peut être intégrée dans le travail quotidien sans reproduire toute une installation. La séquence suivante convient à une compétence destinée à Claude Code, Codex ou OpenCode :

• [ ] créer un projet de test séparé du dépôt de production ;
• [ ] ajouter une compétence minimale contenant SKILL.md et des métadonnées valides ;
• [ ] confirmer que l’agent travaille depuis la racine attendue ;
• [ ] vérifier que la compétence est découverte avant de tester un outil ;
• [ ] exécuter une demande qui doit déclencher la compétence ;
• [ ] exécuter une demande voisine qui ne doit pas la déclencher ;
• [ ] vérifier dans le journal que le contenu de la compétence a été chargé ;
• [ ] tester Read sur un fichier sans donnée sensible ;
• [ ] tester Write uniquement dans un répertoire temporaire ;
• [ ] contrôler Bash et MCP séparément, avec une confirmation explicite ;
• [ ] consigner les chemins, permissions et services indispensables ;
• [ ] conserver une version approuvée permettant le retour arrière.

Le point souvent oublié est la régression. Une mise à jour du Skill peut modifier sa description, appeler un nouveau script ou demander un outil qui n’existait pas dans la version précédente. Le projet de test doit donc rester disponible dans l’environnement distant, avec un petit ensemble de demandes reproductibles et une branche dédiée.

La méthode officielle d’évaluation des Skills peut compléter cette approche pour les équipes qui comparent plusieurs agents. Elle ne transforme pas un résultat ponctuel en garantie universelle : l’évaluation doit être rejouée lorsque la compétence, l’agent, les permissions ou l’espace de travail changent.

FAQ : isoler les derniers cas ambigus

Pourquoi Claude Code ne reconnaît-il pas une compétence Agent Skills ?

Vérifiez d’abord la racine ouverte par l’agent, puis le chemin .claude/skills, le nom exact SKILL.md et la validité du frontmatter. Un fichier présent sur le disque n’est pas forcément situé dans le projet chargé. Si la structure est correcte, testez une compétence minimale afin de séparer un problème de découverte d’une différence de configuration ou de version.

Où placer le fichier SKILL.md ?

Le fichier doit se trouver dans le répertoire de compétence reconnu par l’agent, généralement sous .claude/skills, dans un sous-dossier portant le nom de la compétence. Le point essentiel n’est pas seulement le chemin : le dossier ouvert doit être la bonne racine, la casse doit être respectée et le fichier doit contenir les métadonnées attendues par la spécification active.

Que faire si Agent Skills se déclenche mais ne lit pas les outils ?

Vérifiez d’abord que le contenu de la compétence a été chargé, puis examinez l’autorisation demandée par l’outil. Read, Write, Bash et MCP obéissent à des contrôles différents. Répétez le test avec un fichier sans effet de bord, confirmez le chemin du projet et comparez l’environnement local avec l’espace distant avant d’autoriser une opération plus sensible.

Comment contrôler les permissions et la frontière de confiance ?

L’équipe doit auditer le fichier SKILL.md, les scripts appelés, les chemins accessibles et les connexions externes avant toute mise à disposition. Les droits de lecture, d’écriture, d’exécution et d’accès MCP doivent être validés séparément. Une version approuvée, une branche de test et une procédure de retour arrière limitent l’impact d’une modification inattendue.

La comparaison avec une configuration locale montre pourquoi un environnement distant reste parfois plus fiable pour ces essais : un poste individuel conserve souvent des autorisations implicites, des chemins non documentés et des services MCP déjà actifs, alors qu’un espace partagé expose les dépendances manquantes. À l’inverse, une solution locale demeure préférable pour un besoin durable qui exige des périphériques physiques, une latence parfaitement maîtrisée ou un contrôle complet du système. Pour reproduire un Skill sans modifier le poste principal, la présentation des environnements Mac de Zutcloud permet d’examiner l’option d’un Mac distant ; le centre d’aide de Zutcloud peut ensuite servir à clarifier les conditions d’accès et de support.

Pour un test ponctuel, un projet isolé et une compétence minimale suffisent généralement. Pour plusieurs utilisateurs, des permissions homogènes et une exécution récurrente, il devient pertinent de comparer une configuration locale avec un environnement Mac distant ou cloud, puis de documenter la chaîne complète : livraison du dépôt, montage du projet, services MCP, journal et retour arrière. La location d’un Mac auprès de Zutcloud peut alors offrir un cadre plus propre qu’un poste personnel saturé de réglages implicites, sans obliger l’équipe à acheter une machine dédiée avant d’avoir validé le besoin.

FAQ

Pourquoi Claude Code ne reconnaît-il pas une compétence Agent Skills ?

Commencez par vérifier l’emplacement du projet et la présence de SKILL.md dans le dossier de compétence. Le fichier doit respecter la structure et les champs de métadonnées attendus par la spécification actuelle. Si la compétence n’apparaît toujours pas, testez un exemple minimal avant d’examiner le modèle ou de réinstaller l’outil.

Où placer le fichier SKILL.md d’une compétence Agent Skills ?

Placez-le dans le répertoire de compétence attendu par l’agent, généralement sous .claude/skills dans le projet concerné, avec un sous-dossier propre à la compétence. Vérifiez ensuite que le répertoire ouvert par Claude Code est bien la racine du projet et non un dossier parent ou enfant qui ne contient pas cette arborescence.

Que faire si Agent Skills se déclenche mais ne lit pas les outils ?

Séparez le déclenchement de l’exécution. Une compétence peut être identifiée puis échouer lors d’un appel à Read, Write, Bash ou à un serveur MCP. Consultez la demande d’autorisation, le journal de l’agent et le montage du projet, puis répétez le test avec une opération sans effet de bord avant de réactiver les actions sensibles.

Comment contrôler les permissions et la frontière de confiance d’une compétence ?

Examinez le contenu de SKILL.md, les scripts référencés, les outils demandés et les chemins accessibles avant de l’ajouter à un dépôt partagé. Validez séparément les permissions de lecture, d’écriture, d’exécution et les connexions MCP. Conservez une version approuvée et un point de retour afin de retirer rapidement une compétence modifiée.