Ajouter des Skills à Claude Code : le guide pas à pas

Qu’est-ce qu’un Skill Claude ?

Un Skill Claude est un dossier contenant un fichier SKILL.md (instructions et métadonnées) et, en option, des scripts ou ressources associées, que Claude charge automatiquement quand la description du skill correspond à la tâche demandée. Il rend une compétence réutilisable sans réécrire le prompt à chaque fois, dans Claude Code comme dans l’app Claude.

Concrètement, un Skill résout un problème que tout power-user connaît : tu retapes le même prompt de 15 lignes chaque semaine pour générer un rapport, formater un export CSV ou appliquer une convention de code précise. Avec un Skill, cette logique vit dans un fichier versionné, Claude la découvre tout seul et l’exécute au bon moment. C’est la différence entre un prompt jetable et une capacité qui reste dans ton environnement de travail.

Un Skill n’est ni un prompt système ni un serveur MCP. Le prompt est ponctuel et disparaît à la fin de la conversation. Le MCP connecte Claude à un service externe (base de données, API tierce). Le Skill, lui, encapsule un savoir-faire : des instructions métier, éventuellement accompagnées de scripts exécutables, que Claude va chercher de lui-même selon le contexte.

Si tu veux d’abord solidifier tes bases de prompt avant d’aller plus loin, la méthode pour écrire un bon prompt reste le prérequis logique.

Prérequis

• Claude Code installé et fonctionnel (CLI ou extension IDE)
• Un compte avec accès aux Skills (disponible sur les plans Pro/Team/Enterprise selon la configuration)
• Un éditeur de texte pour écrire du Markdown
• Un cas d’usage précis et récurrent (évite de créer un skill “au cas où”)
• Des notions basiques de bash ou Python si ton skill doit inclure un script

Étape 1 : définir précisément le déclencheur

Avant d’écrire une seule ligne, réponds à cette question : dans quelle situation exacte veux-tu que Claude active ce skill, et dans quelle situation ne veut-il surtout pas s’activer ?

C’est le point le plus mal compris chez les débutants : Claude ne lit pas ton skill en permanence. Il scanne les descriptions de tous les skills disponibles et décide d’en charger un seulement si la description colle à la demande en cours. Une description vague (“aide pour le code”) génère des faux positifs ou, pire, ne se déclenche jamais. Une description précise (“génère un changelog structuré à partir des commits git depuis le dernier tag”) est reconnue immédiatement.

Prenons un cas typique (fictif) : une équipe technique veut standardiser la rédaction de ses pull requests. Le déclencheur pertinent n’est pas “aide pour les PR” mais “rédige la description d’une pull request au format Conventional Commits à partir du diff fourni”. Plus la formulation colle au vocabulaire que l’utilisateur emploiera réellement, plus l’activation est fiable.

Étape 2 : créer la structure de dossier

Un Skill Claude repose sur une arborescence simple :

mon-skill/
  SKILL.md
  scripts/
    generer_changelog.sh
  references/
    format-conventional-commits.md

Le seul fichier obligatoire est SKILL.md. Le reste (scripts, ressources de référence, exemples) est optionnel et s’ajoute selon les besoins réels du skill. Ne mets pas de sous-dossiers inutiles : Claude Code doit pouvoir parcourir la structure sans ambiguïté.

Crée le dossier à la racine de ton espace de skills (voir Étape 4 pour l’emplacement exact) et nomme-le en kebab-case, sans espace ni accent : generer-changelog, pas Générer Changelog.

Étape 3 : rédiger le fichier SKILL.md

Le fichier SKILL.md commence par un frontmatter YAML puis contient les instructions en Markdown classique :

---
name: generer-changelog
description: Génère un changelog structuré (Conventional Commits) à partir des commits git depuis le dernier tag. Utiliser quand on demande un changelog, une release note ou un résumé de commits.
---

# Générer un changelog

## Objectif
Produire un changelog lisible pour une release, groupé par type
(feat, fix, chore, docs) à partir de `git log`.

## Instructions
1. Exécute `scripts/generer_changelog.sh` pour extraire les commits
   depuis le dernier tag.
2. Regroupe les entrées par préfixe Conventional Commits.
3. Ignore les commits `chore(deps)` sauf si `--include-deps` est précisé.
4. Formate le résultat en Markdown avec un titre de version.

## Exemple de sortie attendue
## v2.4.0
### Features
- feat(auth): ajout du login SSO
### Fixes
- fix(cart): correction du calcul de TVA

Deux règles non négociables sur le champ description :

• Elle doit contenir les mots-clés que l’utilisateur emploiera naturellement dans sa demande.
• Elle doit préciser explicitement dans quel contexte le skill s’applique, pour éviter qu’il s’active hors sujet.

Le corps du fichier, lui, s’adresse à Claude comme à un collègue à qui tu délègues une tâche précise : étapes numérotées, format de sortie attendu, cas limites à gérer. Si tu maîtrises déjà la rédaction de prompts structurés, tu reconnaîtras la même logique que dans le guide Claude en 10 prompts, simplement encapsulée dans un fichier persistant.

Étape 4 : placer le skill au bon endroit

L’emplacement détermine la portée du skill :

• Personnel : dans le dossier de configuration Claude Code de ton compte utilisateur. Le skill est disponible sur tous tes projets, mais uniquement pour toi.
• Projet : dans un dossier .claude/skills/ à la racine du repo. Le skill est versionné avec le code, disponible pour toute l’équipe qui clone le projet, et supprimé si le dossier est retiré du repo.
• Organisation (plans Team/Enterprise) : déployé au niveau workspace pour être disponible à tous les membres sans dépendre d’un repo spécifique.

Pour une équipe de développement, le niveau projet est presque toujours le bon choix : le skill vit avec le code qu’il concerne, se met à jour via les pull requests classiques, et disparaît proprement si le projet est archivé. C’est aussi ce qui garde la logique métier lisible et auditable, un point sensible quand des agents codeurs IA interviennent aussi sur le même repo.

Étape 5 : tester et itérer

Un skill mal testé produit deux types d’échecs : il ne se déclenche jamais, ou il se déclenche trop souvent.

1. Lance une demande qui devrait clairement activer le skill et vérifie dans les logs de session que Claude l’a bien chargé.
2. Lance une demande volontairement proche mais hors périmètre pour vérifier qu’il ne se déclenche pas à tort.
3. Si un script est inclus, exécute-le manuellement en dehors de Claude pour éliminer les bugs de script avant de blâmer le déclenchement.
4. Ajuste la description par petites touches : ajoute un synonyme, retire un mot trop générique, précise le contexte d’usage.
5. Documente dans le SKILL.md un exemple de commande qui active le skill, ça sert de test de non-régression pour la prochaine personne qui le modifie.

Cette phase de test ressemble beaucoup au travail d’affinage qu’on fait sur n’importe quel prompt récurrent : les erreurs de prompt classiques (formulation ambiguë, contexte manquant) se retrouvent à l’identique dans une description de skill mal calibrée.

Pièges courants

• Description trop large : “aide pour les tests” déclenche le skill sur n’importe quelle question liée au code. Sois spécifique sur le type de test, le framework, le déclencheur métier.
• Trop de skills qui se chevauchent : si trois skills répondent à des descriptions proches, Claude hésite ou en charge le mauvais. Fusionne ou différencie clairement.
• Scripts non exécutables : un script sans droits d’exécution (chmod +x) ou avec un chemin relatif cassé fait échouer le skill silencieusement. Teste-le en ligne de commande d’abord.
• Skill jamais mis à jour : un skill qui documente une convention de code obsolète devient une source d’erreurs plutôt qu’un gain de temps. Traite-le comme du code : revue et versioning inclus.
• Confusion skill / connaissance générale : ne crée pas un skill pour ce que Claude sait déjà faire nativement. Réserve les skills aux workflows propres à ton équipe ou ton produit.
• Placement au mauvais niveau : un skill personnel qui devrait être partagé avec l’équipe finit par créer des incohérences entre collègues. Si la logique concerne le projet, mets-la dans .claude/skills/ du repo, pas dans ta config perso.

Un skill bien conçu se juge à une seule question : est-ce que Claude l’active exactement quand il le faut, et jamais quand il ne le faut pas. Si la réponse est oui après tes tests, le skill est prêt à vivre dans le repo comme n’importe quelle autre pièce de configuration versionnée.