Claude Code Skills : créer des extensions à activation automatique

Comment créer un skill personnalisé pour Claude Code ? Créez un fichier SKILL.md dans ~/.claude/skills/<name>/ (personnel) ou .claude/skills/<name>/ (au niveau du projet), avec un frontmatter YAML contenant les champs name, description et allowed-tools, suivi d’un contenu markdown décrivant votre expertise. Claude s’appuie sur un raisonnement LLM appliqué à la description pour activer le skill automatiquement dès que votre tâche y correspond. Les skills de projet partagés via git ne demandent aucune configuration à vos collègues.

Trois sessions d’affilée, j’ai collé la même checklist de sécurité dans Claude Code. Cette checklist contenait les schémas de vulnérabilité propres à notre équipe : les contrôles IDOR liés à la conception de notre API, les règles de gestion de session de notre flux d’authentification, les règles d’exposition des données pour nos champs de PII. À chaque fois, Claude les a appliquées à la perfection. À chaque fois, j’ai dû penser à les coller.

Le moment où vous vous surprenez à réexpliquer le même contexte est le moment où vous devriez créer un skill.

TL;DR

Les skills sont des extensions invoquées par le modèle : Claude les découvre et les applique automatiquement selon le contexte, sans que vous ayez à les appeler explicitement ¹. La clé d’un skill fiable, c’est le champ description : Claude s’appuie sur un raisonnement LLM (et non sur une correspondance de mots-clés) pour décider quand activer chaque skill ¹. Créez des skills pour une expertise valable d’une session à l’autre (schémas de sécurité, style de code, règles métier). N’en créez pas pour des tâches ponctuelles : utilisez plutôt des slash commands.

Prérequis : connaître le système d’extensions de Claude Code. Pour la comparaison entre skills, commands et subagents, voyez la section Skills du guide.

Quand créer un skill

Tous les prompts répétés ne méritent pas un skill. Le cadre de décision :

Les skills, ce sont les connaissances dont Claude dispose en permanence. Les slash commands, ce sont les actions que vous déclenchez explicitement. Si vous hésitez entre les deux, demandez-vous : « Claude doit-il appliquer cela automatiquement, ou est-ce à moi de décider quand le lancer ? »

Une erreur fréquente : créer un skill pour quelque chose que vous faites une fois par semaine. J’avais créé un skill git-rebase-helper qui se déclenchait au moindre prompt lié à git : rebases, merges, cherry-picks, et même git status. Sa description était trop large, elle polluait le contexte dans 80 % des sessions où elle ne servait à rien, et elle entrait en concurrence avec les autres skills pour le budget de contexte de 2 % ¹. La solution a été de supprimer le skill et d’utiliser une slash command à la place : /rebase, quand j’en avais réellement besoin. Un skill doit encoder une expertise stable, pas un workflow occasionnel.

Tutoriel : créer un skill de revue de code

Étape 1 : créer le répertoire

Les skills se logent à quatre emplacements possibles, de la portée la plus large à la plus étroite ¹ :

Pour ce tutoriel, nous allons créer un skill personnel :

mkdir -p ~/.claude/skills/code-reviewer

Étape 2 : écrire SKILL.md avec son frontmatter

Tout skill a besoin d’un fichier SKILL.md en deux parties : un frontmatter YAML (entre les marqueurs ---) qui indique à Claude quand utiliser le skill, et un contenu markdown avec les instructions que Claude suit une fois le skill invoqué ¹.

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

### Data Exposure
- PII masked in log output and error messages
- API responses don't leak internal IDs or stack traces
- Sensitive fields excluded from serialization defaults

Notez allowed-tools: Read, Grep, Glob : cela restreint le skill à des opérations en lecture seule. Le relecteur de code peut examiner les fichiers, mais pas les modifier. Les restrictions d’outils empêchent les skills d’avoir des effets de bord non voulus.

Autres champs de frontmatter utiles, au-delà de name, description et allowed-tools ¹ :

Une réserve tirée de la documentation officielle : context: fork « n’a de sens que pour les skills dotés d’instructions explicites qui gagnent à être isolées » ¹. Réservez-le aux skills d’analyse (revue de code, audit de sécurité) où vous voulez un contexte propre, et non aux skills de connaissance qui doivent se fondre dans la conversation principale.

Étape 3 : ajouter des ressources complémentaires

Un skill peut référencer d’autres fichiers du même répertoire ¹ :

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

Référencez-les depuis SKILL.md avec des liens relatifs :

See [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md) for OWASP Top 10 checks.
See [PERFORMANCE_CHECKLIST.md](PERFORMANCE_CHECKLIST.md) for query optimization.

Claude lit ces fichiers à la demande, au moment où le skill s’active, avec les outils de lecture de fichiers habituels ¹. Gardez SKILL.md sous les 500 lignes et déportez la documentation de référence détaillée vers des fichiers complémentaires ³ : des fichiers de skill plus courts réduisent le coût d’injection dans le contexte et gardent Claude concentré sur la tâche en cours.

Étape 4 : tester l’activation

Le skill s’active dès la session Claude Code suivante. Pour le tester :

# Ask Claude to review code — should trigger the skill automatically
claude "Review the authentication middleware in app/security/"

Deux méthodes permettent de vérifier que le skill est bien chargé ¹ :

# In an interactive session, ask Claude directly:
> What skills are available?

# Or check the context budget for excluded skills:
> /context

Si le skill ne s’active pas, le coupable est presque toujours le champ description. Voyez l’étape 5.

Étape 5 : l’étape décisive — rédiger la description

Le champ description est la ligne la plus importante de votre skill. Voici ce qui se passe sous le capot : au démarrage de la session, Claude Code extrait les champs name et description de chaque skill et les injecte dans le contexte de Claude. Quand vous envoyez un message, Claude décide de la pertinence d’un skill par raisonnement de modèle de langage — pas par regex, pas par correspondance de mots-clés, pas par similarité d’embeddings. La documentation officielle l’énonce ainsi : « Claude compare votre tâche aux descriptions des skills pour décider lesquels sont pertinents. Si les descriptions sont vagues ou se recoupent, Claude risque de charger le mauvais skill — ou de passer à côté d’un skill qui aurait aidé » ¹.

Une analyse indépendante du code source de Claude Code confirme le mécanisme : les descriptions de skills sont injectées dans une section available_skills du prompt système, et le modèle sélectionne les skills pertinents au moment de l’invocation par simple compréhension du langage ⁴. Ce matching par LLM a des conséquences importantes sur la façon de rédiger vos descriptions.

Mauvaise description :

description: Helps with code

Claude n’a aucune idée du moment où l’activer. « Helps with code » correspond à tout et à rien — et comme le matching repose sur un raisonnement LLM, une description vague rend l’activation imprévisible.

Description un peu meilleure :

description: Review code for bugs and issues

Trop vague. Quel genre de bugs ? Quel genre de problèmes ? Quand Claude doit-il s’en servir plutôt que de son analyse intégrée ?

Description efficace :

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

Cette description fonctionne parce qu’elle précise : - Ce qu’elle fait : relire du code en cherchant des types de problèmes précis - Quand l’utiliser : examen de modifications, PR, analyse de qualité - Les formulations déclencheuses : review, audit, check — les mots que l’utilisateur tape spontanément

Une contrainte à connaître : toutes les descriptions de skills se partagent un budget de contexte qui « évolue dynamiquement à 2 % de la fenêtre de contexte, avec une valeur de repli de 16 000 caractères » ¹. Si vous avez beaucoup de skills, gardez chaque description concise : une description bavarde prend la place des autres. Vous pouvez modifier ce budget via la variable d’environnement SLASH_COMMAND_TOOL_CHAR_BUDGET ², mais mieux vaut des descriptions plus courtes et plus précises.

Testez plusieurs descriptions. Ouvrez une session neuve, demandez à Claude de relire du code et regardez si le skill s’active. Sinon, ajoutez des formulations déclencheuses. S’il s’active à tort, resserrez la description.

Étape 6 : itérer selon l’usage

Après une semaine d’utilisation, vous découvrirez : - Des points que le skill devrait vérifier mais ne vérifie pas : ajoutez-les dans SKILL.md - Des activations à tort sur des tâches sans rapport : resserrez la description, ou ajoutez disable-model-invocation: true et exigez l’invocation explicite /code-reviewer - Du contexte manquant : ajoutez des fichiers de ressources complémentaires - Des restrictions d’outils trop strictes ou trop lâches : ajustez allowed-tools

Un skill est un document vivant. La première version n’est jamais la dernière.

Pour aller plus loin : les skills comme bibliothèque de prompts

Au-delà des skills à usage unique, cette arborescence fait office de bibliothèque de prompts organisée :

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

Chaque skill encode une facette différente de l’expertise de votre équipe. Ensemble, ils forment une base de connaissances dans laquelle Claude puise automatiquement selon le contexte. Un développeur junior reçoit des conseils de niveau senior sans avoir à les demander.

Une remarque sur le nombre de skills : plus il y a de skills, plus il y a de descriptions en concurrence pour le budget de contexte ¹. Si vous constatez que des skills ne s’activent pas, lancez /context pour voir si certains sont exclus. Mieux vaut peu de skills bien décrits que beaucoup de skills vagues.

Partager vos skills avec votre équipe

Les skills personnels (~/.claude/skills/) n’appartiennent qu’à vous. Réservez-les à vos préférences personnelles, à vos essais et à l’expertise propre à votre façon de travailler.

Les skills de projet (.claude/skills/ à la racine du dépôt) se partagent via git ¹ :

# Create project-level skill
mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...

# Commit and push
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

Dès que vos collègues font un pull, ils récupèrent le skill automatiquement. Aucune installation, aucune configuration. La distribution par git reste le moyen le plus efficace d’uniformiser une expertise au sein d’une équipe.

Bonnes pratiques pour les skills partagés : - Cantonnez les skills de projet à l’expertise du domaine (règles métier, schémas d’architecture) - Gardez les skills personnels pour vos préférences de travail (formatage, style de commit) - Documentez la raison d’être du skill dans un commentaire en tête de SKILL.md - Relisez les modifications de skills en PR comme n’importe quel autre code

À retenir

• Créez un skill dès que vous vous surprenez à réexpliquer du contexte. Si vous collez trois fois la même checklist, elle doit devenir un skill.
• Le champ description décide de tout. Claude fait correspondre vos demandes aux descriptions par raisonnement LLM ¹. Investissez plus de temps dans la description que dans le contenu du skill.
• Limitez les effets de bord avec allowed-tools. Un skill en lecture seule doit être restreint à Read, Grep, Glob.
• Partagez les skills de projet via git. Diffusion du savoir dans l’équipe sans aucune configuration ¹.
• N’abstrayez pas à l’excès. Un skill pour chaque micro-schéma crée une charge de maintenance et mange le budget de contexte. Créez des skills pour une expertise stable, réutilisable et assez précieuse pour être entretenue.

Questions fréquentes

Que sont les skills de Claude Code ?

Les skills sont des extensions invoquées par le modèle, stockées sous forme de fichiers markdown, que Claude découvre et applique automatiquement selon le contexte. Contrairement aux slash commands que vous déclenchez explicitement, un skill s’active dès que le raisonnement LLM de Claude estime que votre tâche du moment correspond à sa description. Les skills encodent une expertise — schémas de sécurité, règles de style de code, logique métier — qui persiste d’une session à l’autre, sans que vous ayez à réexpliquer le contexte à chaque fois.

Comment créer un skill personnalisé pour Claude Code ?

Créez un répertoire sous ~/.claude/skills/<name>/ pour un skill personnel, ou sous .claude/skills/<name>/ pour un skill de projet. À l’intérieur, créez un fichier SKILL.md avec un frontmatter YAML (contenant name, description et, en option, allowed-tools) suivi d’un contenu markdown décrivant l’expertise que Claude doit appliquer. Le champ description est décisif : c’est sur lui que Claude applique son raisonnement LLM pour décider quand activer le skill. Voyez le tutoriel complet ci-dessus pour la marche à suivre pas à pas.

Quelle différence entre les skills Claude Code et les slash commands ?

Les skills s’activent d’eux-mêmes selon le contexte : Claude décide de leur pertinence par raisonnement LLM appliqué à leur description. Les slash commands sont des actions déclenchées par l’utilisateur, que vous lancez explicitement en tapant /command-name. Créez un skill quand Claude doit disposer en permanence de la connaissance (expertise du domaine, normes de qualité). Créez une slash command quand vous voulez décider vous-même du moment de l’exécution (scripts de déploiement, workflows ponctuels).

Les skills Claude Code peuvent-ils appeler d’autres outils ?

Oui, mais c’est vous qui choisissez lesquels via le champ de frontmatter allowed-tools. Un skill en lecture seule, comme un relecteur de code, doit être restreint à Read, Grep, Glob pour éviter tout effet de bord non voulu. Si allowed-tools est omis, le skill peut utiliser n’importe quel outil auquel Claude a accès. Un skill peut aussi définir ses propres hooks dans son frontmatter, actifs uniquement pendant son exécution.

Pourquoi mon skill Claude Code ne s’active-t-il pas ?

La cause la plus fréquente est un champ description vague ou trop large. Claude s’appuie sur un raisonnement LLM — et non sur une correspondance de mots-clés — pour juger de la pertinence d’un skill au regard de votre tâche. Si la description dit « helps with code », Claude ne peut pas distinguer ce cas de n’importe quelle autre tâche de programmation. Soyez précis : nommez les types de problèmes visés, les scénarios déclencheurs et les verbes que les utilisateurs tapent spontanément. Lancez aussi /context dans une session pour voir si votre skill est exclu à cause de la limite de 2 % du budget de contexte. Quand trop de skills se disputent la place, certains sautent.

Où sont stockés les skills Claude Code et comment les partager ?

Les skills se logent à quatre emplacements, de portée croissante : personnel (~/.claude/skills/<name>/SKILL.md), projet (.claude/skills/<name>/SKILL.md), plugin et entreprise (paramètres gérés). Un skill personnel s’applique à tous vos projets. Les skills de projet se partagent via git : dès que vos collègues font un pull, ils récupèrent le skill automatiquement, sans aucune configuration. Toutes les descriptions de skills se partagent un budget de contexte égal à 2 % de la fenêtre de contexte : gardez-les concises si vous avez beaucoup de skills.

Références