Définir des compétences réutilisables (Skills) : packager un ensemble d'instructions

📚 Navigation dans la série : Le chapitre précédent [21 · Sous-agents (Subagents) : paralléliser le travail avec des agents secondaires] présentait la délégation de tâches à des sous-agents dotés de contextes isolés. Ce chapitre propose d'aborder l'organisation sous un autre angle : non pas déléguer une tâche, mais packager une compétence — structurer une suite d'instructions récurrentes sous forme de compétence (Skill) afin que Codex l'utilise automatiquement au moment opportun. Le chapitre suivant [23 · Extensions et modules (Plugins)] présentera comment assembler ces compétences pour les distribuer.

J'ai analysé le dépôt officiel de OpenAI hébergeant les compétences à l'adresse github.com/openai/skills.

La structure d'une compétence (Skill) est minimaliste : elle s'appuie sur un unique fichier SKILL.md. Ce fichier comporte des métadonnées encadrées par deux délimitations horizontales, suivies de consignes décrivant le fonctionnement de la tâche. Ce répertoire minimaliste est qualifié par l'éditeur de « format de rédaction d'un workflow réutilisable » (reusable workflow authoring format). Une fois rédigé, Codex utilise cette compétence de manière autonome sans vous imposer de décrire à chaque fois les étapes du traitement.

Une idée reçue assimile les compétences à de simples alias de commandes slash (comme la commande /review vue au chapitre 12). La réalité est plus subtile. Une commande slash exige une saisie explicite de votre part ; à l'inverse, Codex appelle une compétence de lui-même s'il détecte que votre consigne correspond à la description du service, tout en préservant l'espace de votre contexte.

Ce chapitre présente le rôle d'une compétence (Skill), son mode de chargement partiel (progressive disclosure) pour économiser la mémoire de travail, ses répertoires d'enregistrement, ses modes de déclenchement et sa création.

À la fin de ce chapitre, vous aurez en main :

• La structure d'une compétence (Skill) — associant un fichier SKILL.md à des scripts et ressources optionnels.
• Le principe de « divulgation progressive » (progressive disclosure) — limitant le coût de contexte en ne chargeant les détails de la compétence qu'en cas d'appel.
• Les deux modes de déclenchement (déclenchement explicite par le symbole $ et déclenchement implicite par analyse sémantique).
• Les répertoires de stockage recommandés (.agents/skills au sein du projet et $HOME/.agents/skills pour l'utilisateur).
• L'usage des utilitaires $skill-creator pour l'initialisation et $skill-installer pour l'import de compétences prêtes à l'emploi.

---

01 Qu'est-ce qu'une compétence (Skill) ?

En résumé : une compétence (Skill) est un répertoire structuré contenant un fichier principal SKILL.md et des dossiers optionnels de scripts ou de ressources. Elle sert à encapsuler un savoir-faire spécifique pour le mettre à disposition de Codex.

Dans vos échanges avec Codex, vous répétez fréquemment les mêmes consignes. Lors de la soumission de modifications de code, vous précisez par exemple : « Exécute d'abord les tests, rédige le message de commit en français et préfixe le message par feat: ou fix: ». Répéter ces consignes à chaque message est laborieux. Ces spécifications de traitement doivent être packagées sous forme de compétence.

Analogie : La notice de montage d'un jeu de construction. La notice ne réalise pas le montage à votre place, mais elle détaille l'enchaînement des étapes : « Fixer le châssis, assembler les roues, positionner le toit ». L'enchaînement est standardisé pour chaque montage. Une compétence (Skill) est une notice d'instructions rédigée pour Codex : elle décrit un processus récurrent dans le fichier SKILL.md pour que Codex puisse le reproduire à la demande, sans description préalable.

Le fichier SKILL.md s'articule autour de deux sections :

---
name: nom-competence
description: Description concise du rôle de la compétence pour son déclenchement sémantique.
---

Instructions de traitement à appliquer par Codex.

La section d'en-tête (YAML frontmatter) délimitée par les symboles --- comporte obligatoirement les clés name (l'identifiant utilisé pour appeler la compétence) et description (qui définit le contexte de déclenchement de l'outil). Le corps du document en markdown contient les instructions à dérouler par l'assistant lors de l'appel.

⚠️ Attention aux confusions fréquentes : Certaines documentations non officielles mentionnent l'usage d'une clé trigger dans l'en-tête, et suggèrent de placer les compétences dans ~/.codex/skills/. Ces indications sont erronées. Le schéma de Codex ne gère pas de paramètre trigger (le déclenchement s'appuie sur la clé description) et les fichiers se placent dans .agents/skills (détaillé à la section 04). Suivez les spécifications de la documentation officielle pour éviter les erreurs d'exécution.

Une compétence s'organise sous la forme d'un répertoire pouvant contenir les éléments suivants :

ma-competence/
├── SKILL.md          # Fichier de consignes principal (requis, avec name et description)
├── scripts/          # Dossier optionnel : scripts exécutables (pour des actions déterministes)
└── references/       # Dossier optionnel : documentations de référence consultables par Codex

Seul le fichier SKILL.md est obligatoire. La documentation officielle conseille de privilégier les instructions textuelles aux scripts de code, sauf si l'action exige un enchaînement déterministe strict ou le pilotage d'un exécutable externe. Les instructions en langage naturel offrent plus de flexibilité pour guider Codex.

Exemples d'usage des compétences :

• Validation de commit (commit) : Lancement des tests locaux, formatage du message selon des normes d'équipe et application de préfixes.
• Normes d'écriture d'API (api-conventions) : Validation de la structure des endpoints, typage des retours d'erreurs et contrôles de sécurité.
• Audit avant mise en production (release-check) : Liste de contrôles de configuration, génération du fichier changelog et création de tags git.

💡 En résumé : Une compétence est un répertoire regroupant un fichier de consignes SKILL.md et des ressources optionnelles. Elle permet de packager vos workflows récurrents afin d'éviter la saisie répétitive de consignes.

---

02 Préservation du contexte : Le chargement partiel

L'intérêt de la structure de compétence réside dans sa gestion de la mémoire. Pourquoi est-il possible d'enregistrer des dizaines de compétences sans saturer la fenêtre de contexte de l'assistant ? Cela s'appuie sur le principe de divulgation progressive (progressive disclosure) : les données ne sont chargées qu'en cas de besoin.

Rappelons que la mémoire de travail (le contexte) d'un modèle d'IA est limitée et facturée à la consommation. Si Codex devait lire l'intégralité des instructions de toutes vos compétences dès le démarrage d'une session, l'espace disponible pour votre code serait réduit.

Analogie : L'affichage des étiquettes de plats dans un buffet. Dans un restaurant, chaque plat dispose d'une étiquette descriptive simple : « Ragoût de bœuf - épicé ». Vous identifiez les choix sans avoir à lire les recettes détaillées de chaque plat. La recette complète (les étapes de préparation) reste confinée en cuisine. Une compétence suit cette logique, que la documentation officielle décrit en deux étapes :

Au lancement de la session, Codex charge uniquement l'identifiant (name), la description (description) et le chemin d'accès de chaque compétence. Les instructions complètes du fichier SKILL.md ne sont lues que si l'assistant décide d'activer la compétence.

Le chargement s'effectue ainsi :

• Mode passif : Codex intègre uniquement une liste simplifiée (identifiants, descriptions et chemins d'accès).
• Activation : Si Codex identifie qu'une tâche fait appel à une compétence, il charge le contenu textuel complet du fichier SKILL.md associé.

Cette particularité vous permet de rédiger des notices d'instructions détaillées sans craindre d'encombrer le contexte lors des tâches courantes.

Ce schéma illustre la divulgation progressive : lors de la phase 1 (lancement), Codex ne conserve en mémoire que l'en-tête (identifiant, description, chemin) de chaque compétence. Lors de la phase 2 (exécution d'une tâche), seul le contenu complet du fichier SKILL.md de la compétence sollicitée est lu et injecté dans le contexte, préservant l'espace mémoire pour les autres outils.

Notez toutefois que la liste simplifiée de démarrage fait l'objet d'une limite de taille pour préserver le contexte initial :

Afin de ne pas saturer l'espace de l'invite de démarrage, la liste simplifiée des compétences est limitée à environ 2% de la fenêtre de contexte totale, ou à 8 000 caractères si la taille de la fenêtre n'est pas définie. Si le volume dépasse ce seuil, Codex raccourcit les descriptions ; pour les volumes très importants, certaines compétences peuvent être exclues de la liste avec un message d'alerte.

Conséquence pratique importante : rédigez des descriptions courtes et placez les mots-clés de déclenchement au début de la description. Si une description doit être tronquée par le système, les termes clés indispensables à l'association resteront lisibles pour l'algorithme.

💡 En résumé : Le mécanisme de divulgation progressive préserve le contexte en ne chargeant les instructions complètes du fichier SKILL.md qu'en cas d'activation de la compétence. Rédigez des descriptions concises avec les mots-clés de déclenchement au début.

---

03 Les modes de déclenchement : Appel explicite ou automatique

Une compétence s'active selon deux méthodes distinctes. Le choix dépend de votre volonté de contrôler le déclenchement.

Analogie : Passer commande dans un service de livraison. Vous pouvez cibler un restaurant précis en saisissant son nom dans la recherche (appel explicite). Vous pouvez également décrire votre envie au moteur de recherche (« plat épicé avec riz ») pour que le système vous propose la fiche correspondante (déclenchement sémantique).

Appel explicite par le symbole $

Cette méthode vous permet de forcer l'usage d'une compétence précise. Saisissez le symbole $ suivi du nom de la compétence dans votre message (ou utilisez la commande slash /skills pour afficher la liste de sélection) :

$commit

Le symbole $ ouvre un menu contextuel des compétences disponibles. Lors d'un appel explicite, Codex ne réalise pas d'évaluation sémantique : il charge immédiatement le fichier SKILL.md demandé et applique ses instructions.

⚠️ Note de syntaxe : Certaines anciennes notices utilisaient le symbole @ pour l'appel explicite de compétences. La syntaxe officielle de Codex est le symbole $ (associé à la commande /skills).

Déclenchement automatique par analyse sémantique

Cette approche repose sur l'analyse sémantique de vos consignes par Codex. Si votre demande correspond aux critères décrits dans la clé description d'une compétence, Codex l'active de lui-même sans que vous ayez à la nommer.

Ce mode offre une intégration transparente, mais exige une rédaction soignée de la description de la compétence. La documentation officielle précise :

Le déclenchement sémantique s'appuyant sur la description, veillez à rédiger des descriptions concises, précises et délimitées. Décrivez les cas d'usage types et placez les termes déclencheurs en début de texte.

Évitez les descriptions trop larges comme « Aide pour le code du projet », qui risquent de déclencher la compétence sur des tâches non concernées. Privilégiez des descriptions explicites : « Génère le message de commit suite aux modifications. À utiliser lors des demandes de validation, de création de commit ou d'affichage de diff ». Décrire les formulations types que vous utiliserez dans vos invites fiabilise le déclenchement.

Comparatif des deux modes :

Critère	Appel explicite ($ / /skills)	Déclenchement automatique (Sémantique)
Méthode	Saisie de $ suivi du nom ou sélection dans /skills	Saisie d'une demande classique analysée sémantiquement
Évaluation de pertinence	Aucune (chargement immédiat)	Analyse de correspondance avec la description
Fiabilité	Déterministe (toujours actif)	Dépendante de la qualité de la description
Usage recommandé	Contrôle précis des étapes d'exécution	Automatisation transparente des processus courants
Possibilité de désactivation	Toujours disponible	Modifiable via allow_implicit_invocation (voir section 05)

💡 En résumé : L'appel explicite s'effectue avec le symbole $ ou via la commande /skills. Le déclenchement automatique s'appuie sur la correspondance sémantique avec la clé description de la compétence.

---

04 Répertoires de stockage et portée des compétences

L'emplacement de stockage du répertoire de la compétence détermine son périmètre d'action. Codex recherche les compétences dans quatre niveaux de répertoires. Au niveau du projet, il parcourt le chemin depuis votre répertoire de travail actuel jusqu'à la racine du dépôt Git, et charge les dossiers .agents/skills découverts.

Voici la structure de recherche des répertoires :

Niveau	Chemin de stockage	Portée d'accès
Projet local	$CWD/.agents/skills	Répertoire courant uniquement (spécifique à un module ou micro-service)
Projet parent	$CWD/../.agents/skills	Dossiers parents du projet actuel
Dépôt Git	$REPO_ROOT/.agents/skills	Ensemble du dépôt de code (compétences partagées pour l'équipe)
Utilisateur	$HOME/.agents/skills	Session de l'utilisateur sur tous ses projets locaux
Système partagé	/etc/codex/skills	Partagé pour tous les utilisateurs de la machine ou du conteneur
Intégré	Géré par Codex	Compétences natives fournies par l'application

⚠️ Emplacement à respecter : Les compétences doivent être enregistrées dans .agents/skills (niveau projet) ou $HOME/.agents/skills (niveau utilisateur). N'enregistrez pas vos compétences dans ~/.codex/skills/. Le dossier ~/.codex/ est réservé aux fichiers de configuration de l'application (comme config.toml) ; Codex n'y recherche pas de compétences et les répertoires placés à cet endroit ne seront pas détectés.

Choix de l'emplacement :

• Compétences personnelles globales (ex: vos règles de commit personnelles) : Enregistrez-les dans le dossier utilisateur $HOME/.agents/skills.
• Compétences spécifiques à l'équipe (ex: règles de formatage du dépôt de l'entreprise) : Enregistrez-les dans le dossier .agents/skills à la racine de votre projet et intégrez-les au suivi de version Git pour en faire bénéficier vos collaborateurs.

En cas de doublon de nom (name) entre deux compétences de niveaux différents, Codex ne les fusionne pas et liste les deux versions dans son sélecteur. Pour éviter toute confusion de choix, utilisez des noms distincts selon les périmètres.

Toute modification apportée au fichier SKILL.md est généralement détectée en temps réel. Si la mise à jour ne s'applique pas, fermez et relancez votre session Codex.

💡 En résumé : Les compétences se placent dans .agents/skills (projet) ou $HOME/.agents/skills (utilisateur). Les doublons de noms sont conservés en parallèle sans fusion, ce qui impose d'utiliser des noms distincts.

---

05 Outils d'administration : Création, import et désactivation

Cette section présente la manipulation pratique des compétences via les utilitaires de Codex.

Initialisation avec $skill-creator

La documentation officielle conseille d'utiliser l'utilitaire intégré pour créer une compétence, plutôt que de l'écrire manuellement :

$skill-creator

Cet outil interactif vous interroge sur trois aspects : le but de la compétence, ses critères de déclenchement, et la nécessité d'y associer des scripts de code (le mode instructions textuelles restant recommandé par défaut). Il génère ensuite l'architecture de dossiers et le squelette du fichier SKILL.md dans vos répertoires.

Vous pouvez également créer le dossier manuellement en respectant l'en-tête YAML et la structure décrits à la section 01.

Import avec $skill-installer

Pour exploiter des compétences développées par la communauté ou des éditeurs tiers, utilisez l'installateur :

$skill-installer linear

Cet outil télécharge et installe la compétence dans vos répertoires. Il supporte également l'import depuis des dépôts Git externes.

Note de distribution : L'utilitaire $skill-installer est destiné aux tests et à un usage individuel en local. Pour packager et distribuer des compétences à grande échelle au sein d'une équipe ou d'un produit, utilisez la structure de Plugins présentée au chapitre 23. La compétence (Skill) est le format de conception de la tâche ; l'extension (Plugin) en est le format de distribution.

Désactivation de compétences

Pour masquer une compétence (système ou importée) sans supprimer ses fichiers, vous pouvez la déclarer désactivée dans votre configuration utilisateur ~/.codex/config.toml (bloc [[skills.config]]) :

# Fichier : ~/.codex/config.toml
[[skills.config]]
path = "/chemin/vers/la/competence/SKILL.md"
enabled = false

Renseignez le chemin absolu du fichier SKILL.md concerné et positionnez enabled = false. Relancez votre session Codex pour appliquer la désactivation. Cette méthode permet de désactiver les compétences secondaires afin de préserver l'espace de votre liste simplifiée.

Paramétrage avancé (agents/openai.yaml)

Pour affiner le comportement d'une compétence (comme déclarer des dépendances d'outils ou masquer le déclenchement automatique), vous pouvez ajouter un fichier agents/openai.yaml dans le dossier de la compétence. Le paramètre suivant permet de restreindre l'usage à l'appel explicite :

# Fichier : <dossier_competence>/agents/openai.yaml
policy:
  allow_implicit_invocation: false

Positionner allow_implicit_invocation sur false désactive le déclenchement automatique sémantique. La compétence ne sera alors chargée que si vous la nommez explicitement avec le symbole $ (sécurité recommandée pour les opérations sensibles comme les déploiements).

Voici un récapitulatif des outils et de leurs fichiers associés :

Objectif	Commande / Paramètre	Emplacement cible
Initialiser une compétence	$skill-creator	Console de session
Installer une compétence tierce	$skill-installer <nom>	Console de session
Désactiver temporairement	enabled = false	~/.codex/config.toml
Bloquer l'activation automatique	allow_implicit_invocation: false	<dossier_competence>/agents/openai.yaml
Écrire vos compétences	Fichiers markdown SKILL.md	.agents/skills/ ou $HOME/.agents/skills/

💡 En résumé : L'utilitaire $skill-creator initialise les fichiers, et $skill-installer gère l'import de ressources existantes. La désactivation s'effectue dans le fichier de configuration config.toml, et le blocage du déclenchement s'écrit dans agents/openai.yaml sous la clé allow_implicit_invocation: false.

---

06 En pratique : Concevoir et tester une compétence de synthèse

Voici un exercice pour créer une compétence utilisateur, vérifier sa prise en compte sémantique et la tester avec un déclenchement automatique et explicite.

Note de compatibilité : Les commandes de création de dossiers s'appliquent sur macOS/Linux ou dans Git Bash sous Windows. Le répertoire de l'utilisateur correspond à ~ (sur Windows, généralement C:\Users\VotreNom).

Étape 1 : Créer le répertoire utilisateur

Créez le répertoire utilisateur de stockage des compétences s'il n'existe pas :

mkdir -p ~/.agents/skills/explain-self

Étape 2 : Rédiger le fichier SKILL.md

Créez le fichier ~/.agents/skills/explain-self/SKILL.md et renseignez les consignes suivantes :

---
name: explain-self
description: Explique en langage simple le rôle d'un bloc de code ou la cause d'un message d'erreur. À utiliser lorsque l'utilisateur demande « que fait ce code », « explique cette erreur » ou « décris ce script ».
---

Explique le code ou l'erreur transmis par l'utilisateur en utilisant des termes simples et accessibles pour un débutant :

1. Résume le rôle global de l'élément (en une phrase).
2. Détaille le fonctionnement ligne par ligne ou bloc par bloc.
3. Pour les erreurs, identifie la cause principale et propose une correction type.

Évite le jargon technique complexe et privilégie des analogies simples si possible.

La clé description contient des expressions types que vous pourriez utiliser lors de vos requêtes.

Étape 3 : Valider la détection de la compétence

Ouvrez une session Codex dans votre console :

codex

Affichez la liste des compétences actives :

/skills

Comportement attendu : Le nom explain-self s'affiche dans la liste des compétences détectées avec la description associée. La compétence est reconnue.

Étape 4 : Tester le déclenchement automatique

Saisissez une consigne de code sans appeler explicitement la compétence par son nom :

Que fait ce code : print(sum([1,2,3]) / len([1,2,3]))

Comportement attendu : Codex analyse s'il existe une compétence pertinente. Il détecte la correspondance avec explain-self d'après votre demande. Il charge les instructions de la compétence et structure sa réponse d'après vos consignes (explication simple, rôle global de calcul de moyenne, détails et résultat final 2.0).

Étape 5 : Tester l'appel explicite

Appelez la compétence de manière déterministe avec le symbole $ :

$explain-self explique cette erreur : ZeroDivisionError: division by zero

Comportement attendu : Codex active directement la compétence sans chercher d'association sémantique. Il suit les consignes de traitement pour expliquer la cause de la division par zéro.

Cet exercice confirme le fonctionnement de l'intégration des compétences. Vous pouvez retirer ce dossier de test ou le désactiver si souhaité.

💡 En résumé : L'exercice montre la détection d'une compétence utilisateur dans ~/.agents/skills/, son appel par analyse sémantique (invites naturelles) et son déclenchement forcé via la syntaxe $nom.

---

07 Résumé

Ce chapitre a présenté le packaging d'instructions réutilisables sous la forme de compétences (Skills) dans Codex.

Voici les points clés à retenir :

Thématique	Règle de fonctionnement
Utilité	Encapsule des consignes de traitement récurrentes pour éviter leur saisie répétée.
Contexte	Utilise la divulgation progressive pour ne charger le fichier SKILL.md qu'en cas d'appel.
Déclenchement	Explicite via le symbole $ (ou /skills) ou automatique par association sémantique avec la clé description.
Stockage	Placé dans .agents/skills/ (projet local) ou $HOME/.agents/skills/ (utilisateur global).
Outils	Utilitaires $skill-creator pour l'initialisation et $skill-installer pour l'import de packages existants.
Désactivation	Déclarable via la clé enabled = false dans config.toml ou en configurant allow_implicit_invocation dans openai.yaml.

Vous êtes désormais en mesure de comprendre la structure et l'intérêt d'une compétence, d'exploiter le mécanisme de divulgation progressive pour préserver votre contexte, de choisir le mode de déclenchement explicite ou automatique adapté à votre flux de travail, d'organiser la portée des compétences dans les répertoires correspondants, et de créer ou d'installer des compétences avec les utilitaires d'administration.

---

Le chapitre suivant 23 · Extensions et modules (Plugins) présente le packaging à grande échelle : comment regroupe-t-il des compétences, des sous-agents et des fichiers de configuration au sein d'une extension (Plugin) diffusable à vos équipes ou à la communauté ? Comment installer et administrer ces modules ? Nous verrons comment structurer l'intégration de services tiers.

---

Lectures recommandées

• Workflows de développement : exploration et tests
• Extensions d'éditeurs de code (IDE)
• Extensions et modules (Plugins) dans Codex