Évaluer un skill

Un skill est une affirmation : « un agent qui charge ce fichier produit un meilleur résultat qu’un agent qui ne le charge pas. » Tant que personne ne l’a mesurée, cette affirmation reste une intuition.

Ce guide décrit la tâche : transformer cette intuition en preuve publiée sur le tableau de bord.

Pourquoi évaluer : la stratégie en trois couches

SKRAFT prouve la qualité par trois couches, chacune répondant à une question différente.

Couche 1 : correction du framework (tests déterministes)

Quoi ? Le framework charge-t-il, route-t-il et dirige-t-il correctement les skills ?

Pourquoi ça compte : si le framework a un bug logique, chaque skill construit dessus amplifie ce bug. Ces tests attrapent les problèmes structurels avant qu’ils ne remontent à l’évaluation.

Couche 2 : comportement du skill (comparaison modèle)

Quoi ? Ce skill produit-il de meilleurs résultats que la baseline ?

Pourquoi ça compte : un skill qui semble bon produit souvent un pire résultat en pratique, ou coûte des tokens sans rien apporter. La mesure empirique le détecte ; l’intuition non.

Couche 3 : orchestration d’agents (tests d’intégration)

Quoi ? Les skills, le framework et l’agent travaillent-ils ensemble end-to-end ?

État : En place. Une suite agent est mono-bras — elle atteste une conformité (le bon agent, les skills requis chargés, la forme de handoff déclarée) plutôt qu’un gain — et son verdict est publié sur le tableau de bord et dans le commentaire de PR, à côté des skills. Elle reste indicative : une seule session d’agent réel ne doit pas bloquer un merge sans rapport.

Pourquoi c’est mieux

Les approches classiques (review de code + tests manuels) ont des angles morts :

Angle mort classique Approche SKRAFT
« Le code a l’air correct » mais produit un mauvais résultat Couche 2 force la mesure empirique : si ça ne score pas mieux, ça ne ship pas
Les mutations du code cachent des bugs subtils Couche 1 utilise Stryker : un mutant qui passe tous les tests = case oubliée
Les skills fonctionnent isolés mais cassent ensemble Couche 3 teste l’orchestration agent réelle
« Ça a marché la dernière fois que j’ai essayé » Chaque évaluation est reproductible ; les trajectoires agents sont enregistrées et rejouables
P-hacking (cherry-picking les bons résultats) Couche 2 utilise un test bilatéral pré-enregistré ; les régressions bloquent le merge automatiquement

État actuel (et ce qui arrive)

✅ Fonctionne maintenant :

🔄 En cours :

Le travail est incomplet, mais il démontre une base testable, mesurable, empirique au lieu des releases basées sur l’opinion. Chaque gap que vous voyez aujourd’hui est quelque chose qu’on peut mesurer et combler demain.

Le principe en une phrase

Les mêmes prompts sont soumis deux fois — une fois sans aucun skill (baseline), une fois avec le seul skill testé (skilled) — puis un juge compare les deux trajectoires. Rien d’autre ne change entre les deux passes : la différence observée est donc attribuable au skill, et à rien d’autre.

Étape 1 — Créer la spec d’évaluation

Créez tests/skills/<skill>/eval.yaml, où <skill> est exactement le nom du dossier sous plugins/skraft-framework/skills/. C’est ce chemin qui permet à l’expérience de retrouver le skill à charger : si les deux noms divergent, la baseline et la passe skilled deviennent identiques et l’évaluation ne mesure plus rien.

name: outside-in-tdd
description: Vérifie que la fonctionnalité est pilotée depuis un comportement métier observable.
type: capability
defaults:
  timeout: 3m
  runs: 3
stimuli:
  - name: Piloter une règle métier depuis l'extérieur
    prompt: |
      Notre application de commande en ligne doit appliquer une réduction
      fidélité sur le total à payer. Une commande inconnue doit produire une
      erreur « introuvable ». Implémente-la.
    graders:
      - type: prompt
    rubric:
      - Part d'un test qui traverse la frontière visible du service, formulé en termes métier.
      - Laisse le découpage interne émerger des tests au lieu de le figer d'avance.
      - Relie chaque changement de production à un test qui échouait avant et passe après.

Étape 2 — Respecter les quatre règles qui rendent la mesure honnête

Une spec mal écrite produit un chiffre rassurant qui ne mesure rien. Ces quatre règles sont ce qui sépare une preuve d’un placebo.

  1. Ne jamais nommer le skill dans un prompt, et ne jamais recopier sa formulation. Un prompt qui dit à l’agent quelle technique employer supprime précisément ce que l’évaluation cherche à observer.
  2. Juger le résultat, pas la technique. « Identifie la dépendance manquante comme cause de l’échec » est un résultat. « Lance la commande de diagnostic avec l’option détaillée » est un détail d’implémentation qu’une autre approche, tout aussi valable, échouerait à satisfaire.
  3. Inclure un cas de non-activation. Ajoutez un stimulus qui ressemble au territoire du skill mais tombe en dehors, et marquez-le tags: { intent: non-activation }. La retenue fait partie du comportement attendu : un skill qui se déclenche partout coûte du contexte sans rien apporter.
  4. Budgéter pour la puissance, pas pour le plancher. Cinq essais (stimuli × runs) est le minimum absolu, mais ce n’est pas la contrainte qui mord. Le test des signes tourne sur les paires décisives — les égalités sont jetées — et en dessous de six paires décisives, aucun décompte ne peut atteindre p ≤ 0,05 : un sans-faute 5V/0D score 0,0625, et 7V/1D score 0,070. Les égalités mangeant des paires, prévoyez 12 à 15 essais pour un verdict défendable. Achetez cette puissance d’entrée : rajouter des essais sur une comparaison bruitée est la pire dépense du protocole.

Étape 3 — Valider sans dépenser de quota

Installez le CLI une fois, comme le prescrit Vally :

npm install -g @microsoft/vally-cli@0.12.0
vally --version

La spec est la seule chose qu’une coquille peut casser en silence. Cet appel ne démarre aucun agent :

vally lint --eval-spec tests/skills/<skill>/eval.yaml --strict

Pas besoin de vérifier que les deux côtés de la comparaison sont restés comparables : le runner passe la même spec aux deux, et la seule différence est --skill-dir — vide pour la baseline, le skill évalué pour l’autre. Il ne reste aucune configuration qui puisse dériver.

Ce qui peut encore être faux, c’est le nom du dossier. Si tests/skills/<skill>/ ne correspond à aucun dossier sous plugins/skraft-framework/skills/, le runner signale l’évaluation comme ignorée plutôt que d’évaluer le vide en silence.

Étape 4 — Lancer l’évaluation

L’exécution pilote un vrai agent. Elle exige COPILOT_GITHUB_TOKEN : un PAT fine-grained portant la permission Account › Copilot Requests. Le jeton généré automatiquement par les Actions n’atteint pas Copilot. Le runner réexporte aussi cette valeur sous GITHUB_TOKEN, la variable que Vally 0.12.0 lit pour son juge de comparaison.

./eng/run-vally-evals.sh <skill>   # un seul skill
./eng/run-vally-evals.sh           # tous les skills évalués

En intégration continue, le workflow skill-evaluation fait la même chose de façon planifiée, puis publie les verdicts.

Étape 5 — Lire le verdict

Le juge remonte un décompte de victoires, égalités et défaites. Ce décompte devient un verdict via un test des signes binomial exact bilatéral : une majorité de victoires ne suffit pas, encore faut-il qu’elle soit improbable sous l’hypothèse du hasard.

📐 Vous ne comprenez pas d’où sort le p ? Le deep-dive Lire un verdict d’évaluation déplie la ligne 9V/4E/2D (p=0,065) chiffre par chiffre sur un cas réel : pourquoi les égalités sont jetées, pourquoi le plancher est à six paires, et pourquoi une skill qui gagne largement peut quand même échouer au test des signes.

Verdict Ce qu’il signifie
pass comparaison complète, suffisamment d’essais, avantage significatif
regression même exigence, mais l’avantage est du côté de la baseline — le skill dégrade la réponse
no-improvement comparaison saine, mais l’écart ne se distingue pas du hasard
inconclusive un essai en erreur, un essai non apparié, moins de 5 essais, ou moins de 6 paires décisives — la condition qui mord le plus souvent

Un résultat absent ou fragile n’est jamais affiché comme un succès. Une absence de donnée n’est pas un succès.

Étape 6 — Consulter la preuve

Le tableau de bord affiche le catalogue complet — chaque skill, son coût en contexte, sa couverture d’évaluation — et, pour ceux qui ont été évalués, le verdict et sa tendance sur les derniers passages.

Nul besoin de publier un passage pour le voir. Une seule commande replie les verdicts locaux dans un historique local, rescanne le catalogue et sert la même page :

npm run dashboard:preview   # → http://127.0.0.1:4173/dashboard/

Chaque essai enregistre aussi la trajectoire complète de l’agent. Quand des sessions ont été publiées, le tableau de bord ouvre une vue de rejeu : la passe baseline et la passe skilled du même scénario s’y rejouent côte à côte. C’est là que le verdict cesse d’être un chiffre et devient une explication — on voit où l’agent a bifurqué.

Couverture des agents

Les agents personnalisés sont couverts, mais pas de la même façon que les skills. Une comparaison de skill est bi-bras : baseline contre traitement. Une suite agent est mono-bras — il n’y a pas d’agent baseline à opposer à l’agent dispatché, donc rien à tester au sens statistique.

tests/agents/<suite>/eval.yaml dispatche un vrai agent SKRAFT via eng/vally-agent-executor/ et atteste une conformité avec des graders déterministes : le bon agent a été sélectionné, ses skills requis ont été chargés, le handoff a la forme déclarée. Pas de baseline, donc pas de test des signes : eng/lib/agent-verdict.mjs classe le run en tally de conformité.

Verdict Ce qu’il signifie
pass tous les essais ont tourné et scoré au niveau ou au-dessus du scoring.threshold de la suite
regression tous les essais ont tourné, et au moins un a scoré sous le seuil
inconclusive un essai est parti en erreur, donc il ne prouve rien sur l’agent

Ces verdicts sont publiés sur le tableau de bord et dans le commentaire de PR à côté des skills, mais ils restent indicatifs : une suite joue une seule session d’agent réel, et un run instable ne doit pas bloquer une fusion sans rapport.

Une suite a besoin de @github/copilot-sdk, une devDependency — tout job qui en joue une doit passer par npm install d’abord.

Ce qu’une évaluation ne couvre pas

Une évaluation mesure un seul skill à la fois. Elle ne dit rien de la composition — ce qui se passe quand plusieurs skills se chargent ensemble dans une même passe reste hors de portée de cette mesure.

Aller plus loin