Bonnes pratiques et pieges courants#

Les regles qui separent une skill qui dort dans un dossier d'une skill que toute l'equipe utilise sans y penser.

Temps de lecture : 14 min | Niveau : Intermediaire

Ce que tu sauras faire apres#

• Appliquer les 7 regles d'or de la redaction d'une skill.
• Doser le niveau de liberte laisse a l'agent selon la fragilite de la tache.
• Versionner et partager tes skills sans casser le travail des autres.
• Diagnostiquer une skill qui ne se declenche pas ou qui deraille.
• Verifier une skill avant de la partager, avec une checklist.
• Savoir quel outil lance reellement des evaluations sur une skill.

1. 🥇 Les 7 regles d'or#

Regle 1 : une skill = un savoir-faire#

Une skill qui fait trois choses ne se declenche correctement pour aucune des trois, parce que sa description devient floue.

• Mauvais : outils-data (audit + documentation + tests + rapport).
• Bon : quatre skills separees, chacune avec sa description precise.

Le test : si tu n'arrives pas a ecrire la description en deux phrases, c'est qu'il y a deux skills.

Regle 2 : la description fait tout le travail de declenchement#

C'est le seul texte que l'agent lit en permanence. Elle doit contenir :

• ce que fait la skill, a la troisieme personne ;
• quand l'utiliser, avec les mots exacts que tu tapes.

La doc precise pourquoi c'est critique : l'agent peut avoir plus de 100 skills disponibles, et c'est uniquement sur la description qu'il choisit.

Regle 3 : le SKILL.md court, le detail en reference#

Limite documentee : moins de 500 lignes pour le corps du SKILL.md. Au-dela, decoupe.

Regle 4 : references a un seul niveau#

Tous les fichiers annexes se lient directement depuis SKILL.md.

Mauvais : SKILL.md renvoie a avance.md, qui renvoie a details.md. L'agent risque de ne lire qu'un extrait (avec un head -100) et de passer a cote de l'information.

Bon : SKILL.md liste tout, chaque fichier a sa ligne, avec ce qu'il contient.

Et dans tout fichier de plus de 100 lignes, mets un sommaire en haut, pour que le perimetre soit visible meme sur une lecture partielle.

Regle 5 : n'ecris que ce que l'agent ne sait pas#

Pour chaque paragraphe, pose-toi la question de la doc officielle : « Est-ce que ce paragraphe justifie son cout en tokens ? »

AVANT (verbeux, environ 150 tokens) :

Le format Parquet est un format de stockage en colonnes tres repandu dans le monde
du big data. Il offre une bonne compression et permet de ne lire que les colonnes
necessaires. Pour le lire en Python, il existe plusieurs bibliotheques, mais pandas
est la plus simple a prendre en main. Il faut d'abord l'installer avec pip...

APRES (concis, environ 50 tokens) :

Lis les Parquet avec pandas :
pd.read_parquet(chemin, columns=[...])
Au-dela de 5 Go, utilise polars.

Pourquoi c'est mieux : l'agent sait deja ce qu'est Parquet. Ce qu'il ne sait pas, c'est ton choix de bibliotheque et ton seuil de bascule. Seul ca merite d'etre ecrit.

Regle 6 : vocabulaire constant#

Choisis un terme et garde-le du debut a la fin.

Regle 7 : donne un defaut, pas un menu#

Proposer cinq options fait hesiter l'agent et rend la sortie imprevisible.

• Mauvais : « tu peux utiliser pandas, ou polars, ou duckdb, ou pyspark... »
• Bon : « Utilise pandas. Pour un fichier de plus de 5 Go, utilise polars. »

Un defaut clair, plus une porte de sortie nommee.

2. ⚖️ Doser le niveau de liberte#

La doc propose une image utile : imagine l'agent qui avance sur un chemin.

• Pont etroit au-dessus du vide : il n'y a qu'une seule facon de passer. Donne des instructions exactes, un script a executer tel quel, sans variante. Exemple : une migration de base de donnees, un deploiement.
• Champ ouvert sans danger : beaucoup de chemins menent au but. Donne une direction generale et fais confiance. Exemple : une revue de code, une exploration de donnees.

3. 🗂️ Versionner et partager#

Commiter dans Git#

Une skill projet vit dans .claude/skills/. C'est un dossier comme un autre : tu le commites.

git add .claude/skills/convention-sql-equipe
git commit -m "skill: conventions SQL de l'equipe data"

Ca t'apporte trois choses.

• L'historique : tu sais quand une regle a ete ajoutee, et par qui.
• La revue : une modification de skill passe en pull request, comme du code. C'est important, parce qu'une skill influence tout ce que l'agent produit ensuite.
• Le retour arriere : si une nouvelle regle degrade les sorties, tu reviens a la version d'avant.

Trois facons de partager#

Rappel utile : une skill de plugin s'invoque avec le prefixe du plugin, /nom-du-plugin:nom-de-la-skill.

Ce qui ne se partage pas automatiquement#

Les skills personnalisees ne se synchronisent pas entre surfaces. Ce que tu televerses sur claude.ai n'est pas disponible via l'API, et tes skills Claude Code sont sur ton disque, independantes des deux autres. Sur claude.ai, les skills personnalisees sont propres a chaque utilisateur : chaque membre de l'equipe doit les televerser lui-meme, et il n'y a pas de gestion centralisee par un administrateur.

4. 🧭 Construire par l'evaluation, pas par l'imagination#

La doc est categorique : cree tes evaluations avant d'ecrire une documentation etendue. Sinon tu documentes des problemes imaginaires.

La methode tient en 5 temps.

1. Reperer les manques. Fais tourner l'agent sur de vraies taches, sans skill. Note ce qui rate.
2. Creer 3 scenarios qui testent precisement ces manques.
3. Mesurer la reference. Note le resultat obtenu sans skill. C'est ton point de comparaison.
4. Ecrire le minimum d'instructions pour corriger ce qui ratait. Rien de plus.
5. Iterer. Relance les 3 scenarios et compare a la reference.

Avec quoi executer ces evaluations#

La page « Skill authoring best practices » precise qu'il n'y a pas de mecanisme integre pour lancer ces evaluations : le format JSON qu'elle montre est un exemple, pas un outil. Mais du cote de Claude Code, deux outils existent bel et bien.

Les deux ne lisent pas les fichiers de cas l'un de l'autre. Pour une skill seule, commence par skill-creator.

Pense aussi a tester avec tous les modeles que tu comptes utiliser : Haiku, Sonnet et Opus ne reagissent pas pareil a la meme skill. Ce qui suffit a un modele puissant peut manquer de guidage pour un modele plus rapide et plus economique.

5. ⚠️ Les 10 pieges courants#

Deux pieges specifiques aux skills avec du code#

• Outils MCP sans prefixe. Si ta skill utilise un outil MCP (MCP = Model Context Protocol, le protocole qui branche des serveurs d'outils externes sur l'agent), ecris toujours le nom complet : NomDuServeur:nom_outil. Sans le prefixe, l'agent peut ne pas trouver l'outil, surtout si plusieurs serveurs sont connectes.
• Supposer qu'un paquet est installe. Mauvais : « utilise la bibliotheque pdf ». Bon : donne la commande d'installation, puis l'usage.

Et pour les scripts que tu bundles : resous, ne renvoie pas la balle. Un script qui plante en laissant l'agent se debrouiller est un mauvais script. Gere les erreurs, et justifie tes constantes par un commentaire, pour eviter les valeurs magiques sorties de nulle part.

6. ✅ Checklist avant de partager#

Adaptee de la checklist officielle.

Qualite de base :

• [ ] La description est specifique et contient les mots declencheurs
• [ ] La description dit ce que ca fait et quand l'utiliser
• [ ] Le corps du SKILL.md fait moins de 500 lignes
• [ ] Le detail est dans des fichiers separes
• [ ] Aucune information datee
• [ ] Vocabulaire constant du debut a la fin
• [ ] Les exemples sont concrets, pas abstraits
• [ ] Les references sont a un seul niveau
• [ ] Les procedures ont des etapes claires

Code et scripts :

• [ ] Les scripts gerent leurs erreurs
• [ ] Aucune constante non justifiee
• [ ] Les paquets requis sont listes
• [ ] Aucun chemin en antislash
• [ ] Une etape de verification pour les operations critiques

Tests :

• [ ] Au moins trois evaluations ecrites
• [ ] Testee avec Haiku, Sonnet et Opus, ou au moins avec les modeles que tu utilises vraiment
• [ ] Testee sur des cas reels, pas seulement des cas d'ecole
• [ ] Retours de l'equipe integres

7. Template : faire auditer une skill#

Voici une skill que j'ai ecrite : [COLLE_LE_SKILL_MD].
Contexte : elle doit se declencher quand je [DECRIS_LA_SITUATION].
Elle est utilisee par [TOI_SEUL / TON_EQUIPE_DE_N_PERSONNES].

Audite-la contre la checklist officielle des bonnes pratiques Anthropic :
1. La description declenchera-t-elle au bon moment ? Si non, reecris-la.
2. Qu'est-ce qui devrait sortir du SKILL.md vers un fichier de reference ?
3. Quelles phrases n'apportent rien parce que tu sais deja les faire ? Supprime-les.
4. Le niveau de liberte est-il adapte a la fragilite de la tache ?
5. Manque-t-il une etape de verification ?

Rends un tableau : Point | Probleme | Correction proposee.
Puis donne la version corrigee du fichier, complete.

A retenir#

• Une skill = un savoir-faire. Si la description fait plus de deux phrases, coupe en deux.
• La description est le seul levier de declenchement : soigne-la en priorite.
• SKILL.md sous 500 lignes, detail en reference/, liens a un seul niveau.
• N'ecris que ce que l'agent ne sait pas : ton contexte, tes regles, tes seuils.
• Adapte le niveau de liberte : script exact sur un pont etroit, direction generale en champ ouvert.
• Commite tes skills projet dans Git et fais-les relire comme du code.
• Construis a partir d'evaluations reelles, pas de besoins imagines. Le plugin skill-creator sait les faire tourner pour toi.

Sources#

• Skill authoring best practices
• Agent Skills in Claude Code
• Agent Skills - Overview
• Plugins overview
• Test plugins with evals
• Improving skill-creator: Test, measure, and refine Agent Skills
• Plugin skill-creator (depot officiel)
• Equipping agents for the real world with Agent Skills
• Depot anthropics/skills