Selon la documentation officielle des compétences Claude Code, une compétence est un dossier contenant un fichier SKILL.md avec un en-tête YAML et des instructions en markdown. Claude charge le nom et la description au démarrage, puis récupère le corps complet uniquement quand la compétence est nécessaire. Cette conception à divulgation progressive garde le contexte léger. Ce que vous obtenez ici : une compétence originale pour auditer les liens internes, écrite de zéro, avec des cas de test de déclencheur, une rubrique de résultats et les étapes de packaging pour la rendre reproductible.
Un exemple SKILL.md fonctionnel
Commençons par l'artefact fini pour que vous voyiez où nous allons. Ci-dessous se trouve une compétence qui audite les liens internes dans un site. Copiez-la, installez-la, puis lisez le reste de l'article pour comprendre chaque décision.
description: >
Audits internal links in a project's HTML or Markdown output.
Use when the user asks to check broken links, find dead anchors,
audit site links, or review internal navigation before a deploy.
``
## Internal Link Audit
``
Run a link audit against the built output or source files.
``
### Steps
``
1. Collect all internal links (href or markdown link targets starting
with / or a relative path).
2. Resolve each link against the project root.
3. Check whether the resolved target file or anchor exists on disk.
4. Report broken links grouped by source file. For each broken link,
show: source file, link text, href, and the reason it fails
(missing file, missing anchor, or redirect loop if detectable).
5. List passing links only in a summary count, not individually.
6. If zero broken links are found, say so explicitly.
``
### Output format
``
- Broken links: grouped table per source file.
- Summary line: "X of Y internal links are broken."
- If scripts/ contains check-links.sh, run it first and append
Claude's analysis below the script output.
C'est une compétence réelle et fonctionnelle. Enregistrez-la dans ~/.claude/skills/internal-link-audit/SKILL.md et elle est immédiatement disponible dans chaque projet.
Une chose à noter : la documentation officielle confirme que les commandes personnalisées ont fusionné avec les compétences. Les deux peuvent être invoquées avec /name . Donc /internal-link-audit fonctionne comme une commande directe, et Claude la fera également correspondre automatiquement à partir d'une demande en langage naturel. Ce ne sont pas deux mécanismes séparés.
Choisissez une tâche étroite et écrivez la description
Le champ description n'est pas la documentation. C'est le déclencheur. Chaque mot qu'il contient aide soit Claude à faire correspondre la compétence au bon moment, soit ajoute du bruit qui rend la correspondance pire.
Le guide de Hidekazu Konishi l'exprime clairement : une description vague est la raison la plus courante pour qu'une compétence ne s'active jamais. Écrivez-la à la troisième personne. Commencez par le cas d'usage principal. Puis listez les phrases réelles que les utilisateurs tapent, car la correspondance se fait par rapport à ces phrases, pas par rapport à votre idée interne de la compétence.
Mauvaise description : Aide avec les liens et les choses connexes dans les projets web.
Meilleure : Audite les liens internes dans les résultats HTML ou Markdown d'un projet.
Use when the user asks to check broken links, find dead anchors,
audit site links, or review internal navigation before a deploy.
Remarquez que la deuxième version met en avant l'action (« Audite les liens internes »), nomme les types de fichiers, puis donne quatre phrases de déclenchement concrètes dans la clause Utilisez quand. Chaque phrase est quelque chose qu'un développeur taperait réellement.
L'étroitesse est meilleure
Résistez à l'envie de construire un « vérificateur de lien général ». Une compétence qui fait une chose bien se déclenche de manière fiable. Une compétence qui promet de vérifier les liens, de valider les redirections et de rapporter la vitesse de page se déclenche de manière peu fiable et produit des résultats incohérents. Choisissez la plus petite tranche utile. Vous pouvez toujours écrire une deuxième compétence pour le reste.
Pour l'audit des liens internes, les décisions de réduction étaient :
- Liens internes uniquement, pas externes (outils différents, modes de défaillance différents)
- Vérifie l'existence des fichiers et l'existence des ancres, pas l'état HTTP
- Signale les liens brisés regroupés par fichier source, pas sous forme de liste plate
Chaque décision d'affinage rend les phrases déclencheurs plus spécifiques et le format de sortie plus facile à valider.
Contrôle de l'invocation et fichiers de support
Les compétences se chargent automatiquement quand Claude correspond à la description, et elles répondent aussi aux commandes explicites /skill-name. Selon la documentation officielle, Claude scanne quatre emplacements au démarrage : personnel (~/.claude/skills/), projet (.claude/skills/), plugin et entreprise. L'entreprise surpasse le personnel, le personnel surpasse le projet. Connaître la hiérarchie compte quand vous distribuez une compétence à une équipe où la personnalisation locale pourrait entrer en conflit.
Pour l'invocation, vous avez deux chemins :
- Automatique : Claude lit votre demande, l'associe aux descriptions chargées, déclenche la compétence. Aucune commande slash n'est nécessaire.
- Explicite : Vous tapez /internal-link-audit. Claude charge le corps complet de
SKILL.mdet l'exécute. Utile pour tester et pour les moments où la correspondance automatique ne se déclenche pas.
Les deux chemins exécutent les mêmes instructions. La distinction n'est pas « manuel versus automatique », c'est à propos du signal que Claude utilise pour décider que la compétence s'applique.
Fichiers de support
Un dossier de compétence peut contenir plus que SKILL.md :
scripts/: Code exécutable (Bash, Python) que le corps de la compétence référence. La compétence internal-link-audit référencescripts/check-links.shs'il existe, donc vous pouvez brancher un vrai script de vérification de liens plus tard sans modifier les instructions.references/: Documentation détaillée que Claude charge à la demande, pas à chaque invocation. Bon pour les règles de cas limites que vous ne voulez pas encombrer les instructions principales.assets/: Modèles et formats de sortie.
Pour une première compétence, SKILL.md seul suffit. Ajoutez scripts/ quand vous avez une commande que vous voulez vraiment exécuter. Ajoutez references/ quand vos instructions commencent à sembler longues parce que vous gérez une douzaine de cas limites en ligne.
Si vous gérez déjà un CLAUDE.md pour les instructions au niveau du projet, les compétences se situent à côté, elles ne sont pas un remplacement. Le poste CLAUDE.md for agencies couvre comment structurer ce fichier séparément ; les compétences gèrent les tâches étroites et réutilisables qui n'appartiennent pas à un fichier d'instruction global.
Exécuter les tests de déclenchement positifs et négatifs
Écrire est la partie facile. Les tests, c'est là que la plupart des gens s'arrêtent trop tôt. Selon le guide Towards Data Science sur les compétences Claude Code prêtes pour la production, « tester » ici signifie jeter des vraies questions à la compétence et vérifier qu'elle se comporte correctement, pas des tests unitaires au sens logiciel.
Vous avez besoin de deux types de cas de test : positif (devrait déclencher) et négatif (ne devrait pas déclencher).
Cas de déclenchement positifs pour internal-link-audit
Ces questions devraient toutes invoquer la compétence automatiquement :
- « Vérifiez les liens internes brisés avant de déployer. »
- « Trouvez les ancrages morts dans ma sortie markdown. »
- « Auditez les liens du site dans le dossier de compilation. »
- "Y a-t-il des liens brisés sur le site ?"
- "Examinez la navigation interne dans le projet."
Cas de déclenchement négatifs
Ces invites NE DOIVENT PAS déclencher la compétence. Si c'est le cas, vous avez un problème de sur-déclenchement.
- "Vérifiez si les liens externes dans mon README fonctionnent toujours." (liens externes, domaine de compétence différent)
- "Validez mon sitemap.xml." (tâche complètement différente)
- "Trouvez les images cassées sur la page." (images, pas des liens)
- "Vérifiez le statut HTTP de mes points d'accès API." (HTTP, pas le système de fichiers)
Grille d'évaluation des résultats
Une bonne sortie de /internal-link-audit doit satisfaire à tous les critères suivants :
| Critère | Condition de réussite |
|---|---|
| Groupe des liens brisés par fichier source | Oui, avec un tableau par fichier |
| Affiche le fichier source, le texte du lien, href et la raison de l'échec | Les quatre champs présents pour chaque lien brisé |
| Les liens fonctionnels apparaissent uniquement dans le décompte récapitulatif | Pas de longue liste de liens fonctionnels |
| Message explicite "zéro lien brisé" quand c'est propre | Présent le cas échéant |
| Sortie du script en tête si check-links.sh existe | Le script s'exécute d'abord, l'analyse est ajoutée ci-dessous |
| N'en contrôle pas les liens externes | Liens externes absents du rapport |
Exécutez d'abord les cas positifs. Si la compétence se déclenche sur les cinq, passez aux cas négatifs. Si elle se déclenche sur l'un des cas négatifs, vous avez un problème de description.
Corriger les déclenchements excessifs, les déclenchements manqués et les résultats faibles
Trois modes de défaillance, trois solutions. Ce sont des problèmes distincts et chacun a une solution différente.
Un déclenchement excessif signifie que la compétence s'active quand elle ne devrait pas. Généralement causé par une description trop large. La solution consiste à ajouter un langage d'exclusion à la clause « Utiliser quand » :
Do NOT use for external link checks, HTTP status checks,
sitemap validation, or image audits.
Ajouter des exclusions explicites réduit la surface de correspondance sans supprimer les déclencheurs positifs.
Un déclenchement manqué signifie que la compétence existe mais ne s'active jamais automatiquement. La description ne correspond pas au langage réel des utilisateurs. La solution consiste à ajouter plus de phrases de déclenchement qui reflètent comment les gens demandent réellement, pas comment vous décririez formellement la tâche. « Y a-t-il des liens morts ? » est différent de « auditer la navigation interne », les deux devraient activer la même compétence.
Le guide Towards Data Science décrit une boucle d'optimisation : fractionner les cas de test, mesurer le taux de déclenchement, générer des descriptions améliorées, choisir le meilleur score. Vous pouvez le faire manuellement avec quelques invites, ou utiliser la compétence de création de compétences d'Anthropic pour semi-automatiser.
Une sortie faible signifie que la compétence s'active mais la sortie est incohérente ou incomplète. C'est un problème de corps, pas un problème de description. Regardez la rubrique que vous avez définie. Quels critères échouent ? Ajoutez des instructions de formatage plus spécifiques. Si la sortie manque la colonne « raison de l'échec », dites-le explicitement dans les instructions. S'il énumère tous les liens réussis (ce que vous ne voulez pas), ajoutez « Ne pas énumérer les liens réussis individuellement. »
Si vous gérez une pile d'automatisations Claude Code et que vous voulez voir le contexte global des compétences qui les composent, l'article sur les superpouvoirss de Claude Code couvre le flux de travail entourant.
Pour les équipes en croissance ou les agences gérant plusieurs projets clients, la page dédiée à la configuration Claude Code pour les agences vaut le coup d'œil. Elle explique comment organiser les compétences dans un environnement multi-projets.
Packager la compétence et la maintenir
Une fois que la compétence réussit tous les tests positifs et aucun des tests négatifs, packagez-la correctement.
Structure de dossier finale
~/.claude/skills/internal-link-audit/
├── SKILL.md
├── scripts/
│ └── check-links.sh (optional, referenced in instructions)
└── references/
└── anchor-edge-cases.md (optional, for edge-case rules)
Partage entre projets et personnes
Les compétences personnelles dans ~/.claude/skills/ sont disponibles dans chaque projet sur votre machine. Pour la distribution en équipe, déplacez la compétence vers un référentiel partagé et demandez aux membres de l'équipe de créer un lien symbolique ou de la copier dans leur dossier de compétences personnelles, ou engagez-la dans .claude/skills/ dans un référentiel de projet partagé pour un accès à portée de projet.
Le format de compétence est une norme ouverte. Selon le guide de construction de freeCodeCamp, la même structure SKILL.md fonctionne sur Claude Code, GitHub Copilot, Cursor et Gemini CLI. Les chemins d'installation diffèrent mais le format de fichier ne change pas. Pour Claude Code, le chemin est ~/.claude/skills/. Pour Copilot, c'est ~/.copilot/skills/. Même fichier, maison différente.
Maintenance
Les compétences dérivent. La structure du projet change, le format de sortie doit être mis à jour, ou les phrases de déclenchement ne correspondent plus à la façon dont l'équipe parle de la tâche. Traitez SKILL.md comme tout autre document dans votre repo : versionnez-le, vérifiez-le quand le flux de travail sous-jacent change, et réexécutez les tests de déclenchement après toute modification de la description.
Une checklist de maintenance numérotée :
- Réexécutez tous les tests de déclenchement positifs et négatifs après toute modification de description.
- Mettez à jour la rubrique de résultats si les exigences de format de sortie changent.
- Si vous ajoutez un script à
scripts/, référencez-le explicitement dans le corps deSKILL.mdpour que Claude sache l'utiliser. - Lors de la promotion d'une compétence personnelle en compétence d'équipe, vérifiez les phrases de déclenchement. Les membres de l'équipe peuvent utiliser un langage différent du vôtre.
- Supprimez les compétences qui ne sont plus utilisées. Les compétences obsolètes qui s'exécutent de manière inattendue sont pires que pas de compétence du tout.
FAQ
Où exactement le fichier SKILL.md doit-il se trouver ?
Pour les compétences personnelles disponibles dans tous les projets, le chemin est ~/.claude/skills/your-skill-name/SKILL.md . Le nom du répertoire devient la commande slash. Pour les compétences limitées à un projet (disponibles uniquement dans un dépôt), utilisez .claude/skills/your-skill-name/SKILL.md à la racine du projet. Les compétences d'entreprise suivent un chemin distinct géré par l'administrateur Claude Code de votre organisation.
La compétence charge-t-elle tout son contenu à chaque démarrage de Claude ?
Non. Selon la documentation officielle, Claude analyse les répertoires de compétences au démarrage mais ne charge que le nom et la description dans le contexte. Le corps complet de SKILL.md ne se charge que lorsque la compétence correspond à une demande. C'est la conception de la divulgation progressive : les descriptions restent en contexte, les instructions complètes se chargent à la demande.
Puis-je avoir plus d'une compétence qui s'exécute pour la même demande ?
Les compétences sont mises en correspondance individuellement. Si deux compétences ont des descriptions qui correspondent à la même demande, la hiérarchie des priorités s'applique : l'entreprise remplace le personnel qui remplace le projet. Dans le même niveau, vous voudriez distinguer les descriptions plus soigneusement pour que seule la compétence prévue s'exécute. Les déclencheurs en double sont généralement le signe que deux compétences ont un champ d'application qui se chevauche et devraient être fusionnées ou réduites.
Que se passe-t-il si la description dit « Utiliser quand » mais l'utilisateur tape directement la commande slash ?
La compétence s'exécute de toute façon. L'invocation explicite via /skill-name contourne entièrement la correspondance automatique et charge le corps complet immédiatement. La clause « Use when » du champ description s'applique uniquement à la correspondance automatique. Donc une commande slash directe fonctionne toujours, même si la formulation de l'utilisateur n'aurait pas déclenché la détection automatique.
Comment sais-je quand utiliser une compétence par rapport à l'ajout d'instructions à CLAUDE.md ?
CLAUDE.md est pour le contexte toujours actif : structure du projet, conventions de codage, choses que Claude devrait connaître dans chaque session. Les compétences sont pour les tâches à la demande : des choses que vous faites parfois, pas toujours, et pour lesquelles vous voulez une sortie cohérente. Si vous vous retrouvez à ajouter un flux de travail multi-étapes à CLAUDE.md, il appartient probablement à une compétence à la place.
Le champ description fait le travail que la plupart des gens pensent que le corps fait. Écrivez les phrases de déclenchement du vocabulaire réel de votre équipe, gardez la tâche étroite, et le reste suit.