Ce que nous avons appris en construisant Claude Code : comment nous utilisons les Skills

• Dans Claude Code, les Skills constituent l’un des points d’extension les plus utilisés, et Anthropic partage ici un retour d’expérience concret issu de l’exploitation de centaines de skills en interne
• Un skill n’est pas un simple fichier Markdown, mais une structure de dossier contenant des scripts, des assets, des données, etc., que l’agent peut explorer et exploiter
• Ils se répartissent en 9 catégories de skills — référence de bibliothèque, validation produit, analyse de données, scaffolding de code, CI/CD, etc. — et un bon skill doit s’inscrire clairement dans une seule catégorie
• Lors de la création d’un skill, les conseils pratiques les plus importants portent sur la section Gotchas, l’usage du système de fichiers, la divulgation progressive (Progressive Disclosure) et le stockage des données
• À l’échelle d’une organisation, il est recommandé de distribuer les skills via une marketplace interne de plugins et de suivre leur efficacité à l’aide de hooks de mesure d’usage

---

Qu’est-ce qu’un Skill ?

• Une idée reçue fréquente sur les Skills est que ce serait « juste un fichier Markdown », alors qu’en réalité il s’agit d’une arborescence de dossier contenant des scripts, des assets, des données, etc.
• L’agent peut explorer ce dossier, en découvrir le contenu et le manipuler
• Dans Claude Code, les Skills offrent diverses options de configuration, avec la possibilité d’enregistrer des hooks dynamiques (dynamic hooks)
• Les skills les plus intéressants sont ceux qui exploitent de façon créative ces options de configuration et cette structure en dossiers

Les 9 catégories de skills

• En classant tous les skills utilisés en interne, ils se regroupent de manière récurrente en quelques catégories
• Un bon skill s’inscrit clairement dans une seule catégorie, alors qu’un skill confus chevauche plusieurs catégories

• 1. Library & API Reference

  • Skills qui expliquent comment utiliser correctement une bibliothèque, une CLI ou un SDK
  • Cela concerne non seulement les bibliothèques internes, mais aussi des bibliothèques courantes sur lesquelles Claude Code se trompe souvent
  • Ils incluent souvent un dossier de snippets de code de référence ainsi qu’une liste de points d’attention (gotchas)
  • Exemples : billing-lib (cas limites d’une bibliothèque interne de facturation), internal-platform-cli (toutes les sous-commandes et exemples d’usage d’un wrapper CLI interne), frontend-design (amélioration de l’application du design system)

• 2. Product Verification

  • Skills qui décrivent comment tester et valider qu’un code fonctionne correctement
  • Ils sont souvent utilisés avec des outils externes comme Playwright ou tmux
  • Ils sont très utiles pour garantir la fiabilité des sorties de Claude, au point qu’il vaut la peine pour un ingénieur de passer une semaine entière à créer un excellent skill de validation
  • Il est recommandé d’amener Claude à enregistrer sa sortie en vidéo ou à imposer des assertions programmatiques sur l’état à chaque étape
  • Exemples : signup-flow-driver (exécute inscription → validation d’email → onboarding dans un navigateur headless), checkout-verifier (fait tourner l’UI de paiement avec des cartes de test Stripe puis vérifie l’état de la facture), tmux-cli-driver (pour tester des CLI interactives nécessitant un TTY)

• 3. Data Fetching & Analysis

  • Skills qui se connectent aux stacks de données et de monitoring
  • Ils peuvent inclure des bibliothèques de récupération de données avec credentials, des ID de dashboards spécifiques et des guides de workflow génériques
  • Exemples : funnel-query (tables contenant les événements nécessaires et le user_id canonique pour le funnel inscription → activation → paiement), cohort-compare (comparaison de rétention/taux de conversion entre deux cohortes avec signalement de la significativité statistique), grafana (UID de sources de données, noms de clusters, table de correspondance problème → dashboard)

• 4. Business Process & Team Automation

  • Skills qui automatisent des workflows répétitifs avec une seule commande
  • Les instructions sont relativement simples, mais elles peuvent avoir des dépendances complexes vers d’autres skills ou des MCP
  • Stocker les résultats des exécutions précédentes dans un fichier de log aide le modèle à rester cohérent et à tenir compte de l’historique
  • Exemples : standup-post (standup formaté à partir du ticket tracker, de l’activité GitHub et de Slack), create-ticket (workflow de création avec schéma imposé), weekly-recap (post récapitulatif à partir des PR mergées, tickets fermés et déploiements)

• 5. Code Scaffolding & Templates

  • Skills qui génèrent le boilerplate d’un framework pour une fonctionnalité précise de la codebase
  • Ils peuvent être combinés avec des scripts composables et sont particulièrement utiles lorsqu’il existe des exigences en langage naturel qu’on ne peut pas entièrement couvrir par le code
  • Exemples : new-framework-workflow (scaffolding d’un nouveau service/workflow/handler avec annotations), new-migration (template de fichier de migration et points d’attention), create-app (nouvelle app interne avec authentification, logging et configuration de déploiement déjà branchés)

• 6. Code Quality & Review

  • Skills qui imposent la qualité de code dans l’organisation et aident à la revue de code
  • Pour une robustesse maximale, ils peuvent inclure des scripts ou outils déterministes
  • Ils peuvent aussi être exécutés automatiquement via un hook ou dans une GitHub Action
  • Exemples : adversarial-review (un sous-agent avec un regard neuf critique → corrige → itère jusqu’à ce que les remarques tombent au niveau du simple nitpick), code-style (impose un style de code que Claude maîtrise mal par défaut), testing-practices (indique comment écrire les tests et quoi tester)

• 7. CI/CD & Deployment

  • Skills qui permettent de récupérer, pousser et déployer du code dans la codebase
  • Ils peuvent référencer d’autres skills pour collecter des données
  • Exemples : babysit-pr (surveillance de PR → relance de CI flaky → résolution des conflits de merge → activation de l’auto-merge), deploy-service (build → smoke tests → rollout progressif du trafic → comparaison du taux d’erreur → rollback automatique en cas de régression), cherry-pick-prod (worktree isolé → cherry-pick → résolution de conflits → création d’une PR à partir d’un template)

• 8. Runbooks

  • Skills qui prennent en entrée des symptômes (thread Slack, alerte, signature d’erreur, etc.), mènent une investigation multi-outils et produisent un rapport structuré
  • Exemples : service-debugging (cartographie symptômes → outils → motifs de requêtes), oncall-runner (récupère les alertes → vérifie les causes fréquentes → formate le résultat), log-correlator (collecte les logs de tous les systèmes liés à partir d’un ID de requête)

• 9. Infrastructure Operations

  • Skills qui exécutent les procédures courantes de maintenance et d’exploitation, avec des garde-fous pour les actions destructrices
  • Ils aident les ingénieurs à suivre plus facilement les bonnes pratiques sur des opérations critiques
  • Exemples : resource-orphans (détection des pods/volumes orphelins → notification Slack → période d’attente → confirmation utilisateur → nettoyage en cascade), dependency-management (workflow d’approbation des dépendances de l’organisation), cost-investigation (buckets et motifs de requêtes pour enquêter sur une flambée des coûts de stockage/egress)

Conseils pour écrire des skills

• N’écrivez pas l’évidence

  • Claude Code sait déjà beaucoup de choses sur la codebase et a aussi des opinions de base sur la programmation
  • Si vous créez un skill centré sur la connaissance, vous devez vous concentrer sur des informations qui éloignent Claude de son mode de pensée général par défaut
  • Le skill frontend-design en est un bon exemple : il a été conçu par des ingénieurs d’Anthropic en itérant avec des clients pour améliorer le sens du design de Claude, en l’amenant à éviter des motifs typiques comme la police Inter et les dégradés violets

• Construire une section Gotchas

  • Dans tous les skills, le contenu ayant le plus fort signal est la section Gotchas
  • Elle doit être alimentée à partir des points d’échec fréquents rencontrés par Claude lors de l’usage du skill
  • L’idéal est de continuer à mettre ces gotchas à jour au fil du temps

• Exploiter le système de fichiers et la divulgation progressive

  • Puisqu’un skill est un dossier, il faut utiliser tout le système de fichiers comme outil de context engineering et de divulgation progressive
  • Si vous indiquez à Claude quels fichiers contient le skill, il les lira au bon moment
  • Forme la plus simple : séparer les signatures détaillées de fonctions et les exemples d’usage dans un Markdown dédié comme references/api.md
  • Si la sortie finale est en Markdown, on peut inclure des fichiers template dans le dossier assets/
  • Des dossiers de références, scripts et exemples améliorent l’efficacité de travail de Claude

• Ne contraignez pas excessivement Claude

  • Claude essaie de suivre les instructions, mais comme les skills sont très réutilisables, il faut se méfier d’instructions trop spécifiques
  • Donnez les informations nécessaires, mais laissez une marge pour s’adapter avec souplesse à la situation

• Concevoir le processus de setup

  • Certains skills nécessitent une étape de configuration pour collecter du contexte auprès de l’utilisateur
  • Exemple : si un skill publie un standup sur Slack, il faut demander sur quel canal le poster
  • Bon pattern : enregistrer les informations de setup dans un fichier config.json du répertoire du skill ; si rien n’est configuré, l’agent interroge l’utilisateur
  • Pour poser des questions structurées à choix multiples, il est possible d’indiquer l’usage de l’outil AskUserQuestion

• Le champ Description est destiné au modèle

  • Quand Claude Code démarre une session, il construit la liste des descriptions de tous les skills disponibles
  • Claude parcourt cette liste pour décider : « Existe-t-il un skill adapté à cette demande ? »
  • Le champ description n’est donc pas un résumé, mais une explication de quand déclencher ce skill

• Mémoire et stockage des données

  • Un skill peut inclure une mémoire sous forme de données stockées
  • Cela peut aller d’un simple fichier de log texte ou JSON jusqu’à une base de données SQLite
  • Exemple : si le skill standup-post stocke tout l’historique dans standups.log, Claude peut le relire à l’exécution suivante pour comprendre ce qui a changé depuis la veille
  • Les données enregistrées dans le répertoire du skill peuvent être supprimées lors d’une mise à niveau du skill ; il faut donc les stocker dans le dossier stable ${CLAUDE_PLUGIN_DATA}

• Stocker des scripts et générer du code

  • L’un des outils les plus puissants que l’on puisse donner à Claude est le code lui-même
  • En fournissant des scripts et des bibliothèques, Claude peut se concentrer sur la composition plutôt que sur la reconstitution de boilerplate
  • Exemple : inclure dans un skill de data science une bibliothèque de fonctions utilitaires pour récupérer des données depuis des sources d’événements
  • Claude peut alors combiner ces fonctions pour générer des scripts à la volée et les utiliser pour des analyses complexes comme « que s’est-il passé mardi ? »

• On Demand Hooks

  • Un skill peut inclure des hooks qui ne s’activent que lorsqu’il est invoqué et qui ne persistent que pendant la session
  • Cela convient à des hooks à opinion forte qui seraient trop coûteux à exécuter en permanence, mais très utiles dans certaines situations
  • Exemples :
    • /careful — bloque rm -rf, DROP TABLE, force-push, kubectl delete avec un matcher PreToolUse, activé uniquement lors d’opérations en production
    • /freeze — bloque tous les Edit/Write hors d’un répertoire donné, utile en debugging pour éviter des modifications involontaires

Déploiement des skills

• L’un des grands avantages des skills est qu’ils peuvent être partagés avec toute l’équipe
• Il existe deux façons de les partager :
  • committer le skill dans le repo (sous ./.claude/skills)
  • le transformer en plugin puis l’uploader sur la marketplace Claude Code Plugin, que les utilisateurs installent

• Gestion de la marketplace

  • Pour une petite équipe travaillant sur peu de repos, la bonne approche est souvent de les committer directement dans le repo
  • Les skills commités s’ajoutent petit à petit au contexte du modèle ; à grande échelle, une marketplace interne de plugins devient donc plus avantageuse
  • Il n’existe aucune équipe centrale chargée de décider quels skills doivent entrer dans la marketplace ; les plus utiles sont découverts naturellement
  • Si vous avez un skill à tester, vous pouvez l’uploader dans le dossier sandbox de GitHub puis l’annoncer sur Slack ou ailleurs
  • S’il obtient suffisamment de traction, son propriétaire ouvre une PR pour le déplacer vers la marketplace
  • Comme il est facile de créer des skills médiocres ou redondants, il est important d’avoir un mécanisme de curation avant la mise en production

• Composition des skills

  • Il peut y avoir besoin de dépendances entre skills (par exemple : skill d’upload de fichiers + skill de génération et d’upload de CSV)
  • Ni la marketplace ni les skills n’intègrent nativement de gestion des dépendances, mais si un skill en référence un autre par son nom, le modèle l’appellera s’il est installé

• Mesure des skills

  • Pour suivre la performance des skills, ils journalisent l’usage des skills dans l’entreprise via un hook PreToolUse
  • Cela sert à repérer les skills populaires, ou ceux qui se déclenchent moins que prévu

Conclusion

• Les Skills sont un outil extrêmement puissant et flexible pour les agents, mais ils en sont encore à leurs débuts, et tout le monde cherche encore la meilleure manière de les exploiter
• Cet article n’est pas un guide définitif, mais plutôt une collection de conseils qui ont fait leurs preuves en pratique
• La plupart des skills ont commencé par quelques lignes et un gotcha, puis ont été améliorés en continu à mesure que Claude rencontrait de nouveaux cas limites