En bref
Un skill Claude Code est un fichier Markdown que l’IA lit avant d’agir sur une tâche donnée. Il remplace la documentation longue par une instruction auto-contenue, portant à la fois les règles, le processus et les garde-fous. L’analyse de 116 skills de la communauté Everything Claude Code révèle que 93 % adoptent une architecture monolithe : un seul fichier SKILL.md, sans dépendances externes. La taille médiane observée est de 240 lignes — un repère utile pour calibrer ses propres skills sans sous-spécifier ni sur-documenter.
Qu’est-ce qu’un skill, concrètement
Un skill n’est pas un plugin, ni un outil au sens technique. C’est un fichier texte — généralement SKILL.md — que Claude Code charge en contexte avant d’exécuter une catégorie de tâches. Il encode le comportement attendu : quand s’activer (trigger), comment procéder (process), quelles erreurs éviter (anti-patterns), comment vérifier le résultat (quality gate).
Ce mécanisme repose sur une propriété fondamentale des LLM : si des instructions sont présentes dans le contexte, elles orientent la génération. Le skill n’est pas une configuration système — c’est une instruction textuelle structurée. Sa lecture par l’IA suffit à en activer les règles.
La différence avec un simple prompt : le skill est réutilisable, versionnable, partageable. Il s’intègre dans un dépôt git, évolue avec le projet et peut être injecté par un orchestrateur dans le contexte d’un sous-agent.
En pratique, un skill se charge de deux façons : soit via une référence dans CLAUDE.md (chargement systématique), soit injecté dynamiquement dans le prompt d’un agent au moment de l’orchestration. Cette deuxième modalité est particulièrement utile en mode multi-agents : l’orchestrateur décide quels skills sont pertinents pour chaque sous-agent, sans charger l’ensemble en contexte global.
Anatomie canonique : les quatre composants
L’analyse des 116 skills fait émerger une structure canonique en quatre blocs, présente dans la quasi-totalité des skills bien notés par la communauté.
1. Trigger — La condition d’activation. Décrit quand le skill doit être utilisé. Peut être une phrase directe (“quand le prompt contient X”) ou une liste de situations. Sans trigger explicite, le skill risque d’être sous-utilisé ou appliqué hors contexte.
2. Rules / Process — Le cœur opérationnel. Décrit les étapes dans l’ordre, avec des instructions actionnables. Les skills efficaces numérotent les étapes, utilisent le mode impératif et évitent la prose narrative. Un concept par instruction. Les diagrammes ASCII sont utiles pour les workflows à branchements multiples.
3. Format de sortie — Spécifie explicitement la structure du livrable attendu : type de fichier, organisation, longueur, conventions de nommage. Sans ce bloc, l’IA improvise le format à chaque exécution.
4. Quality gate / Checklist — Les critères de vérification avant livraison. Un skill sans quality gate ne peut pas savoir quand il a terminé. La checklist (- [ ] critère) est le pattern le plus répandu parce qu’il est directement vérifiable.
Un cinquième composant apparaît fréquemment dans les skills plus développés : la decision matrix ou anti-patterns explicites. Ce bloc liste les erreurs connues pour les inhiber proactivement. Nos tests montrent que les anti-patterns explicites réduisent significativement les dérives répétées sur des tâches longues.
Monolithe vs multi-fichiers : quand ajouter des dépendances
Sur 116 skills analysés, 108 (93 %) sont des monolithes purs : un seul fichier SKILL.md, sans aucune dépendance. Les 8 skills restants utilisent des sous-dossiers — agents/, hooks/, scripts/ — pour des besoins système spécifiques (hooks de pré-commit, agents autonomes, scripts shell appelés à l’exécution).
La règle pratique qui se dégage : le monolithe suffit dès que le skill encode un comportement. Les fichiers supplémentaires n’apparaissent que quand le skill déclenche des processus externes — un script bash, un agent distinct, un hook système. Pour tout ce qui est “comment l’IA doit raisonner et produire”, un seul fichier est suffisant et préférable.
L’architecture multi-fichiers a un coût : elle crée des dépendances, complique la portabilité et nécessite une documentation de l’arborescence. Le skill continuous-learning-v2 (365 lignes + 9 fichiers, avec sous-dossiers agents/, hooks/, scripts/) et le skill videodb (11 fichiers, avec reference/ et scripts/) sont fonctionnellement puissants mais difficiles à transférer ou adapter sans connaître leur écosystème complet.
La limite est claire : dès que l’on supprime un fichier compagnon d’un skill multi-fichiers, le comportement change de façon imprévisible. Un monolithe se dégrade gracieusement — il produit un résultat moins précis mais cohérent. Un skill multi-fichiers avec une dépendance manquante peut produire un comportement incohérent sans signal d’erreur explicite.
Taille optimale : 100-300 lignes
La distribution observée sur 116 skills :
| Taille | Proportion | Évaluation |
|---|---|---|
| < 100 lignes | ~10 % | Souvent trop vague |
| 100-300 lignes | ~55 % | Zone optimale |
| 300-500 lignes | ~25 % | Acceptable si structuré |
| > 500 lignes | ~10 % | Risque encyclopédique |
Un skill de moins de 100 lignes peut fonctionner sur des tâches simples, mais manque généralement de format de sortie et de quality gate. Au-delà de 500 lignes, le skill devient une documentation que l’IA survole plutôt qu’une instruction qu’elle suit.
La fourchette 100-300 lignes correspond aux skills qui couvrent un comportement complet sans noyer les instructions critiques dans du contenu accessoire. Le skill article-writing de la communauté (85 lignes) et les trois skills produits dans nos tests (121, 126, 132 lignes) se situent tous dans cette zone et produisent des résultats cohérents sur des tâches répétées.
Les extrêmes observés illustrent les deux dérives opposées. Le plus court du corpus : nanoclaw-repl à 33 lignes — un skill fonctionnel pour une tâche très étroite (lancement d’un REPL), sans format de sortie ni quality gate. Le plus long : kotlin-testing à 824 lignes — un document de référence complet sur les tests Kotlin, qui couvre tous les patterns possibles mais dont la longueur dilue les instructions critiques. Ces deux cas sont des exceptions justifiées par leur contexte ; ils ne constituent pas des modèles généralisables.
Bonnes pratiques : ce qui différencie un skill efficace
Frontmatter minimal mais renseigné. Les 116 skills utilisent systématiquement trois champs : name, description, origin. La description doit être suffisamment précise pour qu’un orchestrateur puisse décider d’injecter ce skill sans lire son contenu intégral. Un frontmatter vague (“skill pour rédiger”) est inutilisable en dispatch automatique.
Exemples concrets, pas de prose. Les skills avec des exemples structurés (tableau, liste nommée, snippet) produisent des résultats plus homogènes que ceux qui décrivent le comportement attendu en prose. L’IA extrait mieux les contraintes d’une liste que d’un paragraphe.
Anti-patterns explicites. Lister ce que le skill ne doit pas faire est aussi important que lister ce qu’il doit faire. Un anti-pattern bien formulé (“ne jamais résumer les données brutes”) est un garde-fou que l’IA active à chaque exécution. Le format tableau (interdit | exemples) rend les interdits plus saillants que les listes à puces.
Decision matrix pour le dispatch comportemental. Quand un skill couvre plusieurs situations (tâche simple vs complexe, données présentes vs absentes), une matrice de décision évite que l’IA choisisse arbitrairement. Le skill search-first de la communauté en est un exemple documenté : deux colonnes (critère / comportement), pas de prose.
Un skill = une responsabilité. Les skills qui couvrent plusieurs domaines distincts dérivent vers l’encyclopédie. La bonne granularité : une catégorie de tâche, un type de livrable, un contexte d’activation.
Le skill remplace la documentation, pas la réflexion. Un skill encode une procédure connue et éprouvée. Il n’est pas conçu pour gérer des cas hors scope non anticipés — face à une situation ambiguë, l’IA doit signaler l’ambiguïté plutôt qu’improviser.
Le skill comme interface d’orchestration
Un usage avancé des skills, observé dans les configurations multi-agents, consiste à les traiter comme une interface de dispatch plutôt que comme de simples guides de comportement. L’orchestrateur lit la description du frontmatter pour décider quel skill injecter dans le prompt de chaque sous-agent. Ce pattern suppose que le frontmatter soit précis et discriminant : deux skills aux descriptions similaires créent une ambiguïté de dispatch.
En pratique, cela conduit à une règle de nommage : {domaine}-{action} (ex: redaction-article, collecte-web, extraction-faits). Le nom du skill doit permettre de sélectionner sans lire le contenu. C’est une contrainte de conception — pas une convention stylistique.
Ce qu’il faut retenir
- Un skill Claude Code est un fichier Markdown auto-contenu qui encode un comportement répétable : trigger, process, format, quality gate.
- 93 % des skills communautaires sont des monolithes. Les fichiers supplémentaires n’apparaissent que pour des besoins système externes (hooks, scripts, agents).
- La taille optimale se situe entre 100 et 300 lignes : assez complet pour être précis, assez court pour être suivi intégralement.
- Les anti-patterns explicites et les checklists de vérification sont les composants les plus sous-utilisés et les plus efficaces.
- Un skill encode une procédure éprouvée, pas une procédure générique : le scope étroit est une force, pas une limitation.
Sources
- Communauté Everything Claude Code, dépôt public de 116 skills analysés, 2024-2025 [NON VÉRIFIÉ — source unique]
- D’après nos observations sur trois skills métier produits (redaction-article, collecte-web, extraction-faits) — la fourchette 100-150 lignes suffit pour des tâches de production répétées
- Anthropic, documentation Claude Code officielle
- Anthropic, “Claude Code: Deep Dive” (guide officiel d’utilisation avancée), 2024 [NON VÉRIFIÉ — URL non disponible au moment de la rédaction]