Skill Claude qui ne se déclenche pas ? 6 vérifications

Vous avez installé un skill, vous avez demandé à Claude de faire la chose pour laquelle il existe, et Claude a continué comme si le skill n'existait pas. Pas d'erreur, pas d'avertissement, rien à greper. Juste le silence.

Nous voyons cela constamment. SkillProof installe et teste chaque skill de son catalogue sur une machine vierge, et l'échec de déclenchement est le défaut le plus courant que nous trouvions. C'est aussi le plus réparable : presque chaque signalement « skill qui ne fonctionne pas » de nos journaux de test remonte à l'une de six causes, et cinq d'entre elles s'éliminent en moins d'une minute.

Déroulez d'abord la checklist. Le reste de l'article détaille chaque vérification avec le symptôme, la cause et le correctif.

La checklist de 30 secondes

1. Bon dossier ? Le fichier doit être à ~/.claude/skills/<skill-name>/SKILL.md, un dossier par skill, nom de fichier exactement SKILL.md.
2. Redémarré ? Claude scanne les skills au démarrage de la session. Les changements faits en cours de session sont invisibles jusqu'au redémarrage.
3. Collision de noms ? Deux skills avec le même name s'éclipsent mutuellement. Un seul survit.
4. Description trop vague ? Si la description ne mentionne pas ce que les utilisateurs demandent littéralement, Claude ne fait jamais le rapprochement. C'est la cause numéro un.
5. Frontmatter valide ? Un seul caractère YAML cassé rend le skill entier invisible, en silence.
6. Skill en conflit ? Un autre skill installé, à la description qui chevauche la vôtre, remporte peut-être la mise.

Si les six passent et que le skill s'active mais que la sortie ne change pas, c'est un autre échec. Sautez à quand il se déclenche mais ne fait rien.

Vérification 1 : le skill est dans le mauvais dossier

Symptôme. Le skill n'apparaît jamais quand vous demandez à Claude « quels skills as-tu d'installés ? ». Comme si vous n'aviez jamais rien copié.

Cause. Claude ne regarde qu'à des endroits précis : ~/.claude/skills/ pour les skills personnels et .claude/skills/ dans un projet pour les skills de projet. À l'intérieur, l'agencement est strict : un dossier par skill, contenant un fichier nommé exactement SKILL.md. Les erreurs que nous voyons le plus quand nous installons des skills communautaires pour les tester : copier tout le dépôt cloné (le chemin devient skills/some-repo/skills/pdf-helper/SKILL.md, un niveau de trop), déposer SKILL.md directement dans ~/.claude/skills/ sans son propre dossier, et un skill.md en minuscules, que certains systèmes de fichiers pardonnent et d'autres non.

Correctif. Vérifiez depuis le terminal :

ls ~/.claude/skills/*/SKILL.md

Chaque skill attendu doit imprimer exactement une ligne. Si un skill manque ou si son chemin a une imbrication de trop, déplacez le dossier pour que SKILL.md se trouve un niveau sous skills/. Notre guide d'installation détaille l'agencement correct pour chaque plateforme.

Vérification 2 : vous n'avez pas redémarré

Symptôme. La structure de dossiers est correcte, vous l'avez corrigée il y a deux minutes, et Claude ne voit toujours pas le skill dans la même conversation.

Cause. La découverte des skills se fait une fois, au démarrage. Claude lit le frontmatter de chaque SKILL.md qu'il trouve et garde cet index pour la session. Un skill ajouté, renommé ou modifié en cours de session n'existe pas aux yeux de la session en cours.

Correctif. Dans Claude Code, quittez et ouvrez une nouvelle session. Dans l'app de bureau, quittez complètement avec Cmd+Q sous macOS (fermer la fenêtre ne compte pas) et rouvrez. Cette vérification coûte si peu que nous la faisons avant tout débogage plus profond, comme on redémarre un routeur avant d'appeler son fournisseur.

Vérification 3 : une collision de noms éclipse votre skill

Symptôme. Vous avez installé le skill, le dossier est bon, vous avez redémarré, et la liste des skills n'affiche soit rien de nouveau, soit un autre skill répondant au même nom.

Cause. Les noms de skills doivent être uniques. Si un skill personnel et un skill de projet partagent un name, ou si deux packs installés livrent chacun un skill nommé seo-audit, l'un éclipse l'autre sans avertissement. Nous l'avons vécu dans notre propre travail de catalogue : deux packs marketing installés côte à côte ont produit un doublon silencieux, et celui que nous voulions ne s'est jamais chargé.

Correctif. Cherchez les doublons :

grep -h "^name:" ~/.claude/skills/*/SKILL.md .claude/skills/*/SKILL.md 2>/dev/null | sort | uniq -d

Toute sortie signifie une collision. Renommez le dossier et le champ name de la copie que vous contrôlez, redémarrez et revérifiez la liste.

Vérification 4 : la description ne dit jamais quand se déclencher

Symptôme. Le skill figure dans la liste des installés. Demandez-le par son nom et il fonctionne très bien. Demandez la tâche avec vos propres mots et rien ne se passe.

Cause. C'est la grande cause, et elle mérite sa propre section, donc voici la version courte : Claude décide de charger ou non un skill en lisant uniquement son champ description et en le comparant à votre demande. Si la description dit ce que le skill est au lieu de quand l'utiliser, le rapprochement n'a jamais lieu. Le skill n'est pas cassé. Il est sans publicité.

Correctif. Réécrivez la description autour des formulations que les utilisateurs tapent réellement. L'analyse approfondie ci-dessous montre trois schémas d'échec réels et leurs réécritures.

Vérification 5 : le frontmatter est invalide

Symptôme. Dossier correct, redémarrage fait, pas de collision de noms, et le skill n'apparaît toujours pas du tout dans la liste. Cela ressemble à la vérification 1, mais le chemin est bon.

Cause. Le bloc YAML en tête de SKILL.md n'a pas pu être parsé, et un skill au frontmatter imparsable est simplement ignoré. Les coupables habituels de nos notes de test : un --- de fermeture manquant, un deux-points non échappé dans la description (« Use for: reports » casse le parseur), des guillemets typographiques collés depuis un article de blog ou un Google Doc, des tabulations utilisées pour l'indentation, et un name qui viole les règles de format (lettres minuscules, chiffres et traits d'union uniquement, 64 caractères max ; les descriptions plafonnent à 1024).

Correctif. Ouvrez le fichier et inspectez le bloc, ou épargnez-vous l'inspection : collez-le dans notre validateur de skill et il signale immédiatement erreurs de parsing, violations de format et contamination par guillemets typographiques. Si le frontmatter parse et que le skill se cache toujours, retournez à la vérification 1, car à ce stade c'est presque toujours le chemin.

Vérification 6 : un autre skill remporte la mise

Symptôme. Vous demandez la tâche et un skill s'active bel et bien, mais pas le vôtre. Ou le comportement change d'une façon qui correspond aux instructions d'un autre skill.

Cause. Quand plusieurs descriptions couvrent plausiblement une demande, Claude choisit celle qui semble la mieux adaptée, et une description plus large et plus assurée tend à battre une plus étroite. Installez un skill « assistant d'écriture » généraliste à côté de votre « formateur de notes de version » et le généraliste peut avaler chaque demande d'écriture, notes de version comprises.

Correctif. Affûtez les deux descriptions pour que leurs territoires ne se chevauchent pas, et ajoutez des exclusions explicites. Une ligne comme « Do NOT use for release notes or changelogs » dans la description du généraliste est grossière et fonctionne. Si vous ne contrôlez pas le skill fautif, désactivez-le le temps de tester le vôtre, puis décidez si vous avez vraiment besoin des deux.

Pourquoi les descriptions échouent : l'analyse approfondie

Nous testons chaque skill que nous référençons, et les problèmes de déclenchement sont la raison numéro un des mauvais scores dans nos revues. Pas les scripts cassés, pas les mauvaises instructions. Les descriptions qui ne matchent jamais.

La mécanique explique pourquoi. Au démarrage, Claude ne charge que le name et la description de chaque skill, une centaine de tokens environ. Le corps, aussi brillant soit-il, reste sur le disque jusqu'à ce que la description remporte le match contre votre demande. La description est un argumentaire de vente adressé à un modèle, et la plupart des auteurs l'écrivent comme une étiquette de musée.

Voici les trois schémas que nous sanctionnons le plus souvent, avec les réécritures qui les ont corrigés lors de nos retests.

Schéma 1 : l'étiquette modeste.

description: Helps with documents.

Rien ici ne se rattache à quoi que ce soit qu'un utilisateur taperait. Comparez avec le skill DOCX d'Anthropic, qui a passé nos tests de déclenchement du premier coup. Sa description nomme le format de fichier, les actions et les formulations qui doivent l'activer. La réécriture qui suit la même logique :

description: Create, edit, and format Word documents (.docx).
  Use when the user mentions a Word doc, .docx file, memo,
  letter, or asks for a deliverable "as a document."

Schéma 2 : le nom interne.

description: Runs the acme-formatter pipeline with corporate config.

Ceci décrit l'implémentation. Aucun utilisateur ne demande à Claude de « lancer le pipeline acme-formatter » ; il demande de « nettoyer ce rapport avant de l'envoyer à un client ». La réécriture traduit le skill dans le vocabulaire de l'utilisateur :

description: Reformat rough drafts into client-ready reports using
  Acme's corporate style. Use when the user wants to clean up,
  polish, or "make presentable" a document for external sharing.

Schéma 3 : la couverture gloutonne.

description: Use for any writing task.

L'échec inverse. Ceci matche tout, donc entre en collision avec chaque skill lié de près ou de loin à l'écriture et se déclenche quand il ne devrait pas, et les utilisateurs le désactivent en une semaine. La réécriture resserre la revendication et clôture les bords :

description: Write and edit marketing copy: landing pages, ads,
  and email campaigns. Do NOT use for technical docs, code
  comments, or internal memos.

Le test que nous appliquons en revue : lire uniquement la description et demander « si un utilisateur tapait sa demande naturellement, ces mots la matcheraient-ils ? ». Écrivez à la troisième personne, dites ce que fait le skill et quand il s'applique, et incluez les noms que les gens utilisent réellement. Si vous écrivez un skill de zéro, notre guide d'écriture couvre le sujet plus en profondeur, et le Skill Creator d'Anthropic échafaude par défaut des descriptions qui passent ce test.

Comment tester correctement le déclenchement

La plupart des gens testent un skill en le nommant : « utilise le skill facture sur ceci ». Cela ne prouve rien, car nommer un skill court-circuite entièrement le rapprochement par description. C'est comme tester un détecteur de fumée en pressant le bouton de test et en conclure que votre maison est ignifugée.

Testez comme un utilisateur demanderait, dans une session fraîche à chaque fois. Pour un skill d'extraction de factures, trois formulations qui devraient déclencher :

• « Sors-moi les totaux de ces factures PDF. »
• « J'ai 30 factures de fournisseurs, mets les montants et les dates dans un tableau. »
• « Extrais les lignes de cette facture. »

Et deux qui ne devraient pas :

• « Résume-moi ce PDF. » (Travail PDF générique ; le territoire d'un autre skill.)
• « Écris un e-mail de facturation à ce client. » (Rédaction, pas extraction.)

Si une formulation censée déclencher ne fait rien, demandez directement à Claude : « Lequel de tes skills installés utiliserais-tu pour cette demande, et pourquoi ? » La réponse vous montre le raisonnement de rapprochement, et elle pointe généralement droit sur le point faible de la description. Si les formulations censées ne pas déclencher activent quand même le skill, vous avez une couverture gloutonne et il vous faut des exclusions. C'est exactement le protocole que nous déroulons pour le catalogue, et la même discipline qu'enseigne le skill Systematic Debugging : reproduire d'abord, une variable à la fois, croire les preuves.

Quand il se déclenche mais ne fait rien

Supposons que le skill s'active bel et bien. Vous pouvez le confirmer en demandant à Claude en cours de conversation si un skill s'est chargé pour la demande, et il vous le dira. Mais la sortie ressemble à ce qu'elle était avant toute installation.

Ce n'est pas un problème de déclenchement, et rien de ce qui précède ne le corrigera. C'est un problème de corps : les instructions à l'intérieur du skill sont trop vagues pour changer le comportement, ou le skill référence des fichiers embarqués qui n'existent pas aux chemins attendus, ou il appelle un script dont les dépendances n'ont jamais été déclarées. La description a fait passer le skill par la porte et le contenu s'est effondré à l'intérieur.

Dans nos tests, c'est l'autre grand panier d'échecs, à peu près l'image miroir des défauts de déclenchement, et c'est la raison principale pour laquelle environ la moitié des skills communautaires échouent à nos tests. Le discriminant rapide : si le comportement n'a pas changé du tout, suspectez le déclenchement ; s'il a changé mais mal ou partiellement, suspectez le corps. Déboguez en conséquence, car les correctifs ne se recoupent pas.

Pièges par plateforme

Le format des skills est identique partout, mais pas la découverte, et un skill qui fonctionne à un endroit peut sembler mort à un autre.

Claude Code lit des dossiers sur le disque : ~/.claude/skills/ pour le personnel, .claude/skills/ par projet. Les deux se chargent ; les collisions de noms entre les deux portées se résolvent en un seul gagnant (vérification 3). Redémarrez la session après tout changement.

Claude Desktop ne lit pas vos dossiers de skills. Les skills se téléversent en zip via Paramètres, sous Capacités, et le zip doit contenir le dossier du skill au premier niveau, ni le SKILL.md nu, ni un répertoire d'emballage. Un skill qui se déclenche très bien dans Claude Code sera simplement absent sur Desktop tant que vous ne l'y aurez pas téléversé séparément.

claude.ai suit la même voie de téléversement que Desktop, avec deux façons supplémentaires de perdre : les skills exigent la fonctionnalité d'exécution de code activée sur votre plan, et les administrateurs d'espace de travail peuvent désactiver les skills à l'échelle de l'organisation, auquel cas rien de ce que vous téléverserez ne se déclenchera jamais et aucune erreur ne le dira. Demandez à votre admin avant de passer une soirée à réécrire des descriptions.

Un piège multiplateforme de plus : un corps de skill écrit pour Claude Code qui invoque git ou lit des fichiers de projet locaux se déclenchera correctement sur claude.ai puis échouera dans la sandbox. C'est un problème de corps déguisé en problème de plateforme.

Quand arrêter de déboguer

Si c'est votre propre skill, continuez, car chaque correctif ci-dessus est permanent, et le validateur plus le test aux cinq formulations vous y mèneront. Si c'est un skill tiers et que vous avez brûlé plus de vingt minutes sur le champ description de quelqu'un d'autre, il est légitime de l'échanger contre un skill qui a déjà traversé cette checklist : chaque skill de nos listes des meilleurs a passé le test de déclenchement sur machine vierge avant d'être référencé.

FAQ

Comment confirmer qu'un skill est bien installé ?

Demandez à Claude « quels skills as-tu d'installés ? » dans une session fraîche. Si votre skill n'est pas dans la réponse, le problème est la découverte (vérifications 1, 3 et 5 : dossier, collision, frontmatter), pas le déclenchement. S'il est listé mais ne s'active jamais, le problème est la description (vérifications 4 et 6).

Puis-je simplement forcer le déclenchement en nommant le skill ?

Oui. « Utilise le skill docx pour rédiger cette note » charge le skill directement, et c'est un contournement acceptable le temps du débogage. Ce n'est pas un correctif pour autant : un skill qu'il faut convoquer par son nom à chaque fois est un skill à la description cassée, et vous oublierez de le convoquer exactement quand cela comptera.

Pourquoi mon skill fonctionne-t-il dans Claude Code mais pas sur Desktop ou claude.ai ?

Des chemins de découverte différents. Claude Code lit des dossiers sur le disque ; Desktop et claude.ai ne voient que les skills téléversés via Paramètres en zip avec le dossier du skill au premier niveau. Sur claude.ai, confirmez aussi que l'exécution de code est activée et que votre administrateur d'espace de travail n'a pas désactivé les skills entièrement.

Installer trop de skills casse-t-il le déclenchement ?

Pas directement. Cinquante skills coûtent quelques milliers de tokens de métadonnées, ce qui est bon marché. Le vrai risque est le chevauchement : plus vous installez de descriptions, plus il est probable que deux d'entre elles revendiquent le même territoire, et alors la mauvaise gagne parfois (vérification 6). Installez selon le besoin, et retirez les skills qui ne se déclenchent jamais.

Mon skill s'est déclenché hier et pas aujourd'hui. Est-ce normal ?

Occasionnellement, oui. Le rapprochement est piloté par le modèle, pas par une regex, donc une description limite se déclenchera sur une formulation et en ratera une quasi identique. Si un skill est capricieux plutôt que mort, traitez-le comme une description faible : ajoutez au champ description les formulations exactes qui ont raté, redémarrez et retestez. Les skills fiables se déclenchent sur chaque formulation raisonnable, raison pour laquelle nous testons avec cinq, pas une.