SKILL.md avec des instructions, et Claude l’ajoute à sa boîte à outils. Claude utilise les skills quand c’est pertinent, ou vous pouvez en invoquer une directement avec /skill-name.
Créez une skill quand vous collez constamment les mêmes instructions, liste de contrôle ou procédure multi-étapes dans le chat, ou quand une section de CLAUDE.md s’est transformée en procédure plutôt qu’en fait. Contrairement au contenu de CLAUDE.md, le corps d’une skill ne se charge que lorsqu’elle est utilisée, donc le matériel de référence long ne coûte presque rien jusqu’à ce que vous en ayez besoin.
Pour les commandes intégrées comme
/help et /compact, et les skills groupées comme /debug et /code-review, consultez la référence des commandes.Les commandes personnalisées ont été fusionnées dans les skills. Un fichier à .claude/commands/deploy.md et une skill à .claude/skills/deploy/SKILL.md créent tous deux /deploy et fonctionnent de la même manière. Vos fichiers .claude/commands/ existants continuent de fonctionner. Les skills ajoutent des fonctionnalités optionnelles : un répertoire pour les fichiers de support, un frontmatter pour contrôler si vous ou Claude les invoquez, et la capacité pour Claude de les charger automatiquement quand c’est pertinent.Compétences groupées
Claude Code inclut un ensemble de compétences groupées, telles que/doctor, /code-review, /batch, /debug, /loop et /claude-api. Les compétences groupées sont basées sur des invites : elles donnent à Claude des instructions détaillées et lui permettent d’orchestrer le travail en utilisant ses outils. La plupart des commandes intégrées exécutent plutôt une logique fixe directement.
Vous invoquez une compétence groupée de la même manière que n’importe quelle autre compétence, en tapant / suivi du nom de la compétence. Claude invoque automatiquement certaines compétences groupées lorsqu’elles sont pertinentes ; d’autres, notamment /verify, ne s’exécutent que lorsque vous les invoquez, ce qui vous permet de contrôler quand ces vérifications plus longues consomment du temps et des tokens.
La plupart des compétences groupées sont disponibles dans chaque session. Quelques-unes dépendent d’une fonctionnalité spécifique : /workflow-authoring, par exemple, n’est disponible que lorsque les flux de travail dynamiques sont activés.
Pour désactiver les compétences groupées, utilisez le paramètre disableBundledSkills.
La vérification de configuration
/doctor reste saisissable lorsque disableBundledSkills est activé, dans Claude Code v2.1.205 et versions ultérieures. Pour la masquer, définissez la variable d’environnement DISABLE_DOCTOR_COMMAND ou une entrée skillOverrides de "doctor": "off". Avant v2.1.205, /doctor était une commande intégrée plutôt qu’une compétence groupée.Exécuter et vérifier votre application
Trois compétences groupées travaillent ensemble pour lancer votre application et confirmer les modifications par rapport à l’application en cours d’exécution au lieu de simplement des tests :/run et /verify fonctionnent sans configuration. Ils déduisent le lancement de votre type de projet (CLI, serveur, TUI, piloté par navigateur) et de ce qui se trouve dans votre README, package.json ou Makefile. Cette déduction devient peu fiable pour les projets qui nécessitent quelque chose au-delà d’un lancement standard : une base de données, un fichier env, une session graphique, une construction multi-étapes.
/run-skill-generator enregistre plutôt la recette. Il fait fonctionner votre application à partir d’un environnement propre, capture ce qui a fonctionné (les commandes d’installation, les variables d’environnement, le script de lancement) et l’enregistre en tant que compétence par projet à .claude/skills/run-<name>/. Après cela, /run, /verify et tout autre agent du référentiel suivent la recette enregistrée au lieu de la redécouvrir. Exécutez /run-skill-generator une fois par projet, et à nouveau si le processus de construction ou de lancement change.
/verify peut également enregistrer sa propre recette. Lorsqu’elle doit construire et piloter votre application sans recette enregistrée, elle écrit ce qui a fonctionné dans .claude/skills/verify/SKILL.md à la racine du référentiel, ou dans le répertoire du package touché dans un monorepo, afin que les exécutions ultérieures et les autres agents suivent les mêmes étapes. À la racine du référentiel, la compétence enregistrée remplace la compétence groupée /verify. Cela nécessite Claude Code v2.1.200 ou version ultérieure.
Claude modifie le fichier enregistré uniquement lorsqu’il a mal dirigé une exécution, comme une commande qui a échoué ou une étape manquante, afin que vous puissiez valider le fichier sans diffs par session. Avant v2.1.205, la compétence groupée a dit à Claude de plier tout ce qu’une exécution a appris, ce qui a causé des conflits de fusion fréquents.
Démarrage
Créer votre première compétence
Cet exemple crée une compétence qui résume les modifications non validées dans votre référentiel git et signale tout ce qui est risqué. Il extrait le diff en direct dans l’invite avant que Claude ne le lise, de sorte que la réponse est ancrée dans votre arborescence de travail réelle plutôt que dans ce que Claude peut deviner à partir des fichiers ouverts. Claude charge la compétence automatiquement lorsque vous posez des questions sur vos modifications, ou vous pouvez l’invoquer directement avec/summarize-changes.
1
Créer le répertoire de la compétence
Créez un répertoire pour la compétence dans votre dossier de compétences personnelles. Les compétences personnelles sont disponibles dans tous vos projets.
2
Écrire SKILL.md
Chaque compétence a besoin d’un fichier La ligne
SKILL.md avec deux parties : un frontmatter YAML entre les marqueurs --- qui indique à Claude quand utiliser la compétence, et du contenu markdown avec les instructions que Claude suit lorsque la compétence s’exécute. Le nom du répertoire devient la commande que vous tapez, et la description aide Claude à décider quand charger la compétence automatiquement.Enregistrez ceci dans ~/.claude/skills/summarize-changes/SKILL.md :!`git diff HEAD` utilise l’injection de contexte dynamique : Claude Code exécute la commande et remplace la ligne par sa sortie avant que Claude ne voie le contenu de la compétence, de sorte que les instructions arrivent avec le diff actuel déjà intégré.3
Tester la compétence
Ouvrez un projet git, apportez une petite modification à n’importe quel fichier, et démarrez Claude Code en exécutant Ou invoquez-la directement avec le nom de la compétence :De l’une ou l’autre façon, Claude devrait répondre avec un court résumé de votre modification et une liste de risques.
claude. Vous pouvez tester la compétence de deux façons.Laissez Claude l’invoquer automatiquement en posant une question qui correspond à la description :Choisir où les skills se chargent
L’endroit où vous enregistrez une skill détermine quelles sessions la chargent. Enregistrez-la dans votre répertoire personnel pour l’obtenir dans chaque projet, validez-la dans un référentiel pour la partager avec tous ceux qui y travaillent, ou distribuez-la via un plugin ou des paramètres gérés pour atteindre toute une équipe.
Les dossiers de skills suivent également ces règles :
- Dossiers avec lien symbolique : une entrée
<skill-name>à l’emplacement entreprise, personnel ou projet peut être un lien symbolique vers un répertoire ailleurs sur le disque. Claude Code litSKILL.mddepuis la cible et charge la skill une seule fois même si plusieurs emplacements pointent vers la même cible. Les skills de plugin gèrent les liens symboliques différemment. - Nom réservé : ne nommez pas un dossier de skill
synced, quelle que soit la casse. Claude Code utilise~/.claude/skills/synced/pour les skills téléchargées depuis claude.ai et ignore une skill que vous créez à ce nom aux emplacements entreprise, personnel et projet. - Fichiers de commande : un fichier Markdown dans
.claude/commands/est le format plus ancien et fonctionne toujours. Il supporte le même frontmatter saufnameetpaths. Pour trouver le nom que vous tapez pour l’invoquer, voir Comment une skill obtient son nom de commande. Préférez une skill pour les nouveaux travaux, puisque les skills supportent aussi les fichiers de support. - Dossier de skill en tant que plugin : ajoutez un
.claude-plugin/plugin.jsonà un dossier de skill et il se charge en tant que plugin nommé<name>@skills-dir, pour qu’il puisse regrouper des agents, des hooks et des serveurs MCP. Dans un.claude/skills/de projet, cela nécessite d’accepter d’abord la boîte de dialogue de confiance de l’espace de travail.
Charger les skills dans les monorepos et les sous-répertoires
Claude Code charge les skills de projet depuis.claude/skills/ dans le répertoire où vous le démarrez et dans chaque répertoire parent jusqu’à la racine du référentiel, donc démarrer dans packages/frontend/ récupère toujours les skills définies à la racine. Quand vous déplacez la session avec /cd sur v2.1.246 ou ultérieur, Claude Code ajoute les skills de projet du nouveau répertoire.
Dans une session s’exécutant dans un git worktree lié, Claude Code recherche les répertoires parents uniquement jusqu’à la racine du worktree. Sur Claude Code v2.1.277 ou ultérieur, quand le checkout du worktree n’a pas de répertoire .claude/skills à sa racine, Claude Code charge à la place les skills de projet du checkout principal. Voir Ce que les worktrees partagent avec le checkout principal.
Les skills dans un répertoire .claude/skills/ en dessous de celui où vous avez démarré ne se chargent pas au démarrage. Elles se chargent la première fois que Claude lit ou édite un fichier dans ce sous-répertoire et restent disponibles pour le reste de la session. Jusqu’à ce moment, elles n’apparaissent pas dans le menu / et vous ne pouvez pas les invoquer par nom. Pour les charger plus tôt, exécutez /add-dir avec le chemin du sous-répertoire, ce qui nécessite Claude Code v2.1.257 ou ultérieur.
Quand une skill imbriquée partage un nom avec une autre skill, les deux restent disponibles. Avec une skill deploy à la racine du référentiel et une autre dans apps/web/.claude/skills/ :
/deployexécute la skill racine. Claude Code liste aussi les variantes qualifiées par répertoire pour Claude, avec une instruction pour invoquer celle dont le répertoire contient les fichiers sur lesquels il travaille, donc la skill imbriquée s’applique toujours au travail dansapps/web/./apps/web:deployexécute la skill imbriquée seule. Sa description nomme le répertoire auquel elle s’applique.
Charger les skills depuis un répertoire en dehors du projet
Quand vous ajoutez un répertoire avec--add-dir ou /add-dir, Claude Code charge les skills dans le .claude/skills/ de ce répertoire, ainsi que son .claude/commands/ et .claude/agents/. Les répertoires que le SDK Agent ajoute via additionalDirectories en TypeScript ou add_dirs en Python se chargent de la même façon, car le SDK les transmet en tant que --add-dir. Le paramètre permissions.additionalDirectories dans settings.json accorde uniquement l’accès aux fichiers et ne charge aucun de ceux-ci.
Claude Code surveille .claude/skills/ dans un répertoire que vous transmettez avec --add-dir au lancement, comme le décrit Éditer une skill pendant une session. Il ne surveille pas le .claude/commands/ ou .claude/agents/ du répertoire ajouté, donc redémarrez la session après avoir modifié un fichier là-bas.
Ces chargements dépendent de la source de paramètre project setting source, qui est activée par défaut. Une politique strictPluginOnlyCustomization, le mode bare et --safe-mode les restreignent davantage, comme ces pages le décrivent. Voir Les répertoires supplémentaires accordent l’accès aux fichiers, pas la configuration pour le tableau complet de ce qu’un répertoire ajouté charge, y compris CLAUDE.md et les paramètres de plugin.
Résoudre les skills qui partagent un nom
Quand deux skills partagent un nom, l’endroit d’où chacune provient décide laquelle/name exécute. Le tableau couvre les emplacements entreprise, personnel, projet, imbriqué, plugin et claude.ai, les skills regroupées et les fichiers de commande :
Utiliser les skills dans les sessions Cowork et cloud
Les sessions Cowork et les sessions cloud, y compris les routines, ne lisent pas~/.claude/skills/ sur votre machine. Les sessions Cowork interactives et planifiées chargent les skills activées pour votre compte claude.ai, synchronisées au démarrage de la session ; gérez-les depuis Customize dans la barre latérale de l’application Desktop ou depuis les paramètres de skills sur claude.ai. Les sessions cloud chargent en outre les skills de projet validées dans le .claude/skills/ du référentiel cloné.
Si une skill existe uniquement dans ~/.claude/skills/ sur votre machine, Claude Code signale que la skill n’a pas été trouvée quand une routine l’invoque, car chaque exécution de routine démarre en tant que nouvelle session cloud. Pour rendre une skill personnelle disponible dans ces sessions :
- Pour les sessions Cowork et cloud, activez la skill pour votre compte claude.ai.
- Pour les sessions cloud, vous pouvez à la place valider la skill dans le
.claude/skills/du référentiel. Les plugins déclarés dans le.claude/settings.jsondu référentiel et les plugins activés uniquement dans vos paramètres utilisateur ne se chargent pas dans les sessions cloud.
~/.claude/skills/.
Skills synchronisées depuis claude.ai
Cette section s’applique à vous si vous utilisez les sessions Cowork ou cloud, ou si vous vous connectez à Claude Code dans votre terminal avec un compte claude.ai. Dans ces sessions, Claude Code charge les skills activées pour votre compte claude.ai, sans configuration de votre part, comme le décrit Où les skills synchronisées se chargent. Ces skills incluent celles que vous créez ou activez dans vos paramètres claude.ai, les skills que votre organisation fournit là-bas, et les skills intégrées d’Anthropic telles quepdf et xlsx.
Claude Code télécharge une skill synchronisée depuis votre compte plutôt que de lire un fichier que vous avez écrit sur la machine où la session s’exécute, donc il applique des règles aux skills synchronisées qui ne s’appliquent pas aux skills que vous stockez dans les emplacements de skills.
Où les skills synchronisées se chargent
Dans une session Cowork ou cloud, Claude Code charge les skills activées pour votre compte claude.ai, et Skills dans les sessions Cowork et cloud dit comment choisir quelles skills ces sessions obtiennent. Dans votre terminal, Claude Code synchronise ces skills dans les sessions où vous vous connectez avec votre compte claude.ai. Quand la session démarre, Claude Code télécharge les skills de votre compte dans~/.claude/skills/synced/ en arrière-plan, puis vérifie claude.ai pour les modifications environ toutes les 10 minutes pendant que la session s’exécute. Quand une vérification découvre qu’une skill a été ajoutée, éditée ou désactivée sur claude.ai, Claude Code l’ajoute, la met à jour ou la supprime dans la session en cours sans redémarrage. La synchronisation dans les sessions de terminal nécessite Claude Code v2.1.273 ou ultérieur.
La synchronisation ne retarde jamais le démarrage, car Claude attend le téléchargement d’une skill uniquement quand il invoque cette skill. Une exécution courte non-interactive peut donc se terminer avant qu’une skill nouvellement ajoutée ne se télécharge, auquel cas une session ultérieure la télécharge. Pour faire en sorte qu’une exécution non-interactive télécharge vos skills et attende la liste avant de répondre à l’invite, définissez CLAUDE_CODE_SYNC_SKILLS sur 1.
Claude Code ne synchronise que dans une session qui se connecte avec votre compte claude.ai et récupère les drapeaux de fonctionnalités depuis Anthropic. Il ne synchronise pas dans ces sessions :
- Une session qui n’utilise pas une connexion stockée par
/login, comme une qui s’authentifie avec une clé API, ou une oùANTHROPIC_AUTH_TOKEN,CLAUDE_CODE_OAUTH_TOKENou un scriptapiKeyHelperfournit les identifiants - Une session qui ne récupère pas les drapeaux de fonctionnalités, comme une sur Amazon Bedrock ou une où vous définissez
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC - Une session en mode bare ou une que vous démarrez avec
--safe-mode - Une session où les paramètres gérés de votre organisation verrouillent les skills aux sources de plugin, ou une que vous démarrez avec une liste
--setting-sourcesqui ometuser
/login pendant une session, redémarrez Claude Code pour commencer la synchronisation.
Les skills qu’une session antérieure a synchronisées restent sur le disque. Claude Code les charge dans les sessions ultérieures connectées au même compte, même quand il ne peut pas atteindre claude.ai.
Claude Code télécharge les skills synchronisées et ne les télécharge jamais. Si vous ou Claude éditez un fichier sous ~/.claude/skills/synced/, la modification n’est pas enregistrée sur votre compte claude.ai, et une synchronisation ultérieure peut la remplacer ou la supprimer. Pour modifier une skill synchronisée, mettez-la à jour sur claude.ai ; la prochaine synchronisation télécharge la nouvelle version.
Pour voir quelles skills se sont synchronisées, exécutez /skills. Le menu les liste sous claude.ai sync.
Certaines skills d’Anthropic, comme pdf et xlsx, se synchronisent toujours. Pour les autres, activez ou désactivez une skill dans vos paramètres de skills sur claude.ai pour changer si elle se synchronise.
Pour arrêter la synchronisation sur une machine, définissez syncClaudeAiSkills sur false dans vos paramètres utilisateur. Claude Code arrête le téléchargement, et la prochaine fois qu’il démarre, il déplace les skills qu’il a déjà synchronisées vers ~/.claude/skills/.trash/ et ne les charge plus. Votre organisation peut désactiver la synchronisation pour tout le monde en désactivant Skills sur claude.ai. Pour arrêter la synchronisation tout en laissant Skills activé, elle peut définir la même clé dans les paramètres gérés.
Si votre organisation désactive Skills sur claude.ai, Claude Code supprime les skills téléchargées et elles cessent de se charger. Les skills supprimées se déplacent vers ~/.claude/skills/.trash/, où vous pouvez récupérer les fichiers jusqu’à ce que le balayage de rétention les supprime. Une fois que votre organisation réactive Skills, Claude Code télécharge les skills que vous avez activées à la prochaine synchronisation.
Quand un nom de skill synchronisée correspond à une autre commande
Vous pouvez invoquer une skill synchronisée par son nom complet,/anthropic-skills:<name>, ou par son nom court, /<name>. Quand une autre commande utilise ce nom court, /<name> exécute l’autre commande, et la skill synchronisée s’exécute uniquement en tant que /anthropic-skills:<name>. Avec une skill deploy locale et une deploy synchronisée, /deploy exécute la skill locale et /anthropic-skills:deploy exécute la synchronisée. Avant v2.1.269, une skill synchronisée n’avait que son nom court.
L’autre commande peut être n’importe laquelle de celles-ci :
- Une commande intégrée ou une skill regroupée, y compris une qui n’est pas disponible dans votre session, par exemple après avoir désactivé les skills regroupées
- Une skill à n’importe quel niveau local ou un fichier dans
.claude/commands/ - Une skill de plugin
- Une invite MCP
/skills et /context groupent les skills synchronisées sous claude.ai sync, et le menu de commande / les marque comme provenant de claude.ai.
Quand il compare les noms, Claude Code ignore la casse, l’espacement et les caractères invisibles, et traite les formes de compatibilité telles que les lettres pleine largeur et les variantes de tiret comme leurs équivalents simples. Par exemple, une skill synchronisée nommée Commit et une skill locale nommée commit comptent comme le même nom, donc /commit continue d’exécuter votre skill locale.
Un nom qui diffère uniquement par une lettre ressemblante d’un autre alphabet compte comme un nom différent, et l’étiquette claude.ai sync est comment vous distinguez les deux. Ces vérifications et étiquettes nécessitent Claude Code v2.1.228 ou ultérieur.
Comment Claude Code gère le frontmatter d’une skill synchronisée
Claude Code applique deux règles au frontmatter d’une skill synchronisée :- Claude Code honore le frontmatter dans chaque type de session, donc une concession
allowed-toolspasse par le flux de permission normal. - Claude Code assainit le texte d’affichage que la skill fournit, comme sa description. Il supprime les caractères de contrôle, et dans le texte qui atteint Claude, comme la description, il échappe aussi les crochets pointus pour que le texte ne puisse pas imiter le formatage interne de Claude Code. Cet assainissement nécessite Claude Code v2.1.228 ou ultérieur.
Comment Claude Code gère le corps d’une skill synchronisée
Ce que Claude Code fait avec le corps d’une skill synchronisée dépend de l’endroit où la session s’exécute :- Dans une session cloud, le corps conserve le comportement qu’une skill locale a, car la session s’exécute dans un conteneur isolé.
- Dans une session Cowork sur votre bureau, le corps conserve le comportement qu’une skill locale a, sauf que Claude Code remplace chaque ligne de commande
!par l’espace réservédisableSkillShellExecution, comme il le fait pour chaque skill que vous fournissez là-bas. - Dans toute autre session sur votre machine, Claude Code n’exécute pas les commandes
!, n’attache pas les fichiers que les références@nomment de la façon qu’il le fait pour une skill locale, et ne substitue pas les espaces réservés${CLAUDE_PROJECT_DIR}et${CLAUDE_SESSION_ID}, donc les références@et les deux espaces réservés atteignent Claude en tant que texte littéral. Une ligne de commande!atteint aussi Claude en tant que texte littéral, ou en tant que cet espace réservé quanddisableSkillShellExecutionest activé. Cette gestion nécessite Claude Code v2.1.228 ou ultérieur.
Éditer une skill pendant une session
Claude Code surveille les répertoires de skills pour les modifications de fichiers, sauf en mode bare. Quand vous ajoutez, éditez ou supprimez une skill sous~/.claude/skills/, le .claude/skills/ du projet, ou un .claude/skills/ à l’intérieur d’un répertoire --add-dir, Claude Code récupère la modification dans la session actuelle, sans redémarrage. Si vous créez un répertoire de skills de niveau supérieur qui n’existait pas quand la session a démarré, redémarrez Claude Code pour qu’il puisse surveiller le nouveau répertoire.
La détection de changement en direct couvre uniquement le texte SKILL.md. Pour un dossier de skill qui est aussi un plugin, les modifications apportées à hooks/, .mcp.json, agents/ et output-styles/ nécessitent /reload-plugins pour prendre effet.
Supprimer une skill
La façon dont vous supprimez une skill dépend de l’endroit d’où elle provient :- Skill personnelle ou de projet : supprimez le répertoire de la skill,
~/.claude/skills/<skill-name>/ou.claude/skills/<skill-name>/. Claude Code la supprime de/skillsdans la session actuelle ; le contenu que Claude Code a déjà chargé depuis elle suit le cycle de vie du contenu de skill. - Skill d’entreprise : un administrateur supprime le répertoire de la skill depuis
.claude/skills/à l’intérieur du répertoire des paramètres gérés, par exemple/etc/claude-code/.claude/skills/<skill-name>/sur Linux. - Skill de plugin : désactivez ou désinstallez le plugin qui la fournit, depuis le menu
/pluginou avec/plugin uninstall <plugin-name>@<marketplace-name>. Claude Code décharge les skills du plugin quand le changement s’applique ou quand vous redémarrez. - Skill synchronisée depuis claude.ai : désactivez la skill pour votre compte claude.ai, au même endroit où vous l’avez activée. Claude Code la supprime de
~/.claude/skills/synced/la prochaine fois qu’elle synchronise vos skills. Si vous supprimez le répertoire à la main à la place, la prochaine synchronisation le télécharge à nouveau pendant que la skill reste activée sur claude.ai. - Skill regroupée : définissez
disableBundledSkillssurtruepour désactiver les skills regroupées, ou définissez une skill sur"off"dansskillOverridespour la masquer.
disable-model-invocation: true dans son frontmatter, ou "user-invocable-only" dans skillOverrides quand vous ne voulez pas éditer le fichier.
Configurer les compétences
Les compétences sont configurées via le frontmatter YAML en haut deSKILL.md et le contenu markdown qui suit.
Types de contenu de compétence
Les fichiers de compétence peuvent contenir n’importe quelles instructions, mais réfléchir à la façon dont vous souhaitez les invoquer aide à guider ce qu’il faut inclure : Le contenu de référence ajoute des connaissances que Claude applique à votre travail actuel. Conventions, modèles, guides de style, connaissances du domaine. Ce contenu s’exécute en ligne afin que Claude puisse l’utiliser aux côtés du contexte de votre conversation./skill-name plutôt que de laisser Claude décider quand les exécuter. Ajoutez disable-model-invocation: true pour empêcher Claude de le déclencher automatiquement. L’exemple ci-dessous ajoute context: fork, qui exécute la compétence dans son propre contexte de sous-agent ; voir Exécuter les compétences dans un sous-agent.
Référence du frontmatter
Configurez une compétence avec le frontmatter YAML entre les marqueurs--- en haut de SKILL.md, et écrivez les instructions de la compétence en Markdown après le --- de fermeture. Les noms de champs utilisent des mots minuscules séparés par des tirets, sauf when_to_use. Un fichier de commande dans .claude/commands/ accepte les mêmes champs sauf name et paths. Cet exemple définit quatre champs :
description est recommandé afin que Claude sache quand utiliser la compétence. Un nom de champ doit correspondre exactement au tableau, tirets inclus : Claude Code ignore un champ qu’il ne reconnaît pas sans signaler une erreur.
Claude Code lit le frontmatter uniquement lorsque l’ouverture --- est la première ligne du fichier. Sinon, il traite le fichier entier, marqueurs --- inclus, comme contenu de compétence. Si le YAML entre les marqueurs ne s’analyse pas, la compétence se charge quand même sans champs définis ; voir Compétence ne se déclenchant pas pour trouver et corriger l’erreur.
Les champs booléens acceptent yes, no, on, off, 1 et 0 dans n’importe quelle casse de lettre, en plus de true et false. Avant v2.1.218, Claude Code ne reconnaissait que true et false.
Utiliser le frontmatter de compétence en dehors de Claude Code
Claude Code accepte tous les champs du tableau ci-dessus. En dehors de Claude Code, vous ne pouvez utiliser que les champs de la spécification Agent Skills :
Lorsque vous activez une compétence personnelle pour votre compte claude.ai, par exemple pour l’utiliser dans les sessions Cowork et cloud et les routines, vous la téléchargez sur claude.ai, donc les mêmes règles s’appliquent.
Si vous incluez un champ que la spécification ne permet pas, l’empaquetage ou le téléchargement échoue avec une erreur matérielle au lieu d’ignorer le champ :
Comment une compétence obtient son nom de commande
La commande que vous tapez pour invoquer une compétence provient de l’endroit où le fichier de compétence se trouve et, pour les compétences de plugin, également du champ frontmattername. Dans une compétence personnelle ou de projet, name définit uniquement l’étiquette d’affichage affichée dans les listes de compétences, et la commande provient toujours du nom du répertoire. Dans une compétence de plugin, name définit le dernier segment de la commande et le préfixe du plugin reste en place.
Le tableau ci-dessous montre d’où provient le nom de la commande pour chaque disposition :
Dans une compétence de plugin, le frontmatter
name remplace le nom du répertoire dans le dernier segment de la commande, donc my-plugin/skills/review/SKILL.md avec name: fancy devient /my-plugin:fancy. Le /fancy nu invoque également la compétence à moins qu’une autre commande n’utilise déjà ce nom. Si le name que vous écrivez commence déjà par le propre préfixe du plugin, Claude Code n’ajoute pas le préfixe à nouveau sur v2.1.246 ou ultérieur. Par exemple, name: my-plugin:fancy devient toujours /my-plugin:fancy. De v2.1.216 à v2.1.245, Claude Code doublait le préfixe lorsque le name le portait déjà.
Dans les sessions non interactives, les noms help et feedback ne sont pas réservés à leurs commandes intégrées terminales uniquement, donc une compétence de plugin avec l’un de ces noms conserve sa commande nue là. Tous les autres noms de commandes intégrées terminales, comme /login, restent réservés même si la commande ne peut pas s’exécuter dans ces sessions.
Pour un SKILL.md racine de plugin, il n’y a pas de répertoire de compétence d’où prendre le nom, donc name fournit le segment final entier. Sans un champ name, Claude Code revient au nom du répertoire du plugin.
Substitutions de chaîne disponibles
Les compétences prennent en charge la substitution de chaîne pour les valeurs dynamiques dans le contenu de la compétence :
Claude Code substitue
${CLAUDE_SKILL_DIR} et ${CLAUDE_PROJECT_DIR} à deux endroits : le contenu markdown de la compétence et les règles Bash dans le frontmatter allowed-tools. Dans une compétence de plugin, Claude Code substitue ${CLAUDE_PLUGIN_ROOT} et ${CLAUDE_PLUGIN_DATA} aux mêmes deux endroits. L’utilisation de la même variable aux deux endroits permet à une compétence d’exécuter un script fourni sans invite de permission. La compétence suivante montre le modèle :
~/.claude/skills/render-chart/, les deux occurrences de ${CLAUDE_SKILL_DIR} se développent à ce répertoire. La règle allowed-tools correspond alors à la commande exacte que le corps de la compétence indique à Claude d’exécuter, donc le script s’exécute sans invite.
La substitution ${CLAUDE_PROJECT_DIR} nécessite Claude Code v2.1.196 ou ultérieur.
Les arguments indexés utilisent les guillemets de style shell, donc enveloppez les valeurs multi-mots entre guillemets pour les passer comme un seul argument. Par exemple, /my-skill "hello world" second fait que $0 se développe à hello world et $1 à second. L’espace réservé $ARGUMENTS se développe toujours à la chaîne d’argument complète telle que tapée.
Un espace réservé indexé sans argument correspondant, comme $2 lorsqu’un seul argument a été passé, reste dans le contenu inchangé. Un espace réservé nommé du frontmatter arguments sans argument correspondant se développe à une chaîne vide.
Si vous passez une valeur d’argument qui elle-même contient du texte comme $1 ou $ARGUMENTS, Claude Code l’insère comme texte littéral et ne l’étend pas. Par exemple, si le corps d’une compétence contient Summarize $0 et que vous exécutez /summarize "$ARGUMENTS from yesterday", Claude reçoit Summarize $ARGUMENTS from yesterday. Claude Code remplace toujours les variables ${CLAUDE_*} comme ${CLAUDE_SKILL_DIR} après avoir inséré les arguments.
Pour inclure un $ littéral avant un chiffre, ARGUMENTS ou un nom d’argument déclaré, comme $1.00 en prose, échappez-le avec une barre oblique inverse : \$1.00. Une barre oblique inverse avant tout autre $ est laissée inchangée. Seule une barre oblique inverse directement avant le jeton l’échappe. Une barre oblique inverse doublée comme \\$1 laisse les deux barres obliques inverses en place, et $1 se développe toujours à la valeur de l’argument. L’échappement par barre oblique inverse couvre uniquement ces espaces réservés d’argument. Une barre oblique inverse n’empêche pas la substitution d’une variable ${CLAUDE_*} où la variable s’applique.
Exemple utilisant les substitutions :
Ajouter des fichiers de support
Les compétences peuvent inclure plusieurs fichiers dans leur répertoire. Cela gardeSKILL.md concentré sur l’essentiel tout en permettant à Claude d’accéder à du matériel de référence détaillé uniquement si nécessaire. Les grandes docs de référence, les spécifications API ou les collections d’exemples n’ont pas besoin de se charger en contexte à chaque fois que la compétence s’exécute.
SKILL.md afin que Claude sache ce que chaque fichier contient et quand le charger :
Contrôler qui invoque une compétence
Par défaut, vous et Claude pouvez invoquer n’importe quelle compétence. Vous pouvez taper/skill-name pour l’invoquer directement, et Claude peut la charger automatiquement lorsqu’elle est pertinente pour votre conversation. Deux champs frontmatter vous permettent de restreindre ceci :
-
disable-model-invocation: true: Seul vous pouvez invoquer la compétence. Utilisez ceci pour les flux de travail avec des effets secondaires ou que vous souhaitez contrôler le timing, comme/commit,/deployou/send-slack-message. Vous ne voulez pas que Claude décide de déployer parce que votre code semble prêt. -
user-invocable: false: Seul Claude peut invoquer la compétence. Utilisez ceci pour les connaissances de base qui ne sont pas actionnables en tant que commande. Une compétencelegacy-system-contextexplique comment fonctionne un ancien système. Claude devrait le savoir lorsqu’il est pertinent, mais/legacy-system-contextn’est pas une action significative pour les utilisateurs.
disable-model-invocation: true, Claude ne peut pas exécuter la compétence automatiquement :
/deploy vous-même.
Voici comment les deux champs affectent l’invocation et le chargement du contexte :
Dans une session régulière, les descriptions de compétences sont chargées en contexte afin que Claude sache ce qui est disponible, mais le contenu complet de la compétence ne se charge que lorsqu’elle est invoquée. Les sous-agents avec compétences préchargées fonctionnent différemment : le contenu complet de la compétence est injecté au démarrage.
Cycle de vie du contenu de la compétence
Lorsque vous ou Claude invoquez une compétence, le contenuSKILL.md rendu entre dans la conversation en tant que message unique et y reste à travers les tours ultérieurs. Cette persistance s’applique aux instructions de la compétence, pas à ses permissions : une subvention allowed-tools s’efface lorsque vous envoyez votre message suivant. Claude Code ne relit pas le fichier de compétence aux tours ultérieurs, donc écrivez les conseils qui devraient s’appliquer tout au long d’une tâche en tant qu’instructions permanentes plutôt que des étapes ponctuelles.
Lorsque Claude réinvoque une compétence dont le contenu rendu est identique à la copie déjà en contexte, Claude Code ajoute une courte note que la compétence est déjà chargée plutôt qu’une deuxième copie du contenu. Lorsque le contenu rendu diffère, parce que les arguments ont changé ou qu’une commande contexte dynamique a produit une nouvelle sortie, Claude Code ajoute le contenu complet à nouveau.
L’auto-compaction porte les compétences invoquées en avant dans un budget de tokens. Lorsque la conversation est résumée pour libérer du contexte, Claude Code réattache l’invocation la plus récente de chaque compétence après le résumé, en gardant les premiers 5 000 tokens de chacune. Les compétences réattachées partagent un budget combiné de 25 000 tokens. Claude Code remplit ce budget à partir de la compétence la plus récemment invoquée, donc les compétences plus anciennes peuvent être entièrement supprimées après la compaction si vous en avez invoqué beaucoup dans une session.
Si une compétence semble cesser d’influencer le comportement après la première réponse, le contenu est généralement toujours présent et le modèle choisit d’autres outils ou approches. Renforcez la description de la compétence et les instructions afin que le modèle continue à la préférer, ou utilisez hooks pour appliquer le comportement de manière déterministe. Si la compétence est grande ou que vous en avez invoqué plusieurs après elle, réinvoquez-la après la compaction pour restaurer le contenu complet.
Pré-approuver les outils pour une compétence
Le champallowed-tools accorde la permission pour les outils listés lors du tour qui invoque la compétence, afin que Claude puisse les utiliser sans vous demander l’approbation. La subvention s’efface lorsque vous envoyez votre message suivant, même si le contenu de la compétence reste en contexte ; invoquer la compétence à nouveau réapplique pour ce tour. Il ne restreint pas les outils disponibles : chaque outil reste appelable, et vos paramètres de permission gouvernent toujours les outils qui ne sont pas listés. Pour pré-approuver les outils pour la session entière plutôt qu’un seul tour, ajoutez plutôt des règles d’autorisation à ces paramètres de permission.
La confiance de l’espace de travail ne contrôle pas ce champ. Claude Code applique l’allowed-tools d’une compétence de projet chaque fois que vous ou Claude invoquez la compétence, y compris dans une exécution -p dans un dossier que vous n’avez jamais approuvé. Une compétence peut se donner un accès aux outils très large, donc examinez l’allowed-tools des compétences archivées dans un référentiel avant d’exécuter Claude Code là.
Cette compétence permet à Claude d’exécuter les commandes git sans approbation par utilisation chaque fois que vous l’invoquez :
disallowed-tools dans le frontmatter de la compétence. La restriction s’efface lorsque vous envoyez votre message suivant. Comme les règles de refus, le champ ne peut pas supprimer EndConversation tant que tout autre outil reste. Pour bloquer les outils à travers toutes les compétences et invites, ajoutez des règles de refus dans vos paramètres de permission.
Passer des arguments aux compétences
Vous et Claude pouvez passer des arguments lors de l’invocation d’une compétence. Les arguments sont disponibles via l’espace réservé$ARGUMENTS.
Cette compétence corrige un problème GitHub par numéro. L’espace réservé $ARGUMENTS est remplacé par tout ce qui suit le nom de la compétence :
/fix-issue 123, Claude reçoit « Fix GitHub issue 123 following our coding standards… »
Si vous invoquez une compétence avec des arguments mais qu’aucun espace réservé dans le contenu de la compétence n’en reçoit un, Claude Code ajoute ARGUMENTS: <your input> à la fin du contenu de la compétence afin que Claude voie toujours ce que vous avez tapé. Un espace réservé est $ARGUMENTS, une forme indexée comme $1 ou un argument nommé. Un espace réservé indexé sans argument à sa position reste comme texte littéral et ne compte pas comme en recevant un. Un espace réservé nommé compte même lorsque sa position n’a pas d’argument, car il se développe à une chaîne vide.
Vous pouvez également empiler plusieurs compétences au début d’un message. Taper /write-tests /fix-issue 123 charge les deux compétences et passe le texte final 123 comme $ARGUMENTS à chacune d’elles. Avant v2.1.199, seule la première compétence se chargeait et recevait /fix-issue 123 comme texte d’argument littéral.
Claude Code étend la première compétence plus jusqu’à cinq autres empilées après elle. L’expansion s’arrête au premier jeton qui n’est pas une compétence invocable par l’utilisateur en ligne, donc une compétence qui s’exécute en tant que sous-agent forké, comme /code-review, ou une dont les arguments peuvent eux-mêmes commencer par une commande slash, comme /loop, termine également la course là. Ce jeton et tout ce qui le suit deviennent le texte d’argument pour chaque compétence étendue. /code-review s’exécute en tant que sous-agent forké à partir de v2.1.218 ; sur les versions antérieures, il s’exécutait en ligne et s’empilait.
Pour accéder aux arguments individuels par position, utilisez $ARGUMENTS[N] ou le plus court $N :
/migrate-component SearchBar JavaScript TypeScript remplace $ARGUMENTS[0] par SearchBar, $ARGUMENTS[1] par JavaScript et $ARGUMENTS[2] par TypeScript. La même compétence utilisant le raccourci $N :
Modèles avancés
Injecter du contexte dynamique
La syntaxe!`<command>` exécute des commandes shell avant que le contenu de la compétence soit envoyé à Claude. La sortie de la commande remplace l’espace réservé, de sorte que Claude reçoit des données réelles, pas la commande elle-même. Claude Code n’exécute pas ces commandes sur votre machine lorsque la compétence est synchronisée depuis votre compte claude.ai. Cette restriction nécessite Claude Code v2.1.228 ou version ultérieure.
Cette compétence résume une demande de tirage en récupérant les données de PR en direct avec GitHub CLI. Les commandes !`gh pr diff` et autres s’exécutent en premier, et leur sortie est insérée dans l’invite :
!`<command>`, de sorte qu’une commande ne peut pas émettre un espace réservé pour qu’une passe ultérieure l’étende.
La forme en ligne n’est reconnue que lorsque ! apparaît au début d’une ligne ou immédiatement après un espace blanc. Si ! suit un autre caractère, comme dans KEY=!`cmd`, l’espace réservé est laissé en tant que texte littéral et la commande ne s’exécute pas.
Pour les commandes multi-lignes, utilisez un bloc de code délimité ouvert avec ```! au lieu de la forme en ligne :
"disableSkillShellExecution": true dans settings. Chaque commande est remplacée par [shell command execution disabled by policy] au lieu d’être exécutée. Les compétences groupées et gérées ne sont pas affectées. Ce paramètre est très utile dans managed settings, où les utilisateurs ne peuvent pas le remplacer.
Claude Code n’exécute jamais ces commandes sur votre machine lorsqu’elles apparaissent dans les compétences synchronisées depuis votre compte claude.ai, quel que soit ce paramètre. Cette restriction nécessite Claude Code v2.1.228 ou version ultérieure. How Claude Code handles the body of a synced skill indique ce que Claude reçoit à la place de la commande dans chaque type de session.
Comment les commandes injectées s’exécutent
Claude Code choisit l’outil qui exécute les commandes injectées d’une compétence à partir de la cléshell dans le frontmatter de la compétence et de votre environnement. Chaque combinaison exécute les commandes via l’outil Bash ou l’outil PowerShell, sauf une qui échoue l’invocation directement :
shell: powershell, avec l’outil PowerShell activé : les commandes s’exécutent via l’outil PowerShell.shell: bashlorsque bash n’est pas disponible : l’invocation échoue avant l’exécution de toute commande. Cela se produit sur Windows sans Git Bash. Claude Code afficheSkill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found.- Toute autre combinaison : les commandes s’exécutent via l’outil Bash lorsque bash est disponible. Sinon, elles s’exécutent via l’outil PowerShell.
- Répertoire de travail : Claude Code exécute chaque commande dans le répertoire de travail actuel du shell de la session. Ce répertoire se déplace lorsque Claude exécute
cd. Utilisez${CLAUDE_SKILL_DIR}ou${CLAUDE_PROJECT_DIR}dans les chemins qui doivent se résoudre de la même manière à chaque fois. - stderr : avec le shell
bashpar défaut, Claude Code fusionne stderr dans stdout. Tout ce que la commande écrit dans stderr apparaît dans le texte injecté. - Délai d’expiration : chaque commande s’exécute sous le délai d’expiration par défaut de 2 minutes de l’outil Bash. Lorsque l’outil Bash déplace une commande expirée en arrière-plan, la compétence s’affiche toujours. Le texte injecté signale le déplacement et nomme la tâche en arrière-plan et le fichier collectant la sortie de la commande. Lorsque la commande est une que l’outil Bash ne met jamais automatiquement en arrière-plan, Claude Code la tue au délai d’expiration. Cet échec abandonne l’invocation.
- Taille de la sortie : la sortie au-delà du plafond en ligne de l’outil Bash arrive sous la forme d’un chemin de fichier plus un court aperçu, pas du texte tronqué. Output limits couvre le plafond et comment ajuster chaque limite.
Quand une commande injectée échoue
Une commande échouée abandonne l’invocation de compétence entière, pas seulement son propre espace réservé. Claude ne voit jamais le contenu de la compétence pour cette invocation. L’abandon afficheShell command failed for pattern "...". Le message d’erreur inclut la sortie de la commande sous [stderr].
Avec le shell bash par défaut, tout code de sortie non nul compte comme un échec. Une exception s’applique : Claude Code traite le code de sortie 1 des commandes de recherche et de comparaison comme un résultat normal et injecte leur sortie. Les codes de sortie de 2 ou plus échouent même pour ces commandes.
Les commandes qui obtiennent l’exception dépendent du shell :
- Shell
bashpar défaut : les commandes listées sous Output limits shell: powershell, lorsque l’outil PowerShell est activé : un ensemble différent qui inclutgrepetgit diffmais pasfindoudiff
bash par défaut, ajoutez || true à toute autre commande que vous vous attendez à quitter non-zéro. Un script de vérification qui quitte 1 lorsqu’il trouve des problèmes en est un exemple.
Vérifications des permissions sur les commandes injectées
Les commandes injectées ne demandent jamais la permission pendant que la compétence s’affiche. Claude Code vérifie chacune d’elles par rapport à vos règles de permission en premier. Une commande qu’une règle de refus correspond abandonne l’invocation avecShell command permission check failed for pattern "...".
En dehors du mode auto, lorsque la vérification des permissions d’une commande retourne autre chose que l’autorisation, Claude Code abandonne l’invocation avec la même erreur. Cela inclut une règle qui vous demanderait normalement. Pour empêcher une commande non appariée d’abandonner ici, pré-approuvez-la avec allowed-tools. Les règles de refus et d’ask remplacent toujours allowed-tools. Voir Manage permissions.
En mode auto, une commande qui aurait autrement besoin de votre approbation n’abandonne pas l’invocation. La compétence se charge avec une instruction indiquant à Claude d’exécuter d’abord la commande, et l’appel propre de Claude passe ensuite par les vérifications habituelles du mode auto. L’invocation abandonne toujours dans une compétence forkée qui définit agent, et dans une session où Claude n’a pas l’outil shell qui exécute les commandes injectées.
Exécuter les compétences dans un sous-agent
Ajoutezcontext: fork à votre frontmatter lorsque vous souhaitez qu’une compétence s’exécute en isolation. Claude Code démarre un nouveau sous-agent du type défini dans le champ agent et lui donne le contenu de la compétence comme invite. Le sous-agent ne voit pas votre historique de conversation, de sorte que les instructions de la compétence doivent être autonomes.
Malgré le nom, une compétence avec
context: fork ne s’exécute pas dans un fork de la conversation actuelle, ce qui remettrait au sous-agent tout ce que vous avez discuté jusqu’à présent. Lorsque la tâche dépend de cet historique, forkez la conversation au lieu d’utiliser context: fork.background: false dans le frontmatter pour attendre le résultat dans le tour qui a invoqué la compétence. Avant v2.1.218, les compétences forkées bloquaient toujours le tour jusqu’à ce qu’elles se terminent.
Claude Code attend également le résultat, même lorsque la compétence ne définit pas background: false, dans des cas comme ceux-ci :
- En mode non-interactif, avec le drapeau
-pou le SDK Agent - Lorsque vous définissez
CLAUDE_CODE_DISABLE_BACKGROUND_TASKSsur1, ce qui désactive également toutes les autres fonctionnalités de tâche en arrière-plan - Lorsque vous invoquez une compétence forkée alors qu’une invocation antérieure de la même compétence s’exécute toujours
- Lorsqu’une tâche planifiée se déclenche avec la compétence comme invite
background: false pour conserver l’ensemble d’outils complet.
Une compétence forkée qui s’exécute en arrière-plan applique ses modifications en dehors des points de contrôle de votre session, de sorte que /rewind ne les annule pas ; utilisez git pour les annuler.
Les compétences et les sous-agents travaillent ensemble dans deux directions :
Avec
context: fork, vous écrivez la tâche dans votre compétence et choisissez un type d’agent pour l’exécuter. Les agents Explore et Plan intégrés ignorent CLAUDE.md et l’état git pour garder leur contexte petit, de sorte qu’une compétence forkée utilisant agent: Explore ne voit que le contenu SKILL.md et l’invite système propre de l’agent. Pour l’inverse, où vous définissez un sous-agent personnalisé qui utilise les compétences comme matériel de référence, voir Subagents.
Exemple : Compétence de recherche utilisant l’agent Explore
Cette compétence exécute la recherche dans un agent Explore forké. Le contenu de la compétence devient la tâche, et l’agent fournit des outils en lecture seule optimisés pour l’exploration de la base de code :- Un nouveau contexte isolé est créé
- Le sous-agent reçoit le contenu de la compétence comme son invite (les instructions « Research $ARGUMENTS thoroughly »)
- Le champ
agentdétermine l’environnement d’exécution (modèle, outils et permissions) - Le sous-agent résume ses résultats et les retourne à votre conversation principale lorsqu’il se termine
agent spécifie quelle configuration de sous-agent utiliser. Les options incluent les agents intégrés (Explore, Plan, general-purpose) ou tout sous-agent personnalisé de .claude/agents/. S’il est omis, utilise general-purpose.
Restreindre l’accès aux compétences de Claude
Par défaut, Claude peut invoquer n’importe quelle compétence qui n’a pasdisable-model-invocation: true défini. Les compétences qui définissent allowed-tools accordent à Claude l’accès à ces outils sans approbation par utilisation pendant le tour qui invoque la compétence ; l’octroi s’efface lorsque vous envoyez votre message suivant. Vos paramètres de permission régissent toujours le comportement d’approbation de base pour tous les autres outils. Quelques commandes intégrées sont également disponibles via l’outil Skill, notamment /init et /security-review. D’autres commandes intégrées telles que /compact ne le sont pas.
Trois façons de contrôler les compétences que Claude peut invoquer :
Désactiver toutes les compétences en refusant l’outil Skill dans /permissions :
Skill(name) pour correspondance exacte, Skill(name *) pour correspondance de préfixe avec n’importe quels arguments.
Si votre règle deny nomme un alias ou un nom non qualifié plutôt que le nom propre de la compétence, Claude Code bloque toujours la compétence : avec Skill(review) il bloque la compétence groupée /code-review via son alias /review, et avec Skill(deploy) il bloque une compétence imbriquée listée comme apps/web:deploy via son nom non qualifié. Avant v2.1.260, Claude Code ne bloquait pas une compétence imbriquée listée sous son nom qualifié lorsque la règle deny nommait uniquement le nom non qualifié.
Claude Code correspond à une règle allow uniquement contre le nom propre de la compétence et le nom dans l’invocation de Claude.
Masquer les compétences individuelles en ajoutant disable-model-invocation: true à leur frontmatter. Cela supprime la compétence du contexte de Claude entièrement.
Avec
user-invocable: false, vous ne pouvez pas invoquer la compétence, mais Claude le peut. Pour empêcher Claude de l’invoquer via l’outil Skill, définissez disable-model-invocation: true.Remplacer la visibilité des compétences à partir des paramètres
Le paramètreskillOverrides contrôle la visibilité des compétences à partir de vos paramètres au lieu du frontmatter propre de la compétence. Utilisez-le pour les compétences dont SKILL.md vous ne voulez pas éditer, comme celles archivées dans un référentiel de projet partagé. Le menu /skills l’écrit pour vous : mettez en surbrillance une compétence et appuyez sur Space pour parcourir les états, puis Esc pour enregistrer dans .claude/settings.local.json.
Chaque clé est un nom de compétence et chaque valeur est l’un des quatre états :
Le menu
/skills étiquette l’état "user-invocable-only" user-only.
À partir de v2.1.199, "off" masque également la compétence des listes de commandes annoncées aux clients Remote Control et aux appelants Agent SDK, en plus du menu terminal /. Invoquer une compétence masquée par son nom complet retourne toujours l’erreur skillOverrides au lieu de l’exécuter.
Une compétence absente de skillOverrides est traitée comme "on". L’exemple ci-dessous réduit une compétence à son nom et en désactive une autre entièrement :
checkup pour /doctor. Si vous définissez une entrée skillOverrides sous un alias dans managed settings ou dans un fichier que vous transmettez avec le drapeau --settings, Claude Code l’applique à la compétence derrière l’alias. Vous ne pouvez restreindre une compétence que davantage via un alias, jamais la rendre plus visible, et si vous définissez également une entrée sous le nom propre de la compétence dans managed settings, cette entrée prend la priorité. Avant v2.1.260, Claude Code n’appliquait pas une entrée sous un alias à la compétence dans aucune source de paramètres.
Dans les paramètres utilisateur, projet et local, Claude Code correspond aux entrées uniquement contre les noms de compétences. Si vous définissez une entrée pour review là, elle s’applique à une compétence nommée review, pas à la compétence groupée /code-review via son alias /review.
Les compétences de plugin ne sont pas affectées par skillOverrides. Gérez-les via /plugin à la place.
Trouver les compétences inutilisées
Chaque compétence dans l’énumération des compétences ajoute à votre contexte à chaque tour, que Claude l’utilise ou non. Exécutez/skill-doctor pour voir ce que chacune de vos compétences coûte et à quelle fréquence elle est utilisée, afin que vous puissiez décider lesquelles désactiver. Dans une session interactive, le rapport s’ouvre dans l’onglet Stats du gestionnaire /plugin. En mode non-interactif avec -p, Claude Code l’imprime en tant que texte.
Le rapport couvre les compétences de votre session autres que les compétences groupées et les compétences d’entreprise. Il signale les compétences dans l’énumération qui n’ont jamais été invoquées et indique où les désactiver. Parmi les compétences qu’il vous dit où désactiver, commencez par celles qui ont le coût de contexte le plus élevé. Le rapport liste également les plugins que vous n’avez pas utilisés récemment.
/skill-doctor nécessite Claude Code v2.1.252 ou version ultérieure et n’est pas disponible dans les sessions qui ignorent feature-flag fetching. Si vous exécutez /skill-doctor sur Remote Control depuis votre téléphone ou navigateur, Claude Code répond Skill usage reports are not available on this connection. à la place. Exécutez /skill-doctor dans le terminal sur la machine où la session s’exécute.
Évaluer et itérer sur une compétence
Voir une compétence se déclencher vous indique que Claude l’a trouvée, pas qu’elle a fait ce que vous aviez l’intention. Pour savoir qu’une compétence fonctionne, mesurez séparément si Claude l’invoque sur les invites qu’elle devrait, et si la sortie correspond à ce que vous attendez quand elle le fait. La vérification des deux est une comparaison de base. Collectez quelques invites réalistes, exécutez chacune dans une session nouvelle avec la compétence disponible et à nouveau avec elle désactivée, et comparez les résultats. Une session nouvelle est importante car le contexte restant de la création de la compétence masquera les lacunes dans les instructions écrites. Deux outils automatisent cette comparaison. Pour une compétence qui est livrée dans un plugin,claude plugin eval exécute chaque invite dans une session isolée avec et sans le plugin, la note avec des évaluateurs que vous définissez ou qu’il écrit pour vous, et quitte avec un code non-zéro en dessous d’un seuil afin que vous puissiez gater CI sur celui-ci. Pour itérer sur une seule compétence à l’intérieur d’une conversation Claude Code, le plugin skill-creator ci-dessous exécute une boucle similaire avec son propre format evals/evals.json. Les deux formats ne sont pas interchangeables.
Exécuter des évaluations avec skill-creator
Le pluginskill-creator automatise la boucle de comparaison à l’intérieur de Claude Code. Installez-le depuis la marketplace officielle :
Marketplace "claude-plugins-official" not found: ajoutez la marketplace avec/plugin marketplace add anthropics/claude-plugins-official, puis réessayez l’installation.- Le plugin n’est pas trouvé dans la marketplace : vérifiez le nom du plugin.
Run /reload-plugins to activate., Claude Code exécute ensuite ce rechargement pour vous. Si le rechargement vous avertit que votre prochain message relierait la conversation, exécutez /reload-plugins --force pour rendre les compétences du plugin disponibles dans la session actuelle. Ensuite, demandez à Claude d’évaluer une compétence existante, par exemple evaluate my summarize-changes skill with skill-creator. Le plugin vous guide à travers l’écriture de cas de test et exécute la boucle :
- Cas de test : stocke les invites, les fichiers d’entrée et le comportement attendu dans
evals/evals.jsonà l’intérieur du répertoire de compétence - Exécutions isolées : génère un sous-agent par cas de test afin que chaque exécution commence avec un contexte propre, et enregistre le nombre de tokens et la durée
- Notation : vérifie chaque assertion par rapport à la sortie et écrit réussi ou échoué avec des preuves dans
grading.json - Benchmark : agrège le taux de réussite, le temps et les tokens pour avec-compétence par rapport à sans-compétence dans
benchmark.jsonafin que vous puissiez comparer l’amélioration du taux de réussite par rapport à la surcharge de tokens et de temps - Comparaison de versions : exécute un A/B en aveugle entre deux versions de la compétence afin que vous puissiez confirmer qu’une modification est une amélioration avant de la valider
- Ajustement de description : génère des invites should-trigger et should-not-trigger, mesure le taux de réussite, et propose des modifications de description quand la compétence s’active sur les mauvaises demandes
- Visionneuse d’examen : ouvre un rapport HTML où vous inspectez chaque sortie et enregistrez les commentaires qualitatifs que l’itération suivante lit
Partager des compétences
Les compétences peuvent être distribuées à différentes portées selon votre audience :- Compétences de projet : Validez
.claude/skills/dans le contrôle de version - Plugins : Créez un répertoire
skills/dans votre plugin - Gérées : Déployez à l’échelle de l’organisation via les paramètres gérés
Générer une sortie visuelle
Les compétences peuvent regrouper et exécuter des scripts dans n’importe quel langage, donnant à Claude des capacités au-delà de ce qui est possible dans une seule invite. Un modèle courant est la génération de sortie visuelle : des fichiers HTML interactifs qui s’ouvrent dans votre navigateur pour explorer les données, déboguer ou créer des rapports. Cet exemple crée un explorateur de base de code : une vue arborescente interactive où vous pouvez développer et réduire les répertoires, voir les tailles de fichiers en un coup d’œil et identifier les types de fichiers par couleur. Créez le répertoire Skill :~/.claude/skills/codebase-visualizer/SKILL.md. La description indique à Claude quand activer cette Skill, et les instructions indiquent à Claude d’exécuter le script fourni. Le chemin du script utilise ${CLAUDE_SKILL_DIR} pour qu’il se résolve correctement que la compétence soit installée au niveau personnel, du projet ou du plugin :
~/.claude/skills/codebase-visualizer/scripts/visualize.py. Ce script analyse une arborescence de répertoires et génère un fichier HTML autonome avec :
- Une barre latérale de résumé affichant le nombre de fichiers, le nombre de répertoires, la taille totale et le nombre de types de fichiers
- Un graphique en barres ventilant la base de code par type de fichier (top 8 par taille)
- Un arbre réductible où vous pouvez développer et réduire les répertoires, avec des indicateurs de type de fichier codés par couleur
Generated /path/to/codebase-map.html, et l’ouvre dans votre navigateur. Si vous travaillez dans un environnement sans interface graphique où aucun navigateur ne s’ouvre, le chemin affiché confirme que le script a réussi.
Ce modèle fonctionne pour toute sortie visuelle : graphiques de dépendances, rapports de couverture de test, documentation API ou visualisations de schémas de base de données. Le script fourni fait le travail tandis que Claude gère l’orchestration.
Dépannage
La compétence ne se déclenche pas
Si Claude n’utilise pas votre compétence quand prévu :- Vérifiez que la description inclut les mots-clés que les utilisateurs diraient naturellement
- Vérifiez que la compétence apparaît dans
What skills are available? - Essayez de reformuler votre demande pour correspondre plus étroitement à la description
- Invoquez-la directement avec
/skill-namesi la compétence est invocable par l’utilisateur
/skill-name fonctionne toujours mais Claude ne peut pas faire correspondre votre description. Exécutez avec --debug pour voir l’erreur d’analyse.
Si la compétence est fournie dans un plugin, vous pouvez mesurer la fréquence à laquelle elle se déclenche sur des invites réalistes plutôt que de vérifier une par une : écrivez un cas d’évaluation avec un évaluateur tool_used: Skill et exécutez-le avec claude plugin eval après chaque modification de description.
Pour trouver les fichiers SKILL.md dont le frontmatter ne s’analyse pas, exécutez claude plugin validate sur le répertoire des compétences, par exemple claude plugin validate .claude/skills pour les compétences du projet ou claude plugin validate ~/.claude/skills pour les compétences personnelles. Nécessite Claude Code v2.1.233 ou ultérieur.
La compétence se déclenche trop souvent
Si Claude utilise votre compétence quand vous ne le souhaitez pas :- Rendez la description plus spécifique
- Ajoutez
disable-model-invocation: truesi vous ne voulez que l’invocation manuelle
Les descriptions de compétences sont tronquées
Claude Code charge une liste de noms et descriptions de compétences dans le contexte pour que Claude sache ce qui est disponible. La liste contient toujours tous les noms de compétences, mais si vous avez de nombreuses compétences, Claude Code raccourcit les descriptions pour s’adapter au budget de caractères de la liste, ce qui peut supprimer les mots-clés dont Claude a besoin pour faire correspondre votre demande. Le budget s’adapte à 1 % de la fenêtre de contexte du modèle. Quand la liste dépasse le budget, Claude Code supprime les descriptions en commençant par les compétences que vous invoquez le moins, de sorte que les compétences que vous utilisez le plus conservent leur texte complet. Exécutez/doctor pour une estimation du coût contextuel de la liste et de ses plus grands contributeurs. Pour trouver les compétences qui valent la peine d’être désactivées, exécutez /skill-doctor. Quand la liste dépasse son budget, Claude Code écrit également un avertissement dans le journal de débogage, visible avec --debug.
La ligne Skills dans /context rapporte la taille de la liste après l’application du budget, de sorte qu’elle correspond à ce que le modèle reçoit. Avant v2.1.196, la ligne comptait le texte complet de chaque description et pouvait afficher une valeur plusieurs fois plus grande que le budget configuré.
Pour augmenter le budget, définissez le paramètre skillListingBudgetFraction (par exemple 0.02 = 2 %) ou la variable d’environnement SLASH_COMMAND_TOOL_CHAR_BUDGET sur un nombre de caractères fixe. Pour libérer du budget pour d’autres compétences, définissez les entrées de faible priorité sur "name-only" dans skillOverrides afin qu’elles s’affichent sans description. Vous pouvez également réduire le texte description et when_to_use à la source : mettez le cas d’utilisation clé en premier, car le texte combiné de chaque entrée est limité à 1 536 caractères quel que soit le budget. Le plafond est configurable avec skillListingMaxDescChars.
Les compétences personnelles ont disparu
Si les dossiers de compétences que vous avez créés dans~/.claude/skills/ ont disparu, regardez dans ~/.claude/skills/.trash/. Quand Claude Code synchronise les compétences depuis claude.ai, il les télécharge dans le sous-dossier synced séparé et ne déplace ni ne supprime les dossiers que vous créez.
Avant v2.1.280, un fichier nommé manifest.json dans ~/.claude/skills/ causait à Claude Code de déplacer les dossiers de compétences que ce fichier listait dans un dossier horodaté sous ~/.claude/skills/.trash/, et ces compétences cessaient de se charger.
Pour restaurer une compétence, déplacez son dossier du dossier horodaté vers ~/.claude/skills/. Faites cela avant que le balayage de rétention supprime les entrées de la corbeille, par défaut 30 jours après leur déplacement vers la corbeille.
Ressources connexes
- Déboguer votre configuration : diagnostiquer pourquoi une skill n’apparaît pas ou ne se déclenche pas
- Évaluer la qualité de la sortie de la skill : le format du fichier eval et le flux de travail d’itération sur agentskills.io
- Meilleures pratiques de création de skills : conseils de rédaction qui s’appliquent à tous les produits Claude
- Subagents : déléguer les tâches à des agents spécialisés
- Plugins : empaqueter et distribuer les skills avec d’autres extensions
- Hooks : automatiser les workflows autour des événements d’outils
- Memory : gérer les fichiers CLAUDE.md pour le contexte persistant
- Commands : référence pour les commandes intégrées et les skills groupées
- Permissions : contrôler l’accès aux outils et aux skills
- Claude Tag skills : les skills de projet validées dans un repo se chargent également lorsque ce repo est utilisé dans un canal Claude Tag