Skills dans Claude Code : Apprendre de nouveaux tours à un vieux chien

Le problème de tout répéter

Avez-vous déjà dû expliquer la même chose à quelqu’un vingt fois ? Imaginez maintenant cela avec un robot qui en plus perd sa mémoire toutes les quelques heures.

“Non, Claude, le commit doit d’abord passer les tests.” “Claude, je t’ai déjà dit d’utiliser le format type: description.” “N’ajoute pas d’emojis !”

C’était mon quotidien jusqu’à ce que je découvre les Skills. Pour être clair : ce sont des instructions que vous écrivez une fois et que Claude suit pour toujours. Comme dresser un chien, mais sans les croquettes.

Que sont les Skills

Depuis la version 2.1.3, Claude Code a fusionné les anciens slash commands avec quelque chose de plus puissant : les Skills. Ce sont des fichiers Markdown avec des instructions que Claude peut exécuter de deux façons :

1. Manuellement : quand vous écrivez /mon-skill
2. Automatiquement : quand Claude détecte qu’il devrait l’utiliser

Ce second point est la magie. Vous n’avez plus à vous souvenir d’invoquer la commande. Si vous avez un skill qui dit “utiliser quand l’utilisateur termine une tâche et qu’il y a des changements non commités”, Claude le fera tout seul.

C’est comme avoir un majordome qui sait quand débarrasser la table sans qu’on le lui demande.

Où ils vivent

~/.claude/skills/          # Personnels (tous vos projets)
.claude/skills/            # Du projet (partagés avec l'équipe)
~/.claude/commands/        # Ancien système, fonctionne encore
.claude/commands/          # Ancien système, fonctionne encore

Si vous voulez que seul vous utilisiez le skill, vous le mettez dans votre répertoire home. Si vous voulez que toute l’équipe l’ait, vous le commitez dans le dépôt. C’est aussi simple que ça.

Anatomie d’un Skill

Un skill est un fichier Markdown avec un frontmatter YAML et ensuite le contenu :

---
name: mon-skill
description: Brève description de ce qu'il fait
---

# Instructions

Ce que Claude doit faire quand ce skill est invoqué.

C’est le minimum. Mais le frontmatter a pas mal d’autres options qui valent la peine d’être connues.

Champs obligatoires

name

L’identifiant du skill. Seulement minuscules, chiffres et tirets (max. 64 caractères). Doit correspondre au nom du fichier ou du répertoire.

name: check-types      # ✓ valide
name: Check_Types      # ✗ invalide (majuscules et underscore)

description

C’est le champ le plus important. Claude l’utilise pour deux choses :

1. Décider quand auto-invoquer le skill
2. Comprendre ce qu’il doit faire

Maximum 1024 caractères. Incluez des mots-clés que l’utilisateur dirait naturellement.

# Mauvais - trop vague
description: Fait des choses avec les commits

# Bon - spécifique et avec des déclencheurs
description: >
  Crée des commits git en vérifiant type-check, lint et tests.
  Utiliser quand l'utilisateur dit "commit", "commite", ou termine une tâche
  avec des changements en attente.

Champs optionnels

model

Force un modèle spécifique pour ce skill. Utile pour des tâches qui nécessitent plus de capacité.

model: opus    # Pour les audits de sécurité, refactoring complexe
model: sonnet  # Équilibre entre capacité et coût
model: haiku   # Pour les tâches simples et rapides

Si vous ne le spécifiez pas, il utilise le modèle de la conversation actuelle.

allowed-tools

Restreint les outils que Claude peut utiliser. Critique pour les skills en lecture seule ou sécurisés.

# Peut seulement lire, pas modifier
allowed-tools:
  - Read
  - Grep
  - Glob

# Peut seulement exécuter des commandes spécifiques
allowed-tools:
  - Bash(git:*)      # Seulement les commandes git
  - Bash(uv:*)       # Seulement les commandes uv
  - Read

Exemple pratique : un skill d’analyse qui ne doit rien toucher :

---
name: analyze-deps
description: Analyse les dépendances du projet sans rien modifier
allowed-tools:
  - Read
  - Grep
  - Bash(uv pip list:*)
---

context: fork

Exécute le skill dans un sous-agent isolé avec son propre contexte. L’historique de la conversation principale n’est pas contaminé.

context: fork

Utile pour des opérations complexes à plusieurs étapes où vous ne voulez pas encombrer le chat de bruit.

agent

Ne fonctionne qu’avec context: fork. Définit quel type d’agent exécute le skill.

context: fork
agent: Explore    # Agent d'exploration rapide
agent: Plan       # Agent de planification

user-invocable

Contrôle si il apparaît dans le menu des / (slash commands). Par défaut c’est true.

user-invocable: false  # Caché du menu, mais Claude peut l'utiliser

Utile pour les skills internes qui ne devraient s’activer qu’automatiquement.

disable-model-invocation

Empêche Claude d’invoquer le skill de son propre chef. Seul vous pouvez l’activer avec /nom.

disable-model-invocation: true

Utile pour des opérations destructrices ou coûteuses qui nécessitent une décision humaine explicite.

hooks

Définit des hooks qui s’exécutent pendant le cycle de vie du skill. Supporte PreToolUse, PostToolUse et Stop.

hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-input.sh $TOOL_INPUT"
          once: true

Variables de substitution

Dans le contenu du skill vous pouvez utiliser :

Tableau récapitulatif

Exemple complet

---
name: security-audit
description: >
  Audit de sécurité OWASP. Utiliser quand l'utilisateur demande de réviser
  la sécurité, chercher des vulnérabilités, ou avant de déployer en production.
model: opus
allowed-tools:
  - Read
  - Grep
  - Glob
user-invocable: true
disable-model-invocation: true  # Seulement manuel, c'est coûteux
---

# Audit de Sécurité

[instructions...]

Pour la référence complète, consultez la documentation officielle des Agent Skills.

Texte libre ou code déterministe ?

C’est la question cruciale : si les skills sont en Markdown, cela signifie-t-il que Claude “interprète” toujours ce que vous écrivez ? Puis-je faire quelque chose de vraiment prévisible ?

La réponse courte : les skills sont aussi déterministes que vous les écrivez.

Pensez à un spectre :

Vague/Flexible ──────────────────────────► Déterministe
"révise le code"        "exécute ces 3 commandes dans l'ordre"

Skill flexible (Claude décide)

---
name: review
description: Révise le code pour chercher des problèmes
---

Analyse le code et suggère des améliorations.

Ici Claude a toute liberté. Il peut regarder ce qu’il veut, suggérer ce qui lui semble bon. Utile pour l’exploration, dangereux pour les processus critiques.

Skill déterministe (script déguisé)

---
name: check
description: Vérifications de qualité obligatoires
allowed-tools:
  - Bash
---

Exécuter **exactement** ces commandes dans l'ordre :

1. `uv run basedpyright src/`
2. `uv run ruff check src/`
3. `uv run pytest -x`

## Règles

- **NE PAS interpréter** les erreurs de façon créative
- **NE PAS continuer** si l'une échoue
- **NE PAS suggérer** de corrections automatiques
- Rapporter seulement : ✓ réussi / ✗ échoué avec sortie

C’est essentiellement un script de 3 lignes. Claude n’a pas de marge pour être créatif. Il exécute, rapporte, point final.

Skill avec logique conditionnelle

---
name: release
description: Prépare la release du projet
---

## Étape 1 : Vérifier la branche

```bash
git branch --show-current

• Si ce n’est PAS main → ARRÊTER avec “Seulement depuis main”

Étape 2 : État propre

git status --porcelain

• S’il y a une sortie → ARRÊTER avec “Changements non commités”

Étape 3 : Bump + push

uv run bump2version patch
git push && git push --tags

Il y a de la logique de branches ici, mais c'est toujours déterministe : les conditions sont explicites.

### Skill qui invoque un vrai script

Si vous avez besoin d'une vraie logique complexe (boucles, parsing, APIs), mettez le code dans un script et que le skill ne fasse que l'exécuter :

.claude/skills/deploy/ ├── SKILL.md └── deploy.sh

**SKILL.md :**
```markdown
---
name: deploy
description: Déploie en production
---

Exécuter :

```bash
bash .claude/skills/deploy/deploy.sh

Rapporter le résultat. NE PAS modifier le script.

**deploy.sh :**
```bash
#!/bin/bash
set -e
uv run pytest || exit 1
hugo --minify
rsync -avz public/ user@server:/var/www/

Le meilleur des deux mondes : la logique complexe vit en Bash/Python où elle appartient, et le skill n’est que le déclencheur.

Quand utiliser chaque approche

Exemple concret : le skill de commit

C’est celui que j’utilise le plus. Avant je devais me rappeler : “bon, exécute les tests, puis le linter, puis le type-check, et seulement après commite”. Maintenant je dis simplement “commite” et Claude fait tout seul.

---
name: commit
description: Crée des commits git avec vérification obligatoire de qualité.
  Exécute type-check, lint et tests avant de commiter.
---

# Commit

## Quand Utiliser (Automatique)

Appliquer quand :
- L'utilisateur dit "commit", "commite", "sauve les changements"
- L'utilisateur termine une tâche et il y a des changements non commités

## Interdit

- Commiter sans exécuter les vérifications
- Demander confirmation (fais-le simplement)
- Ajouter Co-Authored-By
- Utiliser des emojis dans les messages de commit

## Processus

### Phase 1 : Détecter les changements

```bash
git diff --name-only HEAD

Phase 2 : Vérifications OBLIGATOIRES

uv run basedpyright src/
uv run ruff check src/
uv run pytest

Si l’une échoue, NE PAS continuer.

Phase 3 : Créer le commit

1. git add -A
2. Analyser les changements
3. Générer le message : type: description
4. git commit

Vous voyez la section "Quand Utiliser" ? C'est ce qui permet l'auto-invocation. Claude lit ça et pense : "ah, l'utilisateur vient de dire 'c'est bon', il y a des changements en attente, je devrais utiliser ce skill".

## Autre exemple : archivage des tâches

Si vous utilisez un fichier `TASKS.md` pour tracker ce que vous faites (je le faisais avant Beads), ce skill vous nettoie les tâches complétées automatiquement :

```markdown
---
name: archive-tasks
description: Archive les tâches complétées de TASKS.md vers TASKS-DONE.md.
  Utiliser automatiquement quand TASKS.md a beaucoup de tâches complétées
  ou dépasse 20K tokens.
---

# Archive Tasks

## Quand Utiliser (Automatique)

- TASKS.md a plus de 50 tâches complétées `[x]`
- TASKS.md dépasse 20,000 tokens
- L'utilisateur mentionne que TASKS.md est trop gros

## Processus

1. Lire `docs/llm/TASKS.md`
2. Identifier les tâches complétées (`[x]`)
3. Déplacer vers `docs/llm/TASKS-DONE.md` avec date
4. Supprimer de TASKS.md
5. Rapporter combien ont été archivées

## Règles

- **NE PAS supprimer** les tâches en attente `[ ]`
- **PRÉSERVER** le contexte (section parent)
- **AJOUTER** la date d'archivage

Le beau c’est que vous n’avez pas à vous en souvenir. Claude voit que TASKS.md est énorme et agit.

Conseils pour écrire de bons skills

1. Descriptions spécifiques

# Mauvais
description: Fait des choses avec les commits

# Bon
description: Crée des commits git en vérifiant type-check, lint et tests.
  Bloque s'il y a des erreurs.

2. Définir quand appliquer

## Quand Utiliser Ce Skill (Automatique)

Appliquer automatiquement quand :
- L'utilisateur dit "commit" ou "sauve les changements"
- Il y a des changements staged prêts
- L'utilisateur termine une tâche

3. Être explicite avec les interdictions

Claude tend à vouloir être poli et demander confirmation. Si vous ne voulez pas ça, dites-le clairement :

## Interdit

- Demander confirmation (JAMAIS)
- Ajouter Co-Authored-By
- Utiliser des emojis

4. Utiliser model: opus pour l’important

Si le skill fait quelque chose de critique (audit de sécurité, refactoring complexe), forcez le modèle le plus capable :

---
name: owasp
description: Audit de sécurité OWASP
model: opus
---

5. Restreindre les outils si nécessaire

Parfois vous voulez un skill qui ne fait que lire, sans rien modifier :

---
name: readonly-analysis
description: Analyse le code sans le modifier
allowed-tools:
  - Glob
  - Grep
  - Read
---

Skills simples vs complexes

Un skill simple est un seul fichier :

.claude/skills/review.md

Un skill complexe est un répertoire avec des ressources :

.claude/skills/deploy/
├── SKILL.md                 # Instructions
├── templates/
│   └── k8s-deployment.yaml
└── scripts/
    └── healthcheck.sh

Claude peut lire les fichiers du répertoire comme contexte additionnel.

Ce que j’utilise

La différence avec les commands legacy

Les commands continuent de fonctionner, mais les skills sont strictement meilleurs. Si vous avez de vieux commands, pas besoin de les migrer, mais pour les nouvelles choses utilisez des skills.

Conclusion

Les skills sont essentiellement de la programmation, mais en langage naturel. Vous définissez ce que vous voulez qui arrive, quand, et avec quelles restrictions. Claude fait le reste.

Le mieux c’est qu’ils sont versionnés avec votre code. Si vous travaillez en équipe, tout le monde a les mêmes skills. Si vous changez quelque chose, ça reste dans l’historique git.

Ça vaut-il la peine de l’effort de les écrire ? Si vous répétez la même chose plus de trois fois, absolument. Chaque skill que vous écrivez est une conversation que vous n’aurez plus jamais à avoir.

Maintenant si vous m’excusez, je dois aller apprendre à Claude que “refactoriser” ne signifie pas “réécrire tout depuis zéro”.

Résumé : Les skills sont des instructions en Markdown que Claude Code exécute manuellement ou automatiquement. Ils peuvent être aussi flexibles ou déterministes que vous le souhaitez : depuis “analyse ça” jusqu’à des scripts déguisés en prose. Si vous avez besoin d’une logique complexe, invoquez des scripts externes. Ils vivent dans .claude/skills/ et sont versionnés avec votre code.

Cet article a été rédigé en espagnol et traduit avec l’aide de l’IA.