skill-creator

# Guide pour créer des compétences efficaces Cette compétence doit être utilisée lorsque les utilisateurs souhaitent créer une nouvelle compétence (ou mettre à jour une compétence existante) qui étend les capacités de Codex avec des connaissances spécialisées, des flux de travail ou des intégrations d'outils.

npx skills add https://github.com/openai/skills --skill skill-creator

Créateur de Compétence

Cette compétence fournit des conseils pour créer des compétences efficaces.

À propos des Compétences

Les compétences sont des dossiers modulaires et autonomes qui étendent les capacités de Codex en fournissant des connaissances spécialisées, des workflows et des outils. Pensez-y comme des « guides d'intégration » pour des domaines ou des tâches spécifiques—ils transforment Codex d'un agent polyvalent en un agent spécialisé équipé de connaissances procédurales qu'aucun modèle ne peut pleinement posséder.

Ce que les Compétences Fournissent

  1. Workflows spécialisés - Procédures multi-étapes pour des domaines spécifiques
  2. Intégrations d'outils - Instructions pour travailler avec des formats de fichiers ou des APIs spécifiques
  3. Expertise de domaine - Connaissances spécifiques à l'entreprise, schémas, logique métier
  4. Ressources regroupées - Scripts, références et ressources pour les tâches complexes et répétitives

Principes Fondamentaux

La Concision est Clé

La fenêtre de contexte est un bien public. Les compétences partagent la fenêtre de contexte avec tout ce dont Codex a besoin : invite système, historique de conversation, métadonnées d'autres Compétences, et la demande utilisateur réelle.

Hypothèse par défaut : Codex est déjà très intelligent. Ajoutez uniquement le contexte que Codex ne possède pas déjà. Remettez en question chaque information : « Codex a-t-il vraiment besoin de cette explication ? » et « Ce paragraphe justifie-t-il son coût en tokens ? »

Préférez les exemples concis aux explications verbeux.

Définir des Degrés de Liberté Appropriés

Faire correspondre le niveau de spécificité à la fragilité et à la variabilité de la tâche :

Haute liberté (instructions basées sur du texte) : Utiliser quand plusieurs approches sont valides, les décisions dépendent du contexte, ou des heuristiques guident l'approche.

Liberté moyenne (pseudocode ou scripts avec paramètres) : Utiliser quand un motif préféré existe, une certaine variation est acceptable, ou la configuration affecte le comportement.

Basse liberté (scripts spécifiques, peu de paramètres) : Utiliser quand les opérations sont fragiles et sujettes à erreurs, la cohérence est critique, ou une séquence spécifique doit être suivie.

Pensez à Codex comme explorant un chemin : un pont étroit avec des précipices a besoin de garde-fous spécifiques (basse liberté), tandis qu'un champ ouvert permet de nombreuses routes (haute liberté).

Anatomie d'une Compétence

Chaque compétence se compose d'un fichier SKILL.md requis et de ressources optionnelles regroupées :

skill-name/
├── SKILL.md (requis)
│   ├── Métadonnées en frontiaire YAML (requis)
│   │   ├── name: (requis)
│   │   └── description: (requis)
│   └── Instructions Markdown (requis)
├── agents/ (recommandé)
│   └── openai.yaml - Métadonnées UI pour les listes et puces de compétences
└── Ressources Regroupées (optionnel)
    ├── scripts/          - Code exécutable (Python/Bash/etc.)
    ├── references/       - Documentation destinée à être chargée en contexte si nécessaire
    └── assets/           - Fichiers utilisés en sortie (modèles, icônes, polices, etc.)

SKILL.md (requis)

Chaque SKILL.md se compose de :

  • Frontmatter (YAML) : Contient les champs name et description. Ce sont les seuls champs que Codex lit pour déterminer quand la compétence est utilisée, il est donc très important d'être clair et complet dans la description de ce que fait la compétence et quand elle doit être utilisée.
  • Corps (Markdown) : Instructions et conseils pour utiliser la compétence. Chargé uniquement APRÈS que la compétence se déclenche (le cas échéant).

Métadonnées d'agents (recommandé)

  • Métadonnées exposées à l'interface utilisateur pour les listes et puces de compétences
  • Lire references/openai_yaml.md avant de générer les valeurs et suivre ses descriptions et contraintes
  • Créer : display_name orienté utilisateur, short_description, et default_prompt en lisant la compétence
  • Générer de manière déterministe en passant les valeurs comme --interface key=value à scripts/generate_openai_yaml.py ou scripts/init_skill.py
  • Lors des mises à jour : valider que agents/openai.yaml correspond toujours à SKILL.md ; régénérer si obsolète
  • Inclure uniquement les autres champs d'interface optionnels (icônes, couleur de marque) s'ils sont explicitement fournis
  • Voir references/openai_yaml.md pour les définitions de champs et les exemples

Ressources Regroupées (optionnel)

Scripts (scripts/)

Code exécutable (Python/Bash/etc.) pour les tâches qui nécessitent une fiabilité déterministe ou sont réécrits régulièrement.

  • Quand inclure : Quand le même code est réécrité régulièrement ou qu'une fiabilité déterministe est nécessaire
  • Exemple : scripts/rotate_pdf.py pour les tâches de rotation de PDF
  • Avantages : Efficace en tokens, déterministe, peut être exécuté sans être chargé en contexte
  • Remarque : Les scripts peuvent toujours nécessiter d'être lus par Codex pour les correctifs ou les ajustements spécifiques à l'environnement
Références (references/)

Documentation et matériel de référence destinés à être chargés selon les besoins en contexte pour informer le processus et la réflexion de Codex.

  • Quand inclure : Pour la documentation que Codex doit consulter en travaillant
  • Exemples : references/finance.md pour les schémas financiers, references/mnda.md pour le modèle de NDA de l'entreprise, references/policies.md pour les politiques de l'entreprise, references/api_docs.md pour les spécifications d'API
  • Cas d'usage : Schémas de bases de données, documentation d'API, connaissances de domaine, politiques d'entreprise, guides de workflow détaillés
  • Avantages : Garde SKILL.md lean, chargé uniquement quand Codex détermine que c'est nécessaire
  • Meilleure pratique : Si les fichiers sont volumineux (>10k mots), inclure des motifs de recherche grep dans SKILL.md
  • Éviter la duplication : L'information doit vivre soit dans SKILL.md soit dans les fichiers de références, pas les deux. Préférer les fichiers de références pour les informations détaillées sauf si c'est vraiment essentiel à la compétence—cela garde SKILL.md lean tout en rendant l'information découvrable sans monopoliser la fenêtre de contexte. Garder uniquement les instructions procédurales essentielles et les conseils de workflow dans SKILL.md ; déplacer la documentation de référence détaillée, les schémas et les exemples vers les fichiers de références.
Ressources (assets/)

Fichiers non destinés à être chargés en contexte, mais plutôt utilisés dans la sortie que Codex produit.

  • Quand inclure : Quand la compétence a besoin de fichiers qui seront utilisés dans la sortie finale
  • Exemples : assets/logo.png pour les ressources de marque, assets/slides.pptx pour les modèles PowerPoint, assets/frontend-template/ pour le boilerplate HTML/React, assets/font.ttf pour la typographie
  • Cas d'usage : Modèles, images, icônes, code boilerplate, polices, exemples de documents qui sont copiés ou modifiés
  • Avantages : Sépare les ressources de sortie de la documentation, permet à Codex d'utiliser des fichiers sans les charger en contexte

Ce qui Ne Pas Inclure dans une Compétence

Une compétence ne doit contenir que les fichiers essentiels qui soutiennent directement sa fonctionnalité. NE PAS créer de documentation extraneous ou de fichiers auxiliaires, y compris :

  • README.md
  • INSTALLATION_GUIDE.md
  • QUICK_REFERENCE.md
  • CHANGELOG.md
  • etc.

La compétence doit contenir uniquement les informations dont un agent IA a besoin pour faire le travail à accomplir. Elle ne doit pas contenir de contexte auxiliaire sur le processus qui a mené à sa création, les procédures de configuration et de test, la documentation orientée utilisateur, etc. Créer des fichiers de documentation supplémentaires ajoute simplement du désordre et de la confusion.

Principe de Conception Divulgation Progressive

Les compétences utilisent un système de chargement à trois niveaux pour gérer efficacement le contexte :

  1. Métadonnées (nom + description) - Toujours en contexte (~100 mots)
  2. Corps SKILL.md - Quand la compétence se déclenche (<5k mots)
  3. Ressources regroupées - Selon les besoins de Codex (Illimité car les scripts peuvent être exécutés sans être lus dans la fenêtre de contexte)

Motifs de Divulgation Progressive

Garder le corps SKILL.md à l'essentiel et sous 500 lignes pour minimiser le gaspillage de contexte. Diviser le contenu en fichiers séparés quand on approche de cette limite. Quand on divise le contenu dans d'autres fichiers, il est très important de les référencer à partir de SKILL.md et de décrire clairement quand les lire, pour assurer que le lecteur de la compétence sait qu'ils existent et quand les utiliser.

Principe clé : Quand une compétence supporte plusieurs variations, frameworks ou options, garder uniquement le workflow de base et les conseils de sélection dans SKILL.md. Déplacer les détails spécifiques aux variantes (motifs, exemples, configuration) dans des fichiers de références séparés.

Motif 1 : Guide de haut niveau avec références

# Traitement PDF

## Démarrage rapide

Extraire du texte avec pdfplumber :
[exemple de code]

## Fonctionnalités avancées

- **Remplissage de formulaires** : Voir [FORMS.md](FORMS.md) pour le guide complet
- **Référence API** : Voir [REFERENCE.md](REFERENCE.md) pour toutes les méthodes
- **Exemples** : Voir [EXAMPLES.md](EXAMPLES.md) pour les motifs courants

Codex charge FORMS.md, REFERENCE.md, ou EXAMPLES.md uniquement quand c'est nécessaire.

Motif 2 : Organisation spécifique au domaine

Pour les Compétences avec plusieurs domaines, organiser le contenu par domaine pour éviter de charger le contexte non pertinent :

bigquery-skill/
├── SKILL.md (aperçu et navigation)
└── reference/
    ├── finance.md (revenus, métriques de facturation)
    ├── sales.md (opportunités, pipeline)
    ├── product.md (utilisation API, fonctionnalités)
    └── marketing.md (campagnes, attribution)

Quand un utilisateur demande des métriques de ventes, Codex ne lit que sales.md.

De manière similaire, pour les compétences supportant plusieurs frameworks ou variantes, organiser par variante :

cloud-deploy/
├── SKILL.md (workflow + sélection de fournisseur)
└── references/
    ├── aws.md (motifs de déploiement AWS)
    ├── gcp.md (motifs de déploiement GCP)
    └── azure.md (motifs de déploiement Azure)

Quand l'utilisateur choisit AWS, Codex ne lit que aws.md.

Motif 3 : Détails conditionnels

Afficher le contenu de base, lier au contenu avancé :

# Traitement DOCX

## Créer des documents

Utiliser docx-js pour les nouveaux documents. Voir [DOCX-JS.md](DOCX-JS.md).

## Éditer des documents

Pour les modifications simples, modifier directement le XML.

**Pour les modifications suivies** : Voir [REDLINING.md](REDLINING.md)
**Pour les détails OOXML** : Voir [OOXML.md](OOXML.md)

Codex lit REDLINING.md ou OOXML.md uniquement quand l'utilisateur a besoin de ces fonctionnalités.

Directives importantes :

  • Éviter les références profondément imbriquées - Garder les références à un niveau de profondeur à partir de SKILL.md. Tous les fichiers de références doivent être liés directement à partir de SKILL.md.
  • Structurer les fichiers de références plus longs - Pour les fichiers plus longs que 100 lignes, inclure une table des matières au sommet pour que Codex puisse voir la portée complète en prévisualisant.

Processus de Création de Compétence

La création de compétence implique ces étapes :

  1. Comprendre la compétence avec des exemples concrets
  2. Planifier les contenus de compétence réutilisables (scripts, références, ressources)
  3. Initialiser la compétence (exécuter init_skill.py)
  4. Éditer la compétence (implémenter les ressources et écrire SKILL.md)
  5. Valider la compétence (exécuter quick_validate.py)
  6. Itérer selon l'utilisation réelle

Suivre ces étapes dans l'ordre, en ignorant uniquement s'il y a une raison claire pour laquelle elles ne sont pas applicables.

Nommage de Compétence

  • Utiliser uniquement les lettres minuscules, les chiffres et les traits d'union ; normaliser les titres fournis par l'utilisateur en cas hyphenisé (par ex., « Plan Mode » -> plan-mode).
  • Lors de la génération de noms, générer un nom de moins de 64 caractères (lettres, chiffres, traits d'union).
  • Préférer les phrases courtes, conduites par un verbe qui décrivent l'action.
  • Espacer les noms par outil quand cela améliore la clarté ou le déclenchement (par ex., gh-address-comments, linear-address-issue).
  • Nommer le dossier de compétence exactement d'après le nom de la compétence.

Étape 1 : Comprendre la Compétence avec des Exemples Concrets

Ignorer cette étape uniquement quand les motifs d'utilisation de la compétence sont déjà clairement compris. Elle reste précieuse même en travaillant avec une compétence existante.

Pour créer une compétence efficace, comprendre clairement les exemples concrets de la manière dont la compétence sera utilisée. Cette compréhension peut venir soit d'exemples directs de l'utilisateur soit d'exemples générés qui sont validés avec les retours de l'utilisateur.

Par exemple, lors de la création d'une compétence image-editor, les questions pertinentes incluent :

  • « Quelle fonctionnalité la compétence image-editor doit-elle supporter ? Édition, rotation, autre chose ? »
  • « Peux-tu donner des exemples de la façon dont cette compétence serait utilisée ? »
  • « Je peux imaginer les utilisateurs demandant des choses comme 'Enlever les yeux rouges de cette image' ou 'Faire tourner cette image'. Y a-t-il d'autres façons d'imaginer l'utilisation de cette compétence ? »
  • « Qu'est-ce qu'un utilisateur pourrait dire qui devrait déclencher cette compétence ? »

Pour éviter de submerger les utilisateurs, éviter de poser trop de questions dans un seul message. Commencer par les questions les plus importantes et suivre selon les besoins pour une meilleure efficacité.

Conclure cette étape quand il y a une compréhension claire de la fonctionnalité que la compétence doit supporter.

Étape 2 : Planifier les Contenus de Compétence Réutilisables

Pour transformer des exemples concrets en une compétence efficace, analyser chaque exemple par :

  1. Considérer comment exécuter l'exemple à partir de zéro
  2. Identifier quels scripts, références et ressources seraient utiles lors de l'exécution de ces workflows à plusieurs reprises

Exemple : Lors de la création d'une compétence pdf-editor pour gérer des requêtes comme « Aide-moi à faire tourner ce PDF », l'analyse montre :

  1. Faire tourner un PDF nécessite de réécrire le même code à chaque fois
  2. Un script scripts/rotate_pdf.py serait utile à stocker dans la compétence

Exemple : Lors de la conception d'une compétence frontend-webapp-builder pour des requêtes comme « Construis-moi une application de tâches » ou « Construis-moi un tableau de bord pour suivre mes pas », l'analyse montre :

  1. Écrire une webapp frontend nécessite le même boilerplate HTML/React à chaque fois
  2. Un modèle assets/hello-world/ contenant les fichiers de projet boilerplate HTML/React serait utile à stocker dans la compétence

Exemple : Lors de la création d'une compétence big-query pour gérer des requêtes comme « Combien d'utilisateurs se sont connectés aujourd'hui ? » l'analyse montre :

  1. Interroger BigQuery nécessite de redécouvrir les schémas et relations de table à chaque fois
  2. Un fichier references/schema.md documentant les schémas de table serait utile à stocker dans la compétence

Pour établir les contenus de la compétence, analyser chaque exemple concret pour créer une liste des ressources réutilisables à inclure : scripts, références et ressources.

Étape 3 : Initialiser la Compétence

À ce stade, il est temps de réellement créer la compétence.

Ignorer cette étape uniquement si la compétence en cours de développement existe déjà. Dans ce cas, continuer à l'étape suivante.

Lors de la création d'une nouvelle compétence à partir de zéro, toujours exécuter le script init_skill.py. Le script génère commodément un nouveau répertoire de modèle de compétence qui inclut automatiquement tout ce qu'une compétence nécessite, rendant le processus de création de compétence beaucoup plus efficace et fiable.

Utilisation :

scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]

Exemples :

scripts/init_skill.py my-skill --path skills/public
scripts/init_skill.py my-skill --path skills/public --resources scripts,references
scripts/init_skill.py my-skill --path skills/public --resources scripts --examples

Le script :

  • Crée le répertoire de compétence au chemin spécifié
  • Génère un modèle SKILL.md avec un frontmatter approprié et des espaces réservés TODO
  • Crée agents/openai.yaml en utilisant display_name, short_description, et default_prompt générés par agent passés via --interface key=value
  • Crée optionnellement des répertoires de ressources basés sur --resources
  • Ajoute optionnellement des fichiers d'exemple quand --examples est défini

Après l'initialisation, personnaliser SKILL.md et ajouter les ressources selon les besoins. Si vous avez utilisé --examples, remplacer ou supprimer les fichiers d'espace réservé.

Générer display_name, short_description, et default_prompt en lisant la compétence, puis les passer comme --interface key=value à init_skill.py ou régénérer avec :

scripts/generate_openai_yaml.py <path/to/skill-folder> --interface key=value

Inclure uniquement les autres champs d'interface optionnels quand l'utilisateur les fournit explicitement. Pour les descriptions de champs complets et les exemples, voir references/openai_yaml.md.

Étape 4 : Éditer la Compétence

Lors de l'édition de la compétence (nouvellement générée ou existante), se rappeler que la compétence est créée pour une autre instance de Codex à utiliser. Inclure les informations qui seraient bénéfiques et non-évidentes à Codex. Considérer quelle connaissance procédurale, détails spécifiques au domaine, ou ressources réutilisables aideraient une autre instance de Codex à exécuter ces tâches plus efficacement.

Commencer par les Contenus de Compétence Réutilisables

Pour commencer l'implémentation, commencer par les ressources réutilisables identifiées ci-dessus : fichiers scripts/, references/, et assets/. Noter que cette étape peut nécessiter des entrées utilisateur. Par exemple, lors de l'implémentation d'une compétence brand-guidelines, l'utilisateur peut avoir besoin de fournir des ressources de marque ou des modèles à stocker dans assets/, ou de la documentation à stocker dans references/.

Les scripts ajoutés doivent être testés en les exécutant réellement pour assurer qu'il n'y a pas de bugs et que la sortie correspond à ce qui est attendu. S'il y a beaucoup de scripts similaires, seul un échantillon représentatif doit être testé pour assurer la confiance que tous fonctionnent tout en équilibrant le temps à la réalisation.

Si vous avez utilisé --examples, supprimer tous les fichiers d'espace réservé qui ne sont pas nécessaires pour la compétence. Créer uniquement les répertoires de ressources qui sont réellement requis.

Mettre à Jour SKILL.md

Directives d'Écriture : Toujours utiliser la forme impérative/infinitive.

Frontmatter

Écrire le frontmatter YAML avec name et description :

  • name : Le nom de la compétence
  • description : Ceci est le mécanisme de déclenchement principal de votre compétence, et aide Codex à comprendre quand utiliser la compétence.
    • Inclure à la fois ce que la Compétence fait et les déclencheurs/contextes spécifiques pour quand l'utiliser.
    • Inclure toutes les informations « quand utiliser » ici - Pas dans le corps. Le corps est chargé uniquement après le déclenchement, donc les sections « Quand Utiliser Cette Compétence » dans le corps ne sont pas utiles à Codex.
    • Exemple de description pour une compétence docx : « Création, édition et analyse de documents complètes avec support des modifications suivies, commentaires, préservation du formatage et extraction de texte. Utiliser quand Codex doit travailler avec des documents professionnels (fichiers .docx) pour : (1) Créer de nouveaux documents, (2) Modifier ou éditer le contenu, (3) Travailler avec les modifications suivies, (4) Ajouter des commentaires, ou tout autre document tâches »

Ne pas inclure d'autres champs dans le frontmatter YAML.

Corps

Écrire les instructions pour utiliser la compétence et ses ressources regroupées.

Étape 5 : Valider la Compétence

Une fois le développement de la compétence achevé, valider le dossier de compétence pour attraper les problèmes de base tôt :

scripts/quick_validate.py <path/to/skill-folder>

Le script de validation vérifie le format du frontmatter YAML, les champs requis et les règles de nommage. Si la validation échoue, corriger les problèmes signalés et exécuter la commande à nouveau.

Étape 6 : Itérer

Après avoir testé la compétence, les utilisateurs peuvent demander des améliorations. Cela se produit souvent juste après avoir utilisé la compétence, avec un contexte frais de la performance de la compétence.

Workflow d'itération :

  1. Utiliser la compétence sur des tâches réelles
  2. Remarquer les luttes ou les inefficacités
  3. Identifier comment SKILL.md ou les ressources regroupées devraient être mises à jour
  4. Implémenter les changements et tester à nouveau