Dépannage : la skill n'apparaît pas ou ne se déclenche pas

Une ressource installée qui reste sans effet a presque toujours une cause simple : un fichier au mauvais endroit, une description trop vague, un nom en double. Chaque symptôme ci-dessous donne la cause probable, puis la correction.

La skill n'apparaît pas dans l'agent

Première cause : le dossier. Une skill est un dossier qui contient un fichier SKILL.md, et l'agent le cherche dans ses dossiers de skills. Sur la page de votre agent, vous trouvez le dossier global et le dossier de projet. Quelques repères vérifiés dans la documentation : Claude Code lit ~/.claude/skills/ et .claude/skills/ ; Codex lit ~/.agents/skills/ et .agents/skills/ ; Cursor lit .agents/skills/, .cursor/skills/, ~/.agents/skills/ et ~/.cursor/skills/.

Deuxième cause : un dossier de projet situé plus bas que l'endroit où vous avez lancé l'agent. Claude Code charge les skills de .claude/skills/ dans le dossier de lancement et ses parents jusqu'à la racine du dépôt, pas celles d'un sous-dossier, qui ne se chargent qu'à la première lecture d'un fichier de ce sous-dossier.

Troisième cause : la session ne voit pas le changement. Claude Code surveille ses dossiers de skills, mais si le dossier n'existait pas au démarrage, lancez /reload-skills. Pour Codex, redémarrez-le si la skill n'apparaît pas.

Pour contrôler, demandez à l'agent quelles skills sont disponibles, ou ouvrez la liste : /skills dans Codex, Customize puis Skills dans Cursor.

La skill apparaît mais ne se déclenche pas

L'agent ne lit au départ que le nom et la description de chaque skill. Il charge le reste quand votre demande correspond à la description. Donc :

1. Reformulez avec les mots de la description de la skill, que vous lisez dans son fichier SKILL.md.
2. Appelez-la directement : /nom-de-la-skill dans Claude Code, $nom-de-la-skill dans Codex.
3. Si l'appel direct échoue aussi, vérifiez le nom : il doit comporter 1 à 64 caractères, en minuscules, chiffres et tirets, sans tiret au début ni à la fin, et correspondre au nom du dossier.
4. Si vous avez beaucoup de skills, la liste peut raccourcir des descriptions : Claude Code retire d'abord celles des skills les moins utilisées, Codex raccourcit d'abord les descriptions, puis peut omettre des skills.

Un en-tête YAML mal formé donne un cas particulier : dans Claude Code, la skill se charge sans métadonnées, l'appel par son nom marche mais l'agent ne peut plus la choisir seul. Lancez Claude Code avec --debug pour voir l'erreur. Voir aussi l'article sur le déclenchement des skills.

L'agent ne trouve pas le fichier

Une skill peut renvoyer à des fichiers voisins (references/, assets/) ou, pour un DESIGN.md, à un fichier à la racine du projet.

• Fichiers manquants : la copie était incomplète. Recommencez avec le ZIP de la fiche et comparez les dossiers.
• DESIGN.md, prompt ou rule : ces fichiers se placent dans le projet courant, pas dans le dossier des skills. Vérifiez que l'agent a été lancé dans ce projet.
• Skill copiée sans son dossier : si seul SKILL.md est copié, les fichiers qu'il cite n'existent pas.

La commande npx échoue

Lisez d'abord la première ligne du message d'erreur.

• Installation demandée : npx demande confirmation avant de télécharger un paquet. L'option --yes supprime cette question, c'est pourquoi la commande de PalateKit la contient.
• Version de Node.js : la CLI demande Node.js 22 ou plus récent. Vérifiez avec node --version.
• Serveur injoignable : réseau coupé, proxy d'entreprise ou pare-feu. Réessayez, ou utilisez le ZIP.
• Trousseau indisponible : la CLI garde son jeton uniquement dans le trousseau du système. Sous Linux, il faut un trousseau Secret Service (GNOME Keyring ou KWallet) installé et déverrouillé.
• Dossier déjà présent : « already exists ». Relancez avec --force : l'ancienne version est déplacée dans ~/.palatekit/backups/.
• Archive refusée : la CLI contrôle taille, empreinte et chemins avant d'écrire. Un refus signifie que rien n'a été installé.

Si la CLI vous demande de connecter l'appareil, ouvrez le lien affiché et vérifiez que le code est le même dans le navigateur.

Le ZIP est mal décompressé

Symptôme classique : la skill est absente alors que les fichiers sont là. Cause : un niveau de dossier en trop. Beaucoup d'outils de décompression créent un dossier du nom du ZIP, ce qui donne :

.claude/skills/ma-skill/ma-skill/SKILL.md

alors que l'agent attend :

.claude/skills/ma-skill/SKILL.md

Déplacez le dossier intérieur d'un niveau vers le haut et supprimez le dossier vide. Le nom du dossier doit rester identique au nom de la skill, comme l'exige la spécification Agent Skills.

Deux skills se contredisent

Deux situations différentes.

Même nom. Dans Claude Code, la skill d'entreprise passe avant la skill personnelle, qui passe avant la skill de projet : avec deploy dans ~/.claude/skills/ et dans .claude/skills/, /deploy lance la personnelle. Codex ne fusionne pas deux skills du même nom : les deux peuvent apparaître dans ses sélecteurs. Renommez ou supprimez l'une des deux.

Descriptions qui se recouvrent. Deux skills sur le même sujet sont toutes deux candidates, et l'agent peut choisir l'une ou l'autre. Précisez votre demande, appelez la skill voulue par son nom, ou retirez celle dont vous n'avez pas besoin. Avec Codex, allow_implicit_invocation: false dans agents/openai.yaml empêche le déclenchement automatique d'une skill, qui reste appelable par $.

Une ressource payante est refusée

La CLI traduit la réponse du serveur :

• Offre ou achat requis : la ressource demande un abonnement ou un achat. Consultez les tarifs, puis relancez la commande.
• Session expirée : le jeton dure 7 jours. Lancez npx --yes palatekit@latest login, puis status pour voir le compte connecté et son offre.
• Accès refusé pour ce jeton : déconnectez-vous avec logout, puis reconnectez-vous avec le bon compte.
• Ressource introuvable : elle est retirée, ou elle n'est qu'un lien vers la source et n'a pas de fichiers à installer.
• Limite quotidienne : la CLI indique dans combien de minutes réessayer.

Pour mettre à jour une ressource déjà installée, voir l'article sur la gestion et la mise à jour. Pour les méthodes d'installation, voir l'article sur l'installation.