16 KiB
Leçons de la construction de Claude Code : comment nous utilisons les skills — Thariq
Un guide complet sur la façon dont Anthropic utilise les skills en interne, partagé par Thariq (@trq212) le 17 mars 2026.
| ← Retour à Claude Code Best Practice |  |
Contexte
Les skills sont devenus l'un des points d'extension les plus utilisés dans Claude Code. Ils sont flexibles, faciles à créer et simples à distribuer. Mais cette flexibilité rend aussi difficile de savoir ce qui marche le mieux. Thariq partage les leçons tirées d'un usage intensif des skills chez Anthropic, avec des centaines d'entre eux en service actif.
Que sont les skills ?
Une idée reçue courante est que les skills sont « juste des fichiers markdown », mais le plus intéressant est qu'il s'agit de dossiers pouvant inclure des scripts, des assets, des données, etc. — des choses que l'agent peut découvrir, explorer et manipuler. Les skills offrent aussi une grande variété d'options de configuration, dont l'enregistrement de hooks dynamiques.
Types de skills
Après avoir catalogué tous leurs skills, l'équipe a remarqué qu'ils se regroupent en 9 catégories récurrentes. Les meilleurs skills s'inscrivent proprement dans une seule ; les plus confus chevauchent plusieurs catégories.
1/ Référence de bibliothèque & d'API
Des skills qui expliquent comment utiliser correctement une bibliothèque, un CLI ou des SDK. Ils peuvent concerner des bibliothèques internes ou des bibliothèques courantes avec lesquelles Claude Code a parfois des difficultés. Ils incluent souvent un dossier d'extraits de code de référence et une liste de pièges à éviter lors de l'écriture d'un script.
Exemples : billing-lib, internal-platform-cli, frontend-design
2/ Vérification produit
Des skills qui décrivent comment tester ou vérifier que ton code fonctionne. Ils sont souvent associés à un outil externe comme Playwright, tmux, etc. Les skills de vérification sont extrêmement utiles pour s'assurer que la sortie de Claude est correcte. Cela peut valoir le coup qu'un ingénieur passe une semaine entière à rendre tes skills de vérification excellents.
Exemples : signup-flow-driver, checkout-verifier, tmux-cli-driver
3/ Récupération & analyse de données
Des skills qui se connectent à tes stacks de données et de monitoring. Ils peuvent inclure des bibliothèques pour récupérer tes données avec des identifiants, des IDs de dashboard spécifiques, etc., ainsi que des instructions sur les workflows courants ou les moyens d'obtenir des données.
Exemples : funnel-query, cohort-compare, grafana
4/ Processus métier & automatisation d'équipe
Des skills qui automatisent des workflows répétitifs en une seule commande. Ce sont généralement des instructions assez simples, mais qui peuvent avoir des dépendances plus complexes vers d'autres skills ou MCP. Sauvegarder les résultats précédents dans des fichiers de log peut aider le modèle à rester cohérent et à réfléchir aux exécutions précédentes du workflow.
Exemples : standup-post, create-<ticket-system>-ticket, weekly-recap
5/ Échafaudage de code & templates
Des skills qui génèrent du boilerplate de framework pour une fonction spécifique du codebase. Tu peux combiner ces skills avec des scripts composables. Ils sont particulièrement utiles quand ton échafaudage a des exigences en langage naturel qui ne peuvent pas être couvertes purement par du code.
Exemples : new-<framework>-workflow, new-migration, create-app
6/ Qualité & revue de code
Des skills qui font respecter la qualité du code au sein de ton organisation et aident à relire le code. Ils peuvent inclure des scripts ou outils déterministes pour une robustesse maximale. Tu voudras peut-être lancer ces skills automatiquement via des hooks ou à l'intérieur d'une GitHub Action.
Exemples : adversarial-review, code-style, testing-practices
7/ CI/CD & déploiement
Des skills qui t'aident à récupérer, pousser et déployer du code dans ton codebase. Ces skills peuvent référencer d'autres skills pour collecter des données.
Exemples : babysit-pr, deploy-<service>, cherry-pick-prod
8/ Runbooks
Des skills qui partent d'un symptôme (comme un fil Slack, une alerte ou une signature d'erreur), déroulent une investigation multi-outils et produisent un rapport structuré.
Exemples : <service>-debugging, oncall-runner, log-correlator
9/ Opérations d'infrastructure
Des skills qui effectuent de la maintenance routinière et des procédures opérationnelles — dont certaines impliquent des actions destructrices qui bénéficient de garde-fous. Ils permettent aux ingénieurs de suivre plus facilement les bonnes pratiques dans les opérations critiques.
Exemples : <resource>-orphans, dependency-management, cost-investigation
Astuces pour créer des skills
9 bonnes pratiques pour écrire des skills efficaces, plus des conseils sur la distribution et la mesure.
Astuce 1 : N'énonce pas l'évidence
Claude Code en sait beaucoup sur ton codebase, et Claude en sait beaucoup sur le code, y compris de nombreuses opinions par défaut. Si tu publies un skill qui porte avant tout sur de la connaissance, essaie de te concentrer sur l'information qui pousse Claude hors de son mode de pensée habituel. Le skill de design frontend en est un excellent exemple — il a été construit en itérant avec des clients pour améliorer le goût de Claude en matière de design, en évitant les patterns classiques comme la police Inter et les dégradés violets.
Astuce 2 : Construis une section Gotchas (pièges)
Le contenu à plus fort signal dans n'importe quel skill est la section Gotchas. Ces sections doivent être bâties à partir des points d'échec courants que Claude rencontre en utilisant ton skill. Idéalement, tu mettras ton skill à jour au fil du temps pour capturer ces pièges.
Astuce 3 : Utilise le système de fichiers & la divulgation progressive
Un skill est un dossier, pas seulement un fichier markdown. Tu devrais penser l'ensemble du système de fichiers comme une forme d'ingénierie de contexte et de divulgation progressive. Dis à Claude quels fichiers se trouvent dans ton skill, et il les lira au moment opportun. La forme la plus simple est de pointer vers d'autres fichiers markdown — par ex. répartir les signatures de fonctions détaillées et les exemples d'usage dans references/api.md. Tu peux avoir des dossiers de références, de scripts, d'exemples, etc.
Astuce 4 : Évite de mettre Claude sur des rails
Claude essaiera généralement de s'en tenir à tes instructions, et comme les skills sont très réutilisables, tu voudras éviter d'être trop spécifique. Donne à Claude l'information dont il a besoin, mais laisse-lui la flexibilité de s'adapter à la situation. Plutôt que des instructions prescriptives étape par étape, donne l'objectif et les contraintes.
Astuce 5 : Réfléchis à la configuration (setup)
Certains skills peuvent nécessiter d'être configurés avec du contexte de la part de l'utilisateur. Un bon pattern est de stocker ces informations de setup dans un fichier config.json dans le répertoire du skill. Si la config n'est pas en place, l'agent peut alors demander l'information à l'utilisateur. Tu peux instruire Claude d'utiliser l'outil AskUserQuestion pour des questions à choix multiples structurées.
Astuce 6 : Le champ Description est destiné au modèle
Quand Claude Code démarre une session, il construit une liste de chaque skill disponible avec sa description. C'est cette liste que Claude parcourt pour décider « y a-t-il un skill pour cette requête ? ». Ce qui signifie que le champ description n'est pas un résumé — c'est une description de quand déclencher ce skill. Écris-le pour le modèle.
Astuce 7 : Mémoire & stockage de données
Certains skills peuvent inclure une forme de mémoire en stockant des données en leur sein. Tu pourrais stocker des données dans quelque chose d'aussi simple qu'un fichier texte en append-only ou des fichiers JSON, ou d'aussi complexe qu'une base SQLite. Les données stockées dans le répertoire du skill peuvent être supprimées lors d'une mise à jour du skill, alors utilise ${CLAUDE_PLUGIN_DATA} comme dossier stable par plugin pour y stocker des données.
Astuce 8 : Stocke des scripts & génère du code
L'un des outils les plus puissants que tu puisses donner à Claude, c'est du code. Donner à Claude des scripts et des bibliothèques lui permet de consacrer ses tours à la composition, en décidant quoi faire ensuite plutôt qu'à reconstruire du boilerplate. Claude peut alors générer des scripts à la volée pour composer cette fonctionnalité en vue d'analyses plus avancées.
Astuce 9 : Hooks à la demande
Les skills peuvent inclure des hooks qui ne s'activent que lorsque le skill est appelé, et qui durent le temps de la session. Utilise cela pour des hooks plus opinionés que tu ne veux pas exécuter en permanence mais qui sont extrêmement utiles parfois.
Exemples :
/careful— bloque rm -rf, DROP TABLE, force-push, kubectl delete via un matcher PreToolUse sur Bash/freeze— bloque tout Edit/Write qui n'est pas dans un répertoire spécifique
Distribuer des skills
Deux façons de partager des skills avec ton équipe :
- Versionner dans ton dépôt (sous
.claude/skills) — idéal pour les petites équipes travaillant sur relativement peu de dépôts - Créer un plugin et disposer d'une marketplace de plugins Claude Code où les utilisateurs peuvent uploader et installer des plugins
Chaque skill versionné ajoute aussi un petit peu au contexte du modèle. À mesure que tu passes à l'échelle, une marketplace de plugins interne te permet de distribuer des skills et de laisser ton équipe décider lesquels installer.
Gérer une marketplace
Il n'y a pas d'équipe centralisée qui décide quels skills entrent dans une marketplace. Au lieu de cela, essaie de trouver les skills les plus utiles de façon organique. Uploade-les dans un dossier bac à sable sur GitHub et oriente les gens vers lui sur Slack ou d'autres forums. Une fois qu'un skill a pris de l'ampleur (ce qu'il revient à son propriétaire de décider), il peut ouvrir une PR pour le déplacer dans la marketplace. La curation avant publication est importante pour éviter les skills redondants.
Composer des skills
Tu voudras peut-être avoir des skills qui dépendent les uns des autres. Par exemple, un skill d'upload de fichier qui uploade un fichier, et un skill de génération de CSV qui crée un CSV et l'uploade. Ce type de gestion de dépendances n'est pas encore intégré nativement aux marketplaces ni aux skills, mais tu peux simplement référencer d'autres skills par leur nom, et le modèle les invoquera s'ils sont installés.
Mesurer les skills
Pour comprendre comment un skill se comporte, utilise un hook PreToolUse qui te permet de journaliser l'usage des skills au sein de l'entreprise. Ainsi, tu peux repérer les skills populaires ou ceux qui se déclenchent moins que prévu.
Conclusion
Les skills sont des outils incroyablement puissants et flexibles pour les agents, mais c'est encore le début et nous découvrons tous comment les utiliser au mieux. Vois ceci davantage comme un sac d'astuces utiles que nous avons vues fonctionner que comme un guide définitif. La meilleure façon de comprendre les skills est de te lancer, d'expérimenter et de voir ce qui marche pour toi. La plupart des nôtres ont commencé par quelques lignes et un seul piège, et se sont améliorés parce que les gens continuaient de les enrichir à mesure que Claude rencontrait de nouveaux cas limites.
