Comment écrire des fichiers SKILL.md et des descriptions d'outils en Markdown pour les agents d'IA

Les assistants d'IA deviennent beaucoup plus utiles lorsqu'ils peuvent suivre des consignes stables, charger des connaissances spécifiques à un domaine et utiliser des outils système de manière sécurisée. Le Markdown est le format idéal pour cette couche opérationnelle car il est facile à lire pour les humains, compatible avec le contrôle de version sous Git et structuré de façon logique tant pour les personnes que pour les modèles.

Cet article explique comment rédiger des fichiers SKILL.md en Markdown, des instructions d'agent et des descriptions d'outils système. L'objectif n'est pas d'allonger inutilement les prompts, mais de rendre les capacités plus faciles à découvrir, à comprendre et à exécuter par l'agent d'IA au bon moment.

Qu'est-ce qu'un fichier SKILL.md ?

Un fichier SKILL.md est un document d'instructions rédigé en Markdown qui décrit une capacité réutilisable. Dans des systèmes d'agents comme Claude Code de chez Anthropic, les compétences (skills) sont des artefacts stockés dans un répertoire dédié, et chaque compétence est définie par un fichier SKILL.md. Le concept sous-jacent est similaire à travers les différents frameworks d'agents : un document court et structuré indique à l'agent quand utiliser une capacité, quel flux de travail appliquer et où se situent les scripts ou références de support.

Le modèle mental à suivre est très simple :

Un prompt standard indique à l'IA ce qu'elle doit faire à l'étape courante.
Une compétence (Skill) apprend à l'IA comment accomplir de manière répétée une catégorie entière de tâches.
Une description d'outil indique à l'IA quand et comment appeler une fonction système ou une API externe spécifique.

Le Markdown est un excellent choix car une compétence se compose principalement de consignes, d'exemples de mise en œuvre, de contraintes et de liens vers des fichiers de support.

Pourquoi le Markdown est adapté aux compétences des agents

Les instructions d'un agent doivent s'adresser à deux lecteurs : le modèle d'IA et le mainteneur humain. Le Markdown prend soin de ces deux publics.

Pour l'IA, les titres et les listes isolent les déclencheurs d'activation, les étapes du flux de travail, les contraintes, les exemples d'application et la gestion des cas d'erreur. Pour les humains, le même fichier peut être relu dans Git, modifié dans n'importe quel éditeur de texte standard et documenté directement à côté du code source de l'application.

C'est essentiel pour les compétences et les outils, car des instructions floues peuvent engendrer des erreurs critiques dans les flux automatisés. Une compétence mal définie peut s'activer au mauvais moment. Une description d'outil vague peut conduire le modèle à appeler une API avec des paramètres incorrects. Une consigne de sécurité oubliée peut amener l'agent à exécuter des modifications sur le système avant d'avoir réuni des preuves suffisantes.

Différence entre compétences et descriptions d'outils

Les compétences et les outils sont liés, mais ils répondent à des besoins distincts :

| Élément | Objectif | Exemple | |---|---|---| | Compétence (Skill) | Enseigner un flux de travail réutilisable ou une procédure opérationnelle standard | „Comment passer en revue une Pull Request“ | | Description d'outil | Indiquer au modèle ce que fait une fonction et quand l'utiliser | „Rechercher des issues GitHub via une requête sémantique“ | | Prompt système | Définir le comportement global et la tonalité de l'assistant | „Sois synthétique et vérifie toujours les faits“ | | Règles du projet | Expliquer les conventions spécifiques à appliquer dans ce dépôt de code | „Utilise pnpm et n'exécute pas le build manuellement“ |

Selon les documentations d'OpenAI et des SDKs d'agents, les outils (tools) sont des moyens pour les modèles d'obtenir des données, d'appeler des API tierces, d'exécuter du code ou d'interagir avec le système de fichiers. Les guides des SDKs recommandent : les descriptions d'outils doivent être courtes, précises, et expliquer le rôle de la fonction ainsi que son déclencheur. Ce même principe s'applique aux compétences en Markdown : sois explicite sur le but et l'activation.

Structure type d'un fichier SKILL.md

Un fichier de compétence utile doit répondre à six questions clés :

Quelle capacité ce skill fournit-il ?
Dans quelles conditions l'agent doit-il l'activer ?
Dans quelles conditions l'agent doit-il éviter de l'activer ?
Quelles étapes logiques l'agent doit-il suivre ?
Quels fichiers locaux, scripts ou références sont mis à disposition ?
Quel doit être le format de la réponse finale ?

Voici une trame réutilisable :

---
name: markdown-conversion-review
description: Utilise ce skill pour examiner, nettoyer ou normaliser des documents Markdown convertis à partir de PDF, Word, HTML ou fichiers bureautiques.
---

# Compétence : Audit qualité de conversion Markdown

## Quand activer cette compétence (Use This Skill When)
- L'utilisateur te demande de nettoyer ou de normaliser du Markdown issu d'un convertisseur.
- Tu dois préparer un document pour un fichier README, une documentation technique, un article de blog ou un contexte de prompt système.
- Le document d'origine contient des tableaux cassés, des titres mal ordonnés, des liens perdus ou des blocs de code mal fermés.

## Quand ne pas activer cette compétence (Do Not Use This Skill When)
- L'utilisateur pose simplement une question théorique sur la syntaxe du Markdown.
- La tâche exige de modifier des fichiers sources en dehors du document fourni.

## Flux de travail standard (Workflow)
1. **Examen de structure** : Analyse le Markdown pour repérer des hiérarchies de titres incohérentes, des tableaux déformés, des liens morts et des blocs de code non fermés.
2. **Respect du sens** : Conserve l'intention de l'auteur original et l'ordre des idées, à moins que l'utilisateur ne demande explicitement de reformuler le texte.
3. **Normalisation du format** : Utilise une syntaxe Markdown standard et épurée pour uniformiser les titres, listes, liens et tableaux de données.
4. **Indication des limites** : Si certains formats d'origine ne peuvent pas être restaurés avec fiabilité en Markdown, note-les comme réserves en fin de fichier.
5. **Livraison** : Renvoie le Markdown nettoyé accompagné d'une note courte expliquant les choix de conversion clés.

## Exigences de qualité et contraintes (Quality Bar)
- N'invente pas de faits ou de données absents du texte d'origine.
- Conserve les blocs de code de développement à l'identique, sauf demande contraire.
- Privilégie un Markdown standard et épuré au HTML complexe intégré.

## Format de sortie attendu (Output Format)
Renvoie :
1. Le Markdown nettoyé et harmonisé.
2. Des notes explicatives sur les choix clés de mise en forme.
3. La liste des problèmes de structure ou de formatage non résolus ou irrécupérables.

Les champs du Frontmatter dépendent des spécifications du framework d'agent que vous utilisez. Le corps du document (déclencheurs, exclusions, étapes, qualité, format de sortie) est totalement portable.

Comment rédiger un excellent champ de description (Description)

Le champ description dans la définition de l'outil ou de la compétence est le paramètre clé, car l'agent s'appuie dessus de manière sémantique pour décider s'il doit ou non charger cette capacité dans son contexte d'exécution.

Description faible :

description: Aide avec le Markdown.

Description excellente :

description: Utilise ce skill lorsque l'utilisateur te demande de nettoyer, normaliser ou corriger des documents Markdown issus d'un convertisseur, ou de les préparer pour des fichiers README, des articles de blog, de la documentation ou des contextes de prompts système.

La version améliorée présente clairement :

Le déclencheur : „lorsque l'utilisateur te demande de...“
L'action concrète : „nettoyer, normaliser ou corriger... ou de les préparer“
L'objet de travail : „des documents Markdown issus d'un convertisseur“
Les cas d'usage : „des fichiers README, des articles de blog, de la documentation ou des contextes de prompts système“

Comment rédiger les descriptions d'outils (Tool Descriptions)

Les descriptions d'outils doivent être plus courtes et plus concises que les compétences. Un outil exécute une fonction système spécifique, l'IA a donc besoin de trois informations clés :

Que fait l'outil ?
Dans quel cas doit-il être appelé ?
Quels paramètres d'entrée exige-t-il ?

Exemple au format JSON :

{
  "name": "convert_file_to_markdown",
  "description": "Convertit un fichier PDF, DOCX, PPTX, XLSX, HTML ou image importé en format Markdown lorsque l'utilisateur a besoin de texte éditable ou de données textuelles structurées prêtes pour l'IA.",
  "parameters": {
    "type": "object",
    "properties": {
      "file_id": {
        "type": "string",
        "description": "L'identifiant du fichier importé à convertir."
      },
      "preserve_tables": {
        "type": "boolean",
        "description": "Indique s'il faut conserver les tableaux sous forme de tables Markdown lorsque c'est possible. Par défaut true."
      }
    },
    "required": ["file_id"]
  }
}

La description élimine les mots superflus et décrit directement les types de fichiers supportés, l'intention de l'utilisateur et le rôle de chaque variable. Cela réduit grandement les appels erronés par le modèle.

Documenter des outils système en Markdown

Il est recommandé de documenter les limites d'utilisation des outils de votre projet dans des fichiers Markdown lisibles par l'agent :

# Spécification d'outil : convert_file_to_markdown

## Rôle
Convertir des documents de bureau et fichiers chargés en Markdown.

## Quand appeler
- L'utilisateur charge un document et demande directement de le convertir en Markdown.
- Les données textuelles du document doivent être préparées pour un LLM, un fichier README ou une documentation de dépôt.

## Ne pas appeler quand
- L'utilisateur pose uniquement une question théorique sur le Markdown.
- Le fichier d'entrée est déjà du Markdown propre et ne nécessite aucun traitement secondaire.

## Paramètres d'entrée
| Paramètre | Type | Requis | Description / Notes |
|---|---|---:|---|
| file_id | string | Oui | Identifiant unique du fichier chargé |
| preserve_tables | boolean | Non | Tenter de préserver la structure des tables |

## Sortie attendue
Texte Markdown converti et notes de réserves de traitement.

## Gestion des cas d'erreur
- Si le format de fichier n'est pas supporté, réponds en affichant la liste des formats acceptés.
- Si le format d'origine ne peut être préservé, renvoie la meilleure extraction brute possible et signale la limite.

Cela permet d'ajouter des consignes de sécurité ou des règles d'exploitation que le simple schéma d'interface de programmation ne parvient pas toujours à exprimer pour un agent d'IA.

Ce qui rend une compétence réellement utile

Une bonne compétence est purement opérationnelle. Elle aide l'agent à prendre les bonnes décisions d'exécution sur le terrain.

1. Déclencheurs d'activation précis

Utilisez des scénarios concrets plutôt que de simples noms de catégories générales.

Schlecht:

# Compétence SEO

Gut:

## Quand utiliser cette compétence
- L'utilisateur te demande explicitement d'optimiser une page web pour le référencement (SEO).
- Le texte a besoin de meta titres, de meta descriptions, d'une hiérarchie de titres (H2/H3), de liens internes ou d'une FAQ.
- L'utilisateur fait référence à des critères de qualité comme l'E-E-A-T de Google, les recommandations Helpful Content ou les audits de qualité de site.

2. Contraintes d'exclusion claires (Non-Goals)

Définir ce que l'agent ne doit pas faire est tout aussi capital que de lui dicter sa mission. Cela empêche l'assistant d'agir en dehors de son domaine de compétence.

## Limites de compétence
- Ne donne pas de conseils d'ordre légal, médical ou financier qui exigeraient des compétences professionnelles certifiées.
- Ne fabrique pas de faux témoignages clients, de fausses statistiques de vente ou des références de sources inexistantes.
- N'interviens pas sur des pages dont le sujet est totalement étranger aux besoins de l'utilisateur.

3. Étapes de workflow applicables

Proposez un enchaînement logique d'étapes auquel l'agent peut se référer. Écrivez les étapes avec assez de précision pour guider l'action, tout en laissant le degré de liberté nécessaire à l'appréciation de l'IA.

4. Exemples de résultats attendus et à proscrire

Dans l'ingénierie des instructions d'IA : un exemple concret de texte vaut mieux que dix lignes de règles abstraites.

## Exemple de ton et de rédaction

- **Formulation à éviter (incorrecte)** :
  „Notre convertisseur révolutionnaire garantit des résultats parfaits sur 100% de vos documents.“
  *(Raison : Style publicitaire excessif qui donne de fausses attentes à l'utilisateur et nuit à la confiance).*

- **Formulation recommandée (correcte)** :
  „L'outil extrait le contenu textuel des fichiers en Markdown. Il fonctionne de manière optimale lorsque le document d'origine possède des titres clairs, des listes simples et des tableaux standard.“
  *(Raison : Ton neutre et honnête, décrivant la valeur ajoutée réelle ainsi que les limites de la technologie).*

5. Règles de sécurité et permissions

Si votre compétence implique d'exécuter des scripts systèmes, de modifier des fichiers critiques ou d'interroger des API tierces, définissez les limites :

## Sécurité et autorisations
- Lis les fichiers intégralement dans le contexte avant d'essayer de les éditer.
- Ne supprime jamais de fichiers de l'utilisateur sans lui demander une confirmation explicite dans le chat.
- Demande l'autorisation avant d'envoyer des données utilisateur vers des API tierces.

Erreurs courantes lors de la conception de compétences

Erreur 1 : Surcharger une compétence : Un fichier de compétence doit se concentrer sur une tâche unique et cohérente. Si vous tentez de réunir le SEO, l'analyse web, la rédaction publicitaire, la politique d'annonces et l'envoi d'e-mails sous une seule „compétence marketing“, l'agent commettra des erreurs.
Erreur 2 : Utiliser des adjectifs subjectifs et flous : Évitez de dire „écris du code de classe mondiale“ ou „rends le rendu incroyable“. Remplacez-les par des critères vérifiables : „ajoute des liens vers les sources pour les chiffres avancés“, „limite la réponse à 150 mots“.
Erreur 3 : Masquer les règles clés dans de longs paragraphes : Utilisez des listes à puces. Les règles énoncées au milieu de longs blocs de texte sont fréquemment oubliées par les modèles de langage.
Erreur 4 : Manquer d'instructions en cas de panne : Les API peuvent planter, le réseau peut se couper. Prévoyez toujours une instruction de rechange (p. ej., „en cas de panne réseau, applique le mode de traitement local et préviens l'utilisateur“).

Conclusion

Les fichiers SKILL.md en Markdown et les descriptions d'outils précises constituent le socle technique idéal pour modérer le comportement des agents d'IA de façon fiable sans introduire de rigidité excessive. Ils indiquent clairement quand la compétence s'active, comment elle se déroule étape par étape et où s'arrêtent ses droits.

Si vous concevez des flux de travail pour l'IA basés sur la conversion de fichiers, des bases de connaissances ou de la programmation de code, la rédaction de fichiers de compétences en Markdown est le moyen le plus simple et le plus robuste d'unifier vos standards et l'exécution de l'agent.