Le skill à 10 heures bat le skill à 10 minutes à chaque fois

Je pensais qu’écrire un Skill se résumait à déposer un fichier SKILL.md dans un dossier et passer à autre chose. Dix minutes, affaire réglée. Ça fonctionnait correctement jusqu’à ce que je voie les mêmes erreurs se répéter à chaque invocation, sans aucun moyen de savoir si le Skill faisait vraiment ce que j’avais prévu.

Puis Thariq, l’un des ingénieurs qui développe Claude Code chez Anthropic, a publié quelque chose qui a tout reframé : « Bien utiliser les Skills, c’est une question de skill. »

Cette phrase a fait mouche parce qu’elle correspondait exactement à ce que j’observais. L’écart entre un fichier markdown vite fait et un dossier Skill correctement structuré se manifestait dans la qualité réelle des sorties, pas seulement en théorie.

Un Skill est un dossier, pas un fichier

L’idée reçue la plus répandue est qu’un Skill équivaut à un seul fichier SKILL.md. En pratique, un Skill est un dossier contenant des scripts, du code de référence, de la configuration, et le fichier markdown qui relie tout ça.

L’approche interne d’Anthropic repose sur ce qu’ils appellent la divulgation progressive. Plutôt que d’entasser tout dans un seul prompt, ils organisent les fichiers pour que Claude ne lise que ce dont il a besoin au moment où il en a besoin. Un fichier references/api.md contient des signatures de fonctions que Claude charge à la demande. Un répertoire assets/ regroupe des templates de sortie, évitant ainsi au prompt d’avoir à décrire le formatage. Des scripts de validation permettent à Claude de tester ses propres résultats avant de les retourner.

Si vous ouvrez le dépôt skill-creator, vous verrez ce principe à l’œuvre. Les répertoires agents/, references/ et scripts/ sont placés aux côtés du SKILL.md. L’outil qui construit les Skills est lui-même construit comme un Skill.

Les Gotchas comptent plus que le corps du prompt

Thariq a qualifié la section Gotchas de « contenu à plus forte valeur ajoutée » d’un Skill. Pas les instructions principales, pas les exemples. Les Gotchas.

C’est cohérent avec mon expérience. J’ai construit un Skill sans section Gotchas et je me suis retrouvé avec la même erreur trois fois de suite. Dès que j’ai ajouté une ligne documentant ce pattern d’échec précis, le problème a disparu.

Le raisonnement est simple. Claude connaît déjà la plupart de ce que vous pourriez écrire dans le corps du prompt. Lui expliquer comment écrire du TypeScript ou formater du JSON revient à reformuler ce qu’il gère très bien par défaut. Mais lui indiquer ce qu’il ne faut pas faire dans votre contexte spécifique est une information genuinement nouvelle.

Quelques principes tirés du post de Thariq que j’ai trouvés fiables : n’énoncez pas l’évident, car des instructions redondantes peuvent réellement dégrader les performances ; évitez de trop baliser les étapes, car ça tue la capacité d’adaptation de Claude ; et rappelez-vous que le champ description n’est pas une documentation pour les humains, c’est l’entrée que Claude utilise pour décider quand déclencher le Skill.

Skill Creator transforme « ça semble marcher » en « c’est vérifié »

La mise à jour du Skill Creator d’il y a deux semaines a changé ma façon de penser la qualité d’un Skill. Vous définissez des prompts de test, fixez les résultats attendus, et l’outil vérifie si le Skill produit réellement les bons résultats. C’est du test unitaire pour les prompts.

J’ai ajouté des evals à un Skill que j’utilisais depuis des semaines. Deux cas de test que je croyais valides ont échoué immédiatement. Les correctifs étaient mineurs, mais la qualité des sorties a nettement progressé une fois appliqués.

Il existe une distinction utile entre deux types de Skills. Les Skills d’augmentation de capacité apprennent à Claude quelque chose qu’il ne sait pas bien faire seul. Les Skills de préférence encodée imposent le workflow ou les standards spécifiques d’une équipe. Le premier type a une date d’expiration naturelle, car les améliorations du modèle le rendent tôt ou tard superflu. Le second reste précieux aussi longtemps que le workflow existe. Les evals permettent de détecter le moment où un Skill d’augmentation de capacité devient du poids mort.

L’outillage supporte un mode benchmark pour suivre les taux de réussite et la consommation de tokens d’une mise à jour de modèle à l’autre, une exécution parallèle multi-agents pour éviter la contamination de contexte pendant les tests, et un agent comparateur qui effectue des comparaisons A/B à l’aveugle entre des sorties avec et sans le Skill appliqué.

Le rendement cumulé

Sur les centaines de Skills que j’ai vus et les dizaines que je maintiens, un pattern tient bon : la valeur d’un Skill vient de l’itération, pas du premier jet.

La structure en dossier, c’est la façon dont vous façonnez la fenêtre de contexte de Claude. Les Gotchas convertissent vos échecs en connaissances réutilisables. Les evals mesurent si cette connaissance tient toujours la route.

Écrire un SKILL.md prend dix minutes. Ajouter des Gotchas à partir de vrais échecs, construire des cas d’eval et inclure des scripts de validation, ça prend plutôt dix heures. Cet investissement se rembourse à chaque exécution du Skill. Montez-en un ce soir. Au matin, il aura accompli du travail que vous n’avez pas eu à faire.