Personnalisation

La personnalisation vous permet d’adapter Codex aux méthodes de travail de votre équipe.

Dans Codex, la personnalisation repose sur plusieurs couches complémentaires :

• Directives de projet (AGENTS.md) pour les instructions persistantes
• Mémoires pour le contexte utile tiré des travaux précédents
• Skills pour les workflows réutilisables et l’expertise métier
• MCP pour accéder aux outils externes et aux systèmes partagés
• Sous-agents pour déléguer des tâches à des sous-agents spécialisés

Ces couches sont complémentaires et non concurrentes. AGENTS.md façonne le comportement, les mémoires conservent le contexte local, les skills regroupent les processus reproductibles et MCP connecte Codex aux systèmes extérieurs à l’espace de travail local.

Directives AGENTS

AGENTS.md fournit à Codex des directives de projet durables, qui accompagnent votre dépôt et s’appliquent avant que l’agent ne commence à travailler. Veillez à ce que ce fichier reste concis.

Utilisez-le pour définir les règles que Codex doit suivre systématiquement dans un dépôt, telles que :

• Les commandes de build et de test
• Les attentes en matière de revue
• Les conventions propres au dépôt
• Les instructions propres à certains répertoires

Lorsque l’agent émet des hypothèses incorrectes sur votre base de code, corrigez-les dans AGENTS.md et demandez-lui de mettre à jour AGENTS.md afin que la correction soit conservée. Considérez ce mécanisme comme une boucle de rétroaction.

Quand mettre à jour AGENTS.md

• Erreurs répétées : si l’agent commet plusieurs fois la même erreur, ajoutez une règle.
• Trop de lecture : s’il trouve les bons fichiers, mais consulte trop de documents, ajoutez des directives d’orientation (répertoires ou fichiers à traiter en priorité).
• Retours récurrents sur les PR : si vous formulez plusieurs fois le même retour, formalisez-le.
• Dans GitHub : dans un commentaire de pull request, mentionnez @codex en lui adressant une demande (par exemple, @codex add this to AGENTS.md) afin de déléguer la mise à jour à une conversation dans le cloud.
• Automatisation de la détection des écarts : utilisez des tâches planifiées pour exécuter des contrôles récurrents (quotidiens, par exemple) qui recherchent les lacunes dans les directives et suggèrent des ajouts à AGENTS.md.

Associez AGENTS.md à une infrastructure qui impose ces règles : les hooks de pre-commit, les linters et les vérificateurs de types détectent les problèmes avant vous, ce qui permet au système de mieux prévenir les erreurs récurrentes.

Codex peut charger des directives depuis plusieurs emplacements : un fichier global dans votre répertoire personnel Codex (pour vous en tant que développeur) et des fichiers propres au dépôt que les équipes peuvent versionner. Les fichiers les plus proches du répertoire de travail sont prioritaires. Utilisez le fichier global pour définir la manière dont Codex communique avec vous (par exemple, le style des revues, le niveau de détail et les valeurs par défaut), et réservez les fichiers du dépôt aux règles de l’équipe et de la base de code.

<FileTree class="mt-4" tree={[ { name: "~/.codex/", open: true, children: [ { name: "AGENTS.md", comment: "Global (pour vous en tant que développeur)" }, ], }, { name: "repo-root/", open: true, children: [ { name: "AGENTS.md", comment: "Propre au dépôt (pour votre équipe)" }, ], }, ]} />

Instructions personnalisées avec AGENTS.md

Skills

Les skills confèrent à Codex des capacités réutilisables pour les workflows reproductibles. Ils sont souvent la solution la mieux adaptée à ces workflows, car ils prennent en charge des instructions, des scripts et des références plus élaborés, tout en restant réutilisables d’une tâche à l’autre. Les skills sont chargés et visibles par l’agent (au moins leurs métadonnées), ce qui permet à Codex de les découvrir et de les sélectionner implicitement. Les workflows élaborés restent ainsi disponibles sans alourdir le contexte initial.

Utilisez des dossiers de skills pour créer et améliorer vos workflows localement. Si un plugin existe déjà pour le workflow concerné, installez-le d’abord afin de réutiliser une configuration éprouvée. Lorsque vous souhaitez diffuser votre propre workflow auprès de plusieurs équipes ou l’associer à des connecteurs, empaquetez-le sous forme de plugin. Les skills restent le format de création ; les plugins constituent l’unité de distribution installable.

Un skill se compose généralement d’un fichier SKILL.md, auquel peuvent s’ajouter des scripts, des références et des ressources.

<FileTree class="mt-4" tree={[ { name: "my-skill/", open: true, children: [ { name: "SKILL.md", comment: "Obligatoire : instructions + métadonnées" }, { name: "scripts/", comment: "Facultatif : code exécutable" }, { name: "references/", comment: "Facultatif : documentation" }, { name: "assets/", comment: "Facultatif : modèles, ressources" }, ], }, ]} />

Le répertoire du skill peut inclure un dossier scripts/ contenant des scripts CLI que Codex exécute dans le cadre du workflow (par exemple, pour initialiser des données ou lancer des validations). Lorsque le workflow nécessite des systèmes externes (outils de suivi des problèmes, outils de conception, serveurs de documentation), associez le skill à MCP.

Exemple de fichier SKILL.md :

---
name: commit
description: Stage and commit changes in semantic groups. Use when the user wants to commit, organize commits, or clean up a branch before pushing.
---

1. Do not run `git add .`. Stage files in logical groups by purpose.
2. Group into separate commits: feat → test → docs → refactor → chore.
3. Write concise commit messages that match the change scope.
4. Keep each commit focused and reviewable.

Utilisez les skills pour :

• Les workflows reproductibles (étapes de publication, routines de revue, mises à jour de documentation)
• L’expertise propre à une équipe
• Les procédures nécessitant des exemples, des références ou des scripts auxiliaires

Les skills peuvent être globaux (dans votre répertoire utilisateur, pour vous en tant que développeur) ou propres au dépôt (versionnés dans .agents/skills, pour votre équipe). Placez les skills du dépôt dans .agents/skills lorsque le workflow s’applique au projet concerné ; utilisez votre répertoire utilisateur pour les skills destinés à l’ensemble de vos dépôts.

Codex applique le principe de divulgation progressive aux skills :

• Il commence par les métadonnées (name, description) pour les découvrir
• Il ne charge SKILL.md qu’une fois le skill sélectionné
• Il ne consulte les références ou n’exécute les scripts que si nécessaire

Les skills peuvent être invoqués explicitement, mais Codex peut également les sélectionner implicitement lorsque la tâche correspond à leur description. Des descriptions claires améliorent la fiabilité du déclenchement.

Créer des skills

MCP

MCP (Model Context Protocol) est le moyen standard de connecter Codex à des outils externes et à des fournisseurs de contexte. Il est particulièrement utile pour les systèmes hébergés à distance dont dépend votre équipe, tels que Figma, Linear, GitHub ou des services de connaissances internes.

Utilisez MCP lorsque Codex a besoin de capacités extérieures au dépôt local, telles que des outils de suivi des problèmes, des outils de conception, des navigateurs ou des systèmes de documentation partagés.

Vous pouvez vous le représenter ainsi :

• Hôte : Codex
• Client : la connexion MCP au sein de Codex
• Serveur : l’outil externe ou le fournisseur de contexte

Les serveurs MCP peuvent exposer :

• Des outils (actions)
• Des ressources (données consultables)
• Des prompts (modèles de prompts réutilisables)

Cette séparation vous aide à raisonner sur les limites de confiance et de capacité. Certains serveurs fournissent principalement du contexte, tandis que d’autres donnent accès à des actions puissantes.

En pratique, MCP se révèle souvent particulièrement utile lorsqu’il est associé à des skills :

• Un skill définit le workflow et indique les outils MCP à utiliser

Model Context Protocol

Sous-agents

Vous pouvez créer différents agents, leur attribuer des rôles distincts et leur demander d’utiliser les outils de différentes manières. Par exemple, un agent peut exécuter des commandes et des configurations de test particulières, tandis qu’un autre dispose de serveurs MCP qui récupèrent les journaux de production à des fins de débogage. Chaque sous-agent reste concentré sur sa mission et utilise les outils appropriés.

Sous-agents

Combiner Skills et MCP

L’association des skills et de MCP rassemble toutes ces possibilités : les skills définissent des workflows reproductibles, tandis que MCP les connecte aux outils et systèmes externes. Si un skill dépend de MCP, déclarez cette dépendance dans agents/openai.yaml afin que Codex puisse l’installer et le connecter automatiquement (consultez Créer des skills).

Étape suivante

Procédez dans cet ordre :

1. Définissez des instructions personnalisées avec AGENTS.md afin que Codex respecte les conventions de votre dépôt. Ajoutez des hooks de pre-commit et des linters pour imposer ces règles.
2. Installez un plugin lorsqu’un workflow réutilisable existe déjà. Sinon, créez un skill, puis empaquetez-le sous forme de plugin lorsque vous souhaitez le partager.
3. Ajoutez MCP lorsque les workflows nécessitent des systèmes externes (Linear, GitHub, serveurs de documentation, outils de conception).
4. Utilisez des sous-agents lorsque vous êtes prêt à déléguer des tâches bruyantes ou spécialisées à des sous-agents.