Codex : AGENTS.md, skills, subagents, qui fait quoi ?

Le mauvais réflexe avec Codex, c’est de transformer AGENTS.md en débarras.

On y met les commandes, le ton, les règles de tests, les interdictions, les prompts d’article, les préférences perso, les workflows de review. Au bout de deux semaines, le fichier ne guide plus rien. Il surcharge juste chaque session.

La bonne question n’est pas “où mettre l’instruction”. C’est “combien de temps cette instruction doit vivre, et à quel moment Codex doit la charger”.

1. Mets dans AGENTS.md ce qui doit être vrai partout

AGENTS.md sert aux conventions durables du repo. C’est le bon endroit pour dire :

• utilise bun, jamais npm;
• ne lance pas de serveur local sans demande explicite;
• les tutoriels /ai-coding vivent dans src/content/tutorials;
• toute actu récente doit être vérifiée avec une source officielle.

Ce n’est pas le bon endroit pour coller un prompt complet de rédaction de 200 lignes. Codex lit ce fichier au démarrage. Chaque règle inutile devient du bruit pour toutes les tâches, même quand tu corriges un bouton.

Règle simple : si l’instruction doit s’appliquer à 80% des tâches du repo, AGENTS.md. Sinon, ailleurs.

2. Utilise une skill pour un workflow répétable

Une skill Codex est un workflow réutilisable. Elle a un SKILL.md, une description, et des étapes que Codex peut charger quand la demande matche.

Exemples adaptés à ce blog :

• ai-coding-tutorial pour créer un tutoriel /ai-coding avec frontmatter, sources et version EN;
• editorial-newsletter pour transformer une actu IA en angle éditorial;
• une skill SEO si tu veux auditer les metas et liens internes.

L’intérêt est le chargement progressif. Codex voit la description courte, puis lit le détail seulement quand c’est utile. Tu gardes le prompt de base léger, mais tu as quand même des workflows précis.

3. Utilise un agent custom pour une délégation spécialisée

Un agent custom Codex vit dans .codex/agents/*.toml. Il est utile quand tu veux demander explicitement à Codex de déléguer à un profil spécialisé.

Exemple : “spawne l’agent ai-coding-tutorial pour préparer trois angles, puis reviens avec une recommandation”.

Le point important : un agent n’est pas juste un fichier de règles. C’est une session enfant avec ses propres instructions. Il consomme plus de tokens et doit être demandé explicitement. Garde-le pour les tâches où la spécialisation vaut le coût.

4. Utilise des subagents pour le fan-out, pas pour tout

Les subagents sont utiles quand le travail se parallélise vraiment :

• un agent inspecte les articles existants;
• un agent vérifie les docs officielles;
• un agent prépare les angles;
• le parent consolide et décide.

Pour écrire un seul paragraphe, c’est du théâtre. Tu paies plus cher, tu augmentes le risque de résultats incohérents, et tu dois relire davantage.

5. La grille de décision

Besoin	Surface
Convention durable du repo	AGENTS.md
Workflow réutilisable	.agents/skills/<nom>/SKILL.md
Profil spécialisé à invoquer	.codex/agents/<nom>.toml
Recherche parallèle	subagents
Instruction ponctuelle	prompt de la session

6. Le setup propre pour ce blog

Pour ce repo, le découpage sain est :

• AGENTS.md porte les règles globales : bun, build, ton éditorial, collections Astro;
• .agents/skills/ai-coding-tutorial décrit comment créer un tutoriel /ai-coding;
• .codex/agents/ai-coding-tutorial.toml sert à déléguer une recherche ou un draft spécialisé;
• les articles finaux restent dans src/content/tutorials, pas dans les fichiers d’agents.

Ça évite de mélanger consignes, workflow et contenu.

Sources

• OpenAI Codex - Agent Skills
• OpenAI Codex - Custom instructions with AGENTS.md
• OpenAI Codex - Subagents