Quand Addy Osmani — le responsable de l'ingénierie de Google Chrome qui a enseigné les patrons de conception JavaScript à toute une génération de développeurs — a publié ce mois-ci en open source une bibliothèque de plus de vingt compétences d'ingénierie de production, elle a dépassé 14 000 étoiles sur GitHub en quelques jours. La raison est simple : la plupart des compétences d'agent qui circulent sur GitHub sont des expériences inachevées. Les siennes ont été conçues par quelqu'un qui a livré du logiciel à grande échelle. Cet écart — entre une compétence qui fonctionne et une compétence qui gaspille une fenêtre de contexte de 200 000 jetons — est le sujet de ce guide.
Si vous espériez que votre tas de fichiers .md éparpillés aide discrètement votre agent de codage, la vérité dérangeante est qu'il ne le fait probablement pas. Voici comment écrire des compétences qui font réellement la différence.
Ce qu'est vraiment une compétence
Une compétence d'agent est un dossier dont le cœur est un fichier SKILL.md. Ce fichier a deux parties : des métadonnées YAML (un champ name et un champ description) et un corps en markdown contenant des instructions étape par étape. En option, le dossier contient aussi des documents de référence et des scripts exécutables qui ne se chargent qu'au besoin.
Le format est né chez Anthropic et est devenu un standard ouvert de fait. Les mêmes fichiers se branchent désormais sur Claude Code, Cursor, GitHub Copilot, Codex CLI, Gemini CLI, Windsurf et OpenCode — tout agent qui lit des instructions markdown. Écrivez une fois, exécutez partout. Cette portabilité est précisément pourquoi bien rédiger ses compétences rapporte sur chaque outil utilisé par votre équipe.
La divulgation progressive : l'idée centrale
Le concept le plus important est la divulgation progressive. Au démarrage de la session, votre agent ne lit que le name et la description de chaque compétence installée — environ 100 jetons chacune. Il ne lit le corps complet de SKILL.md que lorsque la compétence devient pertinente, et les fichiers de référence groupés uniquement lorsqu'une tâche précise l'exige.
C'est ce qui vous permet d'installer 100 compétences sans noyer la fenêtre de contexte. Une étude de février 2026 de Bosch Research et Carnegie Mellon, qui a analysé plus de 40 000 compétences publiques, a établi que le corps médian d'une compétence avoisine 1 400 jetons — petit, ciblé, chargé à la demande. L'architecture repose sur le système de fichiers : les scripts s'exécutent via bash sans jamais charger leur source dans le contexte, donc seule la sortie coûte des jetons.
Les règles pratiques qui en découlent :
- Maintenez le corps de
SKILL.mdsous 500 lignes. S'il dépasse, scindez-le. - Gardez les liens de référence à un niveau de profondeur depuis
SKILL.md. Les agents prévisualisent partiellement les fichiers profondément imbriqués et se retrouvent avec des informations incomplètes. - Pour les fichiers de référence de plus de 100 lignes, ajoutez une table des matières en tête pour que l'agent voie la portée complète même en lecture partielle.
Anatomie d'une compétence qui fonctionne
Voici le minimum de métadonnées dont tout SKILL.md a besoin :
---
name: processing-pdfs
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDFs or document extraction.
---Deux champs accomplissent un travail énorme. Le name doit être en minuscules, chiffres et tirets uniquement, sous 64 caractères — la forme en gérondif comme processing-pdfs ou testing-code se lit le mieux. La description, plafonnée à 1 024 caractères, est la ligne la plus importante de tout le fichier, car l'agent l'utilise pour choisir parmi des dizaines de compétences possibles.
Rédigez les descriptions à la troisième personne et chargez-les à la fois du quoi fait la compétence et du quand l'utiliser :
# Bon — précis, avec déclencheurs
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing spreadsheets or .xlsx files.
# Mauvais — vague, sans déclencheurs
description: Helps with documentsUne description comme « Helps with documents » ne donne à l'agent aucun critère de discrimination. Elle ne se déclenchera jamais, ou se déclenchera au mauvais moment.
Ajustez la liberté à la fragilité
Le corps d'une excellente compétence calibre la latitude accordée à l'agent selon la fragilité de la tâche. Imaginez l'agent comme un robot parcourant un chemin :
- Champ ouvert, nombreuses routes sûres — utilisez une liberté élevée. Donnez une direction générale en prose et faites confiance au modèle. La revue de code en est un bon exemple : la bonne approche dépend du contexte.
## Processus de revue de code
1. Analyser la structure et l'organisation du code
2. Vérifier les bogues potentiels et les cas limites
3. Suggérer des améliorations de lisibilité et de maintenabilité
4. Vérifier le respect des conventions du projet- Pont étroit avec des falaises de chaque côté — utilisez une liberté faible. Donnez une commande exacte et interdisez toute déviation. La migration de base de données est le cas canonique :
## Migration de base de données
Exécutez exactement ce script :
`python scripts/migrate.py --verify --backup`
Ne modifiez pas la commande et n'ajoutez aucun indicateur.Une mauvaise calibration est la cause la plus fréquente de dérapage : trop de liberté sur une tâche fragile invite à l'improvisation là où vous attendiez de la précision.
Les boucles de vérification ne sont pas négociables
Les compétences d'Osmani ajoutent une couche que la plupart des compétences maison ignorent : chacune se termine par des exigences de preuve et un tableau anti-rationalisation — des excuses courantes qu'un agent pourrait avancer pour sauter une étape, accompagnées d'une réfutation documentée. La philosophie est « du processus, pas de la prose » : un flux avec points de contrôle et critères de sortie, pas un mur de texte de référence.
Le motif qui apporte le plus grand bond de qualité est la boucle valider-corriger-répéter. Donnez à l'agent une liste de contrôle qu'il copie dans sa réponse et coche, et un validateur qu'il doit réussir avant de continuer :
## Processus d'édition de document
1. Effectuez vos modifications dans word/document.xml
2. Validez immédiatement : python ooxml/scripts/validate.py unpacked_dir/
3. Si la validation échoue :
- Examinez le message d'erreur
- Corrigez les problèmes
- Relancez la validation
4. Ne continuez que lorsque la validation réussit
5. Reconstruisez et testez la sortiePour les opérations par lots ou destructrices, allez plus loin avec le motif planifier-valider-exécuter : faites écrire à l'agent un fichier de plan structuré, validez-le avec un script, puis appliquez les changements seulement ensuite. Éditer 50 champs d'un formulaire depuis un tableur sans cela invite à référencer des champs inexistants ; avec, les erreurs surgissent avant que rien ne soit touché.
Construisez les évaluations avant la documentation
Le plus grand changement d'état d'esprit des recommandations officielles : écrivez vos évaluations d'abord. Lancez l'agent sur des tâches réelles sans compétence, documentez ses échecs, puis bâtissez trois scénarios de test qui capturent ces échecs. Établissez une référence, écrivez le minimum d'instructions pour réussir, et itérez. Cela garantit que votre compétence résout un vrai problème plutôt que d'en documenter un imaginaire.
Le flux le plus efficace utilise deux instances du modèle. « Claude A » vous aide à rédiger et affiner ; « Claude B » — une instance neuve chargée de la compétence — exécute des tâches réelles. Vous observez où B bute, ramenez les détails à A, et affinez. Les modèles comprennent nativement le format des compétences, donc vous n'avez pas besoin d'une invite spéciale pour obtenir une bonne structure — vous avez besoin d'une observation réelle de l'usage.
Une liste de contrôle avant publication
Avant de valider une compétence, vérifiez :
- La description est précise et nomme des déclencheurs concrets.
- Le corps de
SKILL.mdest sous 500 lignes ; le détail vit dans des fichiers séparés. - Aucune information datée ne se glisse — placez les motifs obsolètes dans une section « anciens motifs ».
- La terminologie est cohérente (choisissez « point de terminaison API » et ne dérivez pas vers « URL » ou « route »).
- Les références sont à un niveau de profondeur et les exemples concrets, pas abstraits.
- Les scripts gèrent les erreurs explicitement au lieu de les renvoyer à l'agent, et les constantes sont documentées plutôt que des nombres magiques.
- Des boucles de vérification existent pour tout ce qui est critique pour la qualité.
Pourquoi cela compte pour les équipes MENA
Parce que les compétences sont du simple markdown fonctionnant sur tous les grands agents, elles constituent une couverture contre la dépendance à un fournisseur — une préoccupation réelle pour les équipes en Tunisie, en Arabie saoudite et dans la région, qui composent avec des accès et des tarifs de modèles changeants. Une bibliothèque de compétences bien écrite est un savoir institutionnel portable : les flux de travail d'ingénieurs seniors dont dépend votre équipe, encodés une fois et exécutables sur l'agent le plus rapide, le moins cher ou le plus disponible ce trimestre. C'est un levier qu'un tas de .md éparpillés ne donnera jamais.
La conclusion est celle qui a fait mouche avec la sortie d'Osmani : une compétence n'est pas un extrait d'invite jeté dans un dossier. C'est une petite unité testée, à but unique, de jugement d'ingénierie. Traitez-la comme du code de production — concise, calibrée et vérifiée — et vos agents commenceront à se comporter comme les ingénieurs seniors que vous vouliez.
Sources : addyosmani/agent-skills sur GitHub · Bonnes pratiques de rédaction de compétences — Docs Claude · Les compétences fonctionnent mais la plupart des équipes les construisent mal — O'Reilly Radar