Claude Code : skills pour transformer les tâches répétitives en routines réutilisables

Vous retapez la même suite d'étapes à chaque fois : valider le projet, préparer une PR, faire une revue de diff. Ces procédures n'ont rien à faire dans CLAUDE.md (qui décrit des faits) ni dans .claude/rules/ (qui scope des règles). Leur bon endroit : les skills. Un skill est un SKILL.md rangé dans .claude/skills/<nom>/, invocable par /nom, que Claude ou vous pouvez déclencher quand le besoin apparaît.

Ce que vous allez apprendre

Créer un skill projet invocable par /nom
Choisir entre invocation automatique et manuelle (disable-model-invocation)
Passer des arguments à un skill avec $ARGUMENTS
Savoir quand une procédure devient un skill (vs rester dans CLAUDE.md)

Dans quel contexte utiliser cette fonctionnalité ?

Le signal le plus fiable est la répétition manuelle. Si vous vous surprenez à retaper la même consigne en trois points à chaque session, ou à copier-coller un bloc depuis vos notes, cette consigne mérite d'être figée dans un fichier versionné plutôt que rejouée de mémoire.

Le second signal vient de CLAUDE.md. Ce fichier décrit des faits permanents sur le projet ; dès qu'une de ses sections se met à décrire une suite d'étapes, elle est au mauvais endroit et alourdit chaque démarrage de session sans servir la plupart du temps.

Vous retapez la même procédure (validation, préparation de PR, audit)
Une section de CLAUDE.md a dérivé vers une liste d'étapes à suivre
Vous voulez une routine partagée par l'équipe, invocable d'un simple /
Vous voulez éviter que Claude déclenche seul une action à effet (déploiement, commit)

Prérequis

lab-claude opérationnel, ruff et pytest verts
CLAUDE.md déjà posé (voir configurer CLAUDE.md)
.claude/settings.json de base (voir settings.json avancé)

Structure d'un skill

Un skill est un dossier avec un SKILL.md à l'intérieur. Les skills projet vivent dans .claude/skills/<nom>/ et sont partagés par git.

lab-claude/
├── .claude/
│   └── skills/
│       ├── valider/
│       │   └── SKILL.md
│       └── prep-pr/
│           └── SKILL.md
└── ...

Le SKILL.md a deux parties : un frontmatter YAML qui indique à Claude quand le skill est pertinent, et un corps Markdown qui décrit la procédure.

Si vous utilisiez déjà des commandes personnalisées avant l'arrivée des skills, le point suivant vous concerne directement : les deux formats coexistent, mais ne se valent plus tout à fait.

Les champs de frontmatter les plus utiles

Aucun de ces champs n'est obligatoire : un SKILL.md sans frontmatter fonctionne, il prend le nom de son dossier. Ils servent à répondre à deux questions différentes. description et paths déterminent quand Claude charge le skill de lui-même ; disable-model-invocation et user-invocable déterminent qui a le droit de le déclencher.

Le champ le plus important est description, et c'est aussi le plus mal écrit. Il n'est pas lu par un humain mais par Claude, au moment de décider si le skill est pertinent. Une description qui énumère les situations d'usage (« quand les tests échouent en CI », « avant d'ouvrir une PR ») fonctionne nettement mieux qu'une description qui résume le contenu du fichier.

Champ	Effet
`name`	Nom de la commande `/nom` (sinon dérivé du dossier)
`description`	Guide Claude pour décider quand charger le skill automatiquement
`disable-model-invocation`	`true` pour n'autoriser que l'invocation manuelle `/nom`
`allowed-tools`	Outils pré-approuvés pendant l'exécution du skill
`argument-hint`	Hint d'autocomplétion pour les arguments
`paths`	Glob pour charger automatiquement le skill quand Claude touche un fichier matché

Skill vs CLAUDE.md vs rule : la bonne case

Les trois emplacements ne se distinguent pas par leur contenu mais par le moment où ils sont chargés. CLAUDE.md entre en contexte à chaque session, quoi que vous fassiez. Une rule se charge quand Claude touche un fichier de la zone concernée. Un skill ne se charge que lorsqu'il est invoqué, à la main ou par Claude.

Mettre une procédure dans CLAUDE.md n'est donc pas seulement une erreur de rangement : c'est une consommation de contexte permanente pour quelque chose qui ne sert que ponctuellement.

Contenu	Bon endroit
Fait global ("on utilise FastAPI, Ruff, pytest")	`CLAUDE.md`
Règle ciblée ("les tests utilisent `TestClient`")	`.claude/rules/tests.md`
Procédure à exécuter ("lance ruff, pytest, résume le diff")	`.claude/skills/<nom>/SKILL.md`

Si vous écrivez "1. puis 2. puis 3.", c'est un skill.

Application sur `lab-claude`

Objectif : deux skills utiles au quotidien, /valider (validation complète) et /prep-pr (préparation d'une PR).

Skill 1 : `/valider`

Créez le dossier du skill

cd ~/Projets/lab-claude
mkdir -p .claude/skills/valider

Écrivez SKILL.md

---
name: valider
description: Valide lab-claude avec ruff et pytest, résume les erreurs en priorité
disable-model-invocation: true
allowed-tools: Bash(uv run ruff:*) Bash(uv run pytest:*)
---

Valide le projet en deux étapes et résume.

1. Lance `uv run ruff check .` et note les erreurs (type et fichier)
2. Lance `uv run pytest -q` et note les tests en échec
3. Résume en 3 points :
   - Statut global (vert / rouge)
   - Premier blocage à traiter
   - Commande exacte pour reproduire le blocage

Ne modifie aucun fichier. Si tout est vert, confirme en une ligne.

Testez dans une session
Fenêtre de terminal
```
claude
```
Puis :
```
/valider
```

Pourquoi disable-model-invocation: true ici : /valider est déclenché à la demande. Vous ne voulez pas que Claude lance la validation complète de son propre chef en plein milieu d'une exploration.

Skill 2 : `/prep-pr`

Ce second skill illustre deux mécanismes que le premier n'utilisait pas : le passage d'un argument (la branche cible) et la déclaration d'un argument-hint qui alimente l'autocomplétion. Il reste en lecture seule sur le dépôt : les trois commandes git autorisées consultent l'état, aucune ne le modifie.

La dernière ligne du SKILL.md compte autant que les autres. Interdire explicitement git push évite que Claude enchaîne de lui-même sur l'action irréversible une fois le résumé produit.

Créez le skill
Fenêtre de terminal
```
mkdir -p .claude/skills/prep-pr
```

Écrivez SKILL.md

---
name: prep-pr
description: Prépare une PR pour lab-claude : diff, résumé, message de commit suggéré
disable-model-invocation: true
argument-hint: "[cible] optionnel, sinon main"
allowed-tools: Bash(git diff:*) Bash(git log:*) Bash(git status)
---

Prépare une PR contre la branche cible (par défaut `main`).

Cible : $ARGUMENTS

1. `git status` pour vérifier que rien n'est en attente
2. `git diff <cible>...HEAD --stat` pour lister les fichiers touchés
3. `git log <cible>..HEAD --oneline` pour lister les commits
4. Résume en 5 points max :
   - Intention (quoi, pourquoi)
   - Fichiers significatifs modifiés
   - Ce qui reste à tester manuellement
   - Un titre de PR (≤ 70 caractères)
   - Un corps de PR en 3 bullets

Ne propose pas `git push`. Le push reste une action humaine.

Testez
```
/prep-pr
/prep-pr develop
```

Invocation automatique vs manuelle

Deux champs indépendants contrôlent l'accès au skill, un par déclencheur. disable-model-invocation: true retire le skill à Claude et vous le réserve. user-invocable: false fait l'inverse : le skill disparaît de la liste des / et n'est plus chargé que par Claude, ce qui convient à de la connaissance de fond qu'on ne déclenche jamais à la main.

Le critère de décision n'est pas la complexité du skill mais son effet. Un skill qui lit et résume peut être laissé en accès libre ; un skill qui écrit, déploie, commite ou envoie quelque chose à l'équipe doit rester sous contrôle humain.

Frontmatter	Vous invoquez	Claude invoque	Quand utiliser
défaut	oui	oui	Skill sans effet de bord, Claude peut décider
`disable-model-invocation: true`	oui	non	Actions à effet (`/valider`, `/prep-pr`, `/commit`)
`user-invocable: false`	non	oui	Connaissance de fond jamais invoquée à la main

Règle simple : si le skill change l'état du projet ou engage l'équipe, mettez disable-model-invocation: true.

Passer des arguments

$ARGUMENTS reçoit tout ce qui suit le nom du skill, en une seule chaîne. Pour découper cette chaîne en arguments positionnels, utilisez $1, $2, $3 : la numérotation commence à 1, il n'existe pas de $0.

---
name: resume-fichier
description: Résume un fichier du projet en 5 points
---

Résume $ARGUMENTS en 5 points maximum, sans le modifier.

Usage : /resume-fichier app/main.py.

Tools pré-autorisés pendant le skill

Le champ allowed-tools évite les prompts pendant l'exécution du skill. Il complète le allow du settings.json pour les commandes spécifiques à la procédure.

Erreurs fréquentes

Ces cinq symptômes couvrent la quasi-totalité des skills qui ne se comportent pas comme prévu. Deux d'entre eux sont des problèmes d'emplacement ou de syntaxe, les trois autres viennent du contenu : une description mal calibrée, ou un corps rédigé comme une documentation plutôt que comme une consigne.

Le dernier symptôme est le plus déroutant, parce que rien n'échoue visiblement : le skill est bien chargé, mais Claude le traite comme du contexte informatif. Rédiger à l'impératif (« Lance », « Vérifie », « Résume ») suffit généralement à corriger le tir.

Symptôme	Cause probable	Correction
`/<nom>` introuvable	Frontmatter incorrect ou dossier au mauvais endroit	Vérifier `.claude/skills/<nom>/SKILL.md` exactement
Claude ne déclenche jamais le skill auto	`description` trop vague	Ajouter des mots-clés d'usage réel
Claude déclenche le skill trop souvent	`description` trop large	Restreindre, ou passer à `disable-model-invocation: true`
Le skill redemande une autorisation	Commande non listée dans `allowed-tools`	Compléter `allowed-tools` avec le motif exact
Skill invoqué mais ignoré ensuite	Contenu traité comme guide, pas comme tâche	Formuler en impératif ("Lance", "Résume"), pas descriptif

Checklist de fin de guide

Reprenez ces cinq points sur votre propre dépôt avant de considérer le sujet acquis. Le deuxième est le seul qui se vérifie par l'exécution : un skill qui se charge sans erreur mais ne fait pas ce que son nom annonce reste un skill cassé.

J'ai créé au moins un skill projet dans .claude/skills/<nom>/SKILL.md
Le skill s'invoque avec /<nom> et fait ce qu'il promet
J'ai choisi disable-model-invocation selon le risque
J'ai distingué skill (procédure) vs rule (règle ciblée) vs CLAUDE.md (fait global)
allowed-tools reflète les outils réellement utilisés

À retenir

Un skill capture une procédure invocable à la demande
disable-model-invocation: true pour tout ce qui a un effet ou engage
Skills (procédure) / rules (règle) / CLAUDE.md (fait global) : trois cases distinctes
Les skills sont partagés par git, donc accessibles à toute l'équipe
Gardez SKILL.md sous 500 lignes et déportez le détail dans des fichiers annexes

Pour aller plus loin

Skills avancées : scripts et ressources : L'étape au-dessus : sortir la logique dans un script et charger les ressources à la demande.
Packager et partager ses skills en plugin : La distribution de vos skills à une équipe entière, versionnée et installable.
Subagents : isoler le contexte : Quand une skill devient trop lourde, elle se délègue à un agent au contexte séparé.