Créateur de Compétences
Créez des compétences qui donnent à Codex des conseils utiles et non évidents sans contraindre le travail non lié.
Principes Fondamentaux
Supposer que Codex est déjà capable. N'incluez que les informations qui modifient ses décisions ou améliorent son travail. Supprimez les conseils génériques, les instructions répétées, les cas limites spéculatifs et les exemples qui ne clarifient pas matériellement la tâche.
Préserver l'intention et le périmètre de l'utilisateur. Une compétence doit soutenir la tâche demandée, sans remplacer le produit choisi par l'utilisateur, élargir la mission, modifier une configuration non liée, ou impliquer une autorisation pour des actions externes supplémentaires. Ne transformez pas un exemple particulier, un échec passé ou une préférence personnelle en exigence universelle.
L'approbation pour accomplir une tâche n'élargit pas son périmètre ni ses permissions d'exécution. Pour les workflows de nouvelle tentative ou de mutation externe, définissez une condition d'arrêt proportionnelle au risque.
Adapter la spécificité au risque. Laissez au modèle la liberté de choisir une approche appropriée lorsque plusieurs approches sont raisonnables. Utilisez des étapes détaillées, des scripts déterministes ou un langage absolu uniquement lorsque l'exactitude, la sécurité, les permissions ou un workflow véritablement fragile l'exigent.
Pour un travail ouvert, décrivez le résultat et les critères de décision pertinents. Pour les workflows dont la forme est préférable, proposez des exemples utiles ou des scripts configurables. Réservez les séquences fixes et les paramètres étroits pour les opérations où un écart poserait un problème concret. Préservez les invariants opérationnels non évidents, distinguez les exigences réelles des recommandations facultatives ou des conventions locales, et évitez de reformuler des politiques déjà appliquées ailleurs.
Garder la découverte peu coûteuse et précise. Les noms et descriptions des compétences sont disponibles avant qu'une compétence ne soit chargée. Décrivez la capacité réelle et quand elle s'applique, en ajoutant des exclusions uniquement lorsqu'elles empêchent un mauvais routage probable. Évitez les listes exhaustives de capacités et les attrape-tout qui attirent des demandes non liées.
Gardez les compétences autonomes ; faites référence à une autre compétence ou outil uniquement lorsque le workflow demandé l'exige réellement et qu'il est disponible dans l'environnement cible. Les workflows spécialisés de révision, de renforcement ou d'audit ne doivent s'appliquer que lorsqu'ils sont demandés ou réellement nécessaires, et pas simplement parce qu'un travail ordinaire touche au même sujet.
Divulguer les détails progressivement. Gardez l'objectif commun, les contraintes essentielles et le routage utile dans SKILL.md. Placez les conseils substantiels spécifiques au mode, les schémas, les exemples ou les procédures dans des références de support et ne lisez que les références pertinentes pour la tâche en cours. Une compétence simple et autonome n'a pas besoin d'un routeur ou de fichiers supplémentaires.
Anatomie d'une Compétence
Chaque compétence est un dossier contenant un fichier SKILL.md obligatoire et toutes les ressources optionnelles dont son workflow réel a besoin :
skill-name/
|-- SKILL.md Instructions de compétence obligatoires
| |-- frontmatter YAML Nom et description obligatoires
| `-- corps Markdown Instructions chargées lors de l'utilisation de la compétence
|-- agents/ Métadonnées UI et politique d'invocation facultatives
| `-- openai.yaml
|-- scripts/ Aides exécutables facultatives
|-- references/ Documentation facultative chargée selon les besoins
`-- assets/ Fichiers facultatifs utilisés dans la sortie générée
Choisissez la structure qui correspond à la tâche réelle. Certaines compétences sont courtes et autonomes ; d'autres acheminent entre les modes de fonctionnement ou délèguent des mécanismes complexes à des scripts. Évitez de créer des répertoires, des espaces réservés, des exemples ou une documentation auxiliaire sans usage clair.
SKILL.md
Le frontmatter YAML identifie la compétence et détermine quand elle doit être considérée. Incluez les champs name et description obligatoires, et préservez les champs facultatifs supportés comme metadata existants lorsqu'ils sont appropriés.
Le corps Markdown n'est chargé que lorsque la compétence est utilisée. Mettez-y l'objectif, le workflow essentiel, les contraintes réelles et les liens utiles. Gardez les procédures détaillées et les exemples dans les références de support lorsqu'ils ne sont pertinents que pour des modes particuliers.
Les informations sur la compétence sont divulguées en trois étapes :
- Nom et description : Disponibles lors de la sélection de la compétence, gardez-les donc concis et discriminants.
- Corps de SKILL.md : Chargé lorsque la compétence s'applique, gardez donc ses instructions pertinentes pour cette tâche.
- Ressources de support : Lues ou exécutées uniquement lorsque la tâche en cours en a réellement besoin.
Le point d'entrée doit être aussi court que la tâche le permet tout en conservant les contraintes importantes. Une grande limite supérieure n'est pas un objectif : déplacez les détails conditionnels dans les références lorsque cela améliore la clarté ou l'utilisation du contexte, plutôt que d'attendre que le fichier devienne difficile à gérer.
Scripts
Utilisez scripts/ pour le code exécutable lorsque la même logique serait autrement réécrite de manière répétée ou que l'exécution déterministe améliore matériellement la fiabilité.
- Exemple :
scripts/rotate_pdf.pypour une opération PDF qui nécessiterait autrement de recréer le même code. - Utile pour : Transformations répétées, opérations API fiables, traitement de données et autres automatisations concrètes.
- Validation : Exécutez les scripts nouveaux ou modifiés pour vérifier leur comportement. Les scripts peuvent généralement être exécutés sans charger leur implémentation complète dans le contexte, bien qu'un agent puisse avoir besoin de les inspecter pour les corriger ou les adapter.
References
Utilisez references/ pour la documentation nécessaire uniquement dans des contextes particuliers.
- Exemples :
references/schema.mdpour les tables de base de données,references/policies.mdpour les règles de domaine,references/api_docs.mdpour une API, ou des guides d'écriture séparés pour différents livrables. - Utile pour : Schémas, documentation API, politiques d'entreprise, procédures spécifiques au format, workflows détaillés et exemples substantiels.
- Routage : Liez chaque référence depuis
SKILL.mdou une autre ressource pertinente et expliquez quand elle doit être lue. Gardez l'information à un seul endroit plutôt que de la dupliquer dans le point d'entrée et les références.
Gardez les références concentrées sur des informations maintenues, spécifiques à la tâche, qui modifient les décisions de l'agent. Évitez les manuels copiés, les catalogues exhaustifs et les tutoriels génériques déjà disponibles auprès de sources autorisées. Avant de supprimer des ressources existantes, inspectez leurs appelants et leur objectif.
Pour les grandes références, incluez des termes de recherche utiles ou une courte table des matières lorsque cela facilite la recherche du matériel nécessaire.
Assets
Utilisez assets/ pour les fichiers qui appartiennent à la sortie générée plutôt que dans les instructions du modèle.
- Exemples :
assets/logo.png,assets/slides.pptx,assets/font.ttf, ouassets/frontend-template/. - Utile pour : Modèles, images, polices, icônes, projets de base et autres fichiers copiés ou adaptés dans le résultat.
- Contexte : Ne chargez pas les assets comme instructions sauf si la tâche nécessite de les inspecter.
Métadonnées UI et Politique d'Invocation
agents/openai.yaml peut fournir des métadonnées destinées à l'interface utilisateur telles que display_name, short_description, et default_prompt, ainsi que la politique d'invocation. Lors de la création ou de la mise à jour de ces paramètres, lisez references/openai_yaml.md et gardez les valeurs cohérentes avec la compétence.
La sélection automatique de la compétence est autorisée par défaut. Modifiez cette valeur par défaut uniquement lorsque l'utilisateur demande explicitement une compétence à invocation explicite uniquement :
policy:
allow_implicit_invocation: false
Cela garde la compétence disponible lorsqu'elle est invoquée explicitement sous la forme $nom-de-la-competence sans l'ajouter automatiquement au contexte du modèle. Préservez les champs UI, politique et dépendances existants non liés lors de la mise à jour de agents/openai.yaml.
L'initialiseur crée ce fichier automatiquement. Pour les métadonnées nouvelles ou orientées interface uniquement, générez-le avec :
scripts/generate_openai_yaml.py <chemin/vers/dossier-competence> --interface cle=valeur
Le générateur remplace l'intégralité du fichier. Si un fichier existant contient policy ou dependencies, mettez à jour uniquement les champs prévus sur place au lieu de le régénérer.
Incluez les champs d'interface facultatifs uniquement lorsque l'utilisateur les fournit ou les demande.
Ce qu'il ne faut pas inclure
Incluez les fichiers qui soutiennent directement le travail de la compétence. Évitez d'ajouter un README.md, un guide d'installation, un journal des modifications, une référence rapide dupliquée ou toute autre documentation auxiliaire sauf si une tâche spécifique ou une exigence d'empaquetage le demande.
Divulgation Progressive en Pratique
Pour une compétence avec plusieurs modes substantiels, gardez les conseils partagés et les critères de sélection de mode dans SKILL.md. Liez chaque référence de support là où son utilisation devient pertinente. Ne chargez pas chaque référence par défaut, ne dupliquez pas le contenu des références dans le point d'entrée, et n'ajoutez pas de couche de routage lorsqu'il n'y a rien de significatif à router.
Par exemple, une compétence de déploiement peut garder la sélection du fournisseur dans SKILL.md et séparer les détails par fournisseur :
cloud-deploy/
|-- SKILL.md
`-- references/
|-- aws.md
|-- gcp.md
`-- azure.md
Lorsque l'utilisateur choisit AWS, lisez references/aws.md ; ne chargez pas également les guides GCP et Azure. Le même modèle peut séparer les domaines d'activité, les types de livrables ou d'autres modes de fonctionnement véritablement distincts.
Une compétence courte peut plutôt router vers les détails uniquement lorsqu'une opération avancée en a besoin :
## Documents
Traitez les modifications ordinaires directement.
- Pour les modifications suivies, lisez [references/redlining.md](references/redlining.md).
- Pour les aspects internes des documents, lisez [references/ooxml.md](references/ooxml.md).
Ces exemples illustrent des options, pas une structure obligatoire. Choisissez l'organisation qui rend la compétence plus facile à utiliser sans charger de contenu non pertinent.
Créer ou Mettre à Jour une Compétence
Adaptez le travail à la demande. La création d'une nouvelle compétence complexe peut impliquer la compréhension de cas d'utilisation réalistes, le choix de ressources de support, l'initialisation de fichiers, la rédaction d'instructions et la validation du résultat. Une mise à jour ciblée d'une compétence existante peut nécessiter uniquement une modification et une validation ciblées.
Posez des questions de clarification uniquement lorsque l'information manquante compte et ne peut pas être raisonnablement déduite. Respectez un emplacement spécifié par l'utilisateur ; sinon, créez des compétences découvrables dans $CODEX_HOME/skills, ou ~/.codex/skills lorsque CODEX_HOME n'est pas défini.
Gardez la sélection automatique de la compétence activée sauf si l'utilisateur demande explicitement une compétence à invocation explicite uniquement. Lorsque le mode d'invocation prévu est véritablement flou et a de l'importance pour le workflow demandé, demandez si l'utilisateur souhaite une découverte automatique normale ou une invocation explicite uniquement ; sinon, conservez la valeur par défaut. N'inférez pas l'invocation explicite uniquement à partir d'opérations sensibles ou d'approbations requises : gardez la compétence découvrable et exigez l'autorisation immédiatement avant la mutation réelle. Préservez la politique d'invocation d'une compétence existante sauf si l'utilisateur demande de la modifier.
Pour une compétence nouvelle ou substantiellement révisée, considérez les demandes réelles qu'elle devrait traiter et les ressources réutilisables qui amélioreraient ces tâches :
- Une transformation PDF répétée peut justifier un assistant
scripts/rotate_pdf.py. - Un workflow de création d'application peut bénéficier d'un modèle de démarrage
assets/frontend-template/. - Une compétence d'analyse de données peut avoir besoin d'un guide
references/schema.mdpour éviter de redécouvrir les relations entre les tables.
Créez ces ressources uniquement lorsque leur bénéfice concret les justifie. Si l'utilisateur a déjà expliqué clairement la tâche, procédez sans demander d'exemples supplémentaires.
Nommage
- Utilisez des lettres minuscules, des chiffres et des traits d'union.
- Gardez les noms sous 64 caractères et préférez des noms courts orientés action.
- Espacez les noms par outil ou domaine lorsque cela améliore la découverte.
- Nommez le dossier de la compétence d'après la compétence.
Initialiser une Nouvelle Compétence
Pour une nouvelle compétence, utilisez l'initialiseur intégré lorsqu'il aide à créer les fichiers requis de manière cohérente :
scripts/init_skill.py <nom-competence> --path <repertoire-sortie> [--resources scripts,references,assets] [--examples]
Par exemple :
scripts/init_skill.py ma-competence --path "${CODEX_HOME:-$HOME/.codex}/skills"
scripts/init_skill.py ma-competence --path "${CODEX_HOME:-$HOME/.codex}/skills" --resources references
Demandez uniquement les répertoires de ressources dont la compétence a besoin. Utilisez --examples uniquement lorsque des espaces réservés concrets seraient utiles, puis remplacez-les ou supprimez-les avant de terminer. N'initialisez pas une compétence existante une nouvelle fois.
L'initialiseur crée le dossier de la compétence, un modèle de SKILL.md concis et agents/openai.yaml. Il crée les répertoires de ressources et les fichiers d'exemple uniquement sur demande. Passez les valeurs UI générées sous la forme --interface cle=valeur lorsque nécessaire.
Rédiger les Instructions
La description du frontmatter doit expliquer brièvement ce que fait la compétence et quand elle s'applique. Incluez une limite significative lorsque des demandes similaires ne doivent pas activer la compétence.
Par exemple :
description: Créer ou modifier des documents Word lorsque le formatage, les modifications suivies ou les commentaires nécessitent un traitement spécifique au document.
Mettez les workflows détaillés, les choix d'outils, les exemples et les modes de fonctionnement dans le corps ou les références pertinentes plutôt que de tous les énumérer dans la description. Préservez le frontmatter facultatif supporté, comme les metadata existants, lorsqu'il est approprié.
Rédigez uniquement les instructions nécessaires pour qu'une autre instance de Codex puisse accomplir la tâche correctement. Énoncez le résultat souhaité, le contexte non évident, les contraintes réelles et les références ou outils pertinents. Préservez les choix explicites de l'utilisateur et les limites d'autorisation existantes. Évitez de prescrire une structure fixe, un processus ou un nombre d'étapes lorsque la tâche n'en exige pas.
Valider et Itérer
Validez la compétence terminée avec :
scripts/quick_validate.py <chemin/vers/dossier-competence>
Le validateur vérifie le frontmatter, le nommage et les espaces réservés de squelette non terminés ; il ne prouve pas que la compétence prend de bonnes décisions. Vérifiez également que les descriptions restent discriminantes, que les instructions préservent l'intention de l'utilisateur, que les références sont découvrables et que les éventuels scripts ajoutés fonctionnent réellement.
Lorsque des tests sont justifiés, vérifiez le comportement observable ou les invariants significatifs. Évitez les tests qui ne font que correspondre à un libellé, des titres ou des motifs d'expression régulière générés.
Améliorez la compétence en fonction de l'utilisation réelle ou des échecs démontrés. Préférez une correction ciblée à l'accumulation de règles universelles pour chaque cas marginal.