Claude Code skill : créer un skill de A à Z (exemple concret)

ParPhil MAJ

En bref

Un claude code skill est un fichier Markdown structuré (frontmatter YAML + instructions) qui transforme une instruction répétitive en commande invocable via un slash-command.

Versionné dans le dépôt Git, il se partage automatiquement avec toute l’équipe sans configuration individuelle.

Un premier skill fonctionnel se crée en 15 à 20 minutes ; l’article inclut un exemple complet d’audit de pull request.

Des plateformes comme SkillsMP et claudeskills.info proposent des skills prêts à l’emploi, à évaluer selon des critères précis.

Limites à connaître : pas d’accès temps réel à des données externes, pas de mémoire persistante native entre sessions.

Chaque semaine, nous revenons sur la même scène chez nos clients : un développeur ou un responsable marketing retape les mêmes instructions dans Claude, session après session, parce que la configuration précédente a disparu. Un claude code skill règle ce problème à la racine. Ce n’est pas une astuce de power user, c’est un mécanisme officiel d’Anthropic qui transforme une instruction répétitive en commande automatisée Claude, stockée, versionnée et partageable avec l’équipe. Cet article vous explique comment en créer un de zéro, avec un exemple tiré d’une mission réelle.

Sommaire

Comprendre un skill Claude Code : FAQ technique

Cinq questions récurrentes sur les skills Claude Code — définition, structure, hébergement, test, limites. Chaque section se déplie indépendamment selon votre besoin.

Un skill Claude Code est un fichier Markdown placé dans .claude/skills/ à la racine de votre projet. Son nom de fichier (sans extension) devient directement la commande slash : deploy.md donne /deploy dans le chat.

Ce n’est pas un simple prompt sauvegardé dans un Notion ou un doc partagé. Un skill encode quatre choses à la fois :

  • Quoi faire : les instructions précises, avec des exemples si le comportement attendu n’est pas évident
  • Dans quel contexte : quels fichiers lire en priorité, quelles conventions du projet respecter
  • Quels outils utiliser : Read, Edit, Bash, WebFetch, selon ce dont la tâche a réellement besoin
  • Comment structurer la réponse : format de sortie, niveau de détail, éléments obligatoires

Ce qui change concrètement par rapport à un prompt partagé dans un doc : le skill est versionné en Git avec le code. Toute l’équipe dispose du même comportement au premier git clone, sans étape manuelle de copier-coller ni risque de version stale sur une machine ou l’autre.

Un seul champ est vraiment indispensable dans le frontmatter YAML : description. C’est le texte qui apparaît dans /help et qui aide Claude Code à décider si votre skill doit être chargé selon le contexte de la session.

---
description: >
Génère un rapport de sécurité sur les changements en attente.
À utiliser quand le code touche à l'authentification, aux inputs
utilisateur ou aux appels réseau externes.
---
Passe en revue les fichiers modifiés depuis main.
Pour chaque fichier, identifie les vecteurs d'injection, les
appels réseau non authentifiés, et les données sensibles exposées.
Format de sortie : liste à puces, une ligne par finding.

Champs optionnels qui méritent d’être connus :

  • model: sonnet — force un modèle spécifique pour ce skill (utile pour les tâches qui demandent un raisonnement long)
  • isolation: worktree — exécute le skill dans un worktree Git isolé, recommandé pour les refactorings qui modifient beaucoup de fichiers
  • tools: [Read, Bash] — restreint les outils disponibles (principe de moindre privilège : un skill de lecture n’a pas besoin d’Edit)

En l’absence de frontmatter, Claude Code crée quand même la commande slash à partir du nom du fichier, mais sans description visible dans /help. En pratique, personne ne sait que le skill existe ni quand l’invoquer.

Deux emplacements possibles, deux portées très différentes :

EmplacementPortéeVersionné GitUsage recommandé
.claude/skills/Ce projet uniquementOuiSkills métier, workflows spécifiques au projet, conventions d’équipe
~/.claude/skills/Tous les projets de la machineNon (local)Skills personnels universels, préférences de réponse cross-projets

Dans la grande majorité des cas, l’emplacement projet (.claude/skills/) est le bon choix. L’emplacement global est pratique pour un développeur solo, mais devient vite une source de divergence en équipe : chacun a ses skills locaux, personne ne sait exactement quelles commandes existent sur la machine du voisin, et les comportements divergent silencieusement.

Bonne pratique terrain : listez tous les skills disponibles dans votre CLAUDE.md avec une ligne par skill et son contexte d’invocation. Ça sert de documentation vivante et aide Claude Code à suggérer le bon skill au bon moment.

Le cycle de test est rapide : les modifications au fichier Markdown sont prises en compte immédiatement, sans redémarrage de Claude Code.

  1. Créez ou modifiez le fichier .claude/skills/mon-skill.md
  2. Dans Claude Code, tapez /mon-skill dans le chat
  3. Observez : Claude exécute-t-il les bonnes actions ? Lit-il les bons fichiers ? Le format de réponse correspond-il à ce que vous attendez ?
  4. Modifiez les instructions dans le fichier Markdown selon ce que vous observez
  5. Relancez /mon-skill — les changements sont actifs immédiatement

Pièges classiques rencontrés en production :

  • Instructions trop vagues : « analyse le code » laisse Claude improviser. Précisez : « lis les fichiers modifiés depuis main, liste les appels réseau sans authentification, format liste à puces, maximum 10 findings »
  • Scope d’outils trop large : sans restriction tools:, Claude peut modifier des fichiers alors que vous vouliez uniquement un rapport de lecture. Restreignez explicitement
  • Contexte manquant : si le skill doit respecter les conventions du projet, référencez explicitement CLAUDE.md ou README.md dans les instructions
  • Test sur un repo trop propre : testez sur un état de repo réaliste (branches en cours, fichiers modifiés, dette technique), pas sur un état vierge qui ne reflète pas l’usage réel

Un skill n’est pas un script déterministe. C’est une instruction interprétée par un LLM, avec tout ce que ça implique en matière de variabilité.

  • Pas de state persistant entre sessions : chaque invocation repart d’une ardoise vierge. Mémoriser un résultat d’une session à l’autre exige de l’écrire explicitement dans un fichier ou une base de données — le skill ne le fait pas tout seul
  • Logique conditionnelle limitée : deux ou trois branches conditionnelles fonctionnent bien. Au-delà (cinq conditions imbriquées et plus), le modèle peut prendre des chemins inattendus ou ignorer certaines branches
  • Traitement de masse fragile : un skill qui parcourt une liste de 200 fichiers peut dériver, sauter des éléments, ou dépasser la fenêtre de contexte sans prévenir. Pour les traitements volumiques, préférez un script en boucle que le skill appelle via Bash
  • Comportement variable selon le modèle : une formulation qui donne d’excellents résultats sur Sonnet peut produire quelque chose de différent sur un autre modèle ou une version ultérieure. Les instructions ambiguës amplifient ce phénomène
  • Pas de parallélisme natif : un skill s’exécute séquentiellement dans une session. Pour du vrai parallélisme (plusieurs agents en simultané), il faut l’orchestrer au niveau de l’application, pas dans le skill lui-même

À retenir pour la production : les skills excellent sur les workflows répétitifs et bien bornés — deploy, review, init, format. Pour les processus longs, complexes ou à fort enjeu (migration de base de données, déploiement prod avec rollback), écrivez des scripts déterministes en bash ou bun que le skill peut invoquer via Bash, plutôt que d’encoder la logique critique dans les instructions Markdown.

Ce qu’est exactement un claude code skill (et ce que ce n’est pas)

Un claude code skill est un fichier Markdown structuré, stocké dans le répertoire .claude/skills/ de votre projet (ou dans ~/.claude/skills/ pour un usage personnel). Il contient un en-tête YAML qui déclare son identité, et un corps de texte qui décrit les instructions que Claude doit suivre à chaque invocation.

Ce qu’il n’est pas :

Un prompt système : le prompt système s’applique à toute la session, sans déclencheur précis. Le skill, lui, s’active sur commande, avec /nom-du-skill. Vous gardez le contrôle sur quand et sur quoi il intervient.

Une custom instruction (les instructions mémorisées dans le compte Claude.ai) : celles-ci sont globales et non versionnées. Un skill vit dans le dépôt Git du projet ; il voyage donc avec le code, pas avec le profil d’une personne.

Un plugin IA pour développeurs au sens d’une extension tierce : contrairement à un plugin VS Code, un skill ne dépend d’aucune installation externe. Claude Code le lit au démarrage du projet, c’est tout.

Ce qui rend ce module d’instructions personnalisé particulièrement utile en contexte professionnel, c’est sa portabilité. Commité dans le repo, il est disponible pour tous les membres de l’équipe sans configuration individuelle. Chaque développeur qui clone le projet retrouve les mêmes agents spécialisés réutilisables, configurés une fois pour toutes.

Anatomie d’un SKILL.md : le fichier que Claude lit ligne par ligne

La structure d’un skill tient en deux parties : le frontmatter YAML et le corps d’instructions.

Le frontmatter YAML : les quatre champs qui comptent vraiment

« `yaml

—

name: review-typescript

description: Audite un fichier TypeScript selon les conventions du projet

trigger: /review-ts

tools:

– read_file

– run_command

—



`name` est l'identifiant interne, utilisé dans les logs. `description` est la phrase courte affichée dans l'aide intégrée (`/help`) : soyez précis, une description vague génère des invocations accidentelles. `trigger` est le slash-command qui déclenche le skill ; choisissez quelque chose de mémorisable, sans conflit avec les commandes natives de Claude Code. `tools` liste les outils auxquels le skill est autorisé à accéder : restreindre cette liste est une bonne pratique de sécurité élémentaire.

Selon la [documentation officielle Claude Code d'Anthropic](https://docs.anthropic.com/fr/docs/claude-code), un skill minimal fonctionnel tient en moins de 30 lignes au total.

### Le corps d'instructions : ce que Claude exécute réellement

Le corps est du Markdown libre, mais quelques principes améliorent la fiabilité. Décomposez les instructions en étapes numérotées plutôt qu'en prose continue : Claude suit mieux une checklist qu'un paragraphe dense. Évitez les conditions imbriquées ("si A alors B sauf si C") : elles produisent des comportements incohérents selon la longueur du contexte. Terminez systématiquement par un format de sortie attendu explicite ("réponds avec un rapport structuré contenant trois sections...").

## Créer un claude code skill de zéro : procédure pas à pas

Voici la procédure complète, illustrée par un exemple issu du terrain : automatiser la revue de style pour du code TypeScript strict.

### Étape 1 : choisir le bon déclencheur (trigger)

Avant d'écrire une ligne, vérifiez les conflits existants. La commande `cat ~/.claude/skills/*.md | grep trigger` liste tous les triggers déjà définis dans votre environnement. Un conflit silencieux (deux skills avec le même trigger) donne un comportement imprévisible sans message d'erreur. Préfixez vos triggers par le contexte du projet : `/ts-review` plutôt que `/review`, qui est trop générique.

### Étape 2 : rédiger les instructions sans ambiguïté

Commencez par la portée exacte ("ce skill s'applique uniquement aux fichiers `.ts` et `.tsx`"), enchaînez avec les critères numérotés, et fermez avec le format de sortie attendu. Un point souvent négligé : précisez explicitement ce que le skill ne fait PAS. "Ce skill ne modifie aucun fichier, il produit uniquement un rapport" évite des effets de bord sur un code sensible.

### Étape 3 : tester, itérer et versionner

Testez d'abord sur un fichier représentatif mais non critique. Observez si Claude interprète les instructions comme prévu ou si des zones grises apparaissent : 2 à 3 itérations sont normales avant d'atteindre un comportement stable. Une fois satisfaisant, committez : `git add .claude/skills/review-typescript.md`. À partir de là, le skill voyage avec le repo.

Ordre de grandeur honnête : 15 à 20 minutes pour un premier skill fonctionnel, une heure pour un skill robuste avec gestion des cas limites.

## Exemple complet en production : un skill d'audit de pull request

Voici le skill que nous utilisons avec un client PME tech depuis début 2026. Il pré-audite chaque pull request avant la review humaine.

```markdown
---
name: pr-audit
description: Audite une PR TypeScript (conventions, sécurité, tests manquants)
trigger: /pr-audit
tools:
  - read_file
  - list_files
---

Tu es un auditeur de code senior. Quand tu es invoqué avec `/pr-audit`,
tu analyses les fichiers modifiés dans la branche courante.

Vérifie dans cet ordre :
1. Cohérence des noms de variables avec la convention camelCase du projet
2. Présence de types explicites (pas de `any` implicite)
3. Chaque fonction exposée a un test unitaire dans `__tests__/`
4. Absence de `console.log` ou `debugger` oubliés
5. Imports ordonnés : externes, internes, relatifs

Produis un rapport structuré avec trois sections :
- ✅ Points conformes
- ⚠️ Points à corriger avant merge (avec ligne concernée)
- 💡 Suggestions non bloquantes (3 maximum)

Ne modifie aucun fichier. Produis uniquement le rapport.

Sur ce projet, la fourchette observée est de 8 à 12 minutes économisées par cycle de review, principalement sur les allers-retours autour de corrections mineures détectées systématiquement. Ce n’est pas une garantie universelle : la valeur dépend du volume de PRs et de la rigueur des conventions déjà en place.

Où trouver et partager des skills en 2026 : l’écosystème disponible

Si vous ne souhaitez pas partir de zéro, plusieurs ressources existent.

SkillsMP est la plus grande agrégation disponible. D’après un article publié sur Korben en décembre 2025, la plateforme référençait plus de 26 000 skills issus de dépôts GitHub publics. Le signal est intéressant, mais la quantité ne garantit pas la qualité.

claudeskills.info propose un catalogue organisé par cas d’usage (développement, rédaction, analyse de données, automatisation). L’interface est plus orientée découverte que téléchargement brut, ce qui facilite l’exploration si vous ne savez pas encore précisément ce que vous cherchez.

La documentation officielle Claude Code recense des skills bundlés maintenus par Anthropic, utiles comme référence de structure et de style avant d’écrire les vôtres.

Trois critères concrets pour évaluer un skill tiers avant de l’adopter dans votre workflow :

  1. Fraîcheur du dépôt : un skill non mis à jour depuis plus de 6 mois peut ne plus fonctionner avec les versions récentes de Claude Code.
  2. Présence d’exemples d’output : un skill sans exemple de résultat attendu est très difficile à déboguer si le comportement ne correspond pas à vos attentes.
  3. Restriction explicite des outils : un skill qui réclame accès à tous les outils (tools: ["*"]) est une surface d’exposition inutile. Préférez les skills avec une liste restreinte et justifiée.

Les vraies limites d’un skill (ce que la documentation ne dit pas toujours)

Une extension Claude bien conçue excelle dans trois usages : contextualiser Claude sur les conventions d’un projet spécifique, partager un savoir-faire codifié entre membres d’une équipe, et déclencher un workflow déterministe de façon répétable. C’est là que le rapport effort/valeur est le meilleur.

Trois limites méritent d’être énoncées clairement.

Pas d’accès temps réel à des données externes. Un skill ne peut pas interroger une API externe au moment de l’invocation, sauf si l’outil run_command est activé et qu’une commande est configurée côté projet. Ce n’est pas la même chose qu’un agent IA connecté à des sources de données live.

Pas de mémoire persistante native entre sessions. Chaque invocation repart de zéro. Un skill ne remplace pas un système de mémoire long terme : pour ça, il faut une architecture d’agent plus complète (base vectorielle, ou un orchestrateur comme n8n qui maintient l’état entre les runs).

Complexité croissante mal maîtrisée. Nous avons vu des skills qui tentaient d’encoder des dizaines de règles métier dans un seul fichier. Résultat : des instructions contradictoires, des réponses trop génériques, et des comportements différents selon la longueur du contexte. La règle pratique : si un skill dépasse 50 lignes d’instructions, c’est souvent le signe qu’il doit être découpé en plusieurs skills plus ciblés.

Ces limites définissent un périmètre, pas un défaut. Connaître ces bornes permet de choisir le bon outil : skill pour les conventions et les workflows déterministes, agent full-stack pour les tâches nécessitant des données dynamiques ou une mémoire longue.

Ce qu’il faut retenir

Un claude code skill représente l’investissement le plus rentable pour éliminer les instructions répétitives dans votre workflow : 15 à 20 minutes de configuration pour des semaines sans friction. Identifiez votre cas à plus forte répétition, créez un SKILL.md minimal, testez sur un cas réel, puis committez. Ensuite seulement, explorez les marketplaces pour enrichir votre bibliothèque de commandes automatisées Claude adaptées à vos projets.

Publications similaires