# Codex Skills pour débutants : comment automatiser les scénarios de travail des agents IA > Guide pratique pour créer et utiliser les Skills dans Codex : anatomie du fichier SKILL.md, activation explicite et automatique, différences entre les compétences, les scripts et les outils, l'API Skills et la configuration des limites de sécurité. ## 1. Qu'est-ce qu'un Codex Skill : passer des prompts ponctuels aux scénarios réutilisables Lors du développement régulier avec **Codex**, les ingénieurs répètent souvent le même ensemble d'instructions initiales : quels fichiers auditer, selon quels critères, quelles règles architecturales respecter et dans quel format retourner le résultat. Devoir retaper ces exigences à chaque session réduit la productivité et engendre des erreurs aléatoires. Un **Codex Skill (compétence)** est un scénario de travail sauvegardé et réutilisable pour un type de tâche spécifique. Créer une compétence ne consiste pas en un fine-tuning du modèle : les poids de l'IA restent inchangés. L'agent reçoit plutôt un protocole procédural clair qu'il charge dynamiquement dans sa fenêtre contextuelle uniquement lorsque la tâche correspondante survient. ```mermaid flowchart LR subgraph AdHoc ["Традиційний підхід (Ручний промптинг)"] User1["Користувач"] -->|Щоразу вводить довгі правила| Prompt["Великий разовий промпт"] Prompt --> Agent1["Codex"] end subgraph Modular ["Підхід на основі Skills"] User2["Користувач"] -->|Короткий запит: $code-review| Agent2["Codex"] SkillsDir["Репозиторій Skills (SKILL.md)"] -->|Автоматичне підвантаження інструкцій| Agent2 Agent2 --> Output["Стандартизований результат"] end ``` > [!NOTE] > Dans l'écosystème officiel OpenAI, les compétences sont déjà utilisées comme standard d'automatisation. Par exemple, pour migrer une base de code vers de nouveaux modèles, OpenAI fournit une Skill prête à l'emploi `openai-docs`, qui connaît toutes les subtilités du SDK actuel sans nécessiter de chargement manuel de la documentation. --- ## 2. Critères de sélection : quand utiliser un Skill versus un prompt classique Les Skills sont destinés avant tout aux processus présentant une répétitivité marquée, une séquence d'actions stable ou des exigences strictes sur le format des données de sortie. | Critère | Prompt classique | Codex Skill | | :--- | :--- | :--- | | **Fréquence d'utilisation** | Tâche unique et ponctuelle | Scénario régulier (quotidien ou avant chaque release) | | **Complexité du processus** | 1–2 étapes simples | Pipeline multi-étapes réglementé avec validation | | **Fichiers supplémentaires** | Non requis | Nécessite des scripts associés, des références ou des check-lists | | **Exigences de format** | Réponse libre | Structure de rapport stricte (par ex., JSON ou tableau fixe) | | **Droits et restrictions** | Paramètres de session actuels | Actions autorisées et interdites clairement définies | ### Scénarios typiques pour la création d'une compétence - **Vérification pré-release du repository :** Lancement des linters, recherche de code de debug oublié (`console.log`, `TODO`), vérification de la compatibilité des types. - **Code review standardisé :** Vérification de la conformité aux règles architecturales internes de l'équipe sans apporter de modifications autonomes. - **Génération de notes de release :** Extraction de la liste des PR fusionnés, leur catégorisation et mise à jour du `CHANGELOG.md`. - **Migration de composants :** Refactoring étape par étape de patterns obsolètes selon un template pré-approuvé. > [!TIP] > **Règle pratique de l'ingénieur :** Si vous vous surprenez à expliquer pour la troisième fois à Codex la même séquence d'étapes (« lis d'abord ce fichier, puis lance ce test, ne modifie rien, sors le résultat sous forme de tableau »), il est temps d'emballer ce workflow dans un Skill dédié. --- ## 3. Mécanique d'activation : appel explicite via `$name` vs sélection automatique Codex prend en charge deux modes d'activation complémentaires des compétences lors d'une session : l'appel direct déterministe par l'utilisateur et la reconnaissance sémantique automatique. ### Appel explicite (Explicit Invocation) L'utilisateur indique directement le nom de la compétence souhaitée via le préfixe dollar `$` : ```bash $code-review перевір останні зміни у гілці feature/auth ``` Cette méthode garantit une prévisibilité à 100 % : Codex active immédiatement le Skill indiqué, utilise ses instructions comme base de comportement et les applique aux arguments de votre requête. ### Activation automatique (Semantic Auto-Match) Si le préfixe `$name` n'est pas spécifié, Codex analyse la requête utilisateur et la confronte au champ `description` de toutes les compétences connectées : ```mermaid flowchart TD Req["Запит: 'Підготуй релізні нотатки для v2.1.0'"] --> Router{"Аналіз семантичного збігу"} Router -->|Match: description release-notes| LoadSkill["Підвантаження .codex/skills/release-notes/SKILL.md"] Router -->|No Match| Standard["Звичайний діалог без підвантаження навичок"] LoadSkill --> Exec["Виконання регламентованого сценарію"] ``` ```text Description réussie (forte probabilité d’activation précise) : description : Vérifie les fichiers modifiés du projet pour détecter les régressions, les erreurs de typage et les problèmes de style avant la publication. À utiliser lors de l’audit des PR. Description ratée (limites floues) : description : Aide le développeur à mieux écrire du code. ``` --- ## 4. Anatomie d'une compétence et structure SKILL.md : métadonnées, règles et ressources Une compétence minimale se compose d'un seul fichier — `SKILL.md`. Les compétences plus matures peuvent inclure des scripts d'automatisation imbriqués, des guides de référence et des templates. ```text project-review/ ├── SKILL.md # Fichier principal (métadonnées + instructions) ├── scripts/ └── check-deps.sh # Script exécutable pour les vérifications rapides ├── references/ └── styleguide.md # Référence : guide de style interne du code de l'équipe └── templates/ └── report-template.md # Modèle de rapport final ``` ### Structure du fichier `SKILL.md` Le fichier est divisé en deux parties fonctionnelles : un bloc YAML Frontmatter technique au début et des instructions au format Markdown. ```markdown --- name: project-review description: Effectuer un audit complet du code avant la release, vérifier les types et générer un rapport d'erreurs sans apporter de modifications. --- Instructions pour l'audit : 1. Exécuter « npm run typecheck » pour détecter les erreurs TypeScript. 2. Analyser le git diff par rapport à la branche main. 3. Regrouper les observations identifiées par catégories : Critical, Warning, Suggestion. 4. Ne rien modifier automatiquement dans le code source. 5. Fournir un rapport récapitulatif conformément à templates/report-template.md. ``` > [!IMPORTANT] > **Principe de concision :** Ne surchargez pas le `SKILL.md` avec de longues explications philosophiques. Plus le texte est court et précis, moins il occupe d'espace utile dans la fenêtre contextuelle du modèle, et plus l'agent respecte rigoureusement le règlement. --- ## 5. Zones de stockage : compétences projet vs globales personnelles Codex distingue les compétences selon deux périmètres de visibilité en fonction de leur usage : ```mermaid flowchart TD subgraph GlobalScope ["Глобальні навички (~/.codex/skills/)"] G1["Особистий стиль комітів"] G2["Швидкий генератор ліцензій"] end subgraph ProjectScope ["Проєктні навички (.codex/skills/)"] P1["Архітектурний лінтер проєкту"] P2["Генератор DTO та міграцій БД"] P3["Чек-лист релізу сервісу"] end Dev["Розробник"] -->|Власні уподобання| GlobalScope Team["Команда в Git"] -->|Спільні стандарти| ProjectScope ``` ### Compétences Projet (`.codex/skills/` ou `.agents/skills/`) Stockées à la racine du repository du projet et versionnées dans Git. - **Usage :** Standardisation des processus pour toute l'équipe de développement. - **Avantage :** Tout ingénieur (ou runner CI/CD) clonant le repository obtient instantanément le même jeu de compétences agentiques. ### Compétences Personnelles (`~/.codex/skills/`) Situées dans le répertoire home de l'utilisateur courant du système d'exploitation. - **Usage :** Outils individuels spécifiques à un développeur donné (par ex., assistant personnel pour la prise de notes de dev). - **Avantage :** Disponibles dans n'importe quel terminal, indépendamment du projet actif. --- ## 6. Atelier pratique : créer une compétence de vérification de code avec `$skill-creator` La méthode la plus simple et rapide pour créer une nouvelle compétence est d'utiliser le méta-outil système `$skill-creator`, intégré nativement dans Codex. ### Étape 1. Initialisation du générateur Dans la fenêtre de dialogue Codex, appelez la commande : ```bash $skill-creator ``` Décrivez ensuite le workflow souhaité en langage naturel : ```text Crée pour moi une compétence de projet nommée "pr-validator". Objectif : vérifier les fichiers modifiés dans la pull request actuelle. Règles : 1. Exécuter npm run lint et npm test. 2. Vérifier si des tests unitaires ont été ajoutés pour les nouveaux modules. 3. Interdire à l'agent de corriger lui-même les défauts détectés. 4. Présenter le résultat sous forme de tableau avec les colonnes : Fichier, Ligne, Problème, Niveau de risque. ``` ### Étape 2. Vérification de l'artefact généré Le générateur créera le dossier `.codex/skills/pr-validator/` et produira le fichier `SKILL.md` : ```markdown --- name: pr-validator description: Validates pull request changes by running lint and test suites, checking test coverage for new modules, and returning an issue table without modifying code. --- Execution Steps: 1. Identify modified files using git diff against the target branch. 2. Execute "npm run lint" and capture any linter warnings or errors. 3. Execute "npm test" to ensure regression safety. 4. Verify whether newly created source files in src/ have corresponding test files in tests/. 5. Strict constraint: Do NOT modify any project files under any circumstances. 6. Present the audit findings in a markdown table: | File | Line | Issue | Severity | ``` ### Étape 3. Test de la compétence créée en session réelle Ouvrez une nouvelle session Codex et testez le fonctionnement de la compétence : ```bash $pr-validator перевір мою поточну гілку перед відкриттям PR ``` Assurez-vous que l'agent a lancé le linter, n'a pas tenté de modifier les fichiers sources et a retourné un tableau de résultats. --- ## 7. La triade des capacités de l'agent : Skill, Script et Tool Les débutants confondent souvent les notions de compétence, script et outil (Tool / MCP). Ils se complètent mais résolvent des problèmes d'ingénierie fondamentalement différents. ```mermaid flowchart TD subgraph Triad ["Тріада архітектури автономного агента"] Skill["SKILL (Навичка)
'Мозок і регламент'
Пояснює послідовність, контекст та логіку"] Script["SCRIPT (Скрипт)
'Точний алгоритм'
Виконує детерміновану операцію на диску"] Tool["TOOL (Інструмент / MCP)
'Органи чуття та руки'
Надає доступ до API, терміналу, баз даних"] end Skill -->|Керує викликом| Script Skill -->|Використовує| Tool Script -->|Викликається через| Tool ``` ### Matrice comparative de la triade | Composant | Rôle dans le système | Mode d'exécution | Exemple | | :--- | :--- | :--- | :--- | | **Skill (Compétence)** | **Règlement et raisonnement** | Lu et interprété par le modèle | Instruction pour mener un audit de sécurité | | **Script** | **Action calculatoire déterministe** | Exécuté dans l'OS via le terminal | Script Bash de parsing des tags git | | **Tool (Outil)** | **Interface d'accès à l'environnement** | Appelé via le mécanisme Tool Calling | Serveur MCP pour connexion à l'API GitHub | > [!NOTE] > La compétence explique à l'agent **quoi** faire et **dans quel ordre**. Le script exécute rapidement et fiabillement une opération mathématique ou fichier. L'outil accorde les droits d'interaction avec le monde extérieur. --- ## 8. Pilotage programmatique via Skills API et versioning Au-delà du travail local sur les fichiers, OpenAI fournit une **Skills API** spécialisée pour le pilotage programmatique des compétences dans les applications cloud et les systèmes backend. ```bash # Створення нової навички через HTTP API curl https://api.openai.com/v1/skills \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "schema-migrator", "description": "Автоматична валідація та створення міграцій бази даних", "instructions": "Перевір схему Prisma, переконайся у відсутності drop column..." }' ``` ### Pourquoi le versioning des Skills est nécessaire 1. **Immutabilité de l'environnement de production :** Chaque mise à jour d'une compétence crée une nouvelle version (`v1`, `v2`). Les pipelines de production s'ancrent sur une version figée précise, éliminant les pannes inattendues dues à des changements accidentels. 2. **Rollback sécurisé :** Si une description mise à jour provoque une régression ou une baisse de qualité de la génération de code, l'équipe peut revenir instantanément au numéro de version précédent. 3. **A/B testing des instructions :** Possibilité de comparer simultanément la performance de deux éditions alternatives d'une compétence sur des tâches réelles. --- ## 9. Sécurité, limites d'autonomie et règles de confirmation des actions Un Skill influence directement les opérations que l'agent exécute dans votre système. Il est donc impératif de distinguer clairement, dans le corps de la compétence, les actions autonomes des actions contrôlées. ```mermaid flowchart LR Action["Дія агента"] --> Decision{"Тип операції"} Decision -->|Безпечна: Read-Only| Auto["Автономне виконання без пауз
(Читання коду, запуск лінтера)"] Decision -->|Критична: Write / Network| Confirm["Запит підтвердження в інженера
(Видалення файлів, деплой)"] ``` ### Matrice des niveaux de confiance :::tabs @tab Autorisé sans confirmation - Lecture des fichiers de code source et de la documentation. - Consultation des logs de build et des erreurs dans le terminal. - Lancement de tests unitaires isolés en mode lecture seule. - Génération de rapports analytiques et de tableaux. @tab Confirmation obligatoire requise - Modification des fichiers de configuration globale (`package.json`, `.env`). - Suppression ou écrasement de fichiers dans le repository. - Exécution de requêtes réseau ou envoi de données vers des APIs externes. - Création de commits ou push de modifications vers un repository Git distant. ::: > [!WARNING] > **Ne dupliquez pas les interdictions :** Évitez de répéter plusieurs fois des phrases telles que « ne modifie rien » dans chaque point. Il suffit de définir clairement une fois les opérations interdites au début de la section des restrictions ; sinon, l'agent deviendra excessivement passif et demandera confirmation même avant de lire un simple fichier. --- ## 10. Aide-mémoire final et checklist pour créer un Skill fiable Conservez cette checklist et référez-vous-y lors de la conception de chaque nouvelle compétence. ### Aide-mémoire rapide de l'ingénieur ```bash # ─── Робота з навичками в Codex ────────────────────────────────── $skill-creator # Запуск вбудованого майстра створення навичок $ <ваше завдання> # Явний детермінований виклик навички /skills # Перегляд списку доступних навичок у сесії # ─── Файлова структура проєкту ─────────────────────────────────── .codex/skills//SKILL.md # Проєктна навичка (для всієї команди) ~/.codex/skills//SKILL.md # Персональна навичка (для поточної машини) ``` ### Checklist de préparation d'une compétence pour la release - [ ] **Nom clair :** Moins de 64 caractères, en minuscules latines, séparé par des tirets (`kebab-case`). - [ ] **Description informative :** Le champ `description` contient une formule claire indiquant « ce que fait la compétence » et « quand elle doit être lancée ». - [ ] **Corps concis :** Texte synthétique respectant le principe de minimisation de l'empreinte contextuelle.