Claude Code : la commande plugin eval pour tester vos plugins avant de les distribuer

Vous avez passé une semaine à assembler un plugin Claude Code : deux skills, une commande slash, un hook qui bloque les commits vides. Ça marche sur votre machine, sur votre repo, avec vos prompts. Vous êtes tenté de le partager à l'équipe. Mauvaise idée. Un plugin qui « marche » sur trois cas testés à la main casse en général dès qu'il tombe dans un contexte que vous n'aviez pas prévu. La commande claude plugin eval, livrée avec Claude Code 2.1.269 le 11 septembre 2026, existe précisément pour ça : faire tourner votre plugin sur une suite de cas définis et vous dire, chiffres à l'appui, si le comportement est stable.

Cet article suppose que vous savez déjà travailler avec Claude au quotidien et que Claude Code est installé. On va directement au concret : initialiser la suite, écrire un cas utile, lire une sortie, éviter les pièges classiques. Aucun mystère, aucune promesse magique.

À quoi sert vraiment plugin eval (et à quoi ça ne sert pas)

La commande fait tourner votre plugin sur des cas de test que vous définissez, puis vérifie que Claude a produit la sortie attendue. Chaque cas est rejoué 3 fois pour mesurer la reproductibilité, et une exécution de référence « sans plugin » (baseline) tourne en parallèle pour vérifier que votre plugin change réellement le comportement de Claude Code. C'est un point important : si votre skill produit le même résultat qu'un Claude Code vanilla, l'eval vous le dira, et vous saurez que votre plugin ne sert à rien.

Le résultat sort en JSON exploitable et en rapport HTML partageable. Codes de sortie propres pour la CI, graders configurables par cas.

Ce que plugin eval ne fait pas : ce n'est pas un linter. Un manifest cassé, un chemin de skill mal orthographié, un hook mal déclaré, ça ne remonte pas comme une erreur d'eval, ça se manifeste par des cas qui échouent tous pour la mauvaise raison. Testez d'abord que votre plugin se charge (claude plugin list) avant de lancer une suite. Ce n'est pas non plus un test unitaire déterministe : vous testez le comportement d'un LLM, donc vos assertions doivent tolérer les variations légitimes.

Prérequis : un plugin fonctionnel et une clé API

Il vous faut quatre choses avant de taper la première commande. Un plugin déjà créé et chargeable, avec la structure plugins/mon-plugin/ classique (manifest, dossier skills/ ou commands/ selon le cas). Claude Code en version 2.1.269 ou plus récente, sinon la commande n'existe simplement pas. Une clé API Anthropic active dans votre environnement : les evals consomment des tokens réels, chaque cas rejoué 3 fois plus le baseline, ça monte vite si votre suite grossit. Et enfin, un plugin que vous avez déjà testé au moins une fois à la main dans une session interactive. Si vous ne savez pas ce que votre plugin est censé produire, vous ne saurez pas écrire les assertions.

Pour l'installation ou la mise à jour de l'outil, voyez la page dédiée à Claude Code. Si vous en êtes encore à monter votre premier plugin, le guide setup Claude couvre l'environnement en amont.

Initialiser la suite avec plugin eval init

Depuis la racine de votre plugin :

cd plugins/mon-plugin
claude plugin eval init

Claude lit votre plugin, propose des cas de test et des grilles de correction (graders), les exécute une première fois à titre pilote, puis écrit le tout dans un dossier evals/. Vous obtenez en général une structure de ce type :

plugins/mon-plugin/
├── plugin.json
├── skills/
└── evals/
    ├── config.yaml
    ├── cases/
    │   ├── 001-basic-usage.yaml
    │   └── 002-edge-case.yaml
    └── graders/
        └── file-exists.js

Le fichier config.yaml définit le modèle utilisé pour les evals (par défaut, celui de votre plan Claude Code), le nombre de répétitions par cas, et si le baseline « sans plugin » tourne. Chaque fichier dans cases/ est un cas de test autonome. Le dossier graders/ contient les fonctions de correction, souvent des petits scripts JS ou des règles déclaratives.

Les cas générés automatiquement sont un point de départ, pas une suite prête. Claude devine à partir du contenu de votre plugin, souvent trop optimiste. Relisez chaque cas, supprimez ceux qui ne testent rien, adaptez les autres à vos usages réels.

Écrire un cas de test utile

Un cas contient trois choses : un prompt d'entrée, un contexte (fichiers présents, état du repo, variables), et une ou plusieurs assertions vérifiables. Prenez un plugin qui génère des composants React à partir d'une description courte. Un cas utile ressemble à ça :

name: bouton-primaire-simple
prompt: |
  Crée un composant bouton primaire avec un label configurable
  et un handler onClick.
context:
  files: []
graders:
  - type: file-exists
    path: src/components/Button.tsx
  - type: regex-match
    path: src/components/Button.tsx
    pattern: "export (const|function) Button"
  - type: regex-match
    path: src/components/Button.tsx
    pattern: "onClick"

Trois assertions structurelles, pas de jugement subjectif. Vous ne testez pas « le composant est joli » ou « le code est propre », vous testez que le fichier existe, qu'il exporte bien un identifiant nommé Button, et qu'il gère le prop onClick. Ces trois choses sont vérifiables et suffisent à confirmer que votre skill a fait son travail principal.

Règle générale : préférez trois assertions étroites qui vérifient des faits concrets à une grande assertion floue qui essaie de tout capturer. Une assertion étroite qui échoue vous dit exactement quoi corriger. Une assertion floue qui échoue vous laisse deviner.

Lancer plugin eval et lire les résultats

La commande de base :

claude plugin eval

Elle fait tourner tous les cas, chacun 3 fois, plus le baseline sans plugin. Consultez claude plugin eval --help pour la liste à jour des options (filtrage sur un sous-ensemble de cas, niveau de détail des traces, parallélisation) : ne rejouer que les cas pertinents pendant que vous ajustez un cas précis évite de payer une suite complète pour vérifier une seule correction.

La sortie liste chaque cas avec passé/échoué, temps d'exécution et tokens consommés, puis un récapitulatif final. Le rapport HTML est écrit dans evals/reports/ et affiche les diffs par assertion, utile à partager avec quelqu'un qui n'a pas votre terminal sous les yeux.

Quand un cas échoue, lisez la trace avant de blâmer Claude. Trois questions dans l'ordre : l'assertion est-elle bien écrite (regex correcte, chemin de fichier exact) ? Le contexte du cas correspond-il à ce que le plugin attend (fichiers présents, état de repo) ? Le prompt est-il assez précis pour que Claude sache quoi faire ? Neuf fois sur dix, l'erreur est dans le cas de test, pas dans le plugin.

Les trois erreurs qui font échouer les evals au premier run

Assertions trop strictes. Vous testez pattern: "export const Button" et Claude a écrit export function Button. Techniquement, les deux sont corrects. Utilisez export (const|function) Button, ou mieux, vérifiez via une assertion structurelle (parsing AST si le grader le permet) plutôt qu'un match texte exact.

État de repo non réinitialisé. Cas 1 crée Button.tsx. Cas 2 crée Input.tsx mais son assertion vérifie aussi l'absence de Button.tsx. Si les cas partagent le même workspace, cas 2 échoue à cause de cas 1. Configurez un reset entre cas, ou utilisez un workspace éphémère par cas. La plupart des configs par défaut le font, vérifiez.

Prompts ambigus. « Améliore le code » ne donne rien de mesurable. « Refactor la fonction getUser de src/api.ts pour qu'elle retourne User | null au lieu de lever une exception » donne une cible claire, testable. La qualité d'un cas de test dépend d'abord de la précision du prompt d'entrée.

Intégrer les evals dans votre workflow de distribution

Trois moments naturels pour lancer plugin eval. Avant tout commit qui touche le manifest ou un skill, au moins avec --filter sur les cas liés au changement. Avant de tagger une release, la suite complète avec baseline. En CI si le plugin est public ou partagé au-delà de vous, avec un seuil minimal de cas passés que vous fixez vous-même selon la criticité du plugin (les codes de sortie de la commande sont justement prévus pour ça).

Versionnez le dossier evals/ avec le plugin. Quelqu'un qui installe votre plugin peut relancer claude plugin eval chez lui pour vérifier que le comportement est stable dans son contexte (modèle par défaut différent, environnement différent). C'est aussi la meilleure documentation vivante de ce que votre plugin est censé faire : quand un utilisateur ouvre evals/cases/, il voit les cas d'usage réels, pas une doc marketing.

Si votre plugin est distribué à une équipe entière, jetez aussi un œil aux serveurs MCP gérés pour comprendre comment un administrateur peut pousser un jeu de plugins et serveurs approuvés à toute l'organisation. La suite d'évaluations sert alors de contrat entre vous et les utilisateurs finaux.

Passer à la distribution

Une fois les evals verts, vous avez trois voies : partage direct par archive (les versions récentes de Claude Code acceptent les plugins servis en HTTPS avec épinglage SHA-256 pour la reproductibilité), publication sur un repo Git, ou intégration à un marketplace interne. Le point commun : dans les trois cas, les evals versionnées avec le plugin donnent à l'utilisateur final un moyen objectif de vérifier ce qu'il installe.

Si vous êtes en train de construire un produit complet autour de Claude, pas juste un plugin isolé, le programme Construire votre produit IA en 5 semaines couvre la chaîne complète (Next.js, Supabase, déploiement Vercel) avec des sessions live et un livrable en production. Un plugin bien testé est une brique dans ce genre de chantier, rarement la fin de l'histoire. Pour la vue d'ensemble sur ce qu'on peut fabriquer avec Claude Code, voyez la page pilier application.