Guide pratique Codex Skills et Plugins : transformer les workflows d'équipe en capacités réutilisables

La même checklist de revue de code se retrouve copiée dans cinq dépôts. À chaque PR, il faut encore rappeler à la main : “lancez d’abord les tests qui échouent”, “vérifiez la frontière de permissions”, “n’oubliez pas le changelog”. Le problème n’est pas que le prompt est trop court. Le processus n’a pas encore été rendu réutilisable.

Codex Skills et Plugins servent précisément à sortir ces workflows répétés des prompts jetables et d’un AGENTS.md qui enfle. Un Skill est le format d’auteur d’un workflow réutilisable. Un Plugin est une unité installable de distribution. Les deux ne remplacent pas les règles de projet : les règles permanentes restent dans AGENTS.md; les procédures en plusieurs étapes, exemples, scripts et longues références passent dans des Skills; la distribution d’équipe devient un Plugin.

Une table de décision suffit souvent pour choisir entre Skill, Plugin, MCP, AGENTS.md et Subagent. On peut ensuite partir d’une arborescence de Skill minimale, puis aller vers la découpe d’un role-specific plugin, la distribution à l’équipe et la vérification des limites de permissions.

1. Workflows d’équipe copiés-collés : le prompt n’est pas le problème

Revue de code, contrôle avant release, procédure de test, mise à jour de documentation : ces checklists ont souvent une forme stable dans une équipe. Vous avez peut-être déjà copié dans Codex, à chaque PR review, une consigne du type : “vérifie si le changelog manque, si la couverture de tests a baissé et si la documentation API doit être mise à jour”. Les problèmes arrivent vite :

• La maintenance est dispersée : quand la checklist change, il faut mettre à jour les .github/PULL_REQUEST_TEMPLATE.md de cinq projets ou des fichiers de prompts séparés.
• La qualité d’exécution varie : Codex doit reconstruire le processus à chaque fois et peut oublier une étape critique comme “lancer d’abord les tests qui échouent”.
• Les responsabilités se mélangent : frontend, QA, sécurité et documentation finissent dans un même prompt, ce qui rend le standard à appliquer moins évident pour Codex.

Certaines équipes mettent tout dans AGENTS.md, mais cela crée un autre problème. Le fichier de règles projet devient trop long : commandes de build permanentes, conventions de dossiers et consignes de processus temporaires se retrouvent mélangées. On dépasse alors son rôle de fichier de contraintes durables.

Codex propose une séparation plus nette : AGENTS.md pour les règles permanentes, Skills pour les workflows réutilisables, Plugins pour la distribution. L’enjeu est de savoir quoi placer dans chaque couche.

2. Une table de décision pour Skill, Plugin, MCP et AGENTS.md

Un Skill est un format d’auteur pour workflows réutilisables, en général un fichier SKILL.md accompagné éventuellement de scripts, références et assets. Un Plugin est une unité installable dans Codex : il peut regrouper des Skills, app integrations, MCP servers et assets. MCP est le protocole de connexion à des outils externes et à du contexte, par exemple de la documentation tierce, un navigateur, Figma ou GitHub. AGENTS.md sert aux contraintes permanentes du projet : commandes de build, conventions de dossiers, attentes de revue. Un Subagent délègue un rôle pour des tâches bruyantes ou spécialisées.

Quand choisir quelle option

Type de contenu	Meilleure option	Cas typique	À éviter pour
Commandes de build, chemins de scripts de test, conventions de dossiers	AGENTS.md	”Tous les nouveaux composants vont dans src/components/”, “les tests passent par npm run test:unit”	Processus en plusieurs étapes, exemples, appels d’outils externes
Workflows en plusieurs étapes avec exemples, scripts ou références	Skill	Revue de code en 10 étapes, checklist de release en 7 points, génération de docs API	Une seule commande ou une règle en une ligne
Distribution d’équipe et packaging de configuration app/MCP	Plugin	Plugin de rôle frontend avec 4 Skills de revue et un Figma connector	Workflow limité à un seul dépôt et sans besoin de partage
Appels d’outils externes et contexte tiers	MCP	Récupérer les specs Figma, lire des issues via l’API GitHub	Définition pure de workflow sans données externes
Délégation de tâches bruyantes ou spécialisées	Subagent	Confier un diagnostic de tests ou une analyse de logs à un agent dédié	Processus simple faisable dans la conversation principale

Quand extraire un processus d’AGENTS.md vers un Skill

Ces signaux montrent que le processus dépasse le rôle d’un fichier de règles projet et mérite un Skill :

• La même checklist revient dans plusieurs PR et doit être copiée à la main.
• Le processus contient plusieurs étapes et s’appuie sur des exemples, scripts ou références externes.
• Le processus a un déclencheur clair, par exemple “avant la release” ou “pendant la revue de PR”, plutôt qu’une contrainte permanente.
• Plusieurs rôles ont des standards différents, ce qui rend un fichier unique trop confus.
• Le processus a besoin de versioning et de notes de changement, au lieu d’être modifié directement dans les règles du projet.

Quand transformer un Skill en Plugin

Un Skill suffit tant qu’il est itéré dans un dépôt ou dans le workflow d’une personne. Passez au Plugin si vous avez besoin de :

• partage entre équipes, au lieu d’un dossier personnel ou d’un seul dépôt ;
• packaging d’app integrations comme Figma, GitHub, outils CI/CD, ou configuration MCP server ;
• versioning, changelog et mécanisme de mise à jour, plutôt que copies de dossiers Skill ;
• distribution via la Plugin Directory de Codex App à des workspace members ;
• publication d’un paquet stable, et non d’un workflow expérimental qui change souvent.

Un ordre pragmatique : fixez les conventions du dépôt dans AGENTS.md; installez un Plugin existant s’il convient; sinon créez un Skill; packagez-le en Plugin quand la distribution d’équipe devient réelle; ajoutez MCP seulement si un système externe est nécessaire; utilisez un Subagent quand la tâche est assez bruyante ou spécialisée pour être déléguée.

3. Skill minimal en pratique : commencer par la revue de code

Arborescence minimale d’un Skill

Un Skill a besoin au minimum de ceci :

.agents/skills/code-review/
├── SKILL.md
├── references/
│   └── security-checklist.md
└── scripts/
    └── run-failed-tests.sh

Le nom du dossier et le champ name du frontmatter de SKILL.md doivent correspondre, en lowercase alphanumeric + hyphen.

Exemple de SKILL.md : Skill de revue de code

---
name: code-review
description: Use for pull request reviews in frontend projects. Checks changelog, test coverage, security boundary, and API docs. Do not use for backend-only changes or infrastructure PRs.
---

# Code Review Checklist

## Before Starting
1. Run failed tests first: `npm run test:failed`
2. Check if PR has clear description and scope

## Review Steps
1. Changelog: Does `CHANGELOG.md` need update?
2. Test Coverage: Did coverage decrease? Check report in `coverage/`
3. Security: Review changes in `src/auth/`, `src/api/`, and `src/middleware/`
4. API Docs: If API changed, update `docs/api.md`

## Security Boundary Checks
See `references/security-checklist.md` for detailed items.

## Failed Test Runner
Use `scripts/run-failed-tests.sh` to rerun previously failed tests.

Concevoir le déclenchement dans description : before/after

Codex s’appuie sur la description pour décider si un Skill doit être appelé implicitement. Une description floue déclenche trop souvent, ou pas du tout :

Before, risque de faux déclenchement	After, plus fiable
”Code review skill for frontend projects"	"Use for pull request reviews in frontend projects. Checks changelog, test coverage, security boundary, and API docs."
"Help review code"	"Use when reviewing PRs with frontend changes. Do not use for backend-only changes or infrastructure PRs."
"Review checklist"	"Trigger on: PR reviews, code audit requests. Exclude: backend changes, config-only updates.”

La description doit inclure des bornes claires : “Use when…” et “Do not use when…”. Placez les mots déclencheurs comme pull request, review, frontend au début, car une longue description peut être tronquée. Si vous voulez un appel uniquement explicite, définissez allow_implicit_invocation: false.

Emplacements et portée des Skills

Emplacement	Portée	Cas d’usage	À noter
.agents/skills/ à la racine du dépôt	Dépôt courant	Processus de revue, test et release de l’équipe	À committer dans Git pour le partage
$HOME/.agents/skills/	Personnel, multi-projets	Style de code personnel, commandes fréquentes	Pas synchronisé automatiquement avec le dépôt
/etc/codex/skills/	Organisation	Revues sécurité ou conformité uniformes	Demande des droits admin
System bundled	Intégré au système	Skills comme $skill-creator, $skill-installer	Non modifiable

Deux Skills de même nom ne sont pas fusionnés. La priorité est généralement repo > user > admin > system, mais les documents officiels restent la source de vérité si ce comportement change.

Concevoir la progressive disclosure

Ne mettez pas tout dans le SKILL.md principal. Codex utilise une progressive disclosure en trois couches :

1. Metadata : Codex voit d’abord name, description et le file path.
2. Instructions : le SKILL.md complet est chargé seulement après sélection du Skill.
3. Resources : references/, scripts/ et assets/ sont lus seulement si nécessaire.

En pratique, gardez le SKILL.md principal sous 500 lignes environ. Déplacez les longues références dans des fichiers séparés. Réservez scripts/ aux contrôles déterministes, comme un test runner ou une vérification de couverture. Mettez les checklists détaillées, documents de contexte et cas historiques dans references/. Les modèles et captures d’exemple vont dans assets/.

Appel explicite et implicite

L’appel explicite utilise $code-review ou le sélecteur /skills. L’appel implicite laisse Codex décider, via la description, si le Skill correspond à la tâche. Pour le désactiver, définissez allow_implicit_invocation: false dans agents/openai.yaml.

L’appel implicite convient aux workflows fréquents et bien bornés, comme la revue de PR. L’appel explicite est plus sûr pour des tâches rares qui demandent du jugement, par exemple un audit sécurité trimestriel. Si un Skill contient des scripts externes ou des opérations sensibles, privilégiez l’appel explicite.

4. Packaging Plugin et distribution d’équipe : du Skill local à la suite d’équipe

Structure minimale d’un Plugin

Un Plugin n’est pas un simple dossier Skill renommé. C’est un package installable, avec au minimum un manifest .codex-plugin/plugin.json :

.agents/plugins/frontend-review/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── code-review/
│   │   └── SKILL.md
│   ├── accessibility-check/
│   │   └── SKILL.md
│   └── performance-lint/
│       └── SKILL.md
├── assets/
│   └── templates/
└── README.md

Champs requis de plugin.json

{
  "name": "frontend-review",
  "version": "1.0.0",
  "description": "Frontend team code review and accessibility check skills",
  "skills": "./skills/",
  "assets": "./assets/",
  "author": "frontend-team",
  "repository": "https://github.com/org/frontend-review-plugin"
}

Les champs optionnels incluent apps pour les intégrations d’app comme .app.json for Figma, mcpServers pour une configuration MCP server comme .mcp.json, et policy pour les règles de permissions et de partage de données, toujours soumises à la workspace admin policy.

Structure marketplace : répertoire de Plugins d’équipe

Un Plugin marketplace est une liste JSON qui pointe vers les emplacements de Plugins :

.agents/plugins/marketplace.json

{
  "plugins": [
    {
      "source": "local",
      "path": "./frontend-review"
    },
    {
      "source": "github",
      "owner": "openai",
      "repo": "role-specific-plugins",
      "ref": "main",
      "path": "plugins/data-analytics"
    }
  ]
}

local convient aux Plugins internes non publiés. github pointe vers un dépôt public ou un package partagé entre équipes.

Checklist de commandes pour distribuer un Plugin

Les commandes CLI peuvent changer ; gardez la documentation officielle comme référence :

# Scaffold d'un nouveau Plugin
codex plugin create frontend-review

# Ajouter un Plugin au marketplace
codex plugin marketplace add owner/repo --ref main --sparse

# Lister les Plugins installés
codex plugin marketplace list

# Mettre à jour un Plugin
codex plugin marketplace upgrade frontend-review

# Supprimer un Plugin
codex plugin marketplace remove frontend-review

Dans Codex App, la Plugin Directory peut afficher Curated by OpenAI, Shared with you et Created by you. Un local plugin peut être partagé avec des workspace members ou groups. Les workspace admins peuvent désactiver plugin sharing ou définir des managed requirements.

Partager dans un workspace ne veut pas dire publier publiquement. Les connexions app externes et MCP servers exigent toujours une autorisation, et les approval settings continuent de s’appliquer.

Organiser le marketplace d’équipe

Placez un marketplace de dépôt dans $REPO_ROOT/.agents/plugins/marketplace.json pour les Plugins spécifiques au projet. Placez les Plugins d’organisation dans $HOME/.agents/plugins/marketplace.json ou dans un dépôt GitHub organization. Déclarez la version dans le manifest du Plugin, tenez un changelog dans le README, puis testez les mises à jour dans un environnement de test. Les Plugins sensibles, comme sécurité ou conformité, gagnent à rester au niveau organisation pour éviter les installations improvisées.

Commencez par un local skill, stabilisez-le, puis packagez-le en Plugin. Construire le Plugin dès le départ rend souvent l’itération plus lourde.

5. Découper un role-specific Plugin : frontend, QA et documentation

Le dépôt role-specific-plugins d’OpenAI fournit des modèles pour Sales, Data Analytics, Product Design et Financial Markets. Une équipe de développement n’a pas besoin de copier les workflows sales ou finance. Le découpage reste utile : partez d’un rôle, extrayez 3 à 5 petits Skills, puis regroupez-les dans un Plugin.

Cadre de découpage : rôle → livrable répété → sources données/outils → petits Skills → mode de partage

Rôle	Livrable répété	Sources données/outils	Skills à extraire	Apps/MCP possibles	Critère d’acceptation
Ingénieur frontend	Revue de composant, contrôle performance, validation accessibilité	Specs Figma, bibliothèque Storybook existante	component-audit, accessibility-check, performance-lint, design-system-sync	Figma connector, Storybook MCP	Chaque nouveau composant passe les 4 contrôles
Ingénieur QA	Rapport de couverture, diagnostic de suite E2E, checklist de régression	Résultats CI/CD, historique des échecs	test-coverage-check, e2e-suite-runner, flaky-test-diagnosis, regression-suite-builder	Connexion CI/CD, GitHub Actions ou Jenkins	Tests en échec d’abord, couverture stable
Rédacteur technique	Mise à jour API docs, construction de Changelog, guides de migration	API schema, Git commit history	api-doc-generator, changelog-builder, readme-audit, migration-guide-writer	GitHub API, outils schema	Documentation mise à jour quand l’API change
Ingénieur sécurité	Revue de limites de permissions, secrets scan, analyse dépendances	Manifests de dépendances, configuration de stockage des secrets	auth-boundary-check, secrets-scan, dependency-security	Snyk, Dependabot MCP	Checklist sécurité complétée avant chaque release

Exemple de découpage pour un Plugin rôle frontend

frontend-engineer-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── component-audit/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── component-template.md
│   ├── accessibility-check/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── axe-audit.sh
│   ├── performance-lint/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── lighthouse-check.sh
│   └── design-system-sync/
│       ├── SKILL.md
│       └── references/
│           └── design-tokens.md
├── assets/
│   └── templates/
│       └── component-template.tsx
└── README.md

component-audit vérifie si un nouveau composant respecte les règles d’équipe : nommage, dossier, types des props. accessibility-check lance un script axe-core. performance-lint vérifie les principaux indicateurs avec Lighthouse. design-system-sync compare l’implémentation avec les specs Figma.

Exemple de découpage pour un Plugin rôle QA

qa-engineer-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── test-coverage-check/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── coverage-threshold-check.sh
│   ├── e2e-suite-runner/
│   │   └── SKILL.md
│   ├── flaky-test-diagnosis/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── flaky-test-log-analysis.md
│   └── regression-suite-builder/
│       └── SKILL.md
├── .mcp.json
└── README.md

test-coverage-check détecte une baisse de couverture et signale les fichiers non couverts. e2e-suite-runner lance les tests E2E par priorité. flaky-test-diagnosis analyse l’historique des échecs pour repérer les tests instables. regression-suite-builder construit une checklist de régression à partir de la surface modifiée.

Checklist de remplacement des connector placeholders

Les modèles officiels peuvent contenir des connector IDs placeholders dans .app.json. Remplacez-les avant installation :

{
  "app_id": "figma-placeholder"
}

Vérifiez tous les placeholder IDs dans .app.json et remplacez-les par de vrais IDs disponibles dans votre workspace. Ne copiez pas les connector IDs d’un autre workspace : ils peuvent être invalides ou non autorisés chez vous. Les tokens OAuth/Bearer dans la configuration MCP server doivent venir de votre environnement, pas d’un exemple de template. Après remplacement, validez le connector dans un environnement de test.

Le README officiel de role-specific-plugins indique que ces modèles doivent être personnalisés avant usage. Les connector-backed plugins peuvent contenir des app IDs ou connector IDs à remplacer.

6. Sécurité et maintenance : un Plugin n’est pas un laissez-passer

Limites de permissions Connector / MCP

Installer un Plugin ne contourne pas les approval settings de Codex. Les apps externes et MCP servers demandent toujours une autorisation, et le partage de données reste soumis à leurs politiques. Les placeholder IDs dans .app.json doivent être remplacés, mais il ne faut pas copier les connector IDs d’un autre workspace. Les apps externes comme Figma ou GitHub exigent une autorisation séparée. Un Plugin package une configuration ; il n’accorde pas l’autorisation. Les MCP servers restent contrôlables via enabled et tool policy dans config.toml. L’approval mode s’applique aussi : si le mode est “suggest-only”, les scripts du Plugin ne s’exécutent pas automatiquement.

Ne traitez pas un Plugin comme un laissez-passer. Il regroupe workflow, configuration et assets, mais les limites de permissions restent en place.

Revue de source des scripts

Le dossier scripts/ d’un Skill ou Plugin peut contenir des exécutables. Les Plugins tiers et marketplaces communautaires doivent être vérifiés : inspectez tous les fichiers exécutables dans scripts, confirmez leur source, évitez d’exécuter des scripts de dépôts non vérifiés, testez d’abord en environnement de test, et figez les versions avec un tag ou un commit hash plutôt que de suivre main.

Le même principe appliqué aux Skills tiers à risque vaut pour tout script exécutable et Plugin tiers : vérifier la source, réduire les permissions, valider en test.

Versioning et changelog

Le travail d’équipe demande une gestion de version. Déclarez clairement version dans plugin.json, incrémentez-le à chaque mise à jour, et tenez un changelog dans le README pour indiquer les Skills ajoutés, modifiés ou dépréciés. Avant une mise à jour, testez dans un environnement de test, lancez tous les Skills, vérifiez que les scripts fonctionnent, et confirmez que les connectors sont encore disponibles. Dans le marketplace, pointez ref vers un tag ou un commit, pas vers le dernier main.

Impact du nombre de Skills et Plugins

La liste initiale des Skills a un budget de contexte. La documentation officielle indique que cette liste occupe environ 2 % du contexte, ou 8 000 characters lorsque la taille du contexte est inconnue.

Conséquence pratique : une description de Skill trop longue peut être tronquée, donc les mots déclencheurs doivent venir au début. Trop de Skills chargés peuvent aussi rendre le choix plus difficile pour Codex. Les Skills fréquents et bien bornés sont adaptés au dossier repo ou user. Les Skills rares peuvent rester dans un Plugin à installer au besoin, plutôt que d’être présents en permanence.

Si Codex déclenche souvent le mauvais Skill ou ignore le bon, commencez par revoir la description. Ajouter encore plus de Skills règle rarement le problème.

7. Comparaison avec les technologies proches

Comparaison avec Claude Code Skills

BetterLink a déjà couvert le mécanisme des Claude Code Skills. Le modèle mental est proche, mais les produits restent différents : les deux s’appuient sur le format ouvert Agent Skills et sur un fichier SKILL.md; les deux utilisent name, description, et éventuellement scripts/, references/, assets/; les deux suivent une progressive disclosure : metadata → instructions → resources.

Les différences comptent. Codex utilise .agents/skills/, Claude Code utilise .claude/skills/. L’appel Codex passe par $skill-name ou /skills, alors que Claude Code utilise la commande /skill. Côté distribution, Codex Plugin propose marketplace, commandes CLI et workspace sharing ; Claude Code n’a pas aujourd’hui de Plugin marketplace officiel. Les outils intégrés diffèrent aussi : Codex propose $skill-creator, $skill-installer, @plugin-creator, tandis que Claude Code a ses propres commandes.

Si vous avez déjà écrit des Claude Code Skills, vous pouvez réutiliser le modèle mental. Ne copiez pas les chemins ni la syntaxe d’appel : suivez la documentation officielle de chaque produit.

Place de MCP

MCP, le Model Context Protocol, relie des outils externes et du contexte. Il ne remplace ni Skills ni Plugins. Un Skill définit le workflow. MCP connecte l’outil externe, par exemple Figma, GitHub ou un système CI/CD. Un Plugin peut embarquer la configuration MCP server, mais le MCP server reste gouverné par config.toml.

Exemple : un Skill de revue frontend définit le processus “vérifier si le composant respecte le design system”. Un Figma MCP server donne accès au fichier de design. Un Plugin frontend regroupe le Skill de revue et la configuration Figma MCP, mais l’OAuth Figma doit toujours être autorisé séparément.

Cette section clarifie seulement la frontière. Un guide pratique dédié aux Codex MCP tools peut détailler l’implémentation.

Conclusion

Codex Skills et Plugins servent à sortir les workflows d’équipe répétés des prompts copiés-collés et d’un AGENTS.md surchargé. La règle simple : AGENTS.md pour les règles permanentes, Skill pour les workflows en plusieurs étapes, Plugin pour le packaging et la distribution, MCP pour les systèmes externes. Décrivez clairement les conditions de déclenchement, validez d’abord un local skill, puis packagez-le en Plugin quand la distribution est réelle. Les scripts, connector IDs et configurations MCP des Plugins tiers restent à auditer.

Commencez par un Skill minimal. Transformez votre processus de revue de code ou de test en SKILL.md, lancez-le quelques fois et vérifiez si son déclenchement est fiable. Si votre équipe a des rôles frontend, QA, sécurité ou documentation, reprenez le découpage d’OpenAI role-specific-plugins : 3 à 5 petits Skills par rôle, puis un Plugin de rôle.

À lire ensuite sur BetterLink :

• Guide complet pour débuter avec Codex
• Règles de projet AGENTS.md
• Limites de sécurité et gestion des permissions Codex
• Codex MCP tools en pratique
• Comparaison avec Claude Code Skill
• Bases du protocole MCP