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é ?

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.

Les champs de frontmatter les plus utiles

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

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`

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

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. Pour des arguments positionnels : $0, $1, $2.

---
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

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

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

Prochaines étapes

Hooks Claude Code Automatiser le rituel de validation autour des événements Edit, Write, Stop

Workflows concrets Enchaîner rules, skills et hooks sur des cas réels (debug, refactor, PR)

Rules ciblées Compléter les skills avec des règles ciblées par zone