Prérequis
- Claude Code version 1.0 ou ultérieure
- Familiarité de base avec Claude Code
Qu’est-ce que les compétences d’agent ?
Les compétences d’agent regroupent l’expertise en capacités découvrables. Chaque compétence se compose d’un fichierSKILL.md avec des instructions que Claude lit si pertinent, plus des fichiers de support optionnels comme des scripts et des modèles.
Comment les compétences sont invoquées : Les compétences sont invoquées par le modèle—Claude décide de manière autonome quand les utiliser en fonction de votre demande et de la description de la compétence. C’est différent des commandes slash, qui sont invoquées par l’utilisateur (vous tapez explicitement /command pour les déclencher).
Avantages :
- Étendre les capacités de Claude pour vos flux de travail spécifiques
- Partager l’expertise dans votre équipe via git
- Réduire les invites répétitives
- Composer plusieurs compétences pour des tâches complexes
Pour une plongée approfondie dans l’architecture et les applications réelles des compétences d’agent, lisez notre blog d’ingénierie : Équiper les agents pour le monde réel avec les compétences d’agent.
Créer une compétence
Les compétences sont stockées sous forme de répertoires contenant un fichierSKILL.md.
Compétences personnelles
Les compétences personnelles sont disponibles dans tous vos projets. Stockez-les dans~/.claude/skills/ :
- Vos flux de travail et préférences individuels
- Les compétences expérimentales que vous développez
- Les outils de productivité personnels
Compétences de projet
Les compétences de projet sont partagées avec votre équipe. Stockez-les dans.claude/skills/ dans votre projet :
- Les flux de travail et conventions d’équipe
- L’expertise spécifique au projet
- Les utilitaires et scripts partagés
Compétences de plugin
Les compétences peuvent également provenir de plugins Claude Code. Les plugins peuvent regrouper des compétences qui sont automatiquement disponibles lors de l’installation du plugin. Ces compétences fonctionnent de la même manière que les compétences personnelles et de projet.Écrire SKILL.md
Créez un fichierSKILL.md avec un préambule YAML et du contenu Markdown :
name: Doit utiliser uniquement des lettres minuscules, des chiffres et des tirets (64 caractères maximum)description: Brève description de ce que fait la compétence et quand l’utiliser (1024 caractères maximum)
description est essentiel pour que Claude découvre quand utiliser votre compétence. Il doit inclure à la fois ce que fait la compétence et quand Claude devrait l’utiliser.
Consultez le guide des meilleures pratiques pour des conseils complets sur la création, y compris les règles de validation.
Ajouter des fichiers de support
Créez des fichiers supplémentaires à côté de SKILL.md :Restreindre l’accès aux outils avec allowed-tools
Utilisez le champ de préambuleallowed-tools pour limiter les outils que Claude peut utiliser quand une compétence est active :
- Les compétences en lecture seule qui ne doivent pas modifier les fichiers
- Les compétences avec une portée limitée (par exemple, uniquement l’analyse de données, pas d’écriture de fichiers)
- Les flux de travail sensibles à la sécurité où vous voulez restreindre les capacités
allowed-tools n’est pas spécifié, Claude demandera la permission d’utiliser les outils normalement, en suivant le modèle de permission standard.
allowed-tools n’est supporté que pour les compétences dans Claude Code.Afficher les compétences disponibles
Les compétences sont automatiquement découvertes par Claude à partir de trois sources :- Compétences personnelles :
~/.claude/skills/ - Compétences de projet :
.claude/skills/ - Compétences de plugin : regroupées avec les plugins installés
Tester une compétence
Après avoir créé une compétence, testez-la en posant des questions qui correspondent à votre description. Exemple : Si votre description mentionne « fichiers PDF » :Déboguer une compétence
Si Claude n’utilise pas votre compétence, vérifiez ces problèmes courants :Rendre la description spécifique
Trop vague :Vérifier le chemin du fichier
Compétences personnelles :~/.claude/skills/skill-name/SKILL.md
Compétences de projet : .claude/skills/skill-name/SKILL.md
Vérifiez que le fichier existe :
Vérifier la syntaxe YAML
Une syntaxe YAML invalide empêche le chargement de la compétence. Vérifiez le préambule :- L’ouverture
---est à la ligne 1 - La fermeture
---est avant le contenu Markdown - La syntaxe YAML est valide (pas de tabulations, indentation correcte)
Afficher les erreurs
Exécutez Claude Code en mode débogage pour voir les erreurs de chargement des compétences :Partager les compétences avec votre équipe
Approche recommandée : Distribuez les compétences via plugins. Pour partager les compétences via un plugin :- Créez un plugin avec des compétences dans le répertoire
skills/ - Ajoutez le plugin à une marketplace
- Les membres de l’équipe installent le plugin
Étape 1 : Ajouter la compétence à votre projet
Créez une compétence de projet :Étape 2 : Valider dans git
Étape 3 : Les membres de l’équipe obtiennent les compétences automatiquement
Quand les membres de l’équipe tirent les dernières modifications, les compétences sont immédiatement disponibles :Mettre à jour une compétence
Modifiez SKILL.md directement :Supprimer une compétence
Supprimez le répertoire de la compétence :Meilleures pratiques
Garder les compétences ciblées
Une compétence doit traiter une capacité : Ciblée :- « Remplissage de formulaires PDF »
- « Analyse de données Excel »
- « Messages de commit Git »
- « Traitement de documents » (diviser en compétences séparées)
- « Outils de données » (diviser par type de données ou opération)
Écrire des descriptions claires
Aidez Claude à découvrir quand utiliser les compétences en incluant des déclencheurs spécifiques dans votre description : Clair :Tester avec votre équipe
Faites utiliser les compétences par vos coéquipiers et recueillez leurs commentaires :- La compétence s’active-t-elle comme prévu ?
- Les instructions sont-elles claires ?
- Y a-t-il des exemples manquants ou des cas limites ?
Documenter les versions des compétences
Vous pouvez documenter les versions des compétences dans le contenu de votre SKILL.md pour suivre les modifications au fil du temps. Ajoutez une section d’historique des versions :Dépannage
Claude n’utilise pas ma compétence
Symptôme : Vous posez une question pertinente mais Claude n’utilise pas votre compétence. Vérifier : La description est-elle assez spécifique ? Les descriptions vagues rendent la découverte difficile. Incluez à la fois ce que fait la compétence et quand l’utiliser, avec les termes clés que les utilisateurs mentionneraient. Trop générique :La compétence a des erreurs
Symptôme : La compétence se charge mais ne fonctionne pas correctement. Vérifier : Les dépendances sont-elles disponibles ? Claude installera automatiquement les dépendances requises (ou demandera la permission de les installer) quand il en aura besoin. Vérifier : Les scripts ont-ils les permissions d’exécution ?scripts/helper.py
Incorrect : scripts\helper.py (style Windows)
Plusieurs compétences en conflit
Symptôme : Claude utilise la mauvaise compétence ou semble confus entre des compétences similaires. Soyez spécifique dans les descriptions : Aidez Claude à choisir la bonne compétence en utilisant des termes de déclenchement distincts dans vos descriptions. Au lieu de :Exemples
Compétence simple (fichier unique)
Compétence avec permissions d’outils
Compétence multi-fichiers
Listez les packages requis dans la description. Les packages doivent être installés dans votre environnement avant que Claude puisse les utiliser.
Étapes suivantes
Meilleures pratiques de création
Écrivez des compétences que Claude peut utiliser efficacement
Aperçu des compétences d'agent
Découvrez comment les compétences fonctionnent dans les produits Claude
Utiliser les compétences dans l'Agent SDK
Utilisez les compétences par programmation avec TypeScript et Python
Commencer avec les compétences d'agent
Créez votre première compétence