Parlons de votre projet
Aller au contenu
Toutes les publications

Écrire un SKILL.md : méthode et gouvernance pour les agents

Par Docteur en intelligence artificielle · Conseil, conception de systèmes et formation

Agent SkillsSKILL.mdCopilot StudioGouvernance IA27 octobre 202611 min

Une skill utile doit être sélectionnée au bon moment, produire un résultat vérifiable et pouvoir être retirée. Voici une méthode de rédaction, de recette et de gouvernance.

Illustration de l’article « Écrire un SKILL.md : méthode et gouvernance pour les agents »

Un fichier SKILL.md est le point d’entrée d’une procédure réutilisable par un agent : un en-tête YAML décrit sa fonction, puis un corps Markdown indique comment l’exécuter. Savoir écrire ce fichier suppose de traiter ensemble sa sélection, ses instructions et ses limites. La bonne question est aussi de savoir quand il doit être utilisé, comment reconnaître son activation et qui répond de ses changements.

La méthode proposée part d’un exemple illustratif de compte rendu, sans publication ni transmission automatique. Elle s’applique à la préparation d’une skill d’entreprise, puis à sa recette dans l’environnement retenu. Les capacités de téléversement décrites ici concernent les agents Copilot Studio utilisant le harnais GitHub Copilot ; les recommandations de gouvernance sont des choix d’organisation à formaliser.

Que faut-il mettre dans un fichier SKILL.md ?

Un SKILL.md conforme commence par un frontmatter YAML contenant name et description, puis expose en Markdown la procédure et le résultat attendu pour la tâche.

La spécification officielle impose uniquement ces champs dans l’en-tête. Le nom doit correspondre exactement au dossier parent. Pour cet exemple, le fichier serait placé dans `compte-rendu-reunion/SKILL.md`. Le code suivant est un exemple minimal de procédure, à adapter aux règles du service concerné.

Champ obligatoireContraintes exactes
`name`De 1 à 64 caractères : lettres minuscules de a à z, chiffres et traits d’union ; aucun trait d’union initial, final ou consécutif ; nom identique au dossier
`description`De 1 à 1 024 caractères ; indique ce que fait la skill et quand l’utiliser

```markdown
---
name: compte-rendu-reunion
description: >-
Prépare un projet de compte rendu à partir de notes ou d’une
transcription fournie. À utiliser après une réunion pour structurer
décisions, actions, responsables et points à confirmer.
---
# Préparer le compte rendu
1. Lis uniquement les notes ou la transcription fournies.
2. Sépare décisions explicites, actions attribuées et incertitudes.
3. Marque « À confirmer » toute information absente ou ambiguë.
4. Produis un projet en Markdown pour relecture humaine.
5. Attends une demande explicite avant toute transmission.
```

Les champs optionnels sont `license`, `compatibility`, `metadata` et `allowed-tools`. La compatibilité, si renseignée, comporte au plus 500 caractères ; `allowed-tools` est expérimental. Les dossiers conventionnels `scripts/`, `references/` et `assets/` accueillent respectivement code, documentation et ressources. Un fichier minimal n’a pas besoin de ces dossiers vides.

Comment écrire une description qui déclenche au bon moment ?

Une description utile associe une opération précise, des entrées reconnaissables et les situations d’emploi, afin que l’agent puisse sélectionner la skill avant de lire sa procédure.

Au démarrage, l’agent voit le nom et la description, pas toutes les instructions. La description porte donc l’essentiel de l’aiguillage. Exemple faible : « Aide avec les PDF ». Exemple plus utile : « Extrait le texte et les tableaux de PDF fournis pour préparer une synthèse documentaire ; à utiliser quand une demande porte sur l’analyse de ces fichiers. » Le second énonce une action et un contexte, sans prétendre résoudre toute demande documentaire.

Rédiger une bonne description demande aussi de reconnaître les frontières. La skill de compte rendu ne devrait pas s’activer pour écrire une invitation à une réunion. Je recommande de comparer les descriptions voisines avant d’allonger les instructions : des périmètres qui se recouvrent rendent la sélection difficile à interpréter. La définition de l’agent IA et de ses composants aide à distinguer le choix d’une procédure de la production du résultat. Les essais doivent porter sur les deux.

Quand choisir une skill plutôt que des instructions permanentes ?

Une skill convient à une procédure liée à certaines tâches ; une instruction permanente convient à une règle générale qui doit rester applicable dans chaque interaction.

Le billet officiel sur Visual Studio distingue explicitement ces usages : les instructions personnalisées sont toujours actives, tandis que le modèle décide de la pertinence d’une skill. Une convention générale de rédaction peut donc relever des instructions. Préparer un compte rendu selon un modèle, traiter ses incertitudes et organiser sa relecture forme une procédure spécialisée.

Les contraintes transversales doivent en outre être soutenues par les droits et contrôles de l’environnement. Placer une règle essentielle uniquement dans une skill expose au cas où celle-ci ne s’active pas. Définir le périmètre avant l’autonomie de l’agent permet de répartir règles générales, procédures métier et permissions effectives. Cette répartition doit être compréhensible pour le relecteur : où se trouve la règle, dans quelles situations intervient-elle, et par quel moyen vérifie-t-on son respect ?

La description sélectionne une procédure dont les instructions mobilisent seulement les ressources nécessaires.
La description choisit le contexte d’emploi ; le corps du fichier explique le travail attendu.

Comment créer une skill dans Copilot Studio ?

Pour créer une skill dans un agent Copilot Studio utilisant le harnais GitHub Copilot, on peut téléverser un fichier, partir de zéro ou faire générer les instructions.

La présentation Microsoft des skills documente ces méthodes. Pour importer l’exemple, ouvrir l’agent, puis l’onglet Build, le composant Skills et l’option de téléversement. Microsoft accepte un Markdown avec nom et description en frontmatter YAML, ou un ZIP contenant `SKILL.md` et ses éventuels fichiers annexes. Le choix dépend donc du contenu à transmettre, pas de la longueur souhaitée pour la procédure.

La documentation du téléversement prévoit aussi le téléchargement en Markdown et le remplacement de la skill. Conserver le paquet source complet reste utile lorsque des annexes existent. Cette étape d’import ne vaut pas recette. La construction, l’utilisation, les tests et l’évaluation de l’agent relèvent de la facturation à l’usage en Copilot Credits documentée pour ce harnais : le responsable des essais doit suivre la consommation sans lui attribuer un coût supposé.

Comment tester qu’une skill est chargée et réellement activée ?

La recette doit établir que la skill est présente, qu’elle s’active sur les demandes prévues et que son résultat respecte les critères métier définis.

Une réponse bien rédigée ne constitue pas cette preuve. Microsoft documente un échec au chargement qui peut rester silencieux : la skill est ignorée tandis que l’agent charge le reste. Il faut donc observer explicitement la capacité sélectionnée dans les traces disponibles et vérifier l’application de ses étapes distinctives. Si l’environnement ne permet pas d’attester l’activation, conserver cette limite dans le compte rendu de recette.

  1. Vérifier la présence de la skill enregistrée et l’intégrité des fichiers attendus.
  2. Soumettre une demande correspondant à la description et relever les éléments attestant l’activation.
  3. Soumettre une demande voisine qui ne devrait pas déclencher cette procédure.
  4. Tester une entrée incomplète pour observer le signalement des incertitudes et l’arrêt prévu.
  5. Comparer le livrable aux critères métier et conserver les observations avec la version testée.

Ces étapes constituent une méthode proposée, à renseigner dans la grille de recette d’un agent IA. Pour le compte rendu, vérifier notamment que les responsables absents restent à confirmer. Conserver les demandes, les documents d’entrée et les résultats permet de rejouer les essais lors d’un remplacement.

Pourquoi une skill peut-elle être ignorée ou mal exécutée ?

Une skill peut être ignorée à cause de son format ou se charger avec des ressources incomplètes ; ces situations imposent des vérifications différentes.

Microsoft cite le YAML invalide, l’absence de nom ou de description, une description dépassant la capacité du catalogue présenté au modèle, les noms en doublon et un `SKILL.md` illisible, notamment à cause d’un encodage non UTF-8. S’y ajoutent un fichier de ressource non écrit ou un paquet rejeté par la validation structurelle. La limite de 1 024 caractères du standard ne dispense donc pas de vérifier l’acceptation réelle dans le produit.

Le cas des annexes partiellement écrites mérite un contrôle séparé : la skill peut se charger, mais ne plus disposer du contenu auquel ses instructions renvoient. Pour diagnostiquer un écart, vérifier d’abord l’installation, puis les ressources, puis le comportement. Les principes de migration d’un agent sans régression s’appliquent à ce remplacement. Conserver le paquet précédent et les mêmes cas de recette aide à isoler ce qui a changé, au lieu de réécrire immédiatement toute la procédure.

Circuit proposé de revue, d’autorisation, de recette et de retrait d’une skill en entreprise.
Une version n’est autorisée qu’avec un propriétaire, une revue et des résultats de recette conservés.

Qui doit autoriser une skill dans un agent d’entreprise ?

L’entreprise doit désigner qui peut téléverser une skill, qui valide sa procédure et qui autorise son usage avec les données et outils concernés.

Cette répartition relève de la gouvernance proposée ici. Le rédacteur prépare la méthode ; un responsable métier vérifie les critères de sortie et les situations d’arrêt ; un relecteur technique examine scripts, dépendances et permissions. L’administrateur chargé de l’agent applique les accès décidés. Les responsabilités peuvent être adaptées à l’organisation, mais l’autorisation doit porter sur une version identifiable et un périmètre précis.

Une modification de description peut changer les demandes qui déclenchent la skill. Elle mérite donc une revue même si les instructions restent identiques. Le cadre des plugins Copilot : recette, droits et retrait aide à poser les questions d’autorisation et de réversibilité. Un catalogue interne devrait rendre visibles le propriétaire, la version autorisée, les outils nécessaires, les tests réalisés et le moyen de signaler un défaut. La personne qui constate un écart doit savoir à qui le transmettre.

Pourquoi traiter une skill externe comme du code tiers ?

Une skill externe doit être examinée comme du code tiers parce que ses instructions orientent l’agent et que son paquet peut contenir des scripts exécutables.

La validation du YAML ou de l’encodage ne démontre pas que les actions demandées respectent le mandat. La revue doit lire les instructions, les ressources référencées et le code, puis identifier les accès nécessaires. Vérifier aussi la provenance et les conditions de réutilisation. Le champ expérimental `allowed-tools` exprime des outils préapprouvés ; sa présence ne remplace pas le contrôle des permissions effectives dans l’environnement.

Je recommande des essais sur des données adaptées au test, avec les accès nécessaires à la tâche, puis une autorisation explicite de la version retenue. Le hub sécurité des agents IA donne le cadre d’ensemble ; la recette de sécurité d’une migration MCP apporte des questions utiles sur les connexions et les droits. Une procédure externe doit pouvoir être expliquée par son propriétaire interne avant de rejoindre le catalogue autorisé.

Comment versionner, remplacer ou retirer une skill ?

Chaque changement de skill devrait relier une version du paquet, une décision d’autorisation et des résultats de recette, avec un chemin de retrait vérifiable.

Conserver le fichier principal avec ses annexes évite de séparer une instruction de la référence qu’elle suppose. Lors d’un remplacement, rejouer les demandes prévues et les demandes voisines ; documenter ce qui change dans les résultats. Préparer le retour à la version précédente avant d’autoriser la nouvelle. Ce sont des règles de méthode, à adapter au circuit de changement de l’entreprise.

Le retrait doit lui aussi être testé : vérifier que la capacité retirée ne s’active plus et que les autres tâches attendues restent exécutables. Informer les responsables des procédures dépendantes et consigner la décision permet de comprendre une absence ultérieure. Une formation IA peut s’appuyer sur cette boucle complète, de l’écriture au retrait. Le livrable utile est alors une procédure maintenue avec ses preuves de fonctionnement, son propriétaire et ses limites connues.

Questions fréquentes

Quels champs sont obligatoires dans SKILL.md ?

Seuls name et description sont obligatoires dans le frontmatter YAML. Le nom suit les contraintes du standard et correspond au dossier parent ; la description indique la fonction de la skill et ses situations d’emploi.

Une description longue déclenche-t-elle mieux une skill ?

La longueur ne suffit pas. La description doit rendre reconnaissables l’opération, les entrées et le contexte. Elle reste soumise à la limite du standard et à l’acceptation du catalogue du produit utilisé.

Quelle différence entre une skill et les instructions d’un agent ?

Les instructions générales définissent le comportement transversal. Une skill porte une procédure spécialisée sélectionnée pour certaines demandes. Dans Visual Studio, les premières sont toujours actives et les secondes sont chargées selon leur pertinence.

Pourquoi mon agent répond-il sans utiliser ma skill ?

La demande peut ne pas correspondre à sa description, ou la skill peut avoir échoué au chargement. Copilot Studio peut l’ignorer tout en chargeant le reste de l’agent. Il faut vérifier présence, activation et ressources.

Faut-il ajouter des scripts à une skill ?

Les scripts sont facultatifs. Commencer avec des instructions suffit pour l’exemple présenté. Ajouter du code suppose de revoir ses dépendances, ses droits et ses effets, puis de tester le paquet complet.

Qui doit relire une skill avant son utilisation en entreprise ?

La méthode proposée associe une revue métier et une revue technique, puis une autorisation sur une version précise. Le propriétaire conserve les résultats de recette et organise les corrections comme le retrait.

Sources

Analyse et méthode proposées par Anand Candassamy au 27 octobre 2026.

Votre prochain projetParlons-en.Réserver un échange de 15 minutes sur Cal.com, dans un nouvel onglet