Tutoriel officiel sur les compétences d'agent d'Anthropic : notes complètes sur le cours en 6 leçons

Anthropic a enfin publié un tutoriel vidéo officiel sur les compétences des agents, composé de 6 leçons d'une durée totale de 22 minutes. Il couvre l'ensemble du cycle de vie des compétences, de leur définition à leur création, en passant par la configuration de fichiers multiples, la distinction avec d'autres fonctionnalités, le partage et le dépannage.

La plus grande valeur de ce tutoriel n'est pas seulement de vous apprendre à rédiger une compétence, mais d'expliquer la philosophie de conception et les mécanismes sous-jacents des compétences. De nombreux problèmes rencontrés lors de l'utilisation des compétences proviennent d'une compréhension insuffisante de ces mécanismes.

Quels problèmes les compétences résolvent-elles ?

Chaque fois que vous expliquez les normes de codage de votre équipe à Claude, vous vous répétez. À chaque révision de PR, vous devez redécrire comment vous souhaitez que les retours soient organisés. À chaque message de commit, vous devez rappeler à Claude votre format préféré.

Les compétences sont conçues pour éliminer cette répétition. Une compétence est un fichier Markdown qui apprend à Claude comment faire quelque chose une fois, et Claude applique automatiquement ces connaissances dans les situations pertinentes.

Plus précisément, une compétence d'agent est un dossier contenant des instructions, des scripts et des ressources. Claude peut automatiquement les découvrir et les utiliser pour accomplir le travail avec plus de précision et d'efficacité.

Le mécanisme central est le champ description. Lorsque Claude démarre, il charge les noms et les descriptions de toutes les compétences. Lorsque vous faites une demande, Claude effectue une correspondance sémantique entre votre demande et les descriptions de toutes les compétences disponibles pour trouver et activer celle qui correspond. Ce n'est qu'après activation que le contenu complet de la compétence est chargé dans la fenêtre de contexte.

Cela est fondamentalement différent de claude.md. Le contenu de claude.md est chargé dans chaque conversation, quelle que soit l'activité en cours. Une compétence n'est chargée qu'en cas de besoin ; votre liste de contrôle de révision de PR n'a pas besoin d'être dans le contexte pendant le débogage, elle n'apparaît que lorsque vous demandez réellement une révision.

Quand utiliser une compétence ? Si vous vous surprenez à répéter la même chose à Claude, c'est une compétence en devenir.

Créer votre première compétence à partir de zéro

Créer une compétence ne nécessite que deux étapes : créer un répertoire et écrire un fichier.

Première étape : Créez un répertoire nommé d'après la compétence sous ~/.claude/skills/. Le placer ici signifie qu'il s'agit d'une compétence au niveau personnel, disponible dans tous les projets.

Deuxième étape : Créez un fichier SKILL.md dans le répertoire. Le fichier est divisé en deux parties, séparées par trois tirets. La partie supérieure est constituée de métadonnées YAML contenant name et description. La partie inférieure contient les instructions spécifiques que Claude doit suivre.

Lorsque Claude Code démarre, il analyse quatre emplacements pour les compétences : les chemins d'entreprise, le répertoire des compétences personnelles, le répertoire des compétences du projet et les plugins installés. Il ne charge que le nom et la description de chaque compétence, pas le contenu complet.

Lorsque vous envoyez une demande, Claude compare la demande avec toutes les descriptions de compétences. Si l'intention correspond, il vous demandera d'abord de confirmer si vous souhaitez charger la compétence. Ce n'est qu'après confirmation qu'il lit le fichier complet et exécute les instructions. Cette étape de confirmation vous permet de savoir quel contexte Claude utilise.

Si des compétences portant le même nom existent, la priorité, de la plus haute à la plus basse, est : Niveau entreprise (managed-settings.json), Niveau personnel (~/.claude/skills), Niveau projet (project/.claude/skills) et Niveau plugin (project/.claude-plugins/skills).

Cela signifie qu'une entreprise peut imposer des normes via des compétences au niveau de l'entreprise tout en permettant aux individus de personnaliser via des compétences avec des noms différents. Si votre entreprise dispose d'une compétence de révision de code d'entreprise, vous pouvez créer une compétence personnelle appelée front-end-pr-review pour la compléter plutôt que de l'écraser.

Configuration avancée : champs de métadonnées et divulgation progressive

Les compétences de base n'ont besoin que de name et description, mais plusieurs configurations avancées peuvent rendre les compétences plus puissantes.

Le champ allowed-tools peut limiter les outils que Claude peut utiliser lorsque la compétence est active. Par exemple, si vous avez une compétence d'analyse en lecture seule, vous pouvez interdire les commandes d'édition, d'écriture et Bash. Si ce champ est omis, la compétence n'impose aucune restriction et Claude utilise le modèle d'autorisation normal.

Le champ model peut spécifier la version du modèle Claude à utiliser.

La façon dont la description est rédigée détermine directement si une compétence peut être correctement déclenchée. Une bonne description doit répondre à deux questions : Que fait cette compétence ? Quand Claude doit-il l'utiliser ? Si une compétence ne se déclenche pas, ajoutez plus de mots-clés qui correspondent au libellé de vos demandes.

Le concept avancé le plus important est la divulgation progressive. Les compétences partagent la fenêtre de contexte avec votre conversation. Si vous entassez tout dans un fichier SKILL.md de 20 000 lignes, cela consommera un espace de contexte massif.

L'approche correcte est la suivante : placez les instructions essentielles dans SKILL.md et les documents de référence détaillés dans des fichiers séparés, que Claude ne lit qu'en cas de besoin. La structure de répertoire recommandée pour les normes ouvertes est : un dossier scripts pour le code exécutable, references pour les documents de référence et resources pour les fichiers de données comme les images et les modèles. Utilisez des liens dans SKILL.md pour référencer ces fichiers.

Règle clé : SKILL.md ne doit pas dépasser 500 lignes. Si c'est le cas, il doit être divisé. Les scripts peuvent être exécutés directement sans charger leur contenu dans le contexte ; seule la sortie consomme des jetons. Alors, dites à Claude d'exécuter le script plutôt que de le lire. Ceci est particulièrement utile pour la validation de l'environnement et la transformation des données, car le code de script testé est plus fiable que la génération à la volée.

Différences entre les compétences et les autres fonctionnalités de Claude Code

Compétences vs. claude.md : claude.md est toujours chargé dans chaque conversation pour les normes et règles de projet qui s'appliquent toujours, comme "Ce projet utilise le mode strict TypeScript." Les compétences sont chargées à la demande, activées uniquement lorsque Claude correspond à une demande.

Compétences vs. Sous-agents : Les compétences ajoutent des connaissances à la conversation en cours ; une fois activées, les instructions sont ajoutées au contexte existant. Les sous-agents s'exécutent dans un contexte indépendant, accomplissant des tâches et soumettant les résultats séparément, complètement isolés de la conversation principale.

Compétences vs. Hooks : Les hooks sont pilotés par les événements, se déclenchant lorsque des événements spécifiques se produisent, par exemple Claude exécutant un Linter chaque fois qu'un fichier est enregistré. Les compétences sont pilotées par les demandes, s'activant en fonction des questions que vous posez.

Compétences vs. MCP : MCP fournit des connexions à des outils externes, permettant à Claude d'appeler des services comme Gmail ou Notion. Les compétences fournissent des connaissances et des flux de travail, indiquant à Claude comment utiliser ces outils pour effectuer des tâches spécifiques.

Résumé en une phrase : claude.md contient des instructions toujours actives, les compétences contiennent une expertise à correspondance automatique, les sous-agents exécutent des tâches déléguées dans des contextes isolés, les hooks répondent aux événements et MCP se connecte à des outils externes. Ils peuvent être utilisés en combinaison.

Partager les compétences : des individus aux équipes en passant par les organisations

La valeur des compétences réside dans le partage. Une compétence de révision de PR utilisée uniquement par vous-même est utile, mais une compétence partagée par l'équipe peut normaliser les révisions de code et offrir une expérience cohérente.

Trois façons de partager :

La première est le répertoire du projet. Validez la compétence dans le répertoire .claude/skills du dépôt de code. Quiconque clone le dépôt obtient automatiquement ces compétences sans installation supplémentaire. Les mises à jour sont reçues lors du prochain pull. Ceci est adapté aux normes de codage de l'équipe et aux flux de travail spécifiques au projet.

La deuxième est les plugins. Considérez les plugins comme un moyen de distribuer des compétences entre les projets. Une fois téléchargé sur une boutique d'applications, d'autres utilisateurs peuvent les télécharger et les installer. Si votre compétence est générique et non spécifique à un projet, c'est le meilleur choix pour les membres de la communauté.

La troisième est le déploiement en entreprise. Les administrateurs poussent les compétences vers l'ensemble de l'organisation via les paramètres gérés. Les compétences au niveau de l'entreprise ont la priorité la plus élevée et écraseront les compétences personnelles et de projet portant le même nom. Ceci est utilisé pour les normes obligatoires, les exigences de sécurité et les flux de travail de conformité.

Une note importante : les sous-agents n'héritent pas automatiquement de vos compétences. Lorsque vous déléguez une tâche à un sous-agent, il démarre avec un contexte vierge. Les agents intégrés (Explorer, Plan, Verify) ne peuvent pas du tout accéder aux compétences ; seuls les sous-agents personnalisés que vous définissez peuvent les utiliser, et ils doivent être explicitement listés dans agent.md.

Pour créer un sous-agent personnalisé avec des compétences, créez un fichier agent.md dans le répertoire .claude/agents et ajoutez un champ skills listant les noms de compétences requis. Ne listez que les compétences qui sont toujours pertinentes pour l'objectif du sous-agent, car ces compétences seront chargées au démarrage du sous-agent.

Guide de dépannage : six raisons pour lesquelles les compétences échouent et leurs solutions

Les problèmes de compétences relèvent généralement de six catégories :

1. La compétence ne se déclenche pas : La raison est presque toujours une description mal rédigée. Claude utilise la correspondance sémantique ; votre demande doit s'aligner sur le sens de la description. S'il n'y a pas assez de chevauchement, elle ne correspondra pas. Solution : Comparez la description avec le libellé de votre demande et ajoutez des phrases de déclenchement que les utilisateurs disent réellement, comme "aide-moi à analyser", "pourquoi est-ce lent" ou "accélère ça".

1. La compétence ne se charge pas : Vérifiez les chemins et les noms de fichiers. SKILL.md doit être à l'intérieur d'un répertoire nommé, pas directement dans la racine des compétences. Le nom du fichier doit être exactement SKILL.md en majuscules. Exécutez claude --debug pour voir les erreurs de chargement.

1. Claude utilise la mauvaise compétence : Cela signifie que vous avez plusieurs compétences avec des descriptions trop similaires, ce qui empêche Claude de les distinguer. Solution : Rendez chaque description aussi spécifique que possible pour aider Claude à décider quand utiliser laquelle.

1. La compétence personnelle est ignorée : Une compétence de priorité plus élevée (comme une compétence d'entreprise) portant le même nom pourrait l'écraser. Vérifiez les quatre niveaux de priorité. Solution : Renommez votre compétence avec un nom plus unique.

1. Plugin installé mais compétence non visible : Videz le cache avec rm ~/.claude/plugins/cache, redémarrez Claude Code et réinstallez. Si cela ne fonctionne toujours pas, la structure du répertoire du plugin est peut-être erronée ; utilisez l'outil de validation skills-ref validate pour vérifier.

1. Compétence chargée mais échouant lors de l'exécution : Si la compétence utilise des packages externes, assurez-vous qu'ils sont installés. Ajoutez les informations de dépendance à la description de la compétence.

Anthropic fournit également un outil de validation appelé skills-ref pour vérifier si la structure du fichier de la compétence et la syntaxe YAML sont correctes. Il est recommandé de l'installer via uv pour la méthode la plus rapide.