Codex Skills : création, exécution et vérification sur une tâche de revue de code

Le mécanisme des Skills dans Codex

Le mécanisme de compétences (skills), décrit dans la documentation officielle, permet d’associer à l’agent des instructions et des modèles pour des tâches spécialisées sans surcharger le contexte système.

Une compétence se présente sous la forme d’un répertoire contenant un fichier obligatoire SKILL.md. Dans son frontmatter YAML, les champs name et description sont obligatoires, tandis que le corps du fichier contient les règles destinées au modèle :

.agents/skills/boundary-review/
└── SKILL.md

Codex s’appuie sur la divulgation progressive (progressive disclosure) : au démarrage, un index compact des compétences disponibles est généré. Le texte intégral de SKILL.md n’est lu par l’agent qu’au moment précis où il décide d’appliquer une compétence particulière.

La découverte des compétences s’opère selon quatre niveaux :

1. Dépôt (REPO) : .agents/skills dans le répertoire courant et en remontant jusqu’à la racine Git.
2. Utilisateur (USER) : $HOME/.agents/skills.
3. Administrateur (ADMIN) : /etc/codex/skills.
4. Système (SYSTEM) : répertoires système de l’environnement (intégrés / bundled).

L’appel s’effectue de manière explicite (via le préfixe $name) ou de manière implicite (selon la correspondance sémantique entre la requête et le champ description). La disponibilité et les conflits sont gérés dans le fichier config.toml.

Prérequis et isolation

Pour reproduire ce scénario, les éléments suivants sont requis :

• Python 3 ;
• Une interface en ligne de commande Codex CLI installée et authentifiée.

Les données de test ont été enregistrées le 2026-09-16 avec la version 0.153.3 de Codex CLI.

Toutes les commandes sont exécutées dans un répertoire local préparé, situé hors de tout dépôt Git. Étant donné que les instructions textuelles dans SKILL.md orientent le comportement du modèle mais ne garantissent pas l’isolation du système d’exploitation, l’exécution est réalisée avec les options suivantes :

• --ephemeral : empêche la persistance de l’état de session ;
• --skip-git-repo-check : permet l’exécution dans un dossier isolé sans Git ;
• --sandbox read-only : restreint les autorisations d’écriture du processus au niveau de l’environnement d’exécution.

Le CLI peut hériter de configurations globales et émettre des avertissements de service relatifs à des hooks tiers ; par conséquent, la vérification effective repose exclusivement sur les événements de lecture de la compétence ciblée.

Création du skill boundary-review

Créez le répertoire de la compétence dans le dossier courant :

mkdir -p .agents/skills/boundary-review

Enregistrez le contenu suivant dans .agents/skills/boundary-review/SKILL.md :

---
name: boundary-review
description: Review Python pagination code for boundary errors and show one minimal failing input. Use when asked to review pagination boundaries.
---
Read the provided Python file. Do not edit it. Begin your answer with BOUNDARY_REVIEW. Report a specific failing input, expected and actual result, and a minimal correction. Do not inspect files outside this project.

Cette consigne textuelle interdit au modèle de modifier les fichiers et lui impose de débuter sa réponse par le marqueur BOUNDARY_REVIEW, tout en indiquant une entrée défaillante spécifique.

Fichier de test avec anomalie

Créez un fichier pages.py comportant une erreur d’un facteur un typique (off-by-one error) lors du calcul du nombre de pages :

def page_count(total, size):
    return total // size + 1

Sous les conditions size > 0 et total >= 0, la fonction échoue sur les valeurs limites : avec total = 1 et size = 1, elle renvoie 2 au lieu de 1. De même, pour une liste vide où total = 0, la fonction renverra 1.

Exécution et vérification des appels

Les requêtes sont passées entre guillemets simples afin d’éviter que l’interpréteur de commandes n’interprète le caractère $ comme une variable d’environnement.

1. Appel explicite par le nom

Lancez une vérification explicite en spécifiant directement le skill :

codex exec --ephemeral --skip-git-repo-check --sandbox read-only 'Review pages.py using $boundary-review'

Le modèle renvoie le résultat suivant :

BOUNDARY_REVIEW

Failing input:
page_count(1, 1)

Expected result: 1
Actual result: 2

Minimal correction:
def page_count(total, size):
    return (total + size - 1) // size

La seule présence du marqueur BOUNDARY_REVIEW ne suffit pas à prouver que SKILL.md a bien été chargé, car ce marqueur pourrait être induit par le contexte de la requête. Lors de l’exécution effective du 2026-09-16, le journal système a bien enregistré l’événement de commande lisant le fichier .agents/skills/boundary-review/SKILL.md. C’est la combinaison de l’événement de lecture de fichier dans les journaux, du préfixe BOUNDARY_REVIEW et du contre-exemple page_count(1, 1) qui atteste de l’exécution de la directive visée.

2. Appel implicite par la description

Formulez la tâche en langage naturel sans faire référence à l’identifiant $boundary-review :

codex exec --ephemeral --skip-git-repo-check --sandbox read-only 'Review the pagination boundaries in pages.py'

Le journal de cette exécution a également consigné la lecture de .agents/skills/boundary-review/SKILL.md, enclenchée par la correspondance sémantique entre l’énoncé de la requête et le champ description. L’agent a produit une réponse structurée analogue arborant le marqueur BOUNDARY_REVIEW et l’analyse de l’échec sur l’entrée (1, 1).

Vérification logique et étapes pour le lecteur

Vérifions le comportement d’origine de la fonction avec un interpréteur Python local :

python3 -c "from pages import page_count; print(page_count(1, 1))"

La commande affiche 2, confirmant l’anomalie.

Lors du passage de référence du 2026-09-16, le fichier source pages.py n’a pas été modifié ; aucune nouvelle exécution du CLI n’a été menée sur le fichier rectifié. La validité mathématique de la formule proposée (total + size - 1) // size pour total >= 0 et size > 0 a été contrôlée sur plusieurs cas limites :

• (0, 10) -> 0 ;
• (1, 1) -> 1 ;
• (10, 10) -> 1 ;
• (11, 10) -> 2.

Pour appliquer la correction de façon autonome, le lecteur peut adapter pages.py comme suit :

def page_count(total, size):
    if total == 0:
        return 0
    return (total + size - 1) // size

Une fois les modifications enregistrées, le lecteur peut lancer la vérification des assertions :

python3 -c "from pages import page_count; assert page_count(0, 10) == 0; assert page_count(1, 1) == 1; assert page_count(10, 10) == 1; assert page_count(11, 10) == 2; print('OK')"

Le résultat attendu après modification manuelle du fichier est OK.

Diagnostic des dysfonctionnements

Si une compétence n’est pas détectée ou ne s’exécute pas automatiquement :

1. Chemin d’accès : vérifiez que le chemin relatif par rapport au répertoire de travail correspond rigoureusement à .agents/skills/<skill-name>/SKILL.md.
2. Actualisation du registre : si des fichiers ont été ajoutés alors qu’une session était déjà ouverte, redémarrez le processus CLI pour forcer une nouvelle scrutation des répertoires.
3. Blocage dans la configuration : contrôlez ~/.codex/config.toml. Si la compétence a été désactivée, une entrée de la forme :

   [[skills.config]]
   path = "/полный/путь/к/.agents/skills/boundary-review/SKILL.md"
   enabled = false

   empêchera son chargement. Supprimez cette section ou passez la valeur à enabled = true.
4. Conflits d’identifiants : en cas d’homonymie sur name entre l’échelon dépôt et l’échelon utilisateur, les règles de préséance peuvent introduire des ambiguïtés.
5. Précision de la description : pour un appel implicite, les termes déclencheurs clés (« pagination boundaries », « boundary errors ») doivent figurer au début du texte descriptif.
6. Compétences tierces : lorsqu’il convient d’importer des paquets externes, l’utilitaire $skill-installer sert d’interface d’entrée. Tout skill tiers exige obligatoirement un audit manuel préalable de ses fichiers SKILL.md et de son dossier scripts/ avant toute exécution. Aucun composant tiers n’a été installé lors du scénario présenté.