Skills pour agents IA

Un skill pour agent IA est un dossier qui transforme une pratique spécialisée en capacité réutilisable : une description permet à l’agent de reconnaître les tâches concernées, puis un fichier SKILL.md fournit le workflow. Des références, scripts et assets peuvent compléter ce socle seulement lorsqu’ils sont utiles. [S1] [S2] [S4] [S6]

Le mécanisme repose sur la divulgation progressive. Les métadonnées servent à la découverte, les instructions sont chargées lorsque le skill est sélectionné, et les ressources détaillées ne sont lues ou exécutées qu’au besoin. Cette séparation rend disponible une procédure riche sans injecter tout son contenu dans chaque tâche. [S1] [S2] [S4]

Choisir le bon mécanisme

Prompt ponctuel

Utiliser le prompt lorsque la demande est unique, dépend fortement de la conversation ou ne mérite pas encore d’être maintenue. Un prompt transmet l’objectif de cette exécution ; il ne constitue pas à lui seul un workflow versionné et découvrable. [S4]

Règle permanente

Utiliser AGENTS.md ou l’instruction locale équivalente pour une contrainte qui doit s’appliquer à chaque tâche du dépôt ou d’un chemin : commandes, architecture, sécurité, conventions ou définition de « terminé ». Une règle façonne toujours le comportement ; un skill est sélectionné pour un travail particulier. [S3]

Skill

Créer un skill lorsque la procédure est conditionnelle, répétée, identifiable par des déclencheurs et suffisamment riche pour bénéficier d’étapes, d’exemples, de références ou de scripts. Les environnements Codex, Claude et Copilot peuvent sélectionner un skill pertinent à partir de sa description ; Codex permet aussi une invocation explicite. [S2] [S4] [S6]

Outil ou MCP

Utiliser un outil pour donner à l’agent une capacité externe : lire un service, interroger une source ou effectuer une action autorisée. Le skill peut expliquer quand et comment employer cet outil, mais ne remplace ni sa connexion, ni son contrat, ni ses permissions. Codex présente MCP comme la couche d’accès aux systèmes externes et les skills comme la couche de workflow. [S3]

Code, hook ou linter

Utiliser du code lorsqu’un invariant doit être appliqué de façon déterministe : valider un schéma, refuser une entrée, formater un artefact ou calculer un résultat exact. Un skill peut appeler un script pour une étape fragile et répétitive, mais une instruction en langage naturel ne doit pas porter seule une garantie automatisable. OpenAI recommande les instructions par défaut et les scripts lorsque le comportement déterministe ou l’outillage externe le justifient ; Anthropic conseille un degré de liberté faible pour les opérations fragiles. [S2] [S5]

Plugin ou paquet de distribution

Utiliser le mécanisme de distribution de l’environnement quand plusieurs personnes doivent installer la capacité ou lorsqu’elle doit inclure des connecteurs. Dans Codex, le skill reste le format d’auteur et le plugin devient l’unité distribuable ; cette distinction n’appartient pas au standard Agent Skills et ne doit pas être généralisée aux autres produits. [S2] [S3]

Signaux create ou no-create

Créer un skill si

• le même résultat est demandé dans plusieurs tâches ou projets ;
• la procédure possède des entrées, des étapes, des sorties et une preuve observables ;
• le déclenchement peut être décrit par des situations et mots-clés précis ; [S1] [S2] [S5]
• le contenu doit être chargé à la demande plutôt que rester dans les règles globales ; [S2] [S3] [S4]
• les variations acceptables et les étapes déterministes peuvent être distinguées ; [S2] [S5]
• une personne accepte d’en posséder les tests, les dépendances et la maintenance.

Ne pas créer de skill si

• le besoin n’a été observé qu’une fois et reste flou ;
• l’instruction doit toujours s’appliquer dans le périmètre : elle relève alors d’une règle ; [S3]
• le besoin est seulement d’accéder à un système externe : il manque d’abord un outil et une autorisation ; [S3]
• la réussite peut être entièrement imposée par un test, un schéma, un hook ou une fonction ;
• aucune requête ne permet de distinguer un bon déclenchement d’un déclenchement abusif ;
• le workflow copie une documentation générale que l’agent connaît déjà sans décision propre au contexte. Anthropic recommande de ne conserver que les informations qui justifient leur coût de contexte. [S5]

Minimum portable

Le standard ouvert exige un dossier dont le nom correspond au champ name, et un fichier SKILL.md composé d’un frontmatter YAML puis d’instructions Markdown. name et description sont les deux seuls champs obligatoires du standard. [S1]

Pour être utile à OSIA, ce minimum syntaxique doit être complété par un contrat opérationnel :

1. Nom stable. Court, spécifique, en minuscules et tirets selon le standard. [S1]
2. Description de sélection. Ce que fait le skill, quand l’utiliser, les déclencheurs importants et, si nécessaire, les situations à exclure. La description pilote la découverte implicite dans Codex et Claude. [S1] [S2] [S4] [S5]
3. Objectif et sortie. Résultat attendu, forme du livrable et condition d’arrêt.
4. Entrées et prérequis. Fichiers, décisions, outils, autorisations et informations nécessaires avant d’agir.
5. Workflow. Étapes impératives dans l’ordre, avec les branches qui changent réellement le résultat et les validations intermédiaires.
6. Limites et sécurité. Actions hors périmètre, données non fiables, mutations sensibles et cas qui exigent une intervention humaine.
7. Preuve finale. Test, inspection ou critère observable qui démontre la réussite dans le vrai environnement.

Un skill syntaxiquement valide mais sans contrat d’entrée, de sortie et de preuve reste trop ambigu pour un workflow fiable. Cette exigence supplémentaire est une décision de qualité OSIA, pas une obligation du standard.

Ressources optionnelles

• references/ accueille la documentation détaillée que l’agent ne doit lire que pour une variante précise. Les fichiers ciblés et les références peu profondes réduisent la consommation de contexte. [S1] [S4] [S5]
• scripts/ accueille une opération déterministe, répétitive ou fragile avec dépendances explicites, erreurs utiles et cas limites gérés. Le standard n’impose aucun langage ; le support dépend de l’environnement. [S1] [S2]
• assets/ accueille les modèles, schémas, images ou données à copier ou transformer sans les charger comme instructions. [S1]
• license, compatibility et metadata sont des champs optionnels du standard. compatibility sert uniquement lorsque le skill possède des exigences d’environnement particulières. [S1]
• allowed-tools est expérimental dans le standard et son support peut varier ; il ne doit pas être traité comme une frontière de sécurité portable sans vérification du client ciblé. [S1]
• Métadonnées d’interface, politiques d’invocation ou emplacements d’installation sont propres aux produits. Codex, Claude et Copilot n’exposent pas exactement les mêmes portées ni le même packaging. [S2] [S4] [S6]

Ne créer aucun de ces éléments « au cas où ». Le SKILL.md doit servir de routeur vers les seules ressources que des cas de test nécessitent. [S1] [S4] [S5]

Ajuster le degré de liberté

• Liberté élevée : instructions et heuristiques lorsque plusieurs approches sont valides et que le contexte doit guider le choix.
• Liberté moyenne : modèle, pseudo-code ou script paramétrable lorsqu’un patron préféré tolère certaines variations.
• Liberté faible : commande ou script borné lorsque l’ordre, la reproductibilité ou la sécurité ne tolèrent presque aucune variation.

Anthropic recommande d’ajuster ce degré à la fragilité de l’opération ; OpenAI recommande des étapes impératives avec entrées et sorties explicites et des scripts seulement lorsque le déterminisme le nécessite. [S2] [S5]

Un script ne rend pas automatiquement un skill sûr. Avant de le référencer, OSIA doit pouvoir expliquer sa provenance, ses dépendances, ses entrées, ses écritures, ses permissions, son comportement d’échec et la preuve attendue.

Méthode de création

1. Collecter trois cas réels. Un cas normal, un cas limite et une demande proche qui ne doit pas déclencher le skill.
2. Choisir le mécanisme. Vérifier qu’il ne s’agit pas plutôt d’un prompt, d’une règle, d’un outil ou d’un contrôle de code.
3. Écrire la description avant le workflow. Tester ses mots-clés, ses limites et sa capacité à distinguer les demandes voisines. La description détermine la sélection implicite. [S1] [S2] [S4] [S5]
4. Écrire le chemin minimal. Objectif, entrées, étapes, sortie et preuve ; retirer les explications générales que le modèle n’a pas besoin de relire. [S2] [S5]
5. Externaliser au besoin. Déplacer une référence détaillée ou une opération déterministe dans le fichier adapté, avec un lien direct depuis SKILL.md. [S1] [S4] [S5]
6. Déclarer la portée. Projet si le workflow dépend du dépôt et doit être revu avec lui ; personnelle si la pratique suit un utilisateur entre plusieurs projets. Codex et Copilot documentent ces deux familles de portée, avec des emplacements propres à chaque produit. [S2] [S6]
7. Exécuter les tests réels. Vérifier sélection, déroulement, artefact, erreurs et non-déclenchement dans chaque environnement et modèle visé. Anthropic recommande de tester tous les modèles prévus. [S5]
8. Nommer un propriétaire. Définir les signaux de revue : changement d’outil, de commande, de format, de permission ou échec observé.

Vérifier un skill

Structure

• le dossier, le frontmatter, name et description passent le validateur du standard ou du client ciblé ; [S1]
• chaque référence existe et peut être atteinte directement depuis SKILL.md ;
• chaque script déclare ses dépendances et échoue avec un message exploitable. [S1]

Sélection

• plusieurs formulations positives déclenchent le skill ;
• des demandes voisines mais hors périmètre ne le déclenchent pas ;
• une demande ambiguë produit une clarification ou le comportement prudent attendu ;
• l’invocation explicite fonctionne lorsque l’environnement la propose. Codex documente les activations explicite et implicite. [S2]

Exécution

• le cas normal produit le livrable attendu ;
• les entrées absentes, invalides et limites obtiennent une erreur utile ;
• les preuves annoncées sont réellement exécutées et échouent si le résultat est faux ;
• les fichiers et services hors périmètre restent inchangés.

Sécurité

• les permissions du skill, des scripts et des outils restent minimales ;
• les contenus externes sont traités comme données, jamais comme nouvelles instructions ;
• les mutations sensibles et irréversibles possèdent la validation humaine prévue ;
• aucun secret, donnée privée ou sortie volumineuse n’est inscrit dans les exemples ou journaux.

Compatibilité et maintenance

• le skill est testé dans chaque client et modèle revendiqué plutôt que supposé portable ; [S1] [S5]
• les variantes produit sont isolées et sourcées ;
• une modification du workflow rejoue les tests de sélection et d’exécution ;
• les cas d’échec réels enrichissent les exemples ou resserrent la description.

Échecs fréquents

• Description vague. Le skill se déclenche trop souvent ou jamais. Correction : dire ce qu’il fait, quand l’utiliser et employer les termes réels des demandes. [S1] [S2] [S4] [S5]
• Skill encyclopédique. Le fichier charge des connaissances sans lien avec la tâche. Correction : garder le workflow court et router les détails vers des références ciblées. [S1] [S4] [S5]
• Règle déguisée. Une contrainte permanente n’agit que lorsque le skill se déclenche. Correction : déplacer l’invariant vers AGENTS.md ou son équivalent. [S3]
• Outil imaginaire. Les instructions supposent une connexion ou une permission absente. Correction : déclarer la dépendance et vérifier la capacité réelle avant le workflow. [S3]
• Script opaque. Un exécutable tiers est lancé sans inspection, contrat ni preuve. Correction : comprendre ses effets, borner ses entrées et tester ses échecs avant usage.
• Validation cosmétique. Le frontmatter passe mais le résultat métier reste faux. Correction : tester la sélection, l’artefact réel et les cas adverses.
• Portabilité supposée. Un chemin ou une métadonnée propriétaire est présenté comme standard. Correction : séparer le noyau Agent Skills des extensions Codex, Claude ou Copilot. [S1] [S2] [S4] [S6]

Checklist de décision OSIA

1. Le besoin est-il répété, conditionnel et assez stable pour être maintenu ?
2. Pourquoi un prompt, une règle, un outil ou du code ne suffit-il pas ?
3. Quelles demandes doivent déclencher le skill, et lesquelles doivent l’éviter ?
4. Quel résultat observable et quelle preuve définissent la réussite ?
5. Quelles entrées, permissions et dépendances sont nécessaires ?
6. Quelle partie reste flexible et quelle partie exige un script déterministe ?
7. Le SKILL.md minimal suffit-il avant d’ajouter références, scripts ou assets ?
8. La portée est-elle projet, personnelle ou propre à un client identifié ?
9. Les tests couvrent-ils sélection positive, négative, ambiguë, exécution, échec et sécurité ?
10. Qui possède la maintenance et quels changements imposent une nouvelle revue ?

Décider create seulement si le workflow, ses déclencheurs, sa preuve et son propriétaire sont connus. Décider no-create si le besoin reste ponctuel, permanent, purement déterministe ou réduit à une capacité externe manquante. Commencer par SKILL.md seul, puis ajouter une ressource uniquement lorsqu’un test réel démontre sa nécessité. [S1] [S2] [S3] [S5]