Système de compétences Agent Skills de Codex
Les Agent Skills sont le mécanisme d'extension des tâches de Codex. En empaquetant des instructions, des ressources et des scripts optionnels dans des paquets de compétences standardisés, ils permettent à Codex d'exécuter de manière fiable des flux de travail spécifiques.
Un Agent Skill est essentiellement un dossier qui doit contenir un fichierSKILL.md. Le fichier doit au minimum fournir des métadonnées telles que le nom et la description, ainsi que des indications expliquant à l'agent IA comment accomplir une tâche spécifique. Les paquets de compétences peuvent également intégrer des scripts, des documents de référence, des modèles et diverses autres ressources.
my-skill/ ├── SKILL.md # 必备文件：元数据 + 执行指引 ├── scripts/ # 可选：可执行脚本 ├── references/ # 可选：参考文档 ├── assets/ # 可选：模板、各类资源文件 └── ... # 其他额外文件与目录
Terminologie
- Agents IA: agent intelligent IA (traduction couramment utilisée dans le secteur)
- Agent Skills: Agent Skill (concept propriétaire, conserver la désignation fixe)
- métadonnées: métadonnées
- flux de travail: processus métier/flux d'exécution
Que sont les Agent Skills ?
Les compétences sont un format de création pour des flux de travail réutilisables.
Chaque compétence est essentiellement un répertoire contenant un fichierSKILL.md. Codex lit les instructions qui s'y trouvent et les exécute étape par étape.
Vous pouvez considérer une Skill comme une « procédure d'exploitation standard » écrite pour Codex—définissant clairement quoi faire, quand le faire et comment le faire. Codex peut alors l'activer automatiquement au bon moment, ou l'exécuter lorsque vous l'invoquez explicitement.
Les Skills sont un « format de création », tandis que les Plugins sont un « format de distribution ». Utilisez d'abord les Skills pour concevoir le workflow lui-même ; empaquetez-le en tant que Plugin lorsque vous devez le distribuer à d'autres développeurs.
Les Skills sont disponibles dans la CLI Codex, l'extension IDE et l'application Codex.
Vous pouvez afficher ou créer des Skills dans le plugin :
Codex est livré avec unSkill Creatorintégré, cliquez surCréer une Skillpour accéder à la fenêtre de création de Skill, où nous pouvons lui indiquer directement quelle Skill créer :
Afficher les Skills installées :
Fonctionnement des compétences
Codex utilise un mécanisme dedivulgation progressivepour gérer la fenêtre de contexte, en évitant de charger tout le contenu des Skills en une seule fois et de saturer l'espace de prompt.
Processus de chargement progressif
Au démarrage, Codex ne charge que le nom, la description et le chemin de fichier de chaque Skill comme liste initiale.
Ce n'est que lorsque Codex décide d'utiliser une Skill qu'il charge le contenu complet des instructions deSKILL.md.
Pour éviter de saturer l'espace de prompt, le nombre de caractères de la liste initiale des Skills est limité àenviron 2% de la fenêtre de contexte du modèle, ou 8,000 caractères lorsque la fenêtre de contexte est inconnue.
Si trop de Skills sont installées, Codex raccourcit d'abord les descriptions ; si la limite est encore dépassée, certaines Skills peuvent ne pas apparaître dans la liste initiale, et Codex affiche un avertissement.
Cette restriction de budget s'applique uniquement à la liste initiale des compétences. Après que Codex a sélectionné une compétence, il continue de lire le fichier SKILL.md complet pour cette compétence.
Deux méthodes de déclenchement
Codex prend en charge deux façons d'activer des compétences :
Invocation explicite
Référencez directement la compétence dans le prompt. Dans le CLI ou l'IDE, utilisez/skillscomme commande ou saisissez$un symbole pour spécifier une compétence.
Pour une invocation explicite, Codex n'a pas besoin d'effectuer de jugement de correspondance ; il charge directement le fichier SKILL.md complet et l'exécute.
Correspondance implicite
Lorsque la description de tâche que vous fournissez correspond au champdescriptiond'une compétence, Codex sélectionne automatiquement cette compétence.
La précision de la correspondance implicite dépend entièrement de la qualité du champ description.
Lorsque vous rédigez la description, placez les cas d'utilisation principaux et les mots-clés de déclenchement au début, afin que même si la description est tronquée, Codex puisse encore établir une correspondance correcte.
Structure du répertoire de compétences
Une compétence est un répertoire contenant des fichiersSKILL.md, et peut inclure en option des scripts, une documentation de référence, des fichiers de ressources et une configuration de métadonnées.
my-skill/
├── SKILL.md # 必备项：使用指引 + 元数据
├── scripts/ # 可选：可执行代码
├── references/ # 可选：参考文档
├── assets/ # 可选：模板、各类资源
└── agents/
└── openai.yaml
Les responsabilités de chaque fichier/répertoire sont les suivantes :
| Fichier/Répertoire | Obligatoire ? | Description |
|---|---|---|
| SKILL.md | Requis | Le fichier d'instructions principal de la compétence ; doit contenir les champsnameetdescriptionfield |
| scripts/ | Optional | Stocke du code exécutable, utilisé pour les scénarios nécessitant un comportement déterministe ou l'appel d'outils externes |
| references/ | Optional | Stocke de la documentation de référence supplémentaire que Codex peut consulter lors de l'exécution de la compétence |
| assets/ | Optional | Stocke des fichiers de ressources statiques tels que des modèles et des images |
| agents/openai.yaml | Optional | Configure les métadonnées d'interface utilisateur, la politique d'invocation et les déclarations de dépendances d'outils |
Démarrage rapide : Créez votre première compétence
Il est recommandé d'utiliser le créateur de compétences intégré pour générer rapidement un cadre de compétence.
Créer avec skill-creator
Saisissez la commande suivante dans Codex pour lancer le flux de création interactif :
Exemple
$skill-creator
Le créateur posera les questions suivantes dans l'ordre :
| Étape | Question | Description |
|---|---|---|
| 1 | Que fait cette compétence ? | Définissez la tâche que la compétence est censée accomplir |
| 2 | Quand doit-elle se déclencher ? | Déterminez si elle est déclenchée par une invocation explicite ou une correspondance implicite |
| 3 | Instructions pures ou inclut des scripts ? | Le mode d'instruction pure est recommandé par défaut, car il est concis et facile à maintenir |
Création manuelle
Vous pouvez également créer manuellement le répertoire de compétences et le fichier SKILL.md :
Exemple
name: my-skill
description: Expliquez quand cette compétence doit être déclenchée et quand elle ne doit pas l'être.
---
Codex exécutera la tâche en suivant les instructions de compétence ci-dessous.
Codex détecte automatiquement les modifications des fichiers de compétences. Si une compétence ne prend pas effet immédiatement après une mise à jour, veuillez redémarrer Codex.
Instructions de configuration
Emplacement de stockage des compétences
Codex lit les compétences à partir de quatre portées : niveau du dépôt, niveau utilisateur, niveau administrateur et niveau système.
Pour le niveau du dépôt, Codex parcourt vers le haut depuis le répertoire de travail actuel jusqu'à la racine du dépôt, à la recherche du répertoire.agents/skills.
Si deux compétences ont le mêmename, Codex ne les fusionne pas ; les deux apparaîtront dans le sélecteur de compétences.
| Portée | Chemin de stockage | Scénario d'application |
|---|---|---|
| REPO | $CWD/.agents/skills | Compétences dans le répertoire de travail actuel, adaptées aux compétences partagées par l’équipe pour un module ou un microservice spécifique |
| REPO | $CWD/../.agents/skills | Compétences dans les répertoires parents, adaptées aux zones partagées dans des structures de répertoires imbriquées |
| REPO | $REPO_ROOT/.agents/skills | Compétences à la racine du dépôt, adaptées aux compétences de base partagées entre tous les sous-répertoires de l’ensemble du dépôt |
| USER | $HOME/.agents/skills | Ensemble de compétences personnel d’un utilisateur, adapté aux compétences que l’utilisateur peut utiliser dans n’importe quel dépôt |
| ADMIN | /etc/codex/skills | Compétences partagées au niveau de la machine ou du conteneur, adaptées aux scripts SDK, à l’automatisation et aux compétences par défaut de l’administrateur |
| SYSTÈME | Packagé par OpenAI par défaut | Compétences intégrées pour un large public, telles que skill-creator et les compétences de planification, disponibles pour tous les utilisateurs dès qu'ils démarrent Codex |
Codex prend en charge les liens symboliques pour les répertoires de compétences et suit la cible du lien symbolique lors de l'analyse.
Le chemin ci-dessus s'applique au développement local et à la découverte. Si vous devez distribuer des compétences à des utilisateurs en dehors d'un seul dépôt, ou les empaqueter avec l'intégration applicative, utilisez le mécanisme Plugins.
Activation et désactivation des compétences
Dans~/.codex/config.toml, vous pouvez désactiver une compétence sans la supprimer en utilisant l'option[[skills.config]]de configuration :
Exemple
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false
Après avoir modifié le fichier de configuration, vous devez redémarrer Codex pour que les modifications prennent effet.
Configuration facultative des métadonnées
Dansagents/openai.yamlVous pouvez configurer les métadonnées d'interface, les politiques d'invocation et les déclarations de dépendances d'outils pour les compétences dans :
Exemple
# Configuration de l'interface : contrôle la façon dont la compétence est affichée dans l'application Codex
interface:
display_name: "Nom d'affichage destiné aux utilisateurs"
short_description: "Description courte destinée aux utilisateurs"
icon_small: "./assets/small-logo.svg"
icon_large: "./assets/large-logo.png"
brand_color: "#3B82F6"
default_prompt: "Prompt périphérique facultatif à utiliser avec la compétence"
# Configuration de la politique : contrôle le comportement d'invocation de la compétence
policy:
allow_implicit_invocation: false # Définir sur false pour désactiver la correspondance implicite
# Configuration des dépendances : déclare les outils requis par la compétence
dependencies:
tools:
- type: "mcp"
value: "openaiDeveloperDocs" # Nom du serveur MCP
description: "Serveur MCP OpenAI Docs"
transport: "streamable_http" # Protocole de transport
url: "https://developers.openai.com/mcp" # Adresse du service MCP
allow_implicit_invocationLa valeur par défaut detrueest. Lorsqu'elle est définie surfalse, Codex n'invoquera pas implicitement la compétence en fonction des invites de l'utilisateur, mais l'invocation explicite$skillfonctionne toujours.
| Élément de configuration | Type | Valeur par défaut | Description |
|---|---|---|---|
| interface.display_name | String | Vide | Le nom affiché dans l'application Codex |
| interface.short_description | String | Vide | La description courte affichée dans l'application Codex |
| interface.icon_small | Chemin | Vide | Chemin de la petite icône (format SVG) |
| interface.icon_large | Chemin | Vide | Chemin de la grande icône (format PNG) |
| interface.brand_color | Valeur de couleur | Vide | Couleur de marque utilisée pour l'affichage de l'interface utilisateur |
| interface.default_prompt | String | Vide | Le prompt périphérique par défaut utilisé lorsque cette compétence est utilisée |
| policy.allow_implicit_invocation | Boolean | vrai | Indique si Codex est autorisé à faire correspondre et à invoquer implicitement la compétence |
| dependencies.tools | Tableau | Vide | Déclare les outils MCP dont dépend la compétence ; chaque élément doit spécifier le type, la valeur, la description, etc. |
Distribution et installation des compétences
Distribution des compétences via des Plugins
Un dossier de compétence direct convient à la création locale et aux flux de travail limités au dépôt.
Si vous avez besoin de distribuer des compétences réutilisables, de regrouper plusieurs compétences ou de publier des compétences avec l’intégration applicative, vous devriez les empaqueter sous forme dePlugin。
Un Plugin peut contenir une ou plusieurs compétences et peut éventuellement regrouper des mappages applicatifs, des configurations de serveur MCP et des ressources de présentation.
Installation des compétences en vedette
Vous pouvez utiliser$skill-installerpour installer des compétences sélectionnées au-delà de celles intégrées dans l’environnement Codex local.
Par exemple, installez la compétence$linear:
Exemple
$skill-installer linear
Vous pouvez également télécharger des compétences depuis d'autres dépôts via skill-installer.
Codex détecte automatiquement les compétences nouvellement installées. Si elles n'apparaissent pas immédiatement, redémarrez Codex.
skill-installer convient pour une configuration locale et l'expérimentation. Pour distribuer vos propres compétences en vue de leur réutilisation, préférez le mécanisme Plugins.
Bonnes pratiques
| Principe | Description | Scénario d'application |
|---|---|---|
| Une compétence fait une seule chose | Gardez chaque compétence concentrée sur une seule responsabilité; évitez de charger une compétence avec trop de tâches sans rapport. | Toutes les compétences doivent suivre |
| Des instructions plutôt que des scripts | Si un processus peut être décrit avec des instructions, n'écrivez pas de script à moins qu'un comportement déterministe ou l'invocation d'un outil externe ne soit requis. | Le mode instruction pure est recommandé pour la plupart des scénarios |
| Utilisez des phrases à l'impératif | Rédigez les étapes avec des phrases à l'impératif, en indiquant clairement l'entrée et la sortie de chaque étape | Lors de la rédaction des instructions de SKILL.md |
| Testez l'efficacité de la correspondance de la description | Utilisez de vrais prompts pour tester si la compétence se déclenche correctement, en garantissant la précision de la description | Après avoir rédigé la compétence |
| Mots déclencheurs essentiels prérequis | Placez les cas d'utilisation clés et les mots déclencheurs au début de la description pour garantir la correspondance même après troncature. | Lorsque la description peut être tronquée |
Questions fréquentes
Les mises à jour de compétence ne prennent pas effet?
Codex détecte automatiquement les modifications des fichiers de compétence.
Si la compétence n'apparaît pas dans la liste après la mise à jour, redémarrez Codex.
Que se passe-t-il si deux skills ont le même nom ?
Codex ne fusionne pas les skills portant le même nom ; les deux apparaîtront dans le sélecteur de skills.
Il est recommandé d'éviter d'utiliser le même nom de skill dans des portées différentes afin d'éviter toute confusion.
Que faire si la correspondance implicite est imprécise ?
Vérifiez d'abord ladescriptionpour savoir si les scénarios d'utilisation et les limites du skill sont clairement décrits.
Placez les mots déclencheurs principaux au début et évitez que des informations clés apparaissent dans la seconde moitié de la description.
Si la correspondance implicite n'est pas nécessaire, vous pouvez, dans le fichieragents/openai.yaml, définirallow_implicit_invocationsurfalse。
Quand utiliser les Skills et quand utiliser les Plugins ?
Skills est un format de création, adapté au développement local et au partage en équipe au sein d'un dépôt.
Lorsque vous devez distribuer des skills à d'autres développeurs, empaqueter plusieurs skills ou les publier avec une intégration applicative, utilisez le format Plugins.
Comment gérer une liste initiale de skills tronquée ?
Simplifiez la description de chaque skill pour la rendre courte et précise.
Assurez-vous que les mots déclencheurs principaux apparaissent au tout début de la description, afin que la correspondance fonctionne correctement même lorsqu'elle est raccourcie.
Pour les compétences qui ne sont pas couramment utilisées pour la tâche en cours, envisagez de les désactiver temporairement.
Autres extensions