grahama1970/skill-creator

Créateur de Skills

Ce skill fournit des conseils pour créer des skills efficaces.

À propos des Skills

Les skills 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. Considérez-les comme des « guides d’intégration » pour des domaines ou des tâches spécifiques—ils transforment Codex d’un agent généraliste en un agent spécialisé, équipé de connaissances procédurales qu’aucun modèle ne peut posséder entièrement.

Ce que les Skills fournissent

1. Workflows spécialisés - Procédures en plusieurs étapes pour des domaines spécifiques
2. Intégrations d’outils - Instructions pour travailler avec des formats de fichiers ou des API spécifiques
3. Expertise métier - Connaissances propres à l’entreprise, schémas, logique métier
4. Ressources groupées - Scripts, références et actifs pour des tâches complexes et répétitives

Principes fondamentaux

La concision est clé

La fenêtre de contexte est un bien public. Les skills partagent la fenêtre de contexte avec tout ce dont Codex a besoin : prompt système, historique de la conversation, métadonnées des autres skills, et la requête réelle de l’utilisateur.

Hypothèse par défaut : Codex est déjà très intelligent. N’ajoutez que 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 des exemples concis à des explications verbeuses.

Définir des degrés de liberté appropriés

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

• Liberté élevée (instructions textuelles) : À utiliser lorsque plusieurs approches sont valables, que les décisions dépendent du contexte ou que des heuristiques guident l’approche.
• Liberté moyenne (pseudocode ou scripts avec paramètres) : À utiliser lorsqu’un modèle préféré existe, qu’une certaine variation est acceptable ou que la configuration affecte le comportement.
• Faible liberté (scripts spécifiques, peu de paramètres) : À utiliser lorsque les opérations sont fragiles et sujettes aux erreurs, que la cohérence est critique ou qu’une séquence spécifique doit être suivie.

Considérez Codex comme explorant un chemin : un pont étroit avec des falaises nécessite des garde-corps spécifiques (faible liberté), tandis qu’un champ ouvert permet de nombreuses routes (liberté élevée).

Protéger l’intégrité de la validation

Vous pouvez utiliser des sous-agents pendant l’itération pour valider si un skill fonctionne sur des tâches réalistes ou si un problème suspecté est réel. Cela est particulièrement utile lorsque vous souhaitez un passage indépendant sur le comportement, les sorties ou les modes de défaillance du skill après une révision. Ne faites cela que lorsqu’il est possible de lancer de nouveaux sous-agents.

Lorsque vous utilisez des sous-agents pour la validation, traitez cela comme une surface d’évaluation. L’objectif est de savoir si le skill se généralise, et non si un autre agent peut reconstruire la réponse à partir d’un contexte divulgué.

Privilégiez les artefacts bruts tels que les exemples de prompts, les sorties, les diffs, les logs ou les traces. Donnez le minimum de contexte local à la tâche nécessaire pour effectuer la validation. Évitez de transmettre la réponse attendue, le bogue suspecté, le correctif prévu ou vos conclusions antérieures, sauf si la validation les exige explicitement.

Anatomie d’un Skill

Chaque skill se compose d’un fichier SKILL.md obligatoire et de ressources groupées optionnelles :

nom-du-skill/
├── SKILL.md (obligatoire)
│   ├── Métadonnées YAML en en-tête (obligatoire)
│   │   ├── name: (obligatoire)
│   │   └── description: (obligatoire)
│   └── Instructions Markdown (obligatoire)
├── agents/ (recommandé)
│   └── openai.yaml - Métadonnées d’interface utilisateur pour les listes et puces de skills
└── Ressources groupées (optionnel)
    ├── scripts/          - Code exécutable (Python/Bash/etc.)
    ├── references/       - Documentation destinée à être chargée dans le contexte selon les besoins
    └── assets/           - Fichiers utilisés dans la sortie (modèles, icônes, polices, etc.)

SKILL.md (obligatoire)

Chaque SKILL.md se compose de :

• En-tête (YAML) : Contient les champs name et description. Ce sont les seuls champs que Codex lit pour déterminer quand le skill doit être utilisé, il est donc très important d’être clair et complet dans la description de ce qu’est le skill et quand il doit être utilisé.
• Corps (Markdown) : Instructions et conseils pour utiliser le skill. Chargé UNIQUEMENT APRÈS le déclenchement du skill (si jamais).

Métadonnées des agents (recommandé)

• Métadonnées orientées interface utilisateur pour les listes et puces de skills
• Lisez references/openai_yaml.md avant de générer les valeurs et suivez ses descriptions et contraintes
• Créez : display_name, short_description et default_prompt lisibles par un humain en lisant le skill
• Générez 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 : validez que agents/openai.yaml correspond toujours à SKILL.md ; régénérez si obsolète
• N’incluez d’autres champs d’interface optionnels (icônes, couleur de marque) que s’ils sont explicitement fournis
• Voir references/openai_yaml.md pour les définitions de champs et des exemples

Ressources groupées (optionnel)

Scripts (scripts/)

Code exécutable (Python/Bash/etc.) pour des tâches nécessitant une fiabilité déterministe ou réécrites de manière répétée.

• Quand inclure : Lorsque le même code est réécrit de manière répétée ou qu’une fiabilité déterministe est nécessaire
• Exemple : scripts/rotate_pdf.py pour des tâches de rotation de PDF
• Avantages : Efficace en tokens, déterministe, peut être exécuté sans être chargé dans le contexte
• Note : Les scripts peuvent encore devoir être lus par Codex pour des correctifs ou des 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 dans le contexte pour informer le processus et la réflexion de Codex.

• Quand inclure : Pour la documentation que Codex doit consulter pendant le travail
• 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’utilisation : Schémas de base de données, documentation d’API, connaissances métier, politiques d’entreprise, guides de workflow détaillés
• Avantages : Maintient SKILL.md léger, chargé uniquement lorsque Codex le juge nécessaire
• Meilleure pratique : Si les fichiers sont volumineux (>10 000 mots), incluez des modèles de recherche grep dans SKILL.md
• Évitez la duplication : Les informations doivent se trouver soit dans SKILL.md, soit dans les fichiers de références, pas dans les deux. Privilégiez les fichiers de références pour les informations détaillées, sauf si elles sont véritablement essentielles au skill—cela maintient SKILL.md léger tout en rendant les informations découvrables sans monopoliser la fenêtre de contexte. Conservez uniquement les instructions procédurales essentielles et les conseils de workflow dans SKILL.md ; déplacez le matériel de référence détaillé, les schémas et les exemples vers les fichiers de références.

Actifs (assets/)

Fichiers non destinés à être chargés dans le contexte, mais utilisés dans la sortie produite par Codex.

• Quand inclure : Lorsque le skill a besoin de fichiers qui seront utilisés dans la sortie finale
• Exemples : assets/logo.png pour les actifs de marque, assets/slides.pptx pour les modèles PowerPoint, assets/frontend-template/ pour le code HTML/React de base, assets/font.ttf pour la typographie
• Cas d’utilisation : Modèles, images, icônes, code passe-partout, polices, documents d’exemple 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 dans le contexte

Ce qu’il ne faut PAS inclure dans un Skill

Un skill ne doit contenir que les fichiers essentiels qui soutiennent directement sa fonctionnalité. Ne créez PAS de documentation superflue ou de fichiers auxiliaires, notamment :

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

Le skill ne doit contenir que les informations nécessaires à un agent IA pour accomplir la tâche en question. Il ne doit pas contenir de contexte auxiliaire sur le processus de création, les procédures d’installation et de test, la documentation destinée à l’utilisateur, etc. Créer des fichiers de documentation supplémentaires ne fait qu’ajouter du fouillis et de la confusion.

Principe de conception de divulgation progressive

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

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

Modèles de divulgation progressive

Gardez le corps de SKILL.md à l’essentiel et sous 500 lignes pour minimiser le gonflement du contexte. Divisez le contenu en fichiers séparés lorsque vous approchez de cette limite. Lorsque vous divisez le contenu dans d’autres fichiers, il est très important de les référencer depuis SKILL.md et de décrire clairement quand les lire, pour garantir que le lecteur du skill sait qu’ils existent et quand les utiliser.

Principe clé : Lorsqu’un skill prend en charge plusieurs variantes, frameworks ou options, conservez uniquement le workflow de base et les conseils de sélection dans SKILL.md. Déplacez les détails spécifiques aux variantes (modèles, exemples, configuration) dans des fichiers de référence séparés.

Modèle 1 : Guide de haut niveau avec références

# Traitement PDF

## Démarrage rapide

Extraire le texte avec pdfplumber :
[exemple de code]

## Fonctionnalités avancées

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

Codex charge FORMS.md, REFERENCE.md ou EXAMPLES.md uniquement en cas de besoin.

Modèle 2 : Organisation par domaine

Pour les skills avec plusieurs domaines, organisez le contenu par domaine pour éviter de charger un 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)

Lorsqu’un utilisateur pose une question sur les métriques de vente, Codex ne lit que sales.md.

De même, pour les skills prenant en charge plusieurs frameworks ou variantes, organisez par variante :

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

Lorsque l’utilisateur choisit AWS, Codex ne lit que aws.md.

Modèle 3 : Détails conditionnels

Affichez le contenu de base, liez vers le contenu avancé :

# Traitement DOCX

## Création de documents

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

## Modification de documents

Pour les modifications simples, modifiez le XML directement.

**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 lorsque l’utilisateur a besoin de ces fonctionnalités.

Directives importantes :

• Évitez les références profondément imbriquées - Gardez les références à un seul niveau de profondeur par rapport à SKILL.md. Tous les fichiers de référence doivent être liés directement depuis SKILL.md.
• Structurez les fichiers de référence plus longs - Pour les fichiers de plus de 100 lignes, incluez une table des matières en haut afin que Codex puisse voir la portée complète lors de l’aperçu.

Processus de création d’un Skill

La création d’un skill implique ces étapes :

1. Comprendre le skill avec des exemples concrets
2. Planifier le contenu réutilisable du skill (scripts, références, actifs)
3. Initialiser le skill (exécuter init_skill.py)
4. Éditer le skill (implémenter les ressources et écrire SKILL.md)
5. Valider le skill (exécuter quick_validate.py)
6. Itérer en fonction de l’utilisation réelle et tester à l’avance les skills complexes.

Suivez ces étapes dans l’ordre, en ne sautant que s’il existe une raison claire pour laquelle elles ne sont pas applicables.

Nommage du Skill

• Utilisez uniquement des lettres minuscules, des chiffres et des traits d’union ; normalisez les titres fournis par l’utilisateur en casse-kebab (par exemple, « Plan Mode » -> plan-mode).
• Lors de la génération de noms, générez un nom de moins de 64 caractères (lettres, chiffres, traits d’union).
• Privilégiez les phrases courtes commençant par un verbe qui décrivent l’action.
• Espace de noms par outil lorsque cela améliore la clarté ou le déclenchement (par exemple, gh-address-comments, linear-address-issue).
• Nommez le dossier du skill exactement comme le nom du skill.

Étape 1 : Comprendre le Skill avec des Exemples Concrets

Sautez cette étape uniquement lorsque les modèles d’utilisation du skill sont déjà clairement compris. Elle reste précieuse même lorsque vous travaillez sur un skill existant.

Pour créer un skill efficace, comprenez clairement des exemples concrets de la façon dont le skill sera utilisé. Cette compréhension peut provenir soit d’exemples directs d’utilisateurs, soit d’exemples générés validés par les retours des utilisateurs.

Par exemple, lors de la construction d’un skill d’édition d’images, les questions pertinentes incluent :

• « Quelles fonctionnalités le skill d’édition d’images doit-il prendre en charge ? Édition, rotation, autre chose ? »
• « Pouvez-vous donner quelques exemples de la façon dont ce skill serait utilisé ? »
• « Je peux imaginer des utilisateurs demandant des choses comme 'Supprimer les yeux rouges de cette image' ou 'Faire pivoter cette image'. Y a-t-il d’autres façons dont vous imaginez que ce skill soit utilisé ? »
• « Que dirait un utilisateur qui devrait déclencher ce skill ? »
• « Où dois-je créer ce skill ? Si vous n’avez pas de préférence, je le placerai dans $CODEX_HOME/skills (ou ~/.codex/skills lorsque CODEX_HOME n’est pas défini) afin que Codex puisse le découvrir automatiquement. »

Pour ne pas submerger les utilisateurs, évitez de poser trop de questions dans un seul message. Commencez par les questions les plus importantes et suivez si nécessaire pour une meilleure efficacité.

Concluez cette étape lorsqu’il y a une idée claire de la fonctionnalité que le skill doit prendre en charge.

Étape 2 : Planifier le Contenu Réutilisable du Skill

Pour transformer des exemples concrets en un skill efficace, analysez chaque exemple en :

1. Réfléchissant à la façon d’exécuter l’exemple à partir de zéro
2. Identifiant les scripts, références et actifs qui seraient utiles lors de l’exécution répétée de ces workflows

Exemple : Lors de la création d’un skill pdf-editor pour gérer des requêtes comme « Aidez-moi à faire pivoter ce PDF », l’analyse montre :

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

Exemple : Lors de la conception d’un skill frontend-webapp-builder pour des requêtes comme « Construis-moi une application todo » ou « Construis-moi un tableau de bord pour suivre mes pas », l’analyse montre :

1. Écrire une application web frontend nécessite le même passe-partout HTML/React à chaque fois
2. Un modèle assets/hello-world/ contenant les fichiers de projet HTML/React passe-partout serait utile à stocker dans le skill

Exemple : Lors de la création d’un skill big-query pour gérer des requêtes comme « H

…

[tronqué pour la traduction]