Passer au contenu principal
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 via 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

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 fichier SKILL.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
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/my-skill-name
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é personnels

Compétences de projet

Les compétences de projet sont partagées avec votre équipe. Stockez-les dans .claude/skills/ dans votre projet :
mkdir -p .claude/skills/my-skill-name
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 archivées dans git et automatiquement disponibles pour les membres de l’équipe.

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 fichier SKILL.md avec un préambule YAML et du contenu Markdown :
---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
Provide clear, step-by-step guidance for Claude.

## Examples
Show concrete examples of using this Skill.
Exigences des champs :
  • 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)
Le champ 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 :
my-skill/
├── SKILL.md (required)
├── reference.md (optional documentation)
├── examples.md (optional examples)
├── scripts/
│   └── helper.py (optional utility)
└── templates/
    └── template.txt (optional template)
Référencez ces fichiers à partir de SKILL.md :
For advanced usage, see [reference.md](reference.md).

Run the helper script:
```bash
python scripts/helper.py input.txt
```
Claude lit ces fichiers uniquement si nécessaire, en utilisant la divulgation progressive pour gérer efficacement le contexte.

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

Utilisez le champ de préambule allowed-tools pour limiter les outils que Claude peut utiliser quand une compétence est active :
---
name: safe-file-reader
description: Read files without making changes. Use when you need read-only file access.
allowed-tools: Read, Grep, Glob
---

# Safe File Reader

This Skill provides read-only file access.

## Instructions
1. Use Read to view file contents
2. Use Grep to search within files
3. Use Glob to find files by pattern
Quand 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 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
Si 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
Pour afficher toutes les compétences disponibles, demandez directement à Claude :
What Skills are available?
ou
List all available Skills
Cela affichera 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 :
# List personal Skills
ls ~/.claude/skills/

# List project Skills (if in a project directory)
ls .claude/skills/

# View a specific Skill's content
cat ~/.claude/skills/my-skill/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 » :
Can you help me extract text from this 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: Helps with documents
Spécifique :
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
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/skill-name/SKILL.md Compétences de projet : .claude/skills/skill-name/SKILL.md Vérifiez que le fichier existe :
# Personal
ls ~/.claude/skills/my-skill/SKILL.md

# Project
ls .claude/skills/my-skill/SKILL.md

Vérifier la syntaxe YAML

Une syntaxe YAML invalide empêche le chargement de la compétence. Vérifiez le préambule :
cat SKILL.md | head -n 10
Assurez-vous que :
  • 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 :
claude --debug

Partager les compétences avec votre équipe

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

Étape 1 : Ajouter la compétence à votre projet

Créez une compétence de projet :
mkdir -p .claude/skills/team-skill
# Create SKILL.md

Étape 2 : Valider dans git

git add .claude/skills/
git commit -m "Add team Skill for PDF processing"
git push

É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 :
git pull
claude  # Skills are now available

Mettre à jour une compétence

Modifiez SKILL.md directement :
# Personal Skill
code ~/.claude/skills/my-skill/SKILL.md

# Project Skill
code .claude/skills/my-skill/SKILL.md
Les modifications 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 :
# Personal
rm -rf ~/.claude/skills/my-skill

# Project
rm -rf .claude/skills/my-skill
git commit -m "Remove unused Skill"

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 »
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: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.
Vague :
description: For files

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 :
# My Skill

## Version History
- v2.0.0 (2025-10-01): Breaking changes to API
- v1.1.0 (2025-09-15): Added new features
- v1.0.0 (2025-09-01): Initial release
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é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 :
description: Helps with data
Spécifique :
description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files.
Vérifier : Le YAML est-il valide ? Exécutez la validation pour vérifier les erreurs de syntaxe :
# View frontmatter
cat .claude/skills/my-skill/SKILL.md | head -n 15

# Check for common issues
# - Missing opening or closing ---
# - Tabs instead of spaces
# - Unquoted strings with special characters
Vérifier : La compétence est-elle au bon endroit ?
# Personal Skills
ls ~/.claude/skills/*/SKILL.md

# Project Skills
ls .claude/skills/*/SKILL.md

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 ?
chmod +x .claude/skills/my-skill/scripts/*.py
Vérifier : 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 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 :
# Skill 1
description: For data analysis

# Skill 2
description: For analyzing data
Utilisez :
# Skill 1
description: Analyze sales data in Excel files and CRM exports. Use for sales reports, pipeline analysis, and revenue tracking.

# Skill 2
description: Analyze log files and system metrics data. Use for performance monitoring, debugging, and system diagnostics.

Exemples

Compétence simple (fichier unique)

commit-helper/
└── SKILL.md
---
name: generating-commit-messages
description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
---

# Generating Commit Messages

## Instructions

1. Run `git diff --staged` to see changes
2. I'll suggest a commit message with:
   - Summary under 50 characters
   - Detailed description
   - Affected components

## Best practices

- Use present tense
- Explain what and why, not how

Compétence avec permissions d’outils

code-reviewer/
└── SKILL.md
---
name: code-reviewer
description: Review code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
allowed-tools: Read, Grep, Glob
---

# Code Reviewer

## Review checklist

1. Code organization and structure
2. Error handling
3. Performance considerations
4. Security concerns
5. Test coverage

## Instructions

1. Read the target files using Read tool
2. Search for patterns using Grep
3. Find related files using Glob
4. Provide detailed feedback on code quality

Compétence multi-fichiers

pdf-processing/
├── SKILL.md
├── FORMS.md
├── REFERENCE.md
└── scripts/
    ├── fill_form.py
    └── validate.py
SKILL.md :
---
name: pdf-processing
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
---

# PDF Processing

## Quick start

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

For form filling, see [FORMS.md](FORMS.md).
For detailed API reference, see [REFERENCE.md](REFERENCE.md).

## Requirements

Packages must be installed in your environment:
```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 uniquement si nécessaire.

Étapes suivantes