Ce guide vous montre comment créer, utiliser et gérer les Compétences d’Agent dans Claude Code. Les Compétences sont des capacités modulaires qui étendent les fonctionnalités de Claude grâce à des dossiers organisés contenant des instructions, des scripts et des ressources.

​
Prérequis

  • Claude Code version 1.0 ou ultérieure
  • Familiarité de base avec Claude Code

​
Que sont les Compétences d’Agent ?

Les Compétences d’Agent regroupent l’expertise en capacités découvrables. Chaque Compétence consiste en un fichier SKILL.md avec des instructions que Claude lit lorsque c’est 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 /commande pour les déclencher). Avantages :
  • Étendre les capacités de Claude pour vos flux de travail spécifiques
  • Partager l’expertise au sein de votre équipe via git
  • Réduire les invites répétitives
  • Composer plusieurs Compétences pour des tâches complexes
En savoir plus dans l’aperçu des Compétences d’Agent.
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 fichier SKILL.md.

​
Compétences Personnelles

Les Compétences Personnelles sont disponibles dans tous vos projets. Stockez-les dans ~/.claude/skills/ : 
mkdir -p ~/.claude/skills/mon-nom-de-competence
Utilisez les Compétences personnelles pour :
  • Vos flux de travail et préférences individuels
  • Les Compétences expérimentales que vous développez
  • Les outils de productivité personnelle

​
Compétences de Projet

Les Compétences de Projet sont partagées avec votre équipe. Stockez-les dans .claude/skills/ au sein de votre projet : 
mkdir -p .claude/skills/mon-nom-de-competence
Utilisez les Compétences de projet pour :
  • Les flux de travail et conventions d’équipe
  • L’expertise spécifique au projet
  • Les utilitaires et scripts partagés
Les Compétences de Projet sont enregistrées dans git et automatiquement disponibles pour les membres de l’équipe.

​
Compétences de Plugin

Les Compétences peuvent également provenir des plugins Claude Code. Les plugins peuvent regrouper des Compétences qui sont automatiquement disponibles lorsque le plugin est installé. Ces Compétences fonctionnent de la même manière que les Compétences personnelles et de projet.

​
Écrire SKILL.md

Créez un fichier SKILL.md avec un frontmatter YAML et du contenu Markdown : 
---
name: Nom de Votre Compétence
description: Brève description de ce que fait cette Compétence et quand l'utiliser
---

# Nom de Votre Compétence

## Instructions
Fournissez des conseils clairs et étape par étape pour Claude.

## Exemples
Montrez des exemples concrets d'utilisation de cette Compétence.
Le champ description est critique pour que Claude découvre quand utiliser votre Compétence. Il devrait inclure à la fois ce que fait la Compétence et quand Claude devrait l’utiliser. Voir le guide des meilleures pratiques pour des conseils complets de rédaction.

​
Ajouter des fichiers de support

Créez des fichiers supplémentaires à côté de SKILL.md : 
ma-competence/
├── SKILL.md (requis)
├── reference.md (documentation optionnelle)
├── examples.md (exemples optionnels)
├── scripts/
│   └── helper.py (utilitaire optionnel)
└── templates/
    └── template.txt (modèle optionnel)
Référencez ces fichiers depuis SKILL.md : 
Pour une utilisation avancée, voir [reference.md](reference.md).

Exécutez le script d'aide :
```bash
python scripts/helper.py input.txt
```
Claude lit ces fichiers seulement quand c’est nécessaire, utilisant la divulgation progressive pour gérer le contexte efficacement.

​
Restreindre l’accès aux outils avec allowed-tools

Utilisez le champ frontmatter allowed-tools pour limiter quels outils Claude peut utiliser lorsqu’une Compétence est active : 
---
name: Lecteur de Fichier Sécurisé
description: Lire des fichiers sans apporter de modifications. Utilisez quand vous avez besoin d'un accès en lecture seule aux fichiers.
allowed-tools: Read, Grep, Glob
---

# Lecteur de Fichier Sécurisé

Cette Compétence fournit un accès en lecture seule aux fichiers.

## Instructions
1. Utilisez Read pour voir le contenu des fichiers
2. Utilisez Grep pour rechercher dans les fichiers
3. Utilisez Glob pour trouver des fichiers par motif
Lorsque cette Compétence est active, Claude ne peut utiliser que les outils spécifiés (Read, Grep, Glob) sans avoir besoin de demander la permission. C’est utile pour :
  • Les Compétences en lecture seule qui ne devraient pas modifier les fichiers
  • Les Compétences avec une portée limitée (par exemple, seulement 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
Si allowed-tools n’est pas spécifié, Claude demandera la permission d’utiliser les outils comme d’habitude, suivant le modèle de permission standard.
allowed-tools n’est supporté que pour les Compétences dans Claude Code.

​
Voir 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
Pour voir toutes les Compétences disponibles, demandez directement à Claude : 
Quelles Compétences sont disponibles ?
ou 
Liste toutes les Compétences disponibles
Cela montrera toutes les Compétences de toutes les sources, y compris les Compétences de plugin. Pour inspecter une Compétence spécifique, vous pouvez également vérifier le système de fichiers : 
# Lister les Compétences personnelles
ls ~/.claude/skills/

# Lister les Compétences de projet (si dans un répertoire de projet)
ls .claude/skills/

# Voir le contenu d'une Compétence spécifique
cat ~/.claude/skills/ma-competence/SKILL.md

​
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” : 
Pouvez-vous m'aider à extraire du texte de ce PDF ?
Claude décide de manière autonome d’utiliser votre Compétence si elle correspond à la demande—vous n’avez pas besoin de l’invoquer explicitement. La Compétence s’active automatiquement en fonction du contexte de votre question.

​
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 : 
description: Aide avec les documents
Spécifique : 
description: Extraire du texte et des tableaux des fichiers PDF, remplir des formulaires, fusionner des documents. Utilisez lors du travail avec des fichiers PDF ou lorsque l'utilisateur mentionne des PDF, des formulaires ou l'extraction de documents.
Incluez à la fois ce que fait la Compétence et quand l’utiliser dans la description.

​
Vérifier le chemin du fichier

Compétences Personnelles : ~/.claude/skills/nom-competence/SKILL.md Compétences de Projet : .claude/skills/nom-competence/SKILL.md Vérifiez que le fichier existe : 
# Personnel
ls ~/.claude/skills/ma-competence/SKILL.md

# Projet
ls .claude/skills/ma-competence/SKILL.md

​
Vérifier la syntaxe YAML

Un YAML invalide empêche le chargement de la Compétence. Vérifiez le frontmatter : 
cat SKILL.md | head -n 10
Assurez-vous :
  • --- d’ouverture sur la ligne 1
  • --- de fermeture avant le contenu Markdown
  • Syntaxe YAML valide (pas de tabulations, indentation correcte)

​
Voir les erreurs

Exécutez Claude Code avec le mode debug pour voir les erreurs de chargement des Compétences : 
claude --debug

​
Partager les Compétences avec votre équipe

Approche recommandée : Distribuez les Compétences via des plugins. Pour partager des Compétences via plugin :
  1. Créez un plugin avec des Compétences dans le répertoire skills/
  2. Ajoutez le plugin à un marketplace
  3. Les membres de l’équipe installent le plugin
Pour des instructions complètes, voir Ajouter des Compétences à votre plugin. Vous pouvez également partager des Compétences directement via les dépôts de projet :

​
Étape 1 : Ajouter une Compétence à votre projet

Créez une Compétence de projet : 
mkdir -p .claude/skills/competence-equipe
# Créer SKILL.md

​
Étape 2 : Valider dans git

git add .claude/skills/
git commit -m "Ajouter une Compétence d'équipe pour le traitement PDF"
git push

​
Étape 3 : Les membres de l’équipe obtiennent les Compétences automatiquement

Lorsque les membres de l’équipe tirent les derniers changements, les Compétences sont immédiatement disponibles : 
git pull
claude  # Les Compétences sont maintenant disponibles

​
Mettre à jour une Compétence

Éditez SKILL.md directement : 
# Compétence Personnelle
code ~/.claude/skills/ma-competence/SKILL.md

# Compétence de Projet
code .claude/skills/ma-competence/SKILL.md
Les changements prennent effet la prochaine fois que vous démarrez Claude Code. Si Claude Code est déjà en cours d’exécution, redémarrez-le pour charger les mises à jour.

​
Supprimer une Compétence

Supprimez le répertoire de la Compétence : 
# Personnel
rm -rf ~/.claude/skills/ma-competence

# Projet
rm -rf .claude/skills/ma-competence
git commit -m "Supprimer une Compétence inutilisée"

​
Meilleures pratiques

​
Garder les Compétences focalisées

Une Compétence devrait adresser une capacité : Focalisé :
  • “Remplissage de formulaires PDF”
  • “Analyse de données Excel”
  • “Messages de commit Git”
Trop large :
  • “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 : 
description: Analyser les feuilles de calcul Excel, créer des tableaux croisés dynamiques et générer des graphiques. Utilisez lors du travail avec des fichiers Excel, des feuilles de calcul ou l'analyse de données tabulaires au format .xlsx.
Vague : 
description: Pour les fichiers

​
Tester avec votre équipe

Demandez aux coéquipiers d’utiliser les Compétences et de fournir des commentaires :
  • La Compétence s’active-t-elle quand attendu ?
  • 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 votre contenu SKILL.md pour suivre les changements au fil du temps. Ajoutez une section d’historique des versions : 
# Ma Compétence

## Historique des Versions
- v2.0.0 (2025-10-01) : Changements cassants à l'API
- v1.1.0 (2025-09-15) : Ajout de nouvelles fonctionnalités
- v1.0.0 (2025-09-01) : Version initiale
Cela aide les membres de l’équipe à comprendre ce qui a changé entre les 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érifiez : 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 des termes clés que les utilisateurs mentionneraient. Trop générique : 
description: Aide avec les données
Spécifique : 
description: Analyser les feuilles de calcul Excel, générer des tableaux croisés dynamiques, créer des graphiques. Utilisez lors du travail avec des fichiers Excel, des feuilles de calcul ou des fichiers .xlsx.
Vérifiez : Le YAML est-il valide ? Exécutez une validation pour vérifier les erreurs de syntaxe : 
# Voir le frontmatter
cat .claude/skills/ma-competence/SKILL.md | head -n 15

# Vérifier les problèmes courants
# - --- d'ouverture ou de fermeture manquant
# - Tabulations au lieu d'espaces
# - Chaînes non quotées avec des caractères spéciaux
Vérifiez : La Compétence est-elle dans le bon emplacement ? 
# Compétences Personnelles
ls ~/.claude/skills/*/SKILL.md

# Compétences de Projet
ls .claude/skills/*/SKILL.md

​
La Compétence a des erreurs

Symptôme : La Compétence se charge mais ne fonctionne pas correctement. Vérifiez : Les dépendances sont-elles disponibles ? Claude installera automatiquement les dépendances requises (ou demandera la permission de les installer) quand il en a besoin. Vérifiez : Les scripts ont-ils les permissions d’exécution ? 
chmod +x .claude/skills/ma-competence/scripts/*.py
Vérifiez : Les chemins de fichiers sont-ils corrects ? Utilisez des barres obliques (style Unix) dans tous les chemins : Correct : scripts/helper.py Incorrect : scripts\helper.py (style Windows)

​
Plusieurs Compétences entrent 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 déclencheurs distincts dans vos descriptions. Au lieu de : 
# Compétence 1
description: Pour l'analyse de données

# Compétence 2
description: Pour analyser les données
Utilisez : 
# Compétence 1
description: Analyser les données de ventes dans les fichiers Excel et les exports CRM. Utilisez pour les rapports de ventes, l'analyse de pipeline et le suivi des revenus.

# Compétence 2
description: Analyser les fichiers de logs et les données de métriques système. Utilisez pour la surveillance des performances, le débogage et les diagnostics système.

​
Exemples

​
Compétence Simple (fichier unique)

commit-helper/
└── SKILL.md

---
name: Génération de Messages de Commit
description: Génère des messages de commit clairs à partir des diffs git. Utilisez lors de l'écriture de messages de commit ou de la révision des changements mis en scène.
---

# Génération de Messages de Commit

## Instructions

1. Exécutez `git diff --staged` pour voir les changements
2. Je suggérerai un message de commit avec :
   - Résumé sous 50 caractères
   - Description détaillée
   - Composants affectés

## Meilleures pratiques

- Utilisez le présent
- Expliquez quoi et pourquoi, pas comment

​
Compétence avec permissions d’outils

code-reviewer/
└── SKILL.md

---
name: Réviseur de Code
description: Réviser le code pour les meilleures pratiques et les problèmes potentiels. Utilisez lors de la révision de code, de la vérification des PR ou de l'analyse de la qualité du code.
allowed-tools: Read, Grep, Glob
---

# Réviseur de Code

## Liste de vérification de révision

1. Organisation et structure du code
2. Gestion des erreurs
3. Considérations de performance
4. Préoccupations de sécurité
5. Couverture des tests

## Instructions

1. Lire les fichiers cibles en utilisant l'outil Read
2. Rechercher des motifs en utilisant Grep
3. Trouver des fichiers liés en utilisant Glob
4. Fournir des commentaires détaillés sur la qualité du code

​
Compétence Multi-fichiers

pdf-processing/
├── SKILL.md
├── FORMS.md
├── REFERENCE.md
└── scripts/
    ├── fill_form.py
    └── validate.py
SKILL.md : 
---
name: Traitement PDF
description: Extraire du texte, remplir des formulaires, fusionner des PDF. Utilisez lors du travail avec des fichiers PDF, des formulaires ou l'extraction de documents. Nécessite les packages pypdf et pdfplumber.
---

# Traitement PDF

## Démarrage rapide

Extraire du texte :
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

Pour le remplissage de formulaires, voir [FORMS.md](FORMS.md).
Pour la référence API détaillée, voir [REFERENCE.md](REFERENCE.md).

## Exigences

Les packages doivent être installés dans votre environnement :
```bash
pip install pypdf pdfplumber
```
Listez les packages requis dans la description. Les packages doivent être installés dans votre environnement avant que Claude puisse les utiliser.
Claude charge les fichiers supplémentaires seulement quand c’est nécessaire.

​
Prochaines étapes

Meilleures pratiques de rédaction

Écrire des Compétences que Claude peut utiliser efficacement

Aperçu des Compétences d'Agent

Apprendre comment les Compétences fonctionnent dans les produits Claude

Commencer avec les Compétences d'Agent

Créer votre première Compétence