Skills et commandes custom dans Claude Code

C’est quoi les commandes et skills ?

Claude Code est puissant par défaut, mais il devient vraiment redoutable quand vous le personnalisez. Deux mécanismes complémentaires existent pour ça : les commandes custom et les skills.

Les commandes custom sont des fichiers Markdown qui deviennent des commandes slash (/mon-truc). Vous tapez /commit dans Claude Code, et il exécute le prompt que vous avez défini. C’est l’équivalent d’un alias shell, mais pour les interactions avec Claude.

Les skills sont des fichiers Markdown plus riches, stockés dans votre profil utilisateur. Elles décrivent un comportement, une expertise, une méthode de travail. Claude Code les charge automatiquement quand il détecte qu’elles sont pertinentes, ou vous les invoquez manuellement.

En résumé :

	Commandes custom	Skills
Emplacement	`.claude/commands/` dans le projet	`~/.claude/skills/` dans votre home
Déclenchement	Slash explicite (`/nom`)	Automatique ou `/skill-name`
Portée	Projet (partageable en équipe)	Globale (personnelle)
Usage typique	Actions récurrentes (commit, review, test)	Expertises transverses (design system, TDD, debug)

Commandes custom

Structure de base

Les commandes vivent dans le dossier .claude/commands/ à la racine de votre projet. Chaque fichier .md devient une commande slash.

mon-projet/
├── .claude/
│   └── commands/
│       ├── commit.md
│       ├── review.md
│       ├── test.md
│       └── deploy.md
├── src/
└── package.json

Le nom du fichier (sans .md) devient le nom de la commande. commit.md donne /commit. C’est aussi simple que ça.

Le placeholder `$ARGUMENTS`

Chaque commande peut recevoir des arguments. Utilisez $ARGUMENTS dans votre fichier Markdown pour injecter ce que l’utilisateur tape après la commande.

/review src/auth/login.ts

Dans le fichier review.md, $ARGUMENTS sera remplacé par src/auth/login.ts.

Exemple 1 : `/commit` - Messages de commit intelligents

Fichier .claude/commands/commit.md :

Analyse les changements staged (git diff --cached) et génère un message de commit.

Règles :
- Format : type(scope): description courte
- Types autorisés : feat, fix, refactor, docs, test, chore, style, perf
- La description fait max 72 caractères
- Si les changements sont complexes, ajoute un body après une ligne vide
- Le body explique le "pourquoi", pas le "quoi"
- Langue : anglais

Exemples de bons messages :
- feat(auth): add OAuth2 login with Google
- fix(api): handle null response from payment gateway
- refactor(db): extract query builder into separate module

Analyse les changements, propose le message, et attends ma validation avant de committer.

Utilisation :

> /commit

Claude Code lit le diff staged, génère un message structuré, et attend votre feu vert.

Exemple 2 : `/review` - Code review ciblée

Fichier .claude/commands/review.md :

Fais une code review du fichier ou des changements suivants : $ARGUMENTS

Critères de review (par ordre de priorité) :

1. **Bugs et erreurs logiques** : race conditions, null pointers, off-by-one, cas limites non gérés
2. **Sécurité** : injections, données non validées, secrets en dur, permissions manquantes
3. **Performance** : boucles inutiles, requêtes N+1, allocations excessives, manque de cache
4. **Lisibilité** : nommage flou, fonctions trop longues (>30 lignes), nesting excessif (>3 niveaux)
5. **Tests** : code non testable, cas de test manquants évidents

Format de sortie :
- Liste chaque problème avec le numéro de ligne
- Classe chaque problème : 🔴 Critique / 🟡 Important / 🔵 Suggestion
- Propose un fix concret pour chaque problème critique et important
- Termine par un résumé : X critiques, Y importants, Z suggestions

Si $ARGUMENTS est vide, review les changements non commités (git diff).

Utilisation :

> /review src/api/handlers/payment.ts
> /review          # review le diff courant

Exemple 3 : `/test` - Génération de tests

Fichier .claude/commands/test.md :

Génère des tests pour : $ARGUMENTS

Approche :
1. Lis le fichier source et comprends la logique
2. Identifie les cas de test pertinents :
   - Cas nominal (happy path)
   - Cas limites (valeurs vides, null, très grandes)
   - Cas d'erreur (exceptions, timeouts, données invalides)
3. Écris les tests dans le framework de test du projet
4. Chaque test doit être indépendant et déterministe

Conventions :
- Un describe par fonction/méthode publique
- Nommage : "should [comportement attendu] when [condition]"
- Arrange / Act / Assert clairement séparés
- Pas de mock sauf si nécessaire (préfère les vrais objets)
- Si un mock est nécessaire, explique pourquoi

Place le fichier de test à côté du source avec le suffixe .test ou .spec selon la convention du projet.

Utilisation :

> /test src/utils/date-parser.ts

Exemple 4 : `/deploy` - Workflow de déploiement

Fichier .claude/commands/deploy.md :

Lance le workflow de déploiement pour l'environnement : $ARGUMENTS

Étapes :
1. Vérifie que la branche est propre (pas de changements non commités)
2. Lance les tests : npm test (ou le script de test du projet)
3. Si les tests passent, lance le build : npm run build
4. Vérifie que le build a réussi sans warnings critiques
5. Selon l'environnement :
   - staging : push sur la branche staging, déclenche le déploiement auto
   - production : crée un tag de version (semver), push le tag

Si $ARGUMENTS est vide, déploie en staging par défaut.

IMPORTANT : ne déploie JAMAIS en production sans confirmation explicite.
Montre-moi un résumé des changements qui vont être déployés et attends mon "go".

Exemple 5 : `/refactor` - Refactoring guidé

Fichier .claude/commands/refactor.md :

Refactore le code suivant : $ARGUMENTS

Patterns à appliquer (dans l'ordre) :

1. **Extract Method** : toute logique dupliquée ou bloc > 15 lignes
2. **Simplify Conditionals** : remplacer les if/else imbriqués par early returns ou pattern matching
3. **Remove Dead Code** : supprimer le code commenté, les imports inutilisés, les variables non lues
4. **Rename for Clarity** : renommer les variables/fonctions dont le nom ne reflète pas le contenu
5. **Type Safety** : ajouter ou renforcer le typage quand c'est possible

Contraintes :
- Le comportement observable ne change PAS (même inputs -> mêmes outputs)
- Pas de changement d'API publique sans demander
- Chaque transformation est un commit séparé avec un message clair
- Si le refactoring casse des tests, corrige les tests d'abord

Montre-moi le plan de refactoring avant d'exécuter. J'approuve étape par étape.

Sous-dossiers pour organiser les commandes

Si vous avez beaucoup de commandes, organisez-les en sous-dossiers :

.claude/commands/
├── git/
│   ├── commit.md
│   ├── pr.md
│   └── changelog.md
├── code/
│   ├── review.md
│   ├── test.md
│   └── refactor.md
└── ops/
    ├── deploy.md
    └── monitor.md

Les commandes deviennent /git:commit, /code:review, /ops:deploy. Le : sert de séparateur de namespace.

Skills

Qu’est-ce qu’une skill ?

Une skill est un fichier Markdown enrichi qui définit une expertise que Claude Code peut mobiliser. Contrairement aux commandes (qui sont des actions ponctuelles), les skills décrivent un mode de fonctionnement complet.

Les skills vivent dans ~/.claude/skills/ et sont globales : elles s’appliquent à tous vos projets.

~/.claude/
└── skills/
    ├── design-system/
    │   └── skill.md
    ├── tdd/
    │   └── skill.md
    └── debugging/
        └── skill.md

Anatomie d’une skill

Une skill est un fichier Markdown avec un frontmatter YAML qui décrit son identité :

---
name: "Nom de la skill"
description: "Description courte. Claude Code utilise cette description pour décider quand activer la skill."
---

Le contenu de la skill : instructions, règles, exemples, templates.

Le champ description est crucial. C’est ce que Claude Code lit pour décider si la skill est pertinente dans le contexte actuel. Soyez précis et concret.

Skill 1 : Design System

Fichier ~/.claude/skills/design-system/skill.md :

---
name: "Design System Guardian"
description: "Garantit la cohérence visuelle et structurelle du code UI. Active quand on travaille sur des composants, du CSS, du HTML ou des fichiers de style."
---

## Rôle

Tu es le gardien du design system. Chaque composant UI doit respecter les règles ci-dessous.

## Tokens

Utilise exclusivement les design tokens du projet. Jamais de valeurs en dur.

```css
/* Interdit */
color: #3b82f6;
padding: 16px;
font-size: 14px;

/* Correct */
color: var(--color-primary-500);
padding: var(--spacing-4);
font-size: var(--text-sm);

Composants

Règles pour chaque nouveau composant :

Props typées : chaque prop a un type TypeScript strict (pas de any)
Variants : utilise le pattern variant (via cva, class-variance-authority, ou équivalent)
Accessibilité : aria-labels obligatoires sur les éléments interactifs, rôles ARIA quand pertinent
Responsive : mobile-first, breakpoints via les tokens
États : gérer hover, focus, disabled, loading, error pour tout élément interactif

Structure de fichier

components/
├── Button/
│   ├── Button.tsx        # Composant
│   ├── Button.test.tsx   # Tests
│   ├── Button.stories.tsx # Storybook
│   └── index.ts          # Export

Review automatique

Quand je crée ou modifie un composant UI, vérifie automatiquement :


### Skill 2 : TDD (Test-Driven Development)

Fichier `~/.claude/skills/tdd/skill.md` :

```markdown
---
name: "TDD Coach"
description: "Applique le workflow Test-Driven Development. Active quand on développe une nouvelle fonctionnalité ou qu'on corrige un bug."
---

## Workflow strict

Pour chaque fonctionnalité ou correction :

### 1. Red - Écrire le test d'abord

Avant de toucher au code de production :
- Écris un test qui décrit le comportement attendu
- Le test DOIT échouer (rouge)
- Si le test passe sans modifier le code, c'est que le test ne teste rien

```bash
# Lancer le test, vérifier qu'il est rouge
npm test -- --watch path/to/file.test.ts

2. Green - Faire passer le test

Écris le code MINIMUM pour faire passer le test
Pas d’optimisation, pas de refactoring, pas de généralisation
Le code peut être moche, c’est normal à cette étape

3. Refactor - Nettoyer

Le test est vert : tu peux refactorer en sécurité
Élimine la duplication
Améliore le nommage
Extrais les fonctions si nécessaire
Relance les tests après chaque modification

Cycle

Répète Red -> Green -> Refactor pour chaque comportement unitaire.

Règles

JAMAIS de code de production sans test qui le justifie
Un commit par cycle (test + implémentation + refactor)
Si un bug est trouvé, écrire le test qui le reproduit AVANT de le corriger
Taille des tests : un seul assert par test (sauf quand tester un objet complet)

Quand je demande une feature

Demande-moi de décrire le comportement attendu
Propose une liste de cas de test
J’approuve la liste
On commence le premier cycle Red -> Green -> Refactor
On itère jusqu’à avoir couvert tous les cas


### Skill 3 : Debugging systématique

Fichier `~/.claude/skills/debugging/skill.md` :

```markdown
---
name: "Systematic Debugger"
description: "Approche méthodique de debugging. Active quand un bug est signalé ou quand du code ne fonctionne pas comme prévu."
---

## Méthode

Ne jamais deviner. Toujours suivre cette séquence :

### 1. Reproduire

- Identifier les étapes exactes pour reproduire le bug
- Documenter : input, output attendu, output réel
- Si le bug est intermittent, identifier les conditions (timing, état, données)

### 2. Isoler

- Réduire le périmètre : quel fichier, quelle fonction, quelle ligne
- Technique du bisect : commenter la moitié du code, le bug persiste ? On continue dans cette moitié
- Vérifier les hypothèses une par une

### 3. Comprendre

- Lire le code incriminé ligne par ligne
- Tracer le flux de données : d'où vient chaque variable, quel chemin elle emprunte
- Chercher les effets de bord : mutations, état global, closures

### 4. Corriger

- Corriger la cause racine, pas le symptôme
- Si la correction est un patch rapide, l'indiquer et ouvrir une issue pour le fix propre
- Écrire un test qui reproduit le bug AVANT de corriger

### 5. Vérifier

- Le test de reproduction passe
- Les tests existants passent toujours
- Tester manuellement le scénario original

## Anti-patterns à éviter

- Modifier du code au hasard en espérant que ça marche
- Ajouter un try/catch pour masquer l'erreur
- Corriger le symptôme sans comprendre la cause
- Modifier plusieurs choses à la fois (impossible de savoir laquelle a résolu le problème)

## Format de rapport

Quand je corrige un bug, je documente :
- **Symptôme** : ce qui a été observé
- **Cause** : pourquoi ça se produit
- **Fix** : ce qui a été changé et pourquoi
- **Prévention** : comment éviter que ça se reproduise

Frontmatter et métadonnées

Le frontmatter YAML des skills contrôle comment Claude Code les découvre et les active.

---
name: "Nom lisible"
description: "Quand et pourquoi utiliser cette skill. Soyez concret."
---

Bien rédiger la description

La description est le critère de décision. Claude Code la lit pour évaluer la pertinence de la skill par rapport à votre demande.

Mauvais exemples :

description: "Aide pour le code"                    # Trop vague
description: "Skill de test"                        # Ne dit rien sur le contexte
description: "Fait des trucs avec React"            # Pas assez précis

Bons exemples :

description: "Applique les conventions React du projet : hooks custom, error boundaries, suspense patterns. Active quand on crée ou modifie des composants React."
description: "Génère des requêtes SQL optimisées pour PostgreSQL. Active quand on travaille sur des queries, des migrations, ou des problèmes de performance base de données."
description: "Guide la rédaction de documentation technique : README, docstrings, API docs. Active quand on écrit ou met à jour de la documentation."

Partager les commandes en équipe

Les commandes custom dans .claude/commands/ font partie du projet. Versionnez-les dans Git et toute l’équipe en profite.

# Ajouter les commandes au repo
git add .claude/commands/
git commit -m "feat: add custom Claude Code commands for team workflow"

Ça crée un vocabulaire partagé. Tout le monde peut taper /review, /test, /commit et obtenir un comportement cohérent, calibré sur les conventions du projet.

Convention d’équipe recommandée

Documentez les commandes disponibles dans votre CLAUDE.md :

## Commandes disponibles

- `/commit` : génère un message de commit conventionnel
- `/review <fichier>` : code review avec nos critères qualité
- `/test <fichier>` : génère des tests selon nos conventions
- `/deploy <env>` : workflow de déploiement (staging par défaut)
- `/refactor <fichier>` : refactoring guidé étape par étape

Ainsi, chaque nouveau membre de l’équipe sait immédiatement quels raccourcis existent.

Skills personnelles vs commandes partagées

La distinction est importante :

Commandes (.claude/commands/) : partagées, liées au projet, dans Git. Tout le monde les utilise de la même manière.
Skills (~/.claude/skills/) : personnelles, dans votre home. Elles reflètent votre façon de travailler, pas celle de l’équipe.

Si une skill s’avère utile pour toute l’équipe, transformez-la en commande et versionnez-la dans le projet.

Bonnes pratiques

1. Une commande = une action

Chaque commande doit faire une seule chose bien. Si votre commande fait “review + test + deploy”, découpez-la en trois commandes séparées.

2. Soyez explicite dans les instructions

Claude Code suit ce que vous écrivez. Si vous voulez un format précis, décrivez-le. Si vous voulez qu’il attende votre validation, dites-le. Ne laissez pas de place à l’ambiguïté.

<!-- Trop vague -->
Fais un bon commit.

<!-- Explicite -->
Analyse git diff --cached. Génère un message au format type(scope): description.
Types : feat, fix, refactor, docs, test, chore.
Max 72 caractères pour la première ligne.
Propose le message et attends ma confirmation avant de committer.

3. Utilisez le Markdown à fond

Les commandes et skills sont du Markdown. Profitez-en : titres, listes, blocs de code, tableaux. La structure aide Claude Code à comprendre et suivre vos instructions.

4. Testez et itérez

Votre première version ne sera pas parfaite. Utilisez la commande, observez ce que Claude Code fait, ajustez le prompt. En 2-3 itérations, vous aurez une commande fiable.

5. Documentez les conventions existantes

Les meilleures commandes sont celles qui encodent des conventions que votre équipe suit déjà manuellement. Commencez par automatiser ce que vous faites tous les jours.

6. Le placeholder `$ARGUMENTS` est optionnel

Si votre commande n’a pas besoin d’arguments (comme /commit), ne mettez pas $ARGUMENTS. Si elle en a besoin, gérez aussi le cas où l’argument est vide (comme /review qui peut review le diff courant).

7. Combinez commandes et CLAUDE.md

Votre fichier CLAUDE.md définit le contexte global du projet. Vos commandes définissent des actions spécifiques. Les deux se complètent : le CLAUDE.md donne les conventions, et les commandes les appliquent.

# CLAUDE.md
## Conventions de commit
Format conventionnel, en anglais, max 72 caractères.

## Tests
Framework : Vitest. Convention : fichiers .test.ts à côté des sources.

La commande /test peut alors dire “génère des tests selon les conventions du projet” et Claude Code ira lire le CLAUDE.md pour savoir quoi faire.

C’est quoi les commandes et skills ?

Commandes custom

Structure de base

Le placeholder $ARGUMENTS

Exemple 1 : /commit - Messages de commit intelligents

Exemple 2 : /review - Code review ciblée

Exemple 3 : /test - Génération de tests

Exemple 4 : /deploy - Workflow de déploiement

Exemple 5 : /refactor - Refactoring guidé

Sous-dossiers pour organiser les commandes

Skills

Qu’est-ce qu’une skill ?

Anatomie d’une skill

Skill 1 : Design System

Composants

Structure de fichier

Review automatique

2. Green - Faire passer le test

3. Refactor - Nettoyer

Cycle

Règles

Quand je demande une feature

Frontmatter et métadonnées

Bien rédiger la description

Partager les commandes en équipe

Convention d’équipe recommandée

Skills personnelles vs commandes partagées

Bonnes pratiques

1. Une commande = une action

2. Soyez explicite dans les instructions

3. Utilisez le Markdown à fond

4. Testez et itérez

5. Documentez les conventions existantes

6. Le placeholder $ARGUMENTS est optionnel

7. Combinez commandes et CLAUDE.md

Le placeholder `$ARGUMENTS`

Exemple 1 : `/commit` - Messages de commit intelligents

Exemple 2 : `/review` - Code review ciblée

Exemple 3 : `/test` - Génération de tests

Exemple 4 : `/deploy` - Workflow de déploiement

Exemple 5 : `/refactor` - Refactoring guidé

6. Le placeholder `$ARGUMENTS` est optionnel