# Rédaction et tests des modèles pour SKILL.md : guide d'ingénierie complet > Guide professionnel du développement de compétences pour les agents IA : les 4 sections obligatoires de SKILL.md, la synchronisation entre Codex et Claude Code, les modèles de composition, les 5 tests essentiels et la protection contre les régressions. ## 1. Architecture et sections obligatoires du fichier SKILL.md Le fichier **SKILL.md** est un outil d'ingénierie qui transforme un modèle de langage généraliste en ingénieur spécialisé prêt à exécuter un type de tâche réglementé. Il ne duplique pas les invariants globaux du projet, mais y ajoute une connaissance procédurale étroite et hautement spécifique. Avant de créer une compétence pour votre propre dépôt, étudiez impérativement le fichier de configuration des règles du projet (`AGENTS.md` ou `CLAUDE.md`). Ces documents système sont la source absolue de vérité pour les règles critiques de sécurité et les commandes de build. La mission de la Skill est d'apprendre à l'agent la structure et la séquence des étapes, en référençant les règles système plutôt qu'en les copiant. ```mermaid flowchart TD subgraph Structure ["Чотири обов'язкові компоненти якісного SKILL.md"] F["1. Description у Frontmatter
(Формулюється строго як УМОВА, а не тема)"] T["2. When to Trigger
(Точні контекстні критерії та ключові слова)"] P["3. Procedure
(Нумеровані кроки з реальними командами й шляхами)"] Pit["4. Pitfalls & Anti-Patterns
(Дія + Наслідок + Точне виправлення)"] end F --> T --> P --> Pit ``` ### Analyse détaillée des sections obligatoires 1. **Description dans le Frontmatter :** C'est le seul bloc de texte que l'agent lit avant de décider de charger la compétence. Elle doit être formulée comme une condition d'activation prédicative (« Utilisez quand... »), et non comme un titre de sujet abstrait. 2. **When to trigger (Quand activer) :** Une liste exhaustive des requêtes directes, des erreurs dans les logs ou des opérations git déclenchant obligatoirement la compétence. 3. **Procedure (Procédure réglementée) :** Un algorithme numéroté avec les noms exacts des commandes locales et les chemins validés vers les fichiers. 4. **Pitfalls (Pièges) :** Catalogue des incidents passés. Chaque entrée suit la formule : *Action erronée spécifique* → *Défaillance technique précise* → *Recette de correction*. > [!NOTE] > Si la compétence se termine par une procédure de release ou de déploiement, ne dupliquez pas le pipeline lui-même dans la compétence. Terminez plutôt l'algorithme par l'instruction : « Lancez la compétence ship-pipeline ». --- ## 2. Structure de placement : synchronisation entre Codex et Claude Code Dans les workflows modernes, les développeurs utilisent souvent plusieurs clients simultanément (par exemple, **OpenAI Codex** dans le terminal ou l'IDE et **Claude Code**). Les deux runtimes supportent la spécification ouverte des compétences, mais s'attendent à les trouver dans des répertoires différents du projet. ![Chemins de placement des fichiers de compétences pour les runtimes Codex et Claude Code](/api/guides-media/ai_agents/testing-and-writing-skill-md-patterns-guide/images/testing-and-writing-skill-md-patterns-guide-extra-01.webp) ### Matrice des chemins pour les runtimes | Runtime / Agent | Chemin cible du fichier SKILL.md | Spécificités de détection | | :--- | :--- | :--- | | **OpenAI Codex** | `.agents/skills//SKILL.md` | Lu par l'agent Codex lors du scan des outils locaux | | **Anthropic Claude Code** | `.claude/skills//SKILL.md` | Lu par Claude Code lors de l'initialisation de l'environnement de session | > [!IMPORTANT] > **Exigence de double synchronisation :** Si une compétence n'est ajoutée que dans `.claude/skills/`, elle sera totalement invisible pour les agents Codex, et inversement. Créez et maintenez toujours la compétence dans les deux répertoires ou configurez des liens symboliques (symlinks). --- ## 3. Critères de maturité et validation d'une compétence brute Avant de soumettre une compétence au dépôt d'équipe, évaluez-la selon une échelle d'ingénierie standardisée : - **Falsifiabilité du trigger :** Vous pouvez citer au moins 2 requêtes adjacentes dans le même domaine où la compétence **NE DOIT PAS** se déclencher. - **Audit des commandes :** Chaque commande exécutable dans la procédure existe dans la section Local Commands du fichier système `AGENTS.md`. - **Pièges factuels :** Chaque point dans la section Pitfalls décrit un incident réel issu de la pratique, et non une mise en garde générale du type « soyez prudent ». - **Compacité du contexte :** La lecture du texte de la compétence prend moins de 2–3 minutes (jusqu'à 500 lignes). - **Zéro duplication :** Aucun paragraphe ne copie les règles générales de `AGENTS.md`. ```mermaid flowchart LR Draft["Чорновий Skill
(Розмитий опис, копії правил, абстрактні кроки)"] --> Review{"Валідація чернетки"} Review -->|Виявлено недоліки| Fix["Виправлення формулювань і команд"] Fix --> Review Review -->|Всі критерії виконано| Prod["Production-Ready Skill"] ``` --- ## 4. Patterns de composition : routeurs, références et chaînes Les workflows réels sont rarement isolés dans un seul fichier. Tenter de tout décrire dans un `SKILL.md` monolithique conduit à un gonflement du contexte et à une baisse de l'attention du modèle. Utilisez trois patterns architecturaux éprouvés : ### Pattern 1 : Entry Router (Skill-routeur) Une compétence globale agit comme une carte de routage. Elle analyse l'intention de l'utilisateur et délègue la tâche aux sous-compétences spécialisées : ```text Requête : « Optimisez les performances des requêtes de base de données » └── db-router (Entry Router) ├── Redirige vers : neon-migrations (si des modifications de structure sont nécessaires) └── Redirige vers : drizzle-index-optimizer (si des index sont nécessaires) ``` ### Pattern 2 : Fichiers Reference Le fichier principal `SKILL.md` contient uniquement l'algorithme de haut niveau, tandis que les détails complexes, tableaux et grammaires sont externalisés dans le répertoire `references/` : ```text .claude/skills/fleet-coordinator/ ├── SKILL.md # Pipeline d'orchestration concis └── references/ ├── agent-roles.md # Description des spécialisations et matrice des rôles └── file-ownership.md # Règles de prévention des conflits d'écriture ``` ### Pattern 3 : Skill Chain (Chaîne de compétences) Les compétences se référencent mutuellement comme étape logique suivante via le champ `relatedPaths` ou une directive textuelle : ```markdown Après une validation réussie du schéma, lancez impérativement la compétence drizzle-migration-runner. ``` --- ## 5. Stratégies de refactoring : quand diviser, quand fusionner les compétences Le choix entre la division et la consolidation des compétences détermine la robustesse de votre système d'automatisation. :::tabs @tab Diviser une compétence - **Conditions de déclenchement distinctes :** Les scénarios nécessitent des configurations opposées (par exemple, audit de code sans droit d'écriture vs migration de base de données avec modification directe du schéma). - **Surfaces produit différentes :** La compétence tente de réguler simultanément le landing page (design-code, Tailwind) et le serveur backend (NestJS, SQL). - **Surcharge du contexte :** Le volume de texte dépasse 500 lignes et l'agent commence à confondre les étapes. @tab Fusionner des compétences - **Lien indissociable :** Deux micro-compétences ne sont jamais appelées séparément, et l'exécution de l'une sans l'autre n'a aucun sens pratique. - **Duplication de code :** La division entraîne la duplication du même bloc de vérifications dans deux fichiers. ::: > [!TIP] > Dans 90 % des cas, la bonne décision est la **division**. Tenter de créer une « compétence universelle pour tout le backend » se transforme inévitablement en un monolithe inefficace avec un taux élevé d'hallucinations. --- ## 6. Contrat de versioning et pipeline de build des compétences phares Dans les bases de code complexes, les compétences se divisent en trois niveaux technologiques selon leur mode de distribution et de build : ![Matrice de build et de placement des différents types de compétences dans le système](/api/guides-media/ai_agents/testing-and-writing-skill-md-patterns-guide/images/testing-and-writing-skill-md-patterns-guide-extra-02.webp) | Type de compétence | Où éditer le code source | Pipeline de build | Finalité | | :--- | :--- | :--- | :--- | | **Compétence de dépôt (privée)** | `.agents/skills//SKILL.md` + `.claude/skills//SKILL.md` | **Non requis** (lu directement) | Règles internes de l'équipe pour le projet courant | | **Phare public (multi-fichiers)** | `skills-source//` + métadonnées dans le script de génération | `node scripts/build-flagship-skills.mjs skills-source/` | Solutions modulaires complexes avec fichiers reference pour le marketplace | | **Public mono-fichier** | `baseSkills` dans `lib/library/skills.ts` | **Non requis** | Compétences légères de base pour le catalogue de la plateforme | > [!WARNING] > **Interdiction de l'édition manuelle des fichiers générés :** Ne modifiez jamais manuellement le fichier compilé d'une compétence phare. Toutes les modifications doivent être apportées exclusivement dans le dossier source `skills-source//` suivi de l'exécution du script de compilation. --- ## 7. Méthodologie de test : cinq vérifications qualité obligatoires Rédiger une instruction n'est que le début. Pour que la compétence fonctionne de manière fiable en production, elle doit passer successivement 5 étapes de test : ```mermaid flowchart TD T1["1. Trigger Probe
(3 позитивні + 2 негативні запити)"] --> T2["2. Procedure Walk-Through
(Наскрізний запуск на реальному репозиторії)"] T2 --> T3["3. Pitfall Audit
(Перевірка формули: Дія + Збій + Фікс)"] T3 --> T4["4. Scope Test
(Перевірка єдиної відповідальності одним реченням)"] T4 --> T5["5. Staleness Check
(Звірка команд і шляхів з актуальним репозиторієм)"] T5 --> Ready["Схвалено до коміту"] ``` ### Détails du protocole de test 1. **Trigger Probe (Vérification du trigger) :** Formulez 3 requêtes devant activer la compétence et 2 requêtes devant être rejetées. Vérifiez si la description dans le frontmatter distingue clairement ces cas. 2. **Procedure Walk-Through (Parcours manuel) :** Exécutez chaque étape manuellement sur un environnement vivant. Si vous manquez de données d'entrée pour une étape, une condition importante manque dans la compétence. 3. **Pitfall Audit (Audit des défaillances) :** Assurez-vous que chaque piège décrit s'est réellement produit en pratique et que la méthode de résolution proposée est opérationnelle. 4. **Scope Test (Test de focalisation) :** Formulez la finalité de la compétence en une seule phrase simple. Si la phrase nécessite la conjonction « ainsi que », la compétence doit être divisée en deux parties. 5. **Staleness Check (Contrôle de fraîcheur) : Comparez chaque commande CLI avec la configuration actuelle du dépôt et les versions actuelles des dépendances. --- ## 8. Anatomie des anti-patterns : distinguer une compétence fonctionnelle d'un brouillon La comparaison des erreurs typiques permet de réaliser rapidement un auto-audit avant de sauvegarder une compétence. | Indicateur | Brouillon (Draft) | Compétence prête pour la production (Ready) | | :--- | :--- | :--- | | **Formulation du trigger** | Décrit un sujet large : *« Pour travailler avec la base de données »* | Définit une condition précise : *« Utiliser lors de la création de migrations Drizzle »* | | **Description des étapes** | Instructions vagues : *« lancez le linter si nécessaire »* | Commandes claires : *« lancez npm run lint:fix »* | | **Description des risques** | Souhait général : *« soyez prudent avec les fichiers »* | Défaillance concrète : *« git add sur un chemin inexistant interrompra le staging »* | | **Sources des règles** | Copie le texte de `AGENTS.md` dans son contenu | Contient un lien direct vers la section dans `AGENTS.md` | | **Synchronisation** | Créée uniquement dans `.claude/skills/` | Synchronisée dans `.agents/` et `.claude/` simultanément | --- ## 9. Prévention des pièges : éviter la duplication de AGENTS.md Le piège le plus sournois lors du développement de compétences est la duplication des invariants globaux du projet (par exemple, les règles contre les tirets longs, les exigences sur les coins arrondis en CSS ou l'interdiction du push direct sur main). ```text Pourquoi la duplication détruit le système : 1. L’ingénieur copie une règle du fichier AGENTS.md dans le corps du fichier SKILL.md. 2. Un mois plus tard, le comité d’architecture met à jour cette règle dans AGENTS.md. 3. Une formulation obsolète reste présente dans SKILL.md. 4. L’agent reçoit deux signaux système contradictoires et commence à halluciner. ``` ### Indexation sécurisée des changements dans Git Lors de l'exécution des procédures de commit dans les compétences, appliquez toujours une vérification de l'existence des chemins avant l'ajout au staging : ```bash # Небезпечно (якщо файл відсутній, вся команда переривається з помилкою): git add src/generated/schema.ts src/types/db.ts # Безпечно (додаються лише реально існуючі файли): [ -e src/generated/schema.ts ] && git add src/generated/schema.ts [ -e src/types/db.ts ] && git add src/types/db.ts ``` --- ## 10. Checklist finale de préparation à la production Avant de figer la compétence créée dans Git, vérifiez l'accomplissement de chaque point : - [ ] La compétence est synchronisée dans les deux répertoires : `.agents/skills//SKILL.md` et `.claude/skills//SKILL.md`. - [ ] Le champ `description` commence par « Utilisez quand... » et définit des limites d'activation claires. - [ ] Les 5 étapes du protocole de test (Trigger, Procedure, Pitfall, Scope, Staleness) ont été réussies. - [ ] Le texte ne contient aucune phrase marqueur d'incertitude (« si nécessaire », « de manière appropriée »). - [ ] Toutes les commandes console ont été testées dans le terminal vivant du projet. - [ ] Les invariants globaux sont présentés comme des références, non des copies.