Mes skills Claude Code en production : ce que l'audit m'a appris

Un skill Claude Code, c'est un fichier Markdown qu'on place dans ~/.claude/skills/. Il décrit un workflow complet : quand le déclencher, comment l'exécuter étape par étape, ce qu'il doit produire. Claude le lit au moment opportun et le suit. Sans commande manuelle, sans copier-coller de prompt. Tu dis "publie cet article" et le skill enchaîne les vérifications, la génération d'image, le commit, le deploy et le draft LinkedIn.

J'en ai neuf en production sur ce site. Certains tournent parfaitement depuis des mois. Un seul pose problème. Et c'est le plus intéressant à analyser.

Neuf skills, neuf domaines

Pour comprendre ce qui suit, voici à quoi servent mes neuf skills. Chacun couvre un domaine précis de mon workflow :

• blog-article : rédiger et publier un article (FR + EN, OG image, deploy, LinkedIn, dev.to)
• blog-fix : corriger une typo ou un bug sur un article déjà publié sans tout relancer
• fiche-livre : lire un PDF de livre technique et produire une fiche de lecture complète (résumé, radar 5 axes, schémas SVG, bilingue)
• outil-factory : créer ou itérer sur un outil web gratuit (/outils/), avec scoring radar et tests Playwright
• veille-debug : diagnostiquer les bugs du système de veille automatisée (génération d'articles par IA, cron, registry)
• vide-contexte : extraire les insights non-évidents de la session en cours vers la mémoire persistante avant de clearer le contexte
• deep-research : lancer une recherche multi-sources avec vérification adversariale et synthèse citée
• frontend-design : guide de direction visuelle pour ne pas produire du Bootstrap générique
• feature-loop : gérer le cycle complet d'une feature (spécification, implémentation, review, tests, merge)

Huit fonctionnent bien. Le neuvième, feature-loop, cumule 1 002 lignes et environ 25 000 tokens. C'est lui qu'un audit récent a mis sous le microscope.

Ce qu'un audit de skills regarde

Auditer un skill, c'est mesurer quatre choses : sa longueur brute (lignes, tokens), sa structure (le corps versus les fichiers annexes chargés à la demande), la densité des marqueurs d'urgence dans le texte, et ce qu'il reste visible en contexte long, quand Claude est à l'itération 3 d'une session chargée.

Sur les huit skills sains, les chiffres sont clairs : entre 70 et 257 lignes, 1 000 à 7 700 tokens, structure simple. feature-loop est seul dans sa catégorie : 1 002 lignes, 25 000 tokens, et un texte saturé de NON NÉGOCIABLE / JAMAIS / OBLIGATOIRE / LOCKED à chaque paragraphe.

Le diagnostic tient en une phrase : quand tout est critique, rien ne l'est.

La dilution de saillance

Quand Claude charge un skill, il charge le corps entier. Tout ce qui s'y trouve concurrence pour l'attention du modèle. Si dix règles sont toutes marquées OBLIGATOIRE, le modèle n'a aucun moyen de décider laquelle prioriser en cas de conflit ou de contrainte de contexte. Il n'arbitre pas : il moyenne. Et moyenner dix OBLIGATOIRE, ça donne zéro priorité claire.

Les invariants qui changent vraiment le comportement, ceux qui font planter le workflow s'ils sont oubliés, se noient dans les micro-optimisations de tokens et les justifications de design. Résultat : les règles les plus importantes sont suivies avec la même fiabilité que les moins importantes. C'est-à-dire : pas toujours.

Sur les huit skills sains, les règles critiques tiennent en dix lignes maximum. Le reste est soit absent, soit dans des fichiers annexes chargés à l'étape qui en a besoin.

Le décrochage silencieux en contexte long

Un skill se charge au déclenchement. Mais une session de travail s'accumule : lectures de fichiers, sorties d'outils, échanges, itérations. À l'itération 3 d'une feature complexe, le SKILL.md de feature-loop est enfoui sous des milliers de tokens de contexte accumulé.

Les règles en haut du fichier, Claude les voit encore. Celles de la page 8, moins. Ce n'est pas un bug. C'est de la physique de l'attention : un modèle de langage donne plus de poids aux tokens récents et aux tokens en début de contexte. Ce qui est au milieu d'un fichier de 25 000 tokens, enfoui sous des sorties d'outils, est structurellement moins bien traité.

La solution n'est pas de tout remonter en tête. C'est d'extraire ce qui n'a pas sa place dans le corps : les justifications de design, les exemples complets, les recettes bash de 50 lignes. Ces éléments appartiennent dans un fichier references/ chargé à l'étape précise qui en a besoin. Le corps du skill reste un contrat d'exécution, pas une encyclopédie.

Ce qui distingue les skills qui tiennent

Les huit skills sains partagent deux caractéristiques qu'on ne voit pas au premier coup d'œil.

La description est un déclencheur, pas un résumé. Chaque skill a un frontmatter avec une description courte. C'est ce que Claude lit pour décider de l'invoquer ou non. Une description qui résume le skill ("ce skill crée des fiches de livres") est moins efficace qu'une description qui liste des situations concrètes ("déclencher sur : 'fiche livre', 'résume ce livre', un PDF de livre fourni"). La première dit ce qu'est le skill. La seconde dit quand l'appeler, ce qui est la seule chose qui compte au moment du déclenchement.

Le corps fait confiance au modèle. Les skills courts ne sur-spécifient pas. Ils donnent le contrat (objectif, format de sortie, étapes critiques) et laissent Claude raisonner sur le reste. Un skill de 80 lignes bien structuré surpasse un skill de 400 lignes sur-spécifié, parce que les 80 lignes ont toutes de la valeur et que le modèle peut les tenir en tête simultanément. La sur-spécification, c'est souvent de la méfiance codifiée. Et la méfiance en 400 lignes produit un skill que même Claude ne peut pas suivre.

Le repo public : six skills installables

J'ai extrait six de mes skills dans un repo public : github.com/ohugonnot/claude-skills.

Six skills disponibles, organisés en pipeline :

• issue-mr : transformer une idée floue en issue bien formée, branche et MR/PR shell
• feature-loop : boucle autonome quality-gated — writer, test-writer et reviewer sont des agents distincts
• senior-review : review niveau senior par dimensions (correctness, sécurité, design, tests), reviewers aveugles
• branch-wrap-up : clôture propre d'une branche (commit conventionnel, push, capture mémoire)
• book-distill : lire un PDF et produire une fiche de lecture vérifiée, citations mot à mot
• vide-contexte : extraire les insights non-déductibles de la session vers la mémoire persistante avant /clear

L'installation se fait via le marketplace Claude Code en une ligne, ou manuellement en symlink :

# Via marketplace (recommandé)
/plugin marketplace add ohugonnot/claude-skills
/plugin install feature-loop@web-developpeur-skills

# Ou manuellement
git clone https://github.com/ohugonnot/claude-skills.git ~/claude-skills
ln -s ~/claude-skills/plugins/vide-contexte/skills/vide-contexte ~/.claude/skills/vide-contexte

Publier ces skills a changé ma façon de les écrire. Un skill pour usage personnel peut s'appuyer sur du contexte implicite : les conventions du projet, la structure des fichiers, ce que je sais sans l'écrire. Un skill public doit fonctionner à froid, sur un projet inconnu, sans CLAUDE.md local. Cette contrainte force à rendre explicite tout ce qui était tacite. Et un skill explicite est meilleur skill, même pour usage personnel.

Le moteur de recherche qui change la découverte

Le problème de fond avec les skills, ce n'est pas l'écriture. C'est la découverte. Si tu as vingt skills répartis dans des sous-dossiers, savoir lequel appeler pour un besoin donné devient un problème en soi. Le réflexe naturel est de taper le nom du skill, mais encore faut-il se souvenir du nom.

Claude Code dispose maintenant d'un mécanisme de recherche de skills par mots-clés. Au lieu de mémoriser la liste exacte, tu peux chercher par domaine ou par intention : "quelque chose pour publier un article", "un skill de recherche", "pour nettoyer le contexte". Le moteur retourne les skills dont la description correspond.

Ce mécanisme change la façon d'écrire les descriptions. Si c'est ça qui est indexé, la description doit contenir les mots que l'utilisateur va taper quand il cherche, pas les mots qu'on utilise en interne pour nommer le concept. La différence est subtile mais réelle : "nettoyer le contexte avant /clear" déclenche sur "vide le contexte", "sauvegarde avant clear", "extraire la session". Une description tournée vers l'usage cherché, pas vers la définition technique.

Conclusion

Le vrai enseignement de l'audit n'est pas dans la liste des règles. C'est dans l'écart entre feature-loop et les huit autres. Un skill trop long ne casse pas parce qu'il est illisible. Il casse parce qu'il dilue : les règles critiques s'y noient dans du bruit, et le modèle n'a plus de moyen de savoir lesquelles méritent l'attention en priorité.

Le corps d'un skill n'est pas une source de vérité exhaustive. C'est un contrat d'exécution. Plus il est net, mieux il tient quand le contexte s'accumule. Tout ce qui n'est pas strictement nécessaire à l'exécution a sa place ailleurs : dans un fichier de référence, dans un script, ou nulle part.