Augmenter Claude Code avec les skills

Les agents comme Claude Code, Codex, Cursor sont des outils formidables. Out of the box, on obtient déjà des résultats bluffants. De mon côté, je les vois plus comme des frameworks avec une large capacité de personnalisation. Dans les articles précédents, j’ai déjà évoqué pas mal de mécanismes : les hooks et la mémoire, les MCP custom. Aujourd’hui, on s’attaque à l’outil de personnalisation qui change la donne : les skills.

Grâce à eux, l’agent passe d’un assistant générique à un binôme qui suit ma méthode, et qui connaît mes projets et mes contraintes.

Une bibliothèque de prompts pour les tâches répétitives

Si je devais résumer grossièrement, un skill est un moyen rapide d’envoyer au modèle des instructions précises sur une tâche à réaliser. On peut le voir comme une bibliothèque de prompts, mais on verra plus loin que la réalité va bien au-delà. C’est utile dès qu’on rencontre des tâches récurrentes, et en tant que développeur ça arrive un paquet de fois :

• faire un commit avec un message concis et normalisé
• créer une PR avec une bonne description
• review, simplifier, factoriser du code
• résoudre un ticket de A à Z

On invoque un skill avec /nom-du-skill, soit explicitement, soit auto-déclenché par le modèle quand il détecte qu’une tâche correspond à la description.

Skill vs commandes

Pendant longtemps, le seul moyen de personnaliser l’agent était les commandes custom : un fichier markdown dans ~/.claude/commands/, et /ma-commande faisait l’affaire. Les skills sont arrivés plus tard, plus puissants, et en janvier 2026 Anthropic a tranché en fusionnant les commandes dans les skills (doc officielle) : un fichier .claude/commands/deploy.md et un skill .claude/skills/deploy/SKILL.md produisent tous deux /deploy, mais une commande reste un format limité, sans dossier de support ni auto-invocation par le modèle.

Concrètement, une commande est aujourd’hui un skill mono-fichier, avec un frontmatter limité. Les anciens fichiers .claude/commands/ continuent de marcher pour la rétrocompatibilité, mais à terme rien ne dit qu’ils resteront supportés. Si vous démarrez aujourd’hui, partez directement sur des skills.

Un skill mono-fichier, le format minimal

Avant d’aller dans le format complet, regardons le squelette le plus simple d’un skill : un seul fichier SKILL.md, un frontmatter de deux lignes, un prompt. Pas d’étapes, pas d’orchestration. C’est la marche la plus basse à franchir si vous découvrez la personnalisation de Claude Code.

Le frontmatter est un bloc YAML délimité par deux lignes --- en tête de fichier markdown. Il contient des métadonnées que l’outil va lire avant de traiter le corps du fichier (description, configuration…).

Voici par exemple mon skill de commit :

---
description: Create a commit with auto-generated concise message
---

# Commit Workflow

Generate a commit with a clean, concise message following conventional commit style.

## Step 1: Analyze Changes
1. Run `git status` to see modified/staged files
2. Run `git diff` to understand what changed
3. Identify the type: feature, fix, refactor, docs, test, chore...

## Step 2: Generate Commit Message

Use conventional commit format:

- First line: type + colon + space + short description (max 50 chars)
- Use imperative mood ("Add", "Fix", "Update")
- Empty line, then bullet points for details (only if helpful)

## Step 3: Stage and Commit
1. Stage relevant changes: `git add <files>`
2. Create the commit with the generated message
3. Show the result

## Important
- NEVER amend existing commits
- Commit message in English

Trois sections : on explique à quoi sert le skill, on liste les étapes pour produire un message de qualité, on rappelle les règles non négociables. C’est tout. J’invoque ça avec /commit et le modèle déroule.

Passer des arguments

On peut aussi paramétrer un skill. Le champ argument-hint du frontmatter s’affiche pendant l’autocomplétion pour rappeler à l’utilisateur ce qu’il doit saisir, et le placeholder $ARGUMENTS permet de récupérer ce qui a été tapé dans le prompt :

---
description: Fix a GitHub issue
argument-hint: [issue-number]
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description with `gh issue view $ARGUMENTS`
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

Avec /fix-issue 142, $ARGUMENTS est remplacé par 142 à l’exécution. Bref, pratique pour des tâches paramétrées. Si vous avez plusieurs arguments à manipuler indépendamment, le champ arguments permet de les nommer (par exemple arguments: [component, framework] pour récupérer $component et $framework dans le prompt).

Le format complet : ce que le skill apporte en plus

Avec ce qu’on vient de voir, on peut déjà aller loin. Mais on est resté sur le squelette minimal. Le format complet (documentation officielle, guide complet Anthropic) apporte trois choses majeures que la version mono-fichier ne peut pas offrir.

1. L’auto-découverte par le modèle

Contrairement aux commandes legacy qui ne pouvaient être déclenchées qu’à la main, un skill est auto-invocable par le modèle par défaut : Claude Code lit la description du frontmatter, et si elle correspond à ce qu’on est en train de demander, il déclenche le skill tout seul.

Concrètement, si j’ai un skill commit avec une description du genre “Stage and commit current changes following conventional commit style”, le simple fait de dire “fais un commit” suffit pour que Claude Code le déclenche, sans que j’aie besoin de taper /commit.

C’est aussi pour ça que la qualité de la description est cruciale : c’est le seul critère que le modèle utilise pour décider d’invoquer le skill ou non. Si on veut désactiver ce comportement, le frontmatter disable-model-invocation: true ramène le skill au mode user-invocable uniquement.

2. Un dossier complet, pas un fichier unique

Un skill, c’est un dossier avec un SKILL.md comme point d’entrée, et autant de fichiers de support qu’on veut : templates, scripts, références, sous-étapes…

~/.claude/skills/resolve/
├── SKILL.md              # point d'entrée, lu à l'invocation
├── steps/
│   ├── 00-initialization.md
│   ├── 01-fetch-ticket.md
│   └── ...
├── references/
│   └── conventions.md
└── scripts/
    └── helper.sh

Le SKILL.md est lu dès que le skill est invoqué. Les autres fichiers ne sont chargés que quand le SKILL.md les référence explicitement, au moment où le modèle en a besoin.

Cette nuance change tout. On l’a déjà vu dans l’article sur le context engineering : le contexte est la clé. Plus il grossit, plus le modèle perd en efficacité, noyé sous l’information.

Avec un skill, on construit des workflows complexes sans gonfler le contexte initial. Le SKILL.md orchestre, séquence les étapes, et charge progressivement les détails au fur et à mesure de l’exécution. C’est exactement ce qu’on cherche : un workflow détaillé sans étouffer le modèle sous le contexte.

D’ailleurs, Anthropic recommande explicitement de garder le SKILL.md sous les 500 lignes et de déplacer toute la matière détaillée (références, exemples, étapes longues) dans des fichiers de support. Le point d’entrée doit rester un sommaire, pas une encyclopédie.

3. Un frontmatter beaucoup plus riche

Au-delà du description qu’on a vu sur le skill mono-fichier, le format complet expose toute une série d’options pour piloter finement le comportement :

Avec ça, on dépasse largement la simple bibliothèque de prompts. On construit de vrais workflows orchestrés, où chaque skill peut décider de ses outils, de son isolation, ou même du modèle qu’il utilise.

Mon skill /resolve : orchestrer la résolution d’un ticket

Pour illustrer la puissance du format, je vais détailler le skill que j’utilise tous les jours : /resolve. Tout le code est disponible sur GitHub si vous voulez l’éplucher.

L’idée : prendre un ticket YouTrack ou GitHub, et le résoudre de A à Z. J’ai retranscrit ma méthode habituelle en une série d’étapes, chacune dans son propre fichier markdown :

00-initialization.md      # config initiale, création du dossier de travail
01-fetch-ticket.md        # récupération du ticket via MCP YouTrack/GitHub
02-analyze-complexity.md  # estimation de la complexité, détection des risques
03-exploration.md         # exploration du code concerné par le ticket
04-create-plan.md         # création d'un plan d'implémentation détaillé
05-plan-validation.md     # validation du plan avec moi avant d'écrire la moindre ligne
06-implement.md           # implémentation pas à pas, en suivant le plan
07-simplify.md            # simplification du code produit (DRY, clarté, naming)
08-review.md              # code review automatique par un sous-agent
09-finalize.md            # commit, push, création de la PR

Le SKILL.md est un orchestrateur : il décide quelle étape charger en fonction du mode et de l’état courant, exécute les instructions, puis enchaîne avec la suivante. Chaque fichier d’étape n’est lu que quand on en a besoin.

Des modes via les arguments

Selon comment j’invoque le skill, le workflow se comporte différemment :

• /resolve PROJ-42 : mode interactif, le skill me sollicite pour valider chaque étape clé
• /resolve PROJ-42 --plan-only : on s’arrête après la validation du plan, je peux le relire à froid
• /resolve PROJ-42 --auto : mode autonome, aucune sollicitation, ça pousse jusqu’à la PR
• /resolve --continue : reprend là où on s’était arrêté

Ce dernier point mérite un mot. Le skill persiste une state machine dans un fichier JSON (.claude-work/{ticket-id}/status.json) qui suit l’avancement étape par étape. Si je ferme Claude Code en plein milieu, je peux le relancer le lendemain, le skill relit l’état et reprend là où on s’était arrêté. En pratique c’est ce qui fait la différence entre un prompt long et un workflow qui survit aux interruptions.

Pourquoi ça marche

Les ingrédients qui font que ce skill tient la route :

1. Chaque étape est focalisée : le modèle ne lit que les instructions pertinentes pour l’étape courante, pas l’orchestrateur complet
2. Les outils sont déclarés : allowed-tools liste tout ce dont le skill a besoin pour tourner sans interruption. Outils internes (Read, Bash, Edit…), sous-agents, MCP. Pas de prompt de permission qui casse le flux en plein milieu d’un workflow
3. Le state est externalisé : le JSON de statut sert de mémoire entre les sessions
4. Le contrôle reste à l’utilisateur : disable-model-invocation: true, c’est moi qui décide quand lancer ce skill

Pour donner un ordre de grandeur, le skill /resolve totalise environ 3 000 lignes, mais le point d’entrée (SKILL.md) ne fait que ~300 lignes : c’est tout ce qui est chargé par défaut quand le skill démarre. Le reste (les 10 fichiers d’étapes, le fichier de références) ne vient s’ajouter au contexte que lorsque l’orchestrateur en a besoin. Tout coller dans un fichier unique ferait exploser le contexte dès l’invocation, et le modèle se perdrait dans une masse d’instructions dont 90% ne concernent pas l’étape courante. Du coup, un workflow de cette taille n’aurait jamais été exploitable dans le format mono-fichier.

Ce que je ne vous montre pas

Pour être honnête : la version que je vous décris ici, c’est une photo prise après plusieurs mois d’itération. La première mouture du skill ne tenait pas la route. Elle se plantait au milieu, sautait des étapes, oubliait des décisions prises plus haut, et le code produit ne répondait pas à 100% au ticket. J’ai dû reprendre l’orchestrateur des dizaines de fois, redécouper des étapes, déplacer des règles d’un fichier à un autre, ajouter des garde-fous, en supprimer d’autres qui parasitaient plus qu’ils n’aidaient.

Du côté du résultat, je l’utilise sur tous mes tickets, importants ou pas. En revanche, je ne livre jamais la première sortie en l’état : je relis, j’itère plusieurs passes sur le code produit, je remets le doigt là où ça dérive, je redemande des ajustements. Rien de nouveau d’ailleurs, c’est ce que je faisais déjà avant l’arrivée de l’IA quand je codais à la main : aucun premier jet ne part en prod tel quel.

Skill-creator : le skill qui crée des skills

Dernier point, et pas le moins important : créer un skill bien conçu, ce n’est pas trivial. Il y a la description à soigner, le découpage des fichiers à anticiper, et tous les champs de frontmatter à arbitrer.

Heureusement, Anthropic a publié un plugin officiel qui contient un skill dédié à la création de skills : /skill-creator.

Le principe : on lui décrit ce qu’on veut automatiser, et il génère le squelette du skill avec les bonnes pratiques baked-in. Frontmatter cohérent, description calibrée pour l’auto-invocation, et un découpage de dossier propre. Avec des exemples quand le sujet le mérite.

Construisez vos skills, ne copiez pas ceux des autres

Un dernier mot, parce que c’est probablement le piège le plus courant. Depuis que les skills existent, on voit fleurir des packs tout faits : des plugins partagés sur GitHub, des collections vendues par des influenceurs IA, des “starter packs ultimes” qui promettent de transformer votre workflow en deux clics. C’est tentant. Mais à mon avis c’est une mauvaise idée.

Un skill, par construction, encode une manière de travailler. La mienne, avec mes worktrees Docker, mes MCP custom YouTrack et mon process de validation de plan en plusieurs passes, n’est pas la vôtre. Si vous installez aveuglément un skill conçu pour quelqu’un d’autre, au mieux il ne s’activera jamais parce que la description ne matche pas votre vocabulaire, au pire il vous imposera une méthode qui n’est pas la vôtre, et vous lutterez contre l’agent au lieu de le piloter.

Cela dit, attention au piège du tout-ou-rien. Entre installer aveuglément le skill d’un autre et tout réécrire from scratch, il y a un troisième chemin, plus efficace : forker, comprendre, adapter. Lisez les skills publics, prenez ceux qui s’approchent de votre besoin, mais ouvrez-les, modifiez la description pour qu’elle matche votre vocabulaire, retravaillez les étapes pour coller à votre process.

Et si vous démarrez d’une page blanche, repérez une tâche que vous faites trois fois par semaine, ouvrez un SKILL.md, écrivez les étapes comme vous les expliqueriez à un nouveau collègue. C’est déjà un skill. Le reste viendra par itération.