Skills Claude Code efficaces : guide pratique

Les skills sont la fonctionnalité la plus sous-estimée de Claude Code. J’en utilise des dizaines qui couvrent tout, du commit Git à la création d’articles de blog. La plupart des développeurs n’en ont aucun, ou un ou deux copiés depuis un tutoriel.

Cet article montre comment écrire des skills qui fonctionnent en production : la structure, le mécanisme de chargement, les patterns que j’ai identifiés après des mois d’itération, et les erreurs courantes.

Ce qu’est un skill

Un skill est un dossier contenant un fichier SKILL.md. Le fichier combine un frontmatter YAML (métadonnées) et un corps Markdown (instructions). Quand l’utilisateur tape /nom-du-skill ou formule une requête qui correspond à la description, Claude charge les instructions et les suit. La documentation officielle couvre l’installation et la syntaxe de base.

commit-push/
  SKILL.md          # requis : métadonnées + instructions
  references/       # optionnel : docs détaillées
  scripts/          # optionnel : code exécutable
  assets/           # optionnel : templates, fichiers statiques

Le format SKILL.md est un standard ouvert créé par Anthropic et adopté par d’autres produits agents comme Cursor. Un skill écrit pour Claude Code fonctionne tel quel dans ces outils.

Progressive disclosure : pourquoi ça compte

Le mécanisme de chargement est l’aspect le plus important à comprendre. Sans lui, on écrit des skills trop gros qui gaspillent du contexte, ou trop vagues qui ne se déclenchent pas.

Le chargement se fait en trois niveaux :

Niveau 1 - Découverte (~100 tokens par skill). Seuls le name et la description du frontmatter sont injectés dans le system prompt au démarrage de chaque session. Claude sait que le skill existe et quand il s’applique. Même avec des dizaines de skills actifs, ça ne représente que quelques milliers de tokens - négligeable dans un contexte de 200K.

Niveau 2 - Activation (<5 000 tokens). Quand la requête de l’utilisateur correspond à la description d’un skill, Claude lit le corps complet du SKILL.md. C’est là que vivent les instructions détaillées, les workflows pas-à-pas, et les checklists.

Niveau 3 - Exécution (à la demande, taille illimitée). L’agent lit les fichiers du dossier references/ ou exécute les scripts du dossier scripts/ seulement quand les instructions du niveau 2 le demandent. Un skill de blog peut avoir 20 fichiers de référence, mais Claude n’en charge que 2 ou 3 par exécution.

La conséquence pratique : le corps du SKILL.md doit rester sous 5 000 tokens. Tout ce qui dépasse doit aller dans references/. Si le skill est trop gros, Claude charge des milliers de tokens de contexte à chaque activation, même quand il n’a besoin que d’une fraction.

Anatomie du SKILL.md

Voici la structure minimale :

---
name: mon-skill
description: |
  Ce que fait ce skill ET quand l'utiliser.
  Inclure les phrases déclencheuses en français et en anglais.
---

# Mon Skill

## Workflow
1. Première étape
2. Deuxième étape
3. Troisième étape

## Format de sortie
Ce que l'utilisateur doit recevoir en retour.

Le frontmatter : le contrat de routage

Le frontmatter est le composant le plus critique. La description est le seul texte que Claude voit avant de décider s’il active le skill. Si elle est vague, le skill ne se déclenchera pas.

Contraintes techniques :

name en minuscules avec tirets uniquement, 1-64 caractères
name doit correspondre exactement au nom du dossier parent
Du YAML invalide empêche silencieusement le chargement - pas d’erreur, le skill disparaît

Voici la description d’un de mes skills en production :

name: commit-push
description: |
  Commit all changes with an auto-generated conventional commit message
  and push to remote, all in one step.
  Use when: "commit & push", "commit and push", "commit push",
  "/commit-push", "commit et pousse", "pousse ça", "fais un commit
  et push", "commit tout".

Trois éléments à noter :

Ce que ça fait - “commit all changes with auto-generated conventional commit message and push”
Quand l’utiliser - liste explicite de phrases déclencheuses
Bilingue - les déclencheurs sont en anglais et en français

Si je n’avais écrit que “Commit and push changes”, le skill se déclencherait sur “commit and push” mais pas sur “pousse ça” ou “commit tout”.

Le corps : garder ça léger

Le corps du SKILL.md contient le workflow que Claude doit suivre. Voici un extrait simplifié de mon skill /lint-check :

# Lint Check

Run the full Rust lint pipeline and auto-fix errors.

## Workflow

1. Run `cargo fmt -- --check` to detect formatting issues
2. If formatting issues found, run `cargo fmt` to fix them
3. Run `cargo clippy -- -D warnings` to detect lint issues
4. If clippy issues found, fix them one by one
5. Run `cargo check` to verify compilation
6. If errors remain after 3 fix attempts, stop and report

## Error handling

| Scenario | Action |
|----------|--------|
| cargo fmt fails | Report the error, do not continue |
| clippy warns but compiles | Fix warnings, re-run |
| cargo check fails | Show the error, suggest a fix |

Le skill fait 30 lignes, pas 300. Il dit quoi faire, dans quel ordre, et comment réagir aux erreurs. Claude n’a pas besoin qu’on lui explique ce qu’est cargo clippy - il le sait déjà.

Deux philosophies de design

Pattern A : wrappers d’outils

Le skill est un wrapper fin sur un CLI ou un script déterministe. La logique vit dans le code, le skill se contente de l’orchestrer.

Exemples dans mon setup :

/lint-check orchestre cargo fmt, cargo clippy, cargo check
/commit-push orchestre git status, git diff, git log, git add, git commit, git push
/seo-scan orchestre un crawler SEO et met à jour un fichier de suivi

MCP RTK est un bon exemple de ce pattern : le skill orchestre un proxy de filtrage de tokens via des commandes CLI, sans logique dans la prose.

Pattern B : disciplines cognitives

Le skill encode une méthodologie que l’agent doit suivre. C’est du pur prompt engineering - il n’y a pas de script à exécuter, juste un processus de réflexion.

Exemples :

/systematic-debugging impose une méthodologie de debug en 5 étapes (reproduire, isoler, hypothèse, vérifier, corriger)
/security-audit définit une checklist OWASP top 10 avec des patterns à rechercher par catégorie

Le pattern B est plus difficile à bien écrire. La tentation est de sur-expliquer. Claude sait debugger - le skill ajoute une structure au processus, pas des connaissances.

Patterns pour des skills efficaces

Après des mois d’itération, voici les patterns qui fonctionnent.

Bash d’abord, prose ensuite

Un bloc de code que l’agent peut exécuter bat un paragraphe décrivant quoi faire.

Mal :

Vérifier s'il y a des fichiers modifiés non commités dans le dépôt
git actuel en utilisant la commande git status.

Bien :

1. Run `git status` to check for uncommitted changes

Claude sait ce que git status fait. La version courte est plus claire et plus fiable.

State-check avant action

Toujours vérifier l’état courant avant de modifier quoi que ce soit. Sans ça, Claude agit sur des hypothèses et casse des choses.

## Workflow
1. Run `git status` to verify clean working tree
2. Run `git log --oneline -5` to confirm current branch
3. Only then: create the feature branch

Boucles de validation

Après chaque action, vérifier que le résultat est correct avant de passer à la suivante. Mon skill /dev-pipeline le fait à chaque étape :

4. Run `cargo clippy -- -D warnings`
5. If clippy reports errors:
   a. Fix the errors
   b. Re-run clippy
   c. If errors persist after 3 attempts, stop and report
6. Only if clippy passes: proceed to tests

Sans boucle de validation, Claude enchaîne les étapes même quand une échoue. Il finit par “compléter” un pipeline où chaque étape a échoué.

Composer des primitives

Ne pas bundler des workflows entiers dans un seul skill. Composer des skills simples.

Mon skill /dev-pipeline ne réimplémente pas le linting - il appelle /lint-check. Il ne réimplémente pas le commit - il appelle /commit-push. Chaque skill fait une chose, et les workflows composent ces primitives.

# Dev Pipeline

1. Plan the implementation (use EnterPlanMode)
2. Implement the changes
3. Run `/lint-check` to verify code quality
4. Run tests
5. Run `/commit-push` to commit and push

Documenter les formats de sortie

L’agent doit savoir exactement ce qu’il produit. Sans spécification de sortie, Claude improvise un format différent à chaque exécution.

## Output format

Deliver a summary with:
- Files modified: list of paths
- Tests: pass/fail count
- Lint: pass/fail with details
- Commit: the conventional commit message used

Anti-patterns

Ne pas ré-enseigner ce que le modèle sait

# Mauvais
JSON (JavaScript Object Notation) est un format de données
structuré utilisé pour l'échange de données...

# Bon
Generate a JSON response matching the schema in references/schema.md.

Claude sait ce qu’est JSON. Chaque token gaspillé en pédagogie inutile est un token de contexte perdu.

Ne pas écrire de descriptions vagues

# Mauvais - ne se déclenchera presque jamais
name: helper
description: Aide avec des trucs de dev

# Bon - déclencheurs clairs et spécifiques
name: lint-check
description: |
  Run the full Rust lint pipeline (cargo fmt, clippy, check)
  and auto-fix errors. Trigger on: "lint check", "lance le lint",
  "cargo fmt && cargo clippy", "vérifie le code Rust".

La description vague fait que Claude ne sait pas quand activer le skill. Il a des dizaines de descriptions à comparer avec la requête de l’utilisateur - la précision est essentielle.

Ne pas créer de mega-skills monolithiques

Un skill = une capacité. Si la description contient “et” entre deux actions indépendantes, c’est probablement deux skills.

Mon premier /dev-pipeline faisait 500 lignes avec tout inline : linting, tests, review, commit, push, création de MR. Aujourd’hui il fait 40 lignes et compose cinq skills spécialisés.

Ne pas ignorer les modes d’échec

Documenter ce qui peut mal tourner et comment réagir. Sans ça, Claude s’arrête ou invente une solution quand une commande échoue.

## Error handling

| Scenario | Action |
|----------|--------|
| No git remote configured | Stop, ask user to configure |
| Pre-commit hook fails | Fix the issue, retry once |
| Push rejected (not fast-forward) | Run `git pull --rebase`, retry |
| Merge conflict after rebase | Stop, show conflicts to user |

Ne pas utiliser de chemins absolus

# Mauvais
Read /Users/thomas/.claude/scripts/validate.py

# Bon
Read scripts/validate.py from the skill directory

Les chemins absolus cassent quand le skill est partagé ou utilisé sur une autre machine. Les chemins relatifs au dossier du skill ou les variables d’environnement sont portables.

Skills projet-spécifiques

Les skills les plus puissants sont ceux adaptés à un projet spécifique. Dans mon setup, le projet Netir a six skills qui encodent les conventions du projet :

# netir-cpm/SKILL.md (extrait)
name: netir-cpm
description: |
  Commit, push et création de Merge Request GitLab pour Netir.
  Conventions appliquées : assignee ThomasTartrau,
  reviewer netir-bot, label "MR::en attente de review".
  Use when: "/cpm", "crée la MR", "commit push mr".

La différence avec le /cpm générique : les conventions Netir (labels, reviewer, assignee) sont codées en dur. Je n’ai pas besoin de les re-spécifier à chaque MR.

Un autre exemple : /netir-qa-swarm lance quatre agents de review en parallèle, chacun avec un angle différent :

## Agents

| Agent | Focus |
|-------|-------|
| Architecture | Couches, séparation des responsabilités |
| Sécurité | OWASP, injections, auth, rate limiting |
| Qualité Rust | Idiomes, clippy, performance, unwrap |
| Patterns métier | Cohérence domaine, naming, edge cases |

Chaque agent a des instructions spécifiques au codebase Netir (la stack Axum/SQLx, les conventions de nommage, les patterns d’erreur). Un skill de review générique ne connaît pas ces conventions.

Tester un skill

Le test le plus important : invoquer le skill avec des formulations variées et vérifier qu’il se déclenche.

Les utilisateurs ne disent pas “/invoke-my-skill”. Ils disent :

“commit et pousse”
“lance le lint”
“fais une MR”
“check the code”

Si ces formulations naturelles ne déclenchent pas le skill, la description est à revoir. J’ajoute les formulations qui échouent dans les déclencheurs du frontmatter.

Le deuxième test : vérifier que les instructions produisent le résultat attendu sur un cas réel. Pas de dry-run imaginaire - exécuter le skill sur un vrai projet et vérifier la sortie.

Checklist avant de publier un skill

Avant de déployer un nouveau skill dans mon repo de configuration :

Le name correspond exactement au nom du dossier
La description inclut des déclencheurs en français et en anglais
Le corps du SKILL.md fait moins de 5 000 tokens
Les détails sont dans references/, pas dans le corps
Les modes d’échec sont documentés
Le format de sortie est spécifié
Pas de secrets, tokens ou chemins absolus dans le skill
Les commandes destructives sont protégées par des confirmations
Le skill a été testé avec au moins 3 formulations différentes

Ce que j’ai appris

La description est le routeur. Investir autant de temps sur la description que sur le corps. Un skill avec des instructions parfaites mais une description vague ne se déclenchera jamais.

Le code bat la prose. Un script déterministe est toujours plus fiable que des instructions ambiguës. Si une tâche a une seule bonne réponse, mettre la logique dans un script, pas dans du Markdown.

Le contexte le moins cher est celui qu’on ne charge pas. Le progressive disclosure existe pour une raison. Un skill de 200 lignes qui pourrait en faire 40 avec des références gaspille du contexte à chaque activation.

Tester avec des formulations réelles. Les utilisateurs ne tapent pas des commandes propres. Ils écrivent “commit ça”, “pousse”, “lint” - les déclencheurs doivent couvrir ces variantes.

Les skills transforment Claude Code d’un assistant générique en un outil adapté à votre workflow spécifique. La page de mes projets liste les autres outils que j’ai construits autour de cet écosystème.