Accueil › Codex › Skills

Codex Skills : créer, installer et utiliser les compétences de l’agent

Les skills étendent Codex au-delà du code pur. Ce sont des paquets modulaires d’instructions, de scripts et de ressources qui enseignent à l’agent des workflows spécialisés : implémenter un design Figma, déployer sur Vercel, gérer des issues Linear, ou créer des notebooks Jupyter. Le format est un standard ouvert compatible avec Claude Code, Cursor, et d’autres agents.

Qu’est-ce qu’une skill Codex ?

Une skill est un module autonome qui transforme Codex d’un agent généraliste en un spécialiste d’un domaine ou d’un workflow précis. Pensez-y comme un « guide d’onboarding » pour une tâche spécifique : au lieu de demander à Codex d’improviser, vous lui fournissez des connaissances procédurales, des scripts testés, et de la documentation de référence.

La différence avec AGENTS.md est importante : AGENTS.md est toujours chargé dans le contexte à chaque session, quelle que soit la tâche. Les skills utilisent la divulgation progressive : Codex ne charge que les métadonnées (nom, description, chemin) au démarrage, puis charge les instructions complètes seulement quand il décide d’utiliser la skill. C’est plus efficace en tokens pour les projets avec beaucoup de skills.

Le format est un standard ouvert. Le concept a émergé chez Anthropic avec Claude Code, a été adopté par OpenAI pour Codex, puis par Google pour Antigravity, Vercel (skills.sh), et d’autres. Vous pouvez utiliser la même skill avec plusieurs agents de coding.

Anatomie d’une skill

Structure de fichiers

Une skill est un répertoire contenant au minimum un fichier SKILL.md :

ma-skill/
├── SKILL.md              # Obligatoire : métadonnées + instructions
├── agents/
│   └── openai.yaml       # Recommandé : métadonnées UI pour l'app Codex
├── scripts/              # Optionnel : code exécutable (Python, Bash, etc.)
├── references/           # Optionnel : documentation à charger dans le contexte
└── assets/               # Optionnel : templates, icônes, fichiers statiques

Le fichier SKILL.md

Le SKILL.md contient un frontmatter YAML (obligatoire) suivi d’instructions en Markdown :

---
name: mon-deploiement-vercel
description: Déploie des applications sur Vercel. Utiliser quand l'utilisateur
  demande "déploie mon app", "push en production", ou "crée un preview".
---

# Déploiement Vercel

## Workflow
1. Vérifier que le CLI Vercel est installé (`command -v vercel`)
2. Si absent, l'installer sans élévation de permissions
3. Déployer en mode preview par défaut (pas production)
4. Utiliser un timeout de 10 minutes pour le build
5. Retourner l'URL de preview à l'utilisateur

## Règles
- Toujours déployer en preview sauf demande explicite de production
- Si le réseau est bloqué par le sandbox, utiliser `sandbox_permissions=require_escalated`
- Ne jamais escalader les permissions pour la vérification d'installation

Les deux champs du frontmatter sont obligatoires. Le name identifie la skill. La description est le signal de déclenchement principal : c’est sur cette description que Codex se base pour décider d’invoquer la skill automatiquement. Rédigez-la avec des exemples de phrases utilisateur pour améliorer la détection implicite.

Le fichier agents/openai.yaml

Ce fichier optionnel configure les métadonnées UI dans l’app Codex, la politique d’invocation, et les dépendances d’outils :

# agents/openai.yaml
display:
  icon: "🚀"
  category: "deployment"
invocation:
  policy: "explicit"  # ou "implicit" ou "auto"
tools:
  required:
    - "vercel-cli"

N’incluez ce fichier que quand vous avez besoin de personnaliser le comportement dans l’app Codex. Pour les skills simples, le SKILL.md seul suffit.

Le système à trois niveaux

Codex organise les skills en trois catégories :

Les skills système sont installées automatiquement. Les skills curated s’installent par nom simple. Les skills expérimentales nécessitent une URL ou un chemin explicite vers le repo source.

Le catalogue officiel des skills curated

En mars 2026, le repo openai/skills contient environ 35 skills curated couvrant les workflows les plus courants. Voici les catégories principales :

Design et Figma

GitHub

Déploiement

Notion

Contenu et médias

Développement

Expérimentales

Installer des skills

Skills curated (par nom)

Le plus simple : utilisez $skill-installer directement dans Codex :

# Dans le TUI ou l'app Codex, tapez :
$skill-installer install figma
$skill-installer install vercel-deploy
$skill-installer install gh-fix-ci

Les skills curated s’installent par nom simple car Codex résout automatiquement le chemin vers le dossier skills/.curated/ du repo officiel.

Skills expérimentales (par URL)

Les skills expérimentales nécessitent une URL ou un chemin explicite :

$skill-installer install the create-plan skill from the .experimental folder
# ou avec l'URL complète
$skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/create-plan

Installation manuelle (git clone)

Vous pouvez aussi cloner directement une skill dans votre répertoire de skills :

# Installer une skill communautaire
git clone https://github.com/utilisateur/ma-skill 
  ~/.codex/skills/ma-skill

# Redémarrer Codex pour qu'il détecte la nouvelle skill
# (Codex détecte aussi les changements automatiquement dans la plupart des cas)

Les quatre scopes d’installation

Codex découvre les skills dans quatre emplacements, par ordre de priorité :

Repository (.agents/skills/) : skills versionées avec le projet. Codex scanne ce répertoire depuis votre CWD jusqu’à la racine du repo. Idéal pour partager des skills spécifiques au projet avec toute l’équipe.

Utilisateur (~/.codex/skills/) : skills personnelles, disponibles sur tous vos projets. C’est ici que $skill-installer place les skills par défaut.

Admin (/etc/codex/skills/) : skills gérées par l’administrateur système. Pour les déploiements entreprise.

Système (~/.codex/skills/.system/) : skills intégrées à Codex (skill-creator, skill-installer, plan). Installées automatiquement.

Si deux skills portent le même nom, Codex ne les fusionne pas : les deux apparaissent dans le sélecteur de skills.

Invoquer une skill

Invocation explicite

Tapez $nom-de-skill dans votre prompt pour forcer l’utilisation d’une skill :

# Dans le TUI Codex
$figma-implement-design Implémente le composant Card depuis ce lien Figma
$vercel-deploy Déploie l'app en preview
$gh-fix-ci Corrige les tests qui échouent dans la CI

Vous pouvez aussi utiliser la commande /skills dans le TUI ou taper $ pour ouvrir le sélecteur de skills avec recherche fuzzy. Dans l’app Codex, les skills sont listées dans la sidebar.

Invocation implicite

Codex peut choisir automatiquement une skill quand votre tâche correspond à la description de la skill. Par exemple, si vous dites « déploie mon app sur Vercel », Codex reconnaîtra que la skill vercel-deploy est pertinente et la chargera automatiquement.

La qualité de la détection implicite dépend entièrement de la description dans le frontmatter YAML. C’est pourquoi OpenAI recommande d’écrire des descriptions avec des exemples de phrases utilisateur typiques.

Créer une skill

Création assistée avec $skill-creator

La manière la plus simple de créer une skill : utilisez la skill intégrée $skill-creator. Elle vous guide à travers un processus interactif :

# Dans Codex
$skill-creator Crée une skill pour valider les migrations Prisma avant commit

Le créateur vous demande ce que la skill fait, quand elle doit se déclencher, et si elle doit rester uniquement instructionnelle ou inclure des scripts. Le mode instruction-only est le défaut recommandé.

Création manuelle

Pour un contrôle total, créez le répertoire et le fichier SKILL.md manuellement :

# Créer la structure
mkdir -p ~/.codex/skills/prisma-validation
cat > ~/.codex/skills/prisma-validation/SKILL.md << 'EOF'
---
name: prisma-validation
description: Valide les migrations Prisma avant commit. Utiliser quand
  l'utilisateur modifie des fichiers schema.prisma ou demande de vérifier
  les migrations. Ne PAS utiliser pour les requêtes Prisma Client.
---

# Validation des migrations Prisma

## Quand utiliser
- Après modification de `prisma/schema.prisma`
- Avant de committer des changements de schéma
- Quand l'utilisateur demande "vérifie les migrations"

## Workflow
1. Vérifier que `prisma/schema.prisma` est syntaxiquement valide :
   `npx prisma validate`
2. Générer la migration :
   `npx prisma migrate dev --create-only --name auto`
3. Vérifier que la migration SQL générée est cohérente
4. Exécuter `npx prisma generate` pour mettre à jour le client
5. Lancer les tests liés aux modèles modifiés

## Pièges courants
- Ne jamais exécuter `prisma migrate deploy` en dev (c'est pour la prod)
- Si une migration échoue, supprimer le dossier de migration généré
  et corriger le schéma avant de régénérer
EOF

Ajouter des scripts

Pour les workflows déterministes, ajoutez des scripts exécutables dans le répertoire scripts/ :

mkdir -p ~/.codex/skills/prisma-validation/scripts

cat > ~/.codex/skills/prisma-validation/scripts/validate.sh << 'EOF'
#!/bin/bash
set -e
echo "Validating Prisma schema..."
npx prisma validate
echo "Generating migration..."
npx prisma migrate dev --create-only --name auto
echo "Updating Prisma client..."
npx prisma generate
echo "✅ Schema validated and migration created"
EOF

chmod +x ~/.codex/skills/prisma-validation/scripts/validate.sh

Les scripts ajoutés doivent être testés en les exécutant réellement pour vérifier qu’ils fonctionnent et que la sortie correspond aux attentes.

Ajouter de la documentation de référence

Le répertoire references/ contient de la documentation que Codex peut charger dans le contexte quand la skill est active. C’est utile pour de la documentation d’API, des schémas, ou des conventions détaillées trop longues pour le SKILL.md principal :

ma-skill/
├── SKILL.md
└── references/
    ├── api-schema.md         # Schéma d'API à respecter
    └── migration-guide.md    # Guide de migration détaillé

Principes de conception de skills

Le contexte est un bien commun

Les skills partagent la fenêtre de contexte avec tout le reste : le prompt système, l’historique de conversation, les métadonnées des autres skills, et votre requête. Chaque token de votre skill est un token en moins pour le raisonnement de Codex.

La règle d’or de la documentation officielle : « Codex est déjà très intelligent. N’ajoutez que le contexte qu’il ne possède pas déjà. » Challengez chaque paragraphe : « Codex a-t-il vraiment besoin de cette explication ? » et « Ce paragraphe justifie-t-il son coût en tokens ? »

Calibrer le niveau de liberté

La documentation OpenAI propose une métaphore utile : une skill est un chemin. Un pont étroit au-dessus d’un précipice nécessite des garde-fous stricts (peu de liberté). Un champ ouvert permet de nombreuses routes (beaucoup de liberté).

Haute liberté (instructions texte) : quand plusieurs approches sont valides, que les décisions dépendent du contexte, ou que des heuristiques guident l’approche. Exemple : « Choisir la meilleure approche pour refactorer ce module. »

Liberté moyenne (pseudocode ou scripts avec paramètres) : quand un pattern préféré existe mais que de la variation est acceptable. Exemple : « Suivre ce template mais adapter les noms de fichiers au contexte. »

Faible liberté (scripts spécifiques, peu de paramètres) : quand les opérations sont fragiles, que la cohérence est critique, ou qu’une séquence précise doit être respectée. Exemple : « Exécuter exactement ces commandes dans cet ordre. »

Soigner la description

La description dans le frontmatter YAML est le déclencheur principal pour l’invocation implicite. Elle doit :

Expliquer exactement quand la skill doit et ne doit PAS se déclencher. Inclure des exemples de phrases utilisateur typiques qui activent la skill. Définir les limites clairement : « Ne PAS utiliser pour X » est aussi important que « Utiliser pour Y ».

Partager des skills avec l’équipe

Deux approches pour partager des skills :

Via le repo : committez vos skills dans .agents/skills/ ou .codex/skills/ à la racine de votre projet. Tous les membres de l’équipe qui utilisent Codex bénéficieront automatiquement de ces skills quand ils travaillent sur ce repo.

Via la config d’équipe : pour les organisations utilisant les plans ChatGPT Business ou Enterprise, des configurations d’équipe partagées permettent de distribuer des skills à tous les membres sans les versionner dans chaque repo.

Quand vous créez une skill dans l’app Codex, elle est automatiquement disponible partout : dans l’app, la CLI, et l’extension IDE.

Désactiver une skill sans la supprimer

Utilisez le bloc [[skills.config]] dans votre config.toml :

# ~/.codex/config.toml
[[skills.config]]
path = "/chemin/vers/ma-skill/SKILL.md"
enabled = false

Redémarrez Codex après la modification. La skill n’apparaîtra plus dans le sélecteur ni ne sera déclenchée implicitement, mais ses fichiers restent intacts sur le disque.

Pour désactiver toutes les skills système intégrées, utilisez le switch dédié dans la configuration (ajouté dans les mises à jour récentes de Codex).

L’écosystème des skills au-delà de Codex

Le format Agent Skills est devenu un standard de facto. En plus du catalogue officiel OpenAI, des skills sont publiées par des équipes tierces : Vercel (React best practices, Next.js patterns, déploiement), Cloudflare (agents SDK, serveurs MCP), Stripe, Sentry, Expo, Hugging Face, et une communauté grandissante de développeurs individuels.

Le répertoire communautaire awesome-agent-skills recense les skills officielles et communautaires compatibles avec Codex, Claude Code, Antigravity, Cursor, Copilot, et d’autres.

Vercel a lancé skills.sh en janvier 2026, le premier gestionnaire de paquets et annuaire dédié aux skills d’agents. C’est l’équivalent de npm mais pour les skills IA.