J'ai passé une semaine entière à faire la revue des skills et agents de base car ceux fournis par claude-code et autres sources disponibles en autre sur skills.sh sont de moyennes voir mauvaises qualités.
Vous me direz surement que c'est un bon début, mais si vous voulez mettre en place des workflows d'agents IA fiables, et que les scores qualités de vos skills et agents ne dépassent pas les 30% cela ne peut que vous menez à la catastrophe, ou produire des résultats très variables.
Avant de continuer de lire la suite de l'article, je vous invite à vous inscrire à ma newsletter, pour connaître en avant première les futurs sujets traités chaque semaine.
L'explosion de l'écosystème sans contrôle qualité
Une cartographie qui donne le vertige
L'écosystème des skills et agents Claude Code a explosé en quelques mois. Le repo awesome-agent-skills de VoltAgent recense à lui seul plus de 202 skills, compatibles avec Claude Code, Codex, Gemini CLI et Cursor. Côté agents, les collections communautaires dépassent les 100 subagents spécialisés. Au moins cinq repos « awesome » concurrents coexistent sur GitHub (VoltAgent, travisvn, karanb192, ComposioHQ, rahulvrane), avec une duplication significative entre eux et aucune déduplication ni évaluation croisée.
Le constat qui interpelle : zéro processus de review qualité formel n'est documenté dans ces repos. Aucune grille de scoring, aucun critère d'admission au-delà de la conformité technique minimale.
Le paradoxe du badge « Awesome »
Le badge « Awesome » est un signal de popularité, pas de qualité. L'organisation par source (officiel vs communautaire) sert de proxy implicite de fiabilité, mais un skill officiel mal implémenté reste un skill mal implémenté. La quantité prime systématiquement sur la qualité : tant qu'un skill « fonctionne » dans un cas nominal, il est accepté.
Les chiffres de l'industrie confirment le problème
Les données du rapport LangChain 2026 sont sans ambiguïté :
| Indicateur | Valeur |
|---|---|
| Organisations avec agents en production | 57,3 % |
| Citent la qualité comme obstacle n° 1 | 32 % |
| Ne font aucune évaluation | 29,5 % |
| Font des évaluations offline sur jeux de test | 52,4 % |
| Se fient uniquement à la revue humaine | 59,8 % |
| Utilisent le LLM-as-judge | 53,3 % |
En pratique, cela signifie que près d'un tiers des organisations déploient des agents en production sans avoir mesuré leur qualité. Et parmi celles qui évaluent, la majorité se fie à du jugement humain non structuré ou à un LLM-juge dont la reproductibilité est discutable.
| Repo communautaire | Skills/Agents | Grille qualité | Processus de review |
|---|---|---|---|
| awesome-agent-skills (VoltAgent) | 202+ skills | Aucune | Aucun formel |
| awesome-claude-code-subagents | 100+ agents | Aucune | Aucun formel |
| awesome-claude-skills (karanb192) | 50+ skills | Aucune | Aucun formel |
| awesome-claude-skills (travisvn) | 30+ skills | Aucune | Aucun formel |
Tous les développeurs font du TDD sur leurs codes mais pas sur les skills
Les bonnes pratiques officielles pour les skills
La documentation officielle d'Anthropic sur les skills est remarquablement détaillée. Voici les points fondamentaux :
- Description en troisième personne obligatoire (« Processes Excel files », pas « I can help you »)
- SKILL.md inférieur à 500 lignes avec progressive disclosure vers des fichiers externes
- Frontmatter YAML structuré avec name et description
- allowed-tools pour appliquer le principe du moindre privilège
- context: fork pour isoler l'exécution en sous-agent
- Nommage en forme gérondive : processing-pdfs, analyzing-spreadsheets
- Tester avec Haiku, Sonnet ET Opus pour valider la robustesse
Le principe fondamental résume tout : « Claude is already very smart — only add context Claude doesn't already have. » Autrement dit, chaque token dans un skill doit apporter une information que Claude ne possède pas nativement.
Les bonnes pratiques officielles pour les agents
La documentation des subagents définit des exigences tout aussi précises :
- Frontmatter obligatoire : name et description sont requis
- Description détaillée : Claude l'utilise pour décider quand déléguer
- Responsabilité unique : « each subagent should excel at one specific task »
- tools en allowlist pour restreindre les capacités
- Permission modes appropriés (default, acceptEdits, plan...)
- Hooks lifecycle (PreToolUse, PostToolUse, Stop) pour la validation conditionnelle
Le fossé entre documentation et réalité
L'erreur courante est de croire que l'existence de bonnes pratiques suffit à garantir leur adoption. En réalité, le fossé est béant :
# ❌ Skill communautaire typique --- name: my-helper description: "A useful helper skill" --- # My Helper I can help you with many things...
# ✅ Skill conforme aux bonnes pratiques Anthropic --- name: excel-data-processor description: "Processes Excel spreadsheets by extracting structured data, validating formulas, and generating summary reports. Handles .xlsx and .xls formats with multi-sheet support." --- # Excel data processor Extracts, validates, and summarizes data from Excel spreadsheets. ## When to use this skill - User asks to analyze an Excel file - User needs data extraction from spreadsheets - User wants formula validation or summary reports
Les descriptions vagues entraînent un taux d'activation d'environ 50 % — l'agent est ignoré la moitié du temps. Les outils trop permissifs gaspillent des tokens et ralentissent l'exécution. L'absence de context: fork pollue la conversation principale avec 3 000+ tokens de sortie brute. Comme l'explique l'analyse technique de Lee Han Chung, les descriptions sont le seul mécanisme de découverte parmi potentiellement des centaines de skills — le transformer raisonne sur ces descriptions pour choisir quel skill charger.
Anatomie des grilles d'audit : 42 points pour les agents, 49 pour les skills
Pourquoi un scoring déterministe ?
Le LLM-as-judge est utilisé par 53,3 % des organisations pour évaluer leurs agents, selon LangChain. Le problème : sa reproductibilité est insuffisante. Deux évaluations du même agent peuvent produire des résultats différents.
Les checks binaires garantissent l'objectivité : le critère est rempli ou il ne l'est pas. Pas de zone grise, pas de subjectivité. La passe Design (qualitative) complète le scoring par un jugement architectural, mais sur des critères explicites et documentés.
Cette approche s'inspire des grilles de code review : automatisable, traçable, versionnable. Chaque audit produit un score reproductible que l'on peut comparer dans le temps.
agent-reviewer : 42 points en quatre passes
La grille d'audit des agents Claude Code couvre quatre dimensions complémentaires :
Passe 1 — Frontmatter (11 points)
| Critère | Points | Description |
|---|---|---|
| name présent | 1 | Identifiant unique de l'agent |
| description commence par « Use this agent when » | 2 | Déclenchement fiable par Claude |
| 2+ exemples de déclenchement | 2 | Prompts utilisateur qui activent l'agent |
| commentary défini | 1 | Message affiché pendant l'exécution |
| Format user/assistant | 1 | Exemples de conversation |
| model spécifié | 1 | Modèle cible explicite |
| color défini | 1 | Identification visuelle |
| tools restreints | 2 | Least privilege appliqué |
Passe 2 — System prompt (11 points)
| Critère | Points | Description |
|---|---|---|
| Rôle en « You are » (2e personne) | 2 | Cohérence du prompt |
| Pas de première personne | 1 | Évite la confusion de rôle |
| Section Responsibilities | 2 | Périmètre explicite |
| Section Process/Steps | 2 | Workflow documenté |
| Section Output Format | 2 | Format de sortie spécifié |
| Section Edge Cases | 1 | Cas limites gérés |
| Longueur 500-10 000 caractères | 1 | Ni trop court, ni surchargé |
Passe 3 — Validation automatique (6 points)
| Critère | Points | Description |
|---|---|---|
| Scripts de validation sans erreurs | 3 | Exécution sans erreurs |
| Scripts de validation sans warnings | 3 | Exécution sans avertissements |
Passe 4 — Design (14 points)
| Critère | Points | Description |
|---|---|---|
| Responsabilité unique | 2 | Un agent = une tâche |
| Couplage faible | 2 | Indépendance entre agents |
| Triggering précis | 2 | Activation fiable et prévisible |
| Spécificité | 2 | Instructions non génériques |
| Actionnabilité | 2 | Chaque instruction est exécutable |
| Complétude | 2 | Tous les cas sont couverts |
| Séparation des préoccupations | 2 | Pas de mélange de responsabilités |
skill-reviewer : 49 points en quatre passes
La grille des skills couvre un périmètre différent, avec un focus sur la cohérence entre documentation et implémentation :
Passe 1 — Structure (18 points)
| Catégorie | Critères | Points |
|---|---|---|
| Frontmatter | name, slug, description, category, complexity, version, author, triggers, tags | 9 |
| Sections obligatoires | Titre, description, « Quand utiliser », scripts, contraintes, footer | 6 |
| Fichiers | SKILL.md présent, scripts/ séparés, pas d'inline > 10 lignes, cross-références | 3 |
Passe 2 — Cohérence documentation/code (7 points)
| Critère | Points | Description |
|---|---|---|
| Commandes documentées vs implémentées | 2 | Pas de documentation fantôme |
| Flags documentés vs implémentés | 2 | Cohérence des options |
| Exit codes documentés | 1 | Codes de retour explicites |
| Exemples fonctionnels | 1 | Les exemples sont exécutables |
| Skills référencés existants | 1 | Pas de références cassées |
Passe 3 — Qualité technique des scripts (10 points)
| Critère | Points | Description |
|---|---|---|
| Shebang présent | 1 | #!/usr/bin/env bash |
| set -euo pipefail | 2 | Gestion stricte des erreurs |
| Main guard | 1 | Protection d'exécution |
| Trap cleanup | 2 | Nettoyage en cas d'erreur |
| Variables quotées | 1 | Protection contre le word splitting |
| Header comments | 1 | Documentation inline |
| Fichiers temporaires gérés | 1 | Pas de résidus |
| Logging structuré | 1 | Traçabilité |
Passe 4 — Design (14 points)
Identique à la passe Design des agents : responsabilité unique, couplage, idempotence, robustesse, performance, duplication, évolution — deux points chacun.
L'échelle des verdicts
| Score | Verdict | Signification |
|---|---|---|
| 90 %+ | Excellent | Prêt pour la production |
| 80-89 % | Bon | Améliorations mineures nécessaires |
| 70-79 % | Acceptable | Fonctionne mais fragile |
| 60-69 % | Insuffisant | Risques en production |
| < 60 % | Mauvais | À refaire |
Les 10 erreurs les plus fréquentes (et comment les corriger)
Ces dix erreurs couvrent environ 80 % des points perdus dans les audits que nous avons réalisés. Chacune est illustrée par un exemple avant/après.
1. Description vague ou absente
Le problème : l'agent n'est activé que dans 50 % des cas. Claude utilise la description comme seul signal pour décider quand déléguer — une description générique comme « A useful helper » ne fournit aucun critère discriminant.
# ❌ Avant description: "Helps with code analysis" # ✅ Après description: "Use this agent when the user asks to review Python code for security vulnerabilities, performance bottlenecks, or PEP 8 compliance. Triggers on: 'review my code', 'check for vulnerabilities', 'analyze this Python file'."
2. Moins de deux exemples de déclenchement
Le problème : Claude ne sait pas quand déléguer à l'agent. Sans exemples concrets, le modèle doit deviner quels prompts utilisateur correspondent à l'agent.
# ❌ Avant # (aucun exemple) # ✅ Après # Examples: # - "Review the authentication module for security issues" # - "Check this API endpoint for performance problems" # - "Analyze the database queries in models.py"
3. Prompt système en première personne
Le problème : confusion de rôle, comportement incohérent. Un prompt en « je » brouille la frontière entre les instructions de l'auteur et le comportement attendu de l'agent.
# ❌ Avant I am a code reviewer. I analyze code and find bugs. I will provide feedback in a structured format. # ✅ Après You are a code reviewer specialized in Python security analysis. ## Responsibilities - Analyze Python code for security vulnerabilities - Identify SQL injection, XSS, and authentication flaws - Provide remediation recommendations with code examples
4. Pas de section Output Format
Le problème : sorties inconsistantes, post-traitement impossible. Sans format défini, l'agent produit des résultats dont la structure varie à chaque exécution.
# ❌ Avant # (le prompt ne mentionne aucun format de sortie) # ✅ Après ## Output Format Produce a Markdown report with: 1. **Summary**: severity counts (critical/high/medium/low) 2. **Findings**: one H3 per issue with: - File and line number - Description of the vulnerability - Remediation code snippet 3. **Score**: overall security score out of 100
5. Pas de gestion des cas limites
Le problème : comportement imprévisible sur les entrées inattendues. L'agent ne sait pas quoi faire quand le fichier n'existe pas, quand le code n'est pas en Python, ou quand le projet est vide.
# ❌ Avant # (aucune section Edge Cases) # ✅ Après ## Edge Cases - **Empty file**: Return "No code to analyze" with score 100 - **Non-Python file**: Decline politely, suggest the appropriate agent - **File > 5000 lines**: Analyze the first 2000 lines, warn the user - **Binary file**: Skip with explanation
6. Outils trop permissifs (pas de moindre privilège)
Le problème : gaspillage de tokens, agents lents, risques de sécurité. Un agent qui a accès à tous les outils explore des pistes inutiles et consomme du contexte pour rien.
# ❌ Avant # (aucune restriction — l'agent a accès à tout) # ✅ Après tools: - Read - Grep - Glob - Write # Only for writing the report
7. Absence de context:fork
Le problème : pollution de la conversation principale avec 3 000+ tokens de sortie brute. L'intégralité de la production de l'agent — y compris les étapes intermédiaires — s'injecte dans le contexte du parent.
# ❌ Avant # (pas de context: fork) # ✅ Après context: fork # L'agent travaille en isolation
Comme le documente cet article sur DEV.to, l'absence de context: fork est l'une des erreurs les plus coûteuses en termes de tokens.
8. Scripts sans gestion d'erreurs
Le problème : échecs silencieux, résultats partiels non détectés. Un script qui échoue sans le signaler produit des données incomplètes que l'agent traite comme complètes.
# ❌ Avant
#!/bin/bash
result=$(curl $API_URL)
echo $result | jq .data
# ✅ Après
#!/usr/bin/env bash
set -euo pipefail
trap 'echo "ERROR: Script failed at line $LINENO" >&2; exit 1' ERR
readonly API_URL="${1:?Usage: fetch-data.sh <api_url>}"
result=$(curl --fail --silent --show-error "$API_URL")
echo "$result" | jq '.data'
9. Design monolithique (agent « couteau suisse »)
Le problème : difficile à maintenir, à tester, à déclencher précisément. Un agent qui fait « tout » ne fait rien correctement — et Claude ne sait pas quand l'activer plutôt qu'un autre.
Contrairement à une idée reçue, un agent polyvalent n'est pas plus efficace qu'un ensemble d'agents spécialisés. La documentation Anthropic est explicite : « Design focused subagents: each subagent should excel at one specific task. »
La correction : décomposer en sous-agents spécialisés. Un code-reviewer pour l'analyse statique, un security-auditor pour les vulnérabilités, un performance-analyzer pour les bottlenecks.
10. Pas de contraintes de consommation
Le problème : épuisement du contexte en 15-20 minutes, coûts incontrôlés. Sans budget défini, l'agent peut tourner indéfiniment, consommer la totalité du contexte disponible et forcer un redémarrage.
# ❌ Avant # (aucune mention de consommation) # ✅ Après ## Consumption constraints - **Max tools**: 15 tool calls per execution - **Max tokens output**: ~3000 tokens - **Expected duration**: 2-5 minutes - **Context budget**: < 20% of available context window
Ces dix erreurs couvrent environ 80 % des points perdus dans les audits que nous avons réalisés. Les corriger en priorité produit le meilleur retour sur investissement en termes de qualité.
De 38 % à 100 % : retour d'expérience sur un audit systématique
Le contexte
Nous exploitons un système de 12 agents en production dans un workflow de création de contenu technique : orchestrateur, chercheurs (sources et SEO), planificateur, rédacteur, reviewer, générateur LinkedIn, moniteurs système et usage. Ces agents ont été développés itérativement, fonctionnalité par fonctionnalité, sans grille de qualité formelle au départ.
Les scores initiaux
En appliquant la grille à 42 points sur l'ensemble des agents, les résultats étaient sans appel :
| Métrique | Valeur |
|---|---|
| Score le plus bas | 38 % |
| Score le plus haut | 59 % |
| Moyenne | ~48 % |
| Agents au-dessus de « Acceptable » (70 %) | 0 sur 12 |
Les données montrent que tous les agents se situaient dans les catégories « Mauvais » ou « Insuffisant ». Les problèmes récurrents : frontmatter incomplet, descriptions vagues sans mots-clés d'activation, prompts en première personne, aucune section Output Format ni Edge Cases. Certains agents cumulaient six à huit des dix erreurs listées précédemment.
Le processus de correction
La correction a suivi une stratégie priorisée :
- Frontmatter d'abord — impact immédiat sur le déclenchement. Ajouter des descriptions commençant par « Use this agent when », des exemples de déclenchement, des outils restreints
- Prompt système ensuite — passer en deuxième personne, ajouter les sections Responsibilities, Process/Steps, Output Format, Edge Cases
- Design en dernier — décomposer les agents monolithiques, réduire le couplage, ajouter des contraintes de consommation
Chaque agent a nécessité en moyenne deux à trois passes de correction. Le processus complet — audit, corrections, re-audit — a pris environ deux jours pour les 12 agents.
Les résultats après audit
| Métrique | Avant | Après | Delta |
|---|---|---|---|
| Score le plus bas | 38 % | 88 % | +50 pts |
| Score le plus haut | 59 % | 100 % | +41 pts |
| Moyenne | ~48 % | ~95 % | +47 pts |
| Agents au-dessus de « Bon » (80 %) | 0/12 | 12/12 | +12 |
Les impacts observés au-delà du score :
- Déclenchement fiable : les agents s'activent de manière prévisible sur les bons prompts
- Sorties consistantes : le format de sortie est respecté à chaque exécution
- Consommation maîtrisée : les budgets de tokens sont respectés, plus de dépassement de contexte
- Maintenance facilitée : chaque agent a une responsabilité claire et documentée
Dans notre expérience, le gain le plus immédiat est venu du frontmatter : corriger la description et ajouter des exemples de déclenchement a transformé la fiabilité d'activation du jour au lendemain.
Checklist de qualité production en 15 points
Voici une version condensée des grilles complètes, applicable immédiatement à tout agent ou skill Claude Code. Quinze critères fondamentaux, organisés en trois catégories.
Identité (5 points)
- [ ] Frontmatter complet (name, description obligatoires)
- [ ] Description commençant par « Use this agent when » avec mots-clés spécifiques d'activation
- [ ] Au moins deux exemples de déclenchement (prompts utilisateur concrets)
- [ ] Nommage clair et non ambigu (pas de helper, utils, tools)
- [ ] Commentary ou documentation d'usage défini
Prompt et contenu (5 points)
- [ ] Rôle défini en deuxième personne (« You are a... specialized in... »)
- [ ] Sections Responsibilities et Process/Steps présentes et détaillées
- [ ] Section Output Format définie (structure, longueur, format attendu)
- [ ] Edge Cases documentés (comportement sur les cas limites)
- [ ] Longueur du prompt entre 500 et 10 000 caractères
Architecture (5 points)
- [ ] Responsabilité unique (un agent = une tâche, pas de « couteau suisse »)
- [ ] Outils restreints via allowlist (moindre privilège)
- [ ] context: fork si production de contenu volumineuse
- [ ] Scripts avec gestion d'erreurs (set -euo pipefail, trap, exit codes)
- [ ] Contraintes de consommation documentées (tokens, outils, durée)
Cette checklist couvre les fondamentaux. Pour un audit complet, les grilles à 42 et 49 points offrent une granularité supérieure et une couverture exhaustive.
Conclusion
L'écosystème des agents Claude Code souffre d'un déficit structurel de qualité. La croissance explosive — 200+ skills, 100+ agents, dizaines de repos communautaires — n'a pas été accompagnée par des standards d'évaluation. Les bonnes pratiques existent, documentées avec précision par Anthropic, mais elles restent sous-appliquées dans la grande majorité des ressources partagées.
Des grilles d'audit déterministes permettent de mesurer objectivement cette qualité et de guider les corrections. Les résultats sont tangibles : un audit systématique a fait passer nos 12 agents de 38-59 % à 88-100 %, avec des améliorations concrètes en fiabilité de déclenchement, consistance des sorties et maîtrise de la consommation.
Le rapport Anthropic 2026 sur les tendances de l'agentic coding confirme que le développement logiciel transite vers l'orchestration d'agents. Dans ce contexte, la qualité des agents et skills n'est pas un détail technique : c'est un avantage concurrentiel. Les organisations qui investissent dans des standards de qualité rigoureux aujourd'hui seront celles qui tireront le meilleur parti de leurs systèmes multi-agents demain.
Commencez par auditer vos agents existants avec la checklist en 15 points. Identifiez les trois erreurs les plus critiques et corrigez-les en priorité. La qualité se construit un point à la fois.
Qui suis-je ?
Je suis Mathieu GRENIER, CTO d'Easystrat une startup de Montpellier, en France. Je manage une équipe d'une dizaine d'ingénieurs (Graphistes, IA, frontend, backend, devOps, AWS) en remote depuis le Japon.
J'ai aussi mon activité de freelance, où je conseille des entrepreneurs dans leurs projets d'application.
Avec mon expérience personnelle de plus de 15 ans en ESN, j'ai pu travailler pour un large panel d'entreprises de différentes tailles. Ma compréhension des problèmes métiers est une de mes grandes forces et permet à mes clients de pouvoir se projeter plus facilement.
L'essentiel de mon travail consiste à canaliser l'énergie des entrepreneurs sur l'essence même de leur projet.
La technologie, les méthodes, le management sont le cœur de mes compétences.
Vous pouvez me faire confiance sur ces points-là.
Si vous voulez me parler d'un de vos projets, envoyez-moi un email avec vos disponibilités à : contact@mathieugrenier.fr
Tous les articles de ce blog sont écrits par moi, même si je peux m'aider de l'IA pour illustrer mes propos. Mais jamais je ne fournis d'articles 100% IA.
Les agents et skills disponibles en lignes sont de mauvaises qualités