Écrire des skills que votre agent de code utilisera vraiment

J’ai un dossier .claude/skills/ avec quatorze fichiers dedans. Huit d’entre eux sont mobilisés presque quotidiennement par l’agent. Six n’ont jamais été utilisés après leur écriture. La différence entre les deux groupes n’est pas la qualité de la prose, c’est la spécificité du déclencheur.

Un skill qui commence par « Quand l’utilisateur demande de… » est de la documentation déguisée. Un skill qui commence par « Quand un fichier .astro est modifié et que… » est un réflexe automatique. Le premier demande à l’utilisateur de se souvenir qu’il existe. Le second se déclenche seul.

Ce qui fait qu’un skill marche

Après six mois à itérer, j’ai identifié trois propriétés communes aux skills que l’agent utilise vraiment :

1. Un déclencheur observable

Le skill doit répondre à quelque chose que l’agent voit, pas à quelque chose que l’utilisateur pense. Un bon déclencheur : « quand le fichier modifié importe depuis @/lib/seo.ts ». Un mauvais déclencheur : « quand l’utilisateur travaille sur le SEO ». Le premier est détectable dans le diff. Le second nécessite une interprétation subjective.

Les meilleurs déclencheurs que j’ai trouvés :

Extension de fichier (.md → skill blog, .astro → skill composant)
Présence d’un import spécifique
Nom de commande (slash command explicite)
Pattern dans la question (« commit », « test », « deploy »)

2. Une sortie prescrite

Un skill vague (« écris du bon code ») ne produit rien de prévisible. Un skill prescriptif (« génère le frontmatter avec ces champs dans cet ordre, puis lance pnpm blog:lint ») produit un résultat vérifiable.

La prescription n’a pas besoin d’être rigide, elle doit être suffisante pour que le résultat soit conforme sans supervision. Mon skill de blog, par exemple, prescrit :

Le format exact du frontmatter (champs, types, valeurs valides)
La structure du post (ouverture, sections, clôture)
Les vérifications à lancer après écriture
Ce qu’il ne doit jamais faire (inventer des sources, écrire en anglais)

3. Un périmètre fermé

Un skill qui fait une chose la fait bien. Un skill qui fait « tout ce qui concerne le blog » est trop large, l’agent ne sait pas quand l’activer vs. les autres skills. Découper en trois skills séparés (écrire, enrichir, publier) avec des déclencheurs distincts fonctionne mieux qu’un méga-skill omniscient.

Anatomie d’un skill efficace

Voici la structure qui fonctionne pour moi avec Claude Code :

---
description: Quand l'utiliser (une phrase)
---

## Contexte
Ce que l'agent doit savoir (conventions, contraintes, stack).

## Étapes
1. Ce qu'il fait (dans l'ordre).
2. Chaque étape est un verbe à l'impératif.
3. Les conditions de sortie sont explicites.

## Règles strictes
- Ce qu'il ne doit jamais faire.
- Les cas limites à gérer explicitement.

## Vérification
Comment vérifier que le résultat est correct.

L’élément le plus sous-estimé : la section « Règles strictes ». Sans elle, l’agent optimise pour la complétude, il ajoute, il étend, il « améliore ». Les règles strictes coupent cette tendance : « N’ajoute pas de commentaires au code que tu n’as pas modifié. Ne crée pas de fichiers non demandés. Ne modifie pas le frontmatter existant sauf modifiedDate. »

La même structure se généralise au-delà du code. Le pattern d’investigation de tickets support documenté par John Yeo consiste à écrire un skill par domaine d’enquête, billing, webhooks Stripe, entitlements, qui encode la connaissance qu’un opérateur expérimenté a accumulée et que la doc d’API ne porte pas. Mêmes propriétés : déclencheur observable (« le ticket parle de cancellation+upgrade »), sortie prescrite (la séquence de queries à lancer), et règles strictes (ce que le skill ne doit jamais conclure sans corroboration).

Les anti-patterns

Le skill-documentation

Un fichier qui décrit comment les choses marchent sans dire quoi faire. L’agent le lit, comprend le contexte, et ne change rien à son comportement. Convertissez-le en instructions actionnables ou supprimez-le.

Le skill-monologue

Un skill de 500 lignes qui couvre tous les cas. L’agent n’en retient qu’une fraction. Découpez en skills ciblés de 50-100 lignes max, chacun avec un déclencheur clair.

Le skill sans vérification

Un skill qui dit quoi faire mais pas comment vérifier le résultat. L’agent génère du contenu, déclare la tâche terminée, et vous découvrez les problèmes à la relecture. Ajoutez une étape de validation (linter, commande, assertion).

Le test décisif

Avant d’écrire un nouveau skill, posez-vous une question : « Si je supprime ce skill, est-ce que l’agent fera quelque chose de différent demain ? » Si la réponse est non, si le skill ne fait que documenter un comportement que l’agent aurait de toute façon, ne l’écrivez pas. Un skill inutilisé est pire qu’un skill absent : il encombre le contexte et donne une fausse impression de contrôle.

Les bons skills sont peu nombreux, très spécifiques, et mobilisés quotidiennement. Visez huit skills qui marchent plutôt que quarante qui existent. Et la frontière du concept continue d’évoluer, le LLM Council de Karpathy montre par exemple qu’un “skill” peut aussi être un protocole inter-modèles qui orchestre la délibération entre plusieurs LLM, pas seulement une instruction donnée à un seul.

Si cela vous a parlé, vous aimerez Comment j’empêche un binôme IA de réécrire la moitié du dépôt et Les petites automatisations qui se cumulent sur un trimestre. Abonnez-vous ci-dessous pour recevoir le billet de vendredi prochain.