Créer des Skills personnalisés pour Claude Code : un tutoriel complet

Trois sessions d’affilée, j’ai collé la même checklist de sécurité dans Claude Code. La checklist contenait les schémas de vulnérabilité spécifiques à notre équipe — les vérifications IDOR propres à la conception de notre API, les règles de gestion de session pour notre flux d’authentification, les règles d’exposition de données pour nos champs PII. À chaque fois, Claude les a appliquées parfaitement. À 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 construire un skill.

TL;DR

Les skills sont des extensions invoquées par le modèle — Claude les découvre et les applique automatiquement en fonction du contexte, sans que vous ayez à les appeler explicitement ¹. La clé pour des skills fiables est le champ description : Claude utilise le raisonnement LLM (pas la correspondance par mots-clés) pour décider quand activer chaque skill ¹. Construisez des skills pour l’expertise métier qui s’applique d’une session à l’autre (schémas de sécurité, style de code, règles métier). Ne construisez pas de skills pour les tâches ponctuelles — utilisez plutôt les commandes slash.

Prérequis : Familiarité avec le système d’extension de Claude Code. Pour la comparaison entre skills, commandes et sous-agents, consultez la section Skills du guide.

Quand construire un skill

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

Les skills sont pour les connaissances que Claude a toujours à disposition. Les commandes slash sont pour les actions que vous déclenchez explicitement. Si vous hésitez entre les deux, demandez-vous : « Claude devrait-il appliquer ceci automatiquement, ou devrais-je décider quand l’exécuter ? »

Une erreur courante : construire un skill pour quelque chose que vous faites une fois par semaine. J’ai construit un skill git-rebase-helper qui s’activait sur n’importe quel prompt lié à git — rebases, merges, cherry-picks, même git status. La description était trop large, il polluait le contexte dans 80 % des sessions où il n’était pas nécessaire, et il entrait en compétition avec d’autres skills pour le budget de contexte de 2 % ¹. La solution a été de supprimer le skill et d’utiliser une commande slash à la place : /rebase quand j’en avais réellement besoin. Les skills devraient encoder une expertise métier stable, pas des workflows occasionnels.

Tutoriel : construire un skill de revue de code

Étape 1 : Créer le répertoire

Les skills se trouvent dans quatre emplacements possibles, du périmètre le plus large au plus restreint ¹ :

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

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

Étape 2 : Écrire SKILL.md avec le frontmatter

Chaque skill nécessite un fichier SKILL.md en deux parties : le frontmatter YAML (entre les marqueurs ---) qui indique à Claude quand utiliser le skill, et le contenu markdown avec les instructions que Claude suit lorsque le skill est 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 aux opérations en lecture seule. Le réviseur de code peut examiner les fichiers mais ne peut pas les modifier. Les restrictions d’outils empêchent les skills d’avoir des effets de bord non souhaités.

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

Une mise en garde tirée de la documentation officielle : context: fork « n’a de sens que pour les skills avec des instructions explicites qui bénéficient de l’isolation » ¹. Utilisez-le pour les skills d’analyse (revue de code, audit de sécurité) où vous souhaitez un contexte propre, pas pour les skills de connaissances qui doivent se fondre dans la conversation principale.

Étape 3 : Ajouter des ressources complémentaires

Les skills peuvent référencer des fichiers supplémentaires dans le 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 lorsque le skill s’active, en utilisant les outils standard de lecture de fichiers ¹. Gardez SKILL.md en dessous de 500 lignes et déplacez le matériel de référence détaillé dans des fichiers complémentaires ³ — des fichiers de skill plus courts réduisent la surcharge d’injection de contexte et permettent à Claude de rester concentré sur la tâche en cours.

Étape 4 : Tester l’activation

Le skill s’active la prochaine fois que vous démarrez une session Claude Code. Testez-le :

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

Vérifiez que le skill s’est chargé en utilisant l’une des deux méthodes ¹ :

# 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 problème vient presque toujours du champ description. Voir l’étape 5.

Étape 5 : L’étape cruciale — rédiger la description

Le champ description est la ligne la plus importante de votre skill. Voici ce qui se passe en coulisses : au démarrage de la session, Claude Code extrait le name et la description de chaque skill et les injecte dans le contexte de Claude. Lorsque vous envoyez un message, Claude utilise le raisonnement du modèle de langage — pas de regex, pas de correspondance par mots-clés, pas de similarité par embeddings — pour décider si un skill est pertinent. La documentation officielle indique : « Claude compare votre tâche aux descriptions des skills pour décider lesquels sont pertinents. Si les descriptions sont vagues ou se chevauchent, Claude pourrait charger le mauvais skill — ou en manquer un qui aurait été utile » ¹.

Une analyse indépendante du code source de Claude Code confirme le mécanisme : les descriptions des skills sont injectées dans une section available_skills du prompt système, et le modèle utilise la compréhension linguistique standard pour sélectionner les skills pertinents au moment de l’invocation ⁴. La correspondance basée sur le LLM a des implications importantes sur la façon dont vous rédigez les descriptions.

Mauvaise description :

description: Helps with code

Claude n’a aucune idée de quand activer ceci. « Helps with code » correspond à tout et à rien — et comme la correspondance repose sur le raisonnement LLM, les descriptions vagues créent une activation imprévisible.

Meilleure description :

description: Review code for bugs and issues

Trop vague. Quel type de bugs ? Quel type de problèmes ? Quand Claude devrait-il utiliser ceci plutôt que 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.

La description efficace fonctionne parce qu’elle inclut : - Ce qu’il fait : Revue de code pour des types de problèmes spécifiques - Quand l’utiliser : Examen de changements, PRs, analyse de qualité - Phrases déclencheurs : review, audit, check — des mots que l’utilisateur tape naturellement

Une contrainte à connaître : toutes les descriptions de skills partagent un budget de contexte qui « s’adapte dynamiquement à 2 % de la fenêtre de contexte, avec un repli à 16 000 caractères » ¹. Si vous avez beaucoup de skills, gardez chaque description concise — une description verbeuse entre en compétition avec les autres skills pour un espace limité. Vous pouvez remplacer le budget via la variable d’environnement SLASH_COMMAND_TOOL_CHAR_BUDGET ², mais la meilleure solution reste des descriptions plus courtes et plus précises.

Testez différentes descriptions. Démarrez une nouvelle session, demandez à Claude de revoir du code, et vérifiez si le skill s’active. Si ce n’est pas le cas, ajoutez plus de phrases déclencheurs. S’il s’active quand il ne devrait pas, rendez la description plus spécifique.

Étape 6 : Itérer en fonction de l’utilisation

Après une semaine d’utilisation, vous découvrirez : - Des schémas que le skill devrait vérifier mais qu’il ne vérifie pas — ajoutez-les à SKILL.md - Des fausses activations sur des tâches non liées — 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

Les skills sont des documents vivants. La première version n’est jamais la version finale.

Avancé : les skills comme bibliothèque de prompts

Au-delà des skills à usage unique, la structure de répertoires fonctionne comme une 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 en fonction du contexte. Un développeur junior reçoit des conseils de niveau senior sans avoir à les demander.

Une note sur le nombre de skills : plus de skills signifie plus de descriptions en compétition pour le budget de contexte ¹. Si vous remarquez que des skills ne s’activent pas, exécutez /context pour vérifier si certains sont exclus. Privilégiez un nombre réduit de skills bien décrits plutôt que de nombreux skills vagues.

Partager des skills avec votre équipe

Les skills personnels (~/.claude/skills/) sont les vôtres uniquement. Utilisez-les pour vos préférences personnelles, vos schémas expérimentaux ou votre expertise spécifique à votre workflow.

Les skills de projet (.claude/skills/ à la racine du dépôt) sont partagés 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

Quand vos coéquipiers tirent les changements, ils obtiennent le skill automatiquement. Pas d’installation, pas de configuration. La distribution via git est le moyen le plus efficace de standardiser l’expertise au sein d’une équipe.

Recommandations pour les skills partagés : - Gardez les skills de projet centrés sur l’expertise métier (règles métier, schémas d’architecture) - Gardez les skills personnels pour les préférences de workflow (formatage, style de commit) - Documentez pourquoi le skill existe dans un commentaire en haut de SKILL.md - Révisez les modifications de skills dans les PRs comme n’importe quel autre code

Points clés à retenir

• Construisez un skill quand vous vous surprenez à réexpliquer le contexte. Si vous collez la même checklist trois fois, cela devrait être un skill.
• Le champ description détermine tout. Claude utilise le raisonnement LLM pour faire correspondre vos requêtes aux descriptions ¹. Investissez plus de temps dans la description que dans le contenu du skill.
• Utilisez allowed-tools pour contraindre les effets de bord. Les skills en lecture seule devraient être restreints à Read, Grep, Glob.
• Partagez les skills de projet via git. Distribution des connaissances d’équipe sans aucune configuration ¹.
• N’abstraisez pas à l’excès. Un skill pour chaque micro-schéma crée une charge de maintenance et entre en compétition pour le budget de contexte. Construisez des skills pour une expertise qui est stable, réutilisable et suffisamment précieuse pour être maintenue.

Références