Quand vous retravaillez un skill pour un agent comme Codex, il est difficile de savoir si vous l’améliorez vraiment ou si vous changez simplement son comportement. Une version paraît plus rapide, une autre semble plus fiable, puis une régression passe inaperçue : le skill ne se déclenche pas, saute une étape obligatoire ou laisse des fichiers superflus dans le projet.
Un skill est avant tout un ensemble organisé de prompts et d’instructions destiné à un LLM. Le moyen le plus fiable de l’améliorer au fil du temps consiste à l’évaluer comme tout autre prompt destiné à une application fondée sur un LLM.
Les evals (abréviation d’évaluations) vérifient si le résultat produit par un modèle et les étapes suivies pour l’obtenir correspondent à vos attentes. Au lieu de vous demander « est-ce que ça a l’air mieux ? » ou de vous fier à votre intuition, vous pouvez poser des questions concrètes :
- L’agent a-t-il invoqué le skill ?
- A-t-il exécuté les commandes attendues ?
- Les résultats respectent-ils les conventions qui comptent pour vous ?
Concrètement, une évaluation se déroule ainsi : un prompt → une exécution enregistrée (trace + artefacts) → quelques vérifications → un score que vous pouvez comparer d’une version à l’autre.
En pratique, les évaluations de skills ressemblent à des tests de bout en bout légers : vous lancez l’agent, enregistrez ce qui se passe et notez le résultat selon quelques règles.
Cet article montre comment procéder avec Codex. Vous commencerez par définir vos critères de réussite, puis vous ajouterez des vérifications déterministes et une grille de notation pour repérer les améliorations comme les régressions.
1. Définissez les critères de réussite avant de rédiger le skill
Avant de rédiger le skill, précisez ce qui vous permettra de mesurer sa réussite. Pour cela, vous pouvez regrouper vos vérifications en quelques catégories :
- Résultat : la tâche a-t-elle abouti ? L’application fonctionne-t-elle ?
- Déroulement : Codex a-t-il invoqué le skill, utilisé les outils prévus et suivi les étapes attendues ?
- Style : le résultat respecte-t-il les conventions demandées ?
- Efficacité : l’agent a-t-il atteint son objectif sans multiplier les commandes inutiles ni consommer trop de tokens, par exemple ?
Limitez cette liste aux vérifications indispensables. À ce stade, il suffit de préciser les comportements auxquels vous tenez le plus, sans formaliser chacune de vos préférences.
Dans cet article, par exemple, nous évaluons un skill qui initialise une application de démonstration. Certaines vérifications portent sur des actions précises. L’agent a-t-il exécuté npm install ? A-t-il créé package.json ? Nous les complétons par une grille de style pour évaluer le respect des conventions et l’organisation du projet.
Cette combinaison est délibérée. Des vérifications rapides et ciblées permettent de repérer tôt une régression précise, sans attendre un verdict global de réussite ou d’échec à la fin.
2. Créez le skill
Un skill Codex se présente sous la forme d’un répertoire contenant un fichier SKILL.md. Ce fichier commence par un en-tête YAML (name, description), suivi des instructions Markdown qui définissent le comportement du skill. Le répertoire peut aussi contenir des ressources et des scripts. Le nom et la description jouent un rôle plus important qu’il n’y paraît. Codex s’appuie principalement sur eux pour décider s’il doit invoquer le skill et à quel moment ajouter le reste de SKILL.md au contexte de l’agent. Si le nom ou la description sont vagues ou couvrent trop de cas, le déclenchement du skill devient peu fiable.
Pour démarrer rapidement, utilisez le créateur de skills intégré à Codex (lui-même un skill). Lancez-le pour être guidé pas à pas :
$skill-creatorLe créateur vous demande ce que fait le skill, quand il doit se déclencher et s’il repose uniquement sur des instructions ou aussi sur des scripts. Par défaut, il recommande de s’en tenir aux instructions. Pour en savoir plus sur la création d’un skill, consultez la documentation.
Un exemple de skill
L’exemple de cet article est volontairement minimal : le skill initialise une petite application de démonstration React de manière prévisible et reproductible.
Ce skill :
- Génère un projet à partir du modèle React + TypeScript de Vite
- Configure Tailwind CSS avec le plugin officiel pour Vite
- Impose une arborescence minimale et cohérente
- Précise les critères à remplir pour considérer la tâche comme terminée et en vérifier facilement la réussite
Vous pouvez coller la première version ci-dessous dans l’un de ces fichiers :
.codex/skills/setup-demo-app/SKILL.md(pour ce dépôt), ou~/.codex/skills/setup-demo-app/SKILL.md(pour votre compte utilisateur).
---
name: setup-demo-app
description: Scaffold a Vite + React + Tailwind demo app with a small, consistent project structure.
---
## Quand utiliser ce skill
Utilisez ce skill lorsque vous avez besoin d’une nouvelle application de démonstration pour tester rapidement une idée d’interface ou reproduire un problème.
## Application à créer
Créez une application React en TypeScript avec Vite et configurez Tailwind. Limitez l’application au strict nécessaire.
Arborescence du projet après l’initialisation :
- src/
- main.tsx (point d’entrée)
- App.tsx (composant racine de l’interface)
- components/
- Header.tsx
- Card.tsx
- index.css (import de Tailwind)
- index.html
- package.json
Exigences de style :
- Écrivez les composants en TypeScript.
- Utilisez uniquement des composants fonctionnels.
- Appliquez les styles avec des classes Tailwind, sans modules CSS.
- N’ajoutez aucune bibliothèque d’interface supplémentaire.
## Étapes
1. Générez le projet avec Vite à partir du modèle React TypeScript :
npm create vite@latest demo-app -- --template react-ts
2. Installez les dépendances :
cd demo-app
npm install
3. Installez et configurez Tailwind avec le plugin pour Vite.
- npm install tailwindcss @tailwindcss/vite
- Ajoutez le plugin Tailwind à vite.config.ts.
- Remplacez le contenu de src/index.css par :
@import "tailwindcss";
4. Créez l’interface minimale :
- Header : affichez le titre de l’application et un court sous-titre.
- Card : créez un conteneur de carte réutilisable.
- App : affichez Header et 2 instances de Card, chacune avec du texte d’exemple.
## Critères de réussite
- La commande npm run dev démarre le serveur de développement sans erreur.
- Le fichier package.json existe.
- Les fichiers src/components/Header.tsx et src/components/Card.tsx existent.Ce skill impose délibérément certains choix. Sans contraintes précises, il n’y aurait rien de concret à évaluer.
3. Déclenchez le skill manuellement pour repérer ses hypothèses implicites
Comme le déclenchement d’un skill dépend largement du nom et de la description dans SKILL.md, vérifiez d’abord que le skill setup-demo-app se déclenche quand vous vous y attendez.
Pour vos premiers essais, activez explicitement le skill dans un dépôt réel ou un répertoire de test, avec la commande slash /skills ou en préfixant son nom par $. Observez où les choses se passent mal. Vous repérerez ainsi les cas où le skill ne se déclenche jamais, se déclenche trop facilement ou s’exécute en s’écartant des étapes prévues.
À ce stade, la priorité n’est ni la rapidité ni la finition. Cherchez plutôt les hypothèses implicites du skill, par exemple :
-
Sur le déclenchement : certains prompts, comme « préparez une démo React rapide », devraient invoquer
setup-demo-appmais ne le font pas. D’autres, plus génériques (« ajoutez des styles Tailwind »), le déclenchent par erreur. -
Sur l’environnement : le skill suppose qu’il s’exécute dans un répertoire vide, ou que
npmest disponible et qu’il faut le privilégier par rapport aux autres gestionnaires de paquets. -
Sur l’exécution : l’agent saute
npm installparce qu’il suppose que les dépendances sont déjà installées, ou configure Tailwind avant même que le projet Vite existe.
Lorsque vous voudrez reproduire ces exécutions, passez à codex exec. Conçue pour l’automatisation et l’intégration continue, cette commande envoie les informations de progression à stderr et écrit uniquement le résultat final sur stdout. Vous pouvez ainsi plus facilement lancer les exécutions depuis un script, les enregistrer et les examiner.
Par défaut, codex exec s’exécute dans un bac à sable aux permissions restreintes. Si votre tâche nécessite d’écrire des fichiers, utilisez --full-auto. En règle générale, surtout lorsque vous automatisez une tâche, accordez uniquement les permissions nécessaires à son exécution.
Voici un exemple d’exécution manuelle :
codex exec --full-auto \
'Utilisez le skill $setup-demo-app pour créer le projet dans ce répertoire.'Ce premier essai sert surtout à découvrir les cas limites. Chaque correction manuelle, qu’il s’agisse d’ajouter un npm install manquant, de rectifier la configuration de Tailwind ou de préciser les conditions de déclenchement dans la description, peut donner lieu à une évaluation. Vous pourrez ainsi fixer le comportement attendu avant de passer à des évaluations à grande échelle.
4. Utilisez quelques prompts ciblés pour détecter rapidement les régressions
Les évaluations sont utiles même sans vaste jeu de tests. Pour un seul skill, 10 à 20 prompts suffisent pour détecter rapidement des régressions et confirmer des améliorations.
Commencez par un petit fichier CSV, puis enrichissez-le à mesure que vous rencontrez des échecs en développement ou à l’usage. Chaque ligne doit décrire une situation pour laquelle vous voulez vérifier si le skill setup-demo-app doit se déclencher ou doit rester inactif, et préciser le résultat attendu en cas de déclenchement.
Voici à quoi pourrait ressembler une première version de evals/setup-demo-app.prompts.csv :
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"Chaque cas vérifie un aspect légèrement différent :
-
Invocation explicite (
test-01)
Ce prompt nomme directement le skill. Il vérifie que Codex peut invoquersetup-demo-appsur demande et qu’une modification du nom, de la description ou des instructions du skill ne compromet pas cet usage direct. -
Invocation implicite (
test-02)
Ce prompt décrit exactement le scénario visé, à savoir la création d’une démo minimale avec React + Tailwind, sans nommer le skill. Il vérifie si le nom et la description dansSKILL.mdsont assez précis pour que Codex sélectionne le skill de lui-même. -
Invocation en contexte (
test-03)
Ce prompt précise le sujet de la démo (l’API Responses), mais demande toujours la même configuration de base. Il vérifie que le skill se déclenche avec un prompt réaliste qui contient quelques informations annexes et que l’application obtenue respecte toujours l’arborescence et les conventions attendues. -
Témoin négatif (
test-04)
Ce prompt ne doit pas invoquersetup-demo-app. Il s’agit d’une demande courante et proche du cas visé (« ajoutez Tailwind à une application existante »), que Codex risque d’associer à tort à la description du skill (« démo React + Tailwind »). Inclure au moins un casshould_trigger=falsepermet de repérer les faux positifs, où Codex sélectionne le skill trop facilement et génère un nouveau projet alors que l’utilisateur voulait modifier un projet existant.
Cette combinaison est délibérée. Certaines évaluations doivent confirmer que le skill se comporte correctement lorsqu’on l’invoque explicitement. D’autres doivent vérifier qu’il s’active avec des prompts réalistes dans lesquels l’utilisateur ne le mentionne jamais.
Chaque fois que vous repérez un échec, qu’un prompt ne déclenche pas le skill ou que le résultat s’écarte de vos attentes, ajoutez une ligne au fichier. Au fil du temps, ce petit CSV recense les scénarios que le skill setup-demo-app doit continuer à traiter correctement.
Ce petit jeu de données garde ainsi une trace, régulièrement enrichie, des comportements que le skill doit conserver.
5. Commencez par des vérifications déterministes simples
Le principe central de l’évaluation consiste à utiliser codex exec --json pour que votre harnais d’évaluation puisse noter ce qui s’est réellement passé, sans se limiter à l’apparence du résultat final.
Avec l’option --json, stdout fournit un flux JSONL d’événements structurés. Vous pouvez alors écrire facilement des vérifications déterministes qui portent directement sur le comportement attendu, par exemple :
- L’agent a-t-il exécuté
npm install? - A-t-il créé
package.json? - A-t-il exécuté les commandes prévues dans le bon ordre ?
Ces vérifications sont volontairement simples. Elles vous donnent rapidement des résultats faciles à expliquer, avant même d’introduire une notation par un modèle.
Un script d’exécution minimal en Node.js
Pour commencer, la procédure suivante suffit :
- Pour chaque prompt, exécutez
codex exec --json --full-auto "<prompt>" - Enregistrez la trace JSONL sur le disque
- Analysez la trace et appliquez les vérifications déterministes aux é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
"--sandbox",
"workspace-write", // Allow changes inside the example repository
prompt,
],
{ encoding: "utf8" }
);
if (res.error) throw res.error;
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.completed" &&
e.item?.type === "command_execution" &&
e.item.status === "completed" &&
e.item.exit_code === 0 &&
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";
const { exitCode, stderr } = runCodex(prompt, tracePath);
if (exitCode !== 0) {
throw new Error(`Codex exited with status ${exitCode}: ${stderr}`);
}
const events = parseJsonl(readFileSync(tracePath, "utf8"));
console.log({
ranNpmInstall: checkRanNpmInstall(events),
hasPackageJson: checkPackageJsonExists(path.join(projectDir, "demo-app")),
});L’intérêt de cette approche est que chaque vérification est déterministe et facile à déboguer.
Si une vérification échoue, ouvrez le fichier JSONL pour voir exactement ce qui s’est passé. Chaque exécution de commande y figure sous la forme d’un événement item.*, dans l’ordre chronologique. Vous pouvez ainsi expliquer et corriger facilement les régressions, 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 « L’agent a-t-il fait l’essentiel ? », mais laissent ouverte la question « A-t-il procédé comme vous le souhaitiez ? »
Pour un skill comme setup-demo-app, de nombreuses exigences sont qualitatives : la structure des composants, les conventions de style ou la conformité de la configuration de Tailwind. Vérifier uniquement la présence de fichiers ou le nombre de commandes exécutées suffit rarement à les évaluer.
Une solution pratique consiste à ajouter à votre pipeline d’évaluation une seconde étape qui fait appel à un modèle :
- Exécutez le skill d’initialisation (il écrit le code sur le disque)
- Effectuez une vérification du style en lecture seule dans le dépôt obtenu
- Exigez une réponse structurée que votre harnais pourra noter de manière cohérente
Codex le permet directement avec --output-schema, qui impose à la réponse finale de respecter le schéma JSON que vous définissez.
Un schéma simple pour la grille de notation
Commencez par définir un petit schéma qui couvre les vérifications souhaitées. Créez par exemple 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
}Avec ce schéma, les champs restent stables (overall_pass, score, résultats de chaque vérification). Vous pouvez ainsi regrouper les résultats, comparer les écarts et suivre leur évolution.
Le prompt de vérification du style
Lancez ensuite une deuxième commande codex exec qui se limite à examiner le dépôt et renvoie une réponse JSON conforme à la grille :
codex exec \
"Évaluez le dépôt demo-app selon les critères suivants :
- Le dépôt contient un projet Vite + React + TypeScript.
- Tailwind est configuré avec @tailwindcss/vite et la feuille de style CSS importe tailwindcss.
- Le répertoire src/components contient Header.tsx et Card.tsx.
- Les composants sont fonctionnels et utilisent les classes utilitaires de Tailwind pour les styles, sans modules CSS.
Renvoyez les résultats de la grille au format JSON avec les identifiants de vérification suivants : vite, tailwind, structure, style." \
--output-schema ./evals/style-rubric.schema.json \
-o ./evals/artifacts/test-01.style.jsonC’est là que --output-schema prend tout son intérêt. Un texte libre serait difficile à analyser ou à comparer. Avec cette option, vous obtenez un objet JSON de structure prévisible que votre harnais d’évaluation peut noter de la même manière sur de nombreuses exécutions.
Si vous intégrez ensuite cette suite d’évaluations à votre CI, la GitHub Action de Codex permet explicitement de transmettre --output-schema via codex-args. Vous pouvez donc imposer le même format de sortie dans vos workflows automatisés.
7. Étendez les évaluations à mesure que le skill évolue
Une fois le cycle d’évaluation en place, vous pouvez approfondir les aspects les plus importants pour votre skill. Commencez modestement et ajoutez des vérifications plus poussées là où elles vous permettront de juger le résultat avec davantage de certitude.
Voici quelques exemples :
-
Nombre de commandes et répétitions inutiles : comptez les éléments
command_executiondans la trace JSONL pour repérer les régressions qui amènent l’agent à tourner en boucle ou à relancer des commandes. Les événementsturn.completedindiquent également la consommation de tokens. -
Budget de tokens : suivez
usage.input_tokensetusage.output_tokenspour détecter un allongement involontaire des prompts et comparer l’efficacité des différentes versions. -
Vérification du build : exécutez
npm run buildune fois que le skill a terminé. Ce test de bout en bout offre une garantie supplémentaire et permet de détecter les imports défectueux ou les outils mal configurés. -
Test rapide de fonctionnement : lancez
npm run devet envoyez une requête au serveur de développement aveccurl, ou exécutez un test Playwright léger si vous en avez déjà un. Réservez cette vérification aux cas où elle est utile : elle renforce la confiance dans le résultat, mais prend du temps. -
État du dépôt : vérifiez que l’exécution ne génère aucun fichier indésirable et que la sortie de
git status --porcelainest vide ou ne contient que des changements explicitement autorisés. -
Régressions liées au bac à sable et aux permissions : vérifiez que le skill fonctionne toujours sans exiger de permissions plus étendues que prévu. Dès que vous automatisez les exécutions, il est particulièrement important de limiter les privilèges accordés par défaut.
La démarche reste la même : commencez par des vérifications rapides qui permettent d’expliquer le comportement de l’agent, puis ajoutez des tests plus lents et plus lourds uniquement lorsqu’ils réduisent le risque.
8. Points à retenir
Le petit exemple de setup-demo-app montre comment passer d’une impression (« ça a l’air mieux ») à une preuve : lancez l’agent, enregistrez ce qui se passe et notez le résultat à l’aide de quelques vérifications. Une fois ce cycle en place, il devient plus facile de confirmer l’effet de chaque ajustement et de repérer chaque régression. Voici les points à retenir :
- Mesurez ce qui compte. De bonnes évaluations font ressortir les régressions et permettent d’expliquer les échecs.
- Définissez des critères de réussite vérifiables. Utilisez
$skill-creatorpour rédiger une première version, puis précisez les instructions jusqu’à ce que les conditions de réussite soient sans ambiguïté. - Fondez vos évaluations sur le comportement observé. Enregistrez la trace JSONL avec
codex exec --jsonet écrivez des vérifications déterministes portant sur les événementscommand_execution. - Faites appel à Codex lorsque les règles ne suffisent plus. Ajoutez une étape de notation structurée avec une grille et
--output-schemapour évaluer de manière fiable le style et le respect des conventions. - Enrichissez vos tests à partir des échecs rencontrés. Chaque correction manuelle révèle un cas à couvrir. Faites-en un test pour que le skill continue à le traiter correctement.