Tester systématiquement les skills d’agents à l’aide d’évaluations

Lorsque vous faites évoluer un skill pour un agent comme Codex, il est difficile de savoir si vous l’améliorez réellement ou si vous modifiez simplement son comportement. Une version paraît plus rapide, une autre semble plus fiable, puis une régression apparaît : le skill ne se déclenche pas, saute une étape obligatoire ou laisse des fichiers superflus.

Un skill est avant tout un ensemble organisé de prompts et d’instructions destiné à un LLM. La manière la plus fiable de l’améliorer au fil du temps consiste à l’évaluer comme n’importe quel autre prompt destiné à une application utilisant un LLM.

Les évaluations (« evals », abréviation de l’anglais evaluations) vérifient que la sortie d’un modèle et les étapes suivies pour la produire correspondent à vos attentes. Au lieu de vous demander « est-ce que ça semble mieux ? » ou de vous fier à vos impressions, elles vous permettent de poser des questions concrètes comme :

• L’agent a-t-il appelé le skill ?
• A-t-il exécuté les commandes attendues ?
• A-t-il produit des résultats qui respectent les conventions qui vous importent ?

Concrètement, une évaluation suit ce déroulement : un prompt → une exécution enregistrée (trace + artefacts) → un petit ensemble de vérifications → un score que vous pouvez comparer au fil du temps.

En pratique, les évaluations de skills d’agents ressemblent beaucoup à des tests de bout en bout légers : vous exécutez l’agent, enregistrez ce qui s’est passé et attribuez un score au résultat selon un petit ensemble de règles.

Cet article présente une méthode claire pour procéder avec Codex : définir d’abord les critères de réussite, puis ajouter des vérifications déterministes et une notation fondée sur une grille de critères afin de faire ressortir les améliorations comme les régressions.

1. Définissez les critères de réussite avant d’écrire le skill

Avant d’écrire le skill lui-même, définissez par écrit ce qui constitue une réussite en termes réellement mesurables. Pour structurer cette réflexion, vous pouvez répartir vos vérifications en quelques catégories :

• Objectifs de résultat : La tâche a-t-elle été menée à bien ? L’application fonctionne-t-elle ?
• Objectifs de processus : Codex a-t-il appelé le skill, utilisé les outils prévus et suivi les étapes attendues ?
• Objectifs de style : Le résultat respecte-t-il les conventions demandées ?
• Objectifs d’efficacité : L’agent est-il parvenu au résultat sans multiplier les actions improductives, par exemple des commandes inutiles ou une consommation excessive de tokens ?

Gardez cette liste courte et concentrez-vous sur les vérifications qui doivent impérativement réussir. L’objectif n’est pas de formaliser toutes vos préférences dès le départ, mais de cerner les comportements qui comptent le plus pour vous.

Cet article évalue par exemple un skill qui met en place une application de démonstration. Certaines vérifications sont concrètes : a-t-il exécuté npm install ? A-t-il créé package.json ? Le guide les associe à une grille de critères de style structurée pour évaluer les conventions et la mise en page.

Cette combinaison est délibérée. L’objectif est d’obtenir rapidement des signaux ciblés qui révèlent des régressions précises, plutôt qu’un simple verdict de réussite ou d’échec à la fin.

2. Créez le skill

Un skill Codex est un répertoire contenant un fichier SKILL.md avec un en-tête YAML (name, description), suivi d’instructions Markdown qui définissent le comportement du skill, ainsi que des ressources et scripts facultatifs. Le nom et la description ont plus d’importance qu’il n’y paraît. Ce sont les principaux éléments sur lesquels Codex s’appuie pour décider s’il doit appeler le skill et quand injecter le reste de SKILL.md dans le contexte de l’agent. S’ils sont vagues ou surchargés, le déclenchement du skill ne sera pas fiable.

Le moyen le plus rapide de démarrer est d’utiliser le créateur de skills intégré à Codex (qui est lui-même un skill). Il vous guide tout au long de la création :

$skill-creator

Le créateur vous demande ce que fait le skill, quand il doit se déclencher et s’il repose uniquement sur des instructions ou s’il s’appuie sur des scripts. Par défaut, il recommande de se limiter aux instructions. Pour en savoir plus sur la création d’un skill, consultez la documentation.

Un exemple de skill

Cet article utilise un exemple volontairement minimal : un skill qui met en place une petite application de démonstration React de manière prévisible et reproductible.

Ce skill permettra de :

• Générer la structure initiale d’un projet à partir du modèle React + TypeScript de Vite
• Configurer Tailwind CSS avec la méthode officielle utilisant le plugin Vite
• Imposer une structure de fichiers minimale et cohérente
• Définir clairement les critères d’achèvement pour faciliter l’évaluation de la réussite

Voici une ébauche concise que vous pouvez coller dans l’un des fichiers suivants :

• .codex/skills/setup-demo-app/SKILL.md (au niveau du dépôt), ou
• ~/.codex/skills/setup-demo-app/SKILL.md (au niveau de l’utilisateur).

---
name: setup-demo-app
description: Scaffold a Vite + React + Tailwind demo app with a small, consistent project structure.
---

## When to use this

Use when you need a fresh demo app for quick UI experiments or reproductions.

## What to build

Create a Vite React TypeScript app and configure Tailwind. Keep it minimal.

Project structure after setup:

- src/
  - main.tsx (entry)
  - App.tsx (root UI)
  - components/
    - Header.tsx
    - Card.tsx
  - index.css (Tailwind import)
- index.html
- package.json

Style requirements:

- TypeScript components
- Functional components only
- Tailwind classes for styling (no CSS modules)
- No extra UI libraries

## Steps

1. Scaffold with Vite using the React TS template:
   npm create vite@latest demo-app -- --template react-ts

2. Install dependencies:
   cd demo-app
   npm install

3. Install and configure Tailwind using the Vite plugin.
   - npm install tailwindcss @tailwindcss/vite
   - Add the tailwind plugin to vite.config.ts
   - In src/index.css, replace contents with:
     @import "tailwindcss";

4. Implement the minimal UI:
   - Header: app title and short subtitle
   - Card: reusable card container
   - App: render Header + 2 Cards with placeholder text

## Definition of done

- npm run dev starts successfully
- package.json exists
- src/components/Header.tsx and src/components/Card.tsx exist

Cet exemple de skill impose volontairement des choix précis. Sans contraintes claires, il n’y a rien de concret à évaluer.

3. Déclenchez manuellement le skill pour révéler ses hypothèses implicites

L’appel d’un skill dépend fortement du nom et de la description figurant dans SKILL.md. La première chose à vérifier est donc que le skill setup-demo-app se déclenche bien quand vous vous y attendez.

Dès le début, activez explicitement le skill dans un véritable dépôt ou un répertoire d’essai, soit avec la commande slash /skills, soit en le mentionnant avec le préfixe $, puis observez où il échoue. Vous pourrez ainsi repérer les cas problématiques : le skill ne se déclenche pas du tout, se déclenche trop facilement ou s’exécute en s’écartant des étapes prévues.

À ce stade, vous ne cherchez pas à optimiser la vitesse ni à peaufiner le résultat. Vous cherchez à repérer les hypothèses implicites du skill, par exemple :

• Hypothèses de déclenchement : des prompts comme « Mettez rapidement en place une démo React » qui devraient appeler setup-demo-app mais ne le font pas, ou des prompts plus généraux (« Ajoutez des styles Tailwind ») qui le déclenchent involontairement.

• Hypothèses sur l’environnement : le skill suppose qu’il s’exécute dans un répertoire vide, ou que npm est disponible et préféré aux autres gestionnaires de paquets.

• Hypothèses d’exécution : l’agent omet npm install parce qu’il suppose que les dépendances sont déjà installées, ou configure Tailwind avant que le projet Vite existe.

Lorsque vous êtes prêt à rendre ces exécutions reproductibles, passez à codex exec. Conçu pour l’automatisation et l’intégration continue, il transmet la progression en continu à stderr et n’écrit que le résultat final dans stdout. Les exécutions sont ainsi plus faciles à piloter par script, à enregistrer et à examiner.

Par défaut, codex exec s’exécute dans un bac à sable restreint. Si votre tâche doit écrire des fichiers, exécutez-le avec --full-auto. En règle générale, surtout dans un contexte d’automatisation, utilisez le minimum d’autorisations nécessaires pour accomplir la tâche.

Une exécution manuelle simple pourrait ressembler à ceci :

codex exec --full-auto \
  'Use the $setup-demo-app skill to create the project in this directory.'

Ce premier essai pratique vise surtout à découvrir les cas limites, plutôt qu’à valider le bon fonctionnement. Chaque correction manuelle, comme l’ajout d’un npm install manquant, la correction de la configuration Tailwind ou une description plus précise des conditions de déclenchement, peut devenir une future évaluation. Vous pourrez ainsi stabiliser le comportement attendu avant de passer à des évaluations à grande échelle.

4. Utilisez un petit ensemble de prompts ciblés pour détecter rapidement les régressions

Vous n’avez pas besoin d’un vaste banc d’essai pour tirer parti des évaluations. Pour un seul skill, un petit ensemble de 10 à 20 prompts suffit à révéler les régressions et à confirmer rapidement les améliorations.

Commencez par un petit fichier CSV et enrichissez-le au fil des échecs réels rencontrés pendant le développement ou l’utilisation. Chaque ligne doit représenter une situation dans laquelle il vous importe que le skill setup-demo-app s’active ou ne s’active pas , et préciser les critères de réussite lorsqu’il s’active.

Par exemple, une première version de evals/setup-demo-app.prompts.csv pourrait ressembler à ceci :

id,should_trigger,prompt
test-01,true,"Create a demo app named `devday-demo` using the $setup-demo-app skill"
test-02,true,"Set up a minimal React demo app with Tailwind for quick UI experiments"
test-03,true,"Create a small demo app to showcase the Responses API"
test-04,false,"Add Tailwind styling to my existing React app"

Chacun de ces cas teste un aspect légèrement différent :

• Appel explicite (test-01)
  Ce prompt nomme directement le skill. Il vérifie que Codex peut appeler setup-demo-app à la demande et que les modifications du nom, de la description ou des instructions du skill ne compromettent pas son utilisation directe.

• Appel implicite (test-02)
  Ce prompt décrit exactement le scénario visé par le skill, à savoir la mise en place d’une démo minimale React + Tailwind, sans nommer le skill. Il vérifie que le nom et la description dans SKILL.md sont suffisamment explicites pour que Codex sélectionne le skill de lui-même.

• Appel contextuel (test-03)
  Ce prompt ajoute un contexte lié au domaine (l’API Responses), tout en nécessitant la même configuration de base. Il vérifie que le skill se déclenche avec des prompts réalistes contenant quelques informations accessoires, et que l’application obtenue respecte toujours la structure et les conventions attendues.

• Témoin négatif (test-04)
  Ce prompt ne doit pas appeler setup-demo-app. Il s’agit d’une demande courante et proche du cas visé (« Ajoutez Tailwind à une application existante »), qui peut correspondre involontairement à la description du skill (« démo React + Tailwind »). Inclure au moins un cas should_trigger=false aide à repérer les faux positifs, lorsque Codex sélectionne le skill trop facilement et génère la structure d’un nouveau projet alors que l’utilisateur souhaitait une modification ponctuelle d’un projet existant.

Cette combinaison est délibérée. Certaines évaluations doivent confirmer que le skill se comporte correctement lorsqu’il est appelé explicitement ; d’autres doivent vérifier qu’il s’active avec des prompts réels dans lesquels l’utilisateur ne mentionne jamais le skill.

Lorsque vous repérez des ratés, des prompts qui ne déclenchent pas le skill ou des résultats qui s’écartent de vos attentes, ajoutez-les sous forme de nouvelles lignes. Au fil du temps, ce petit fichier CSV devient un recueil évolutif des scénarios que le skill setup-demo-app doit continuer à traiter correctement.

Au fil du temps, ce petit jeu de données devient un recueil évolutif de ce que le skill doit continuer à faire correctement.

5. Commencez par des évaluateurs déterministes légers

C’est le cœur de l’étape d’évaluation : utilisez codex exec --json pour que votre harnais d’évaluation puisse noter ce qui s’est réellement passé, et pas seulement juger si le résultat final semble correct.

Lorsque vous activez --json, stdout devient un flux JSONL d’événements structurés. Il est alors facile d’écrire des vérifications déterministes directement liées aux comportements qui vous importent, par exemple :

• A-t-il exécuté npm install ?
• A-t-il créé package.json ?
• A-t-il exécuté les commandes attendues, dans l’ordre prévu ?

Ces vérifications sont volontairement légères. Elles vous donnent rapidement des indications faciles à interpréter, avant même d’ajouter une notation par modèle.

Un script d’exécution Node.js minimal

Voici une approche simple qui suffit pour commencer :

1. Pour chaque prompt, exécutez codex exec --json --full-auto "<prompt>"
2. Enregistrez la trace JSONL sur disque
3. Analysez la trace et effectuez des vérifications déterministes sur les événements

// evals/run-setup-demo-app-evals.mjs
import { spawnSync } from "node:child_process";
import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
import path from "node:path";

function runCodex(prompt, outJsonlPath) {
  const res = spawnSync(
    "codex",
    [
      "exec",
      "--json", // REQUIRED: emit structured events
      "--full-auto", // Allow file system changes
      prompt,
    ],
    { encoding: "utf8" }
  );

  mkdirSync(path.dirname(outJsonlPath), { recursive: true });

  // stdout is JSONL when --json is enabled
  writeFileSync(outJsonlPath, res.stdout, "utf8");

  return { exitCode: res.status ?? 1, stderr: res.stderr };
}

function parseJsonl(jsonlText) {
  return jsonlText
    .split("\n")
    .filter(Boolean)
    .map((line) => JSON.parse(line));
}

// deterministic check: did the agent run `npm install`?
function checkRanNpmInstall(events) {
  return events.some(
    (e) =>
      (e.type === "item.started" || e.type === "item.completed") &&
      e.item?.type === "command_execution" &&
      typeof e.item?.command === "string" &&
      e.item.command.includes("npm install")
  );
}

// deterministic check: did `package.json` get created?
function checkPackageJsonExists(projectDir) {
  return existsSync(path.join(projectDir, "package.json"));
}

// Example single-case run
const projectDir = process.cwd();
const tracePath = path.join(projectDir, "evals", "artifacts", "test-01.jsonl");

const prompt =
  "Create a demo app named demo-app using the $setup-demo-app skill";

runCodex(prompt, tracePath);

const events = parseJsonl(readFileSync(tracePath, "utf8"));

console.log({
  ranNpmInstall: checkRanNpmInstall(events),
  hasPackageJson: checkPackageJsonExists(path.join(projectDir, "demo-app")),
});

L’intérêt ici est que tout est déterministe et débogable.

Si une vérification échoue, vous pouvez ouvrir le fichier JSONL et voir exactement ce qui s’est passé. Chaque exécution de commande apparaît sous la forme d’un événement item.*, dans l’ordre d’exécution. Les régressions sont ainsi faciles à expliquer et à corriger, ce qui est précisément l’objectif à ce stade.

6. Effectuez des vérifications qualitatives avec Codex et une grille de notation

Les vérifications déterministes répondent à la question « a-t-il fait le minimum attendu ? » , mais pas à la question « l’a-t-il fait comme vous le souhaitiez ? »

Pour les skills comme setup-demo-app, de nombreuses exigences sont qualitatives : structure des composants, conventions de style ou conformité de Tailwind à la configuration prévue. Il est difficile de vérifier ces aspects en se contentant de contrôler l’existence de fichiers ou de compter les commandes.

Une solution pragmatique consiste à ajouter une seconde étape, assistée par un modèle, à votre pipeline d’évaluation :

1. Exécutez le skill de configuration (cette étape écrit du code sur disque)
2. Effectuez une vérification du style en lecture seule sur le dépôt obtenu
3. Exigez une réponse structurée que votre harnais peut noter de manière cohérente

Codex le permet directement avec --output-schema, qui impose à la réponse finale de respecter un schéma au format JSON Schema que vous définissez.

Un schéma simple pour la grille de notation

Commencez par définir un petit schéma qui regroupe les vérifications importantes pour vous. Par exemple, créez evals/style-rubric.schema.json :

{
  "type": "object",
  "properties": {
    "overall_pass": { "type": "boolean" },
    "score": { "type": "integer", "minimum": 0, "maximum": 100 },
    "checks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "pass": { "type": "boolean" },
          "notes": { "type": "string" }
        },
        "required": ["id", "pass", "notes"],
        "additionalProperties": false
      }
    }
  },
  "required": ["overall_pass", "score", "checks"],
  "additionalProperties": false
}

Ce schéma vous fournit des champs stables (overall_pass, score, résultats par vérification) que vous pouvez combiner, comparer et suivre dans le temps.

Le prompt de vérification du style

Lancez ensuite une seconde exécution de codex exec qui se limite à inspecter le dépôt et produit une réponse JSON conforme à la grille de notation :

codex exec \
  "Evaluate the demo-app repository against these requirements:
   - Vite + React + TypeScript project exists
   - Tailwind is configured via @tailwindcss/vite and CSS imports tailwindcss
   - src/components contains Header.tsx and Card.tsx
   - Components are functional and styled with Tailwind utility classes (no CSS modules)
   Return a rubric result as JSON with check ids: vite, tailwind, structure, style." \
  --output-schema ./evals/style-rubric.schema.json \
  -o ./evals/artifacts/test-01.style.json

C’est là que --output-schema est utile. Au lieu d’un texte libre difficile à analyser ou à comparer, vous obtenez un objet JSON prévisible que votre harnais d’évaluation peut noter sur de nombreuses exécutions.

Si vous intégrez ensuite cette suite d’évaluations à la CI, la GitHub Action de Codex permet explicitement de transmettre --output-schema via codex-args. Vous pouvez ainsi imposer la même sortie structurée dans vos workflows automatisés.

7. Enrichissez vos évaluations à mesure que le skill gagne en maturité

Une fois la boucle de base en place, vous pouvez enrichir vos évaluations sur les aspects les plus importants pour votre skill. Commencez modestement, puis ajoutez des vérifications plus approfondies uniquement là où elles renforcent réellement votre confiance dans les résultats.

Voici quelques exemples :

• Nombre de commandes et actions répétitives inutiles : Comptez les éléments command_execution dans la trace JSONL pour détecter les régressions où l’agent commence à tourner en boucle ou à relancer des commandes. La consommation de tokens est également disponible dans les événements turn.completed.

• Budget de tokens : Suivez usage.input_tokens et usage.output_tokens pour repérer un allongement involontaire des prompts et comparer l’efficacité des différentes versions.

• Vérifications du build : Exécutez npm run build une fois le skill terminé. Vous obtenez ainsi un indicateur de bout en bout plus robuste et détectez les imports défectueux ou les outils mal configurés.

• Tests de bon fonctionnement à l’exécution : Lancez npm run dev et envoyez une requête au serveur de développement avec curl, ou exécutez un test Playwright léger si vous en avez déjà un. Utilisez cette méthode de façon ciblée. Elle renforce la confiance dans les résultats, mais prend du temps.

• Propreté du dépôt : Assurez-vous que l’exécution ne génère aucun fichier indésirable et que la sortie de git status --porcelain est vide (ou correspond à une liste explicite d’éléments autorisés).

• Régressions liées au bac à sable et aux autorisations : Vérifiez que le skill fonctionne toujours sans élargir les autorisations au-delà de ce que vous aviez prévu. Appliquer le principe du moindre privilège par défaut est particulièrement important dès que vous automatisez.

La démarche reste la même : commencez par des vérifications rapides qui expliquent le comportement, puis ajoutez des vérifications plus lentes et plus lourdes uniquement lorsqu’elles réduisent les risques.

8. Points clés à retenir

Ce petit exemple setup-demo-app montre comment passer de « ça semble mieux » à des preuves : exécutez l’agent, enregistrez ce qui s’est passé et notez le résultat à l’aide de quelques vérifications. Une fois cette boucle en place, chaque ajustement devient plus facile à valider et chaque régression plus facile à repérer. Voici les points clés à retenir :

• Mesurez ce qui compte. De bonnes évaluations rendent les régressions visibles et les échecs compréhensibles.
• Partez de critères vérifiables pour définir ce qui constitue un travail terminé. Utilisez $skill-creator pour démarrer, puis affinez les instructions jusqu’à ce que la réussite ne laisse aucune place à l’ambiguïté.
• Fondez les évaluations sur le comportement. Capturez une trace JSONL avec codex exec --json et écrivez des vérifications déterministes portant sur les événements command_execution.
• Utilisez Codex là où les règles ne suffisent pas. Ajoutez une étape structurée fondée sur une grille de notation avec --output-schema pour évaluer de manière fiable le style et le respect des conventions.
• Étendez la couverture à partir des échecs réels. Chaque correction manuelle est un signal. Faites-en un test pour que le skill continue à traiter correctement ce cas.