Une description d’outil MCP est une phrase attachée à une seule fonction
appelable : ce qu’elle fait, ce qu’elle prend, si elle modifie quelque chose.
Elle accompagne chaque requête que le client envoie au modèle, aux côtés de la
description de tous les autres outils. Un skill est un dossier contenant un
fichier SKILL.md, qui renferme une procédure — fais ceci, puis vérifie cela,
demande avant cette autre chose — et son corps n’est chargé qu’une fois que le
modèle a décidé que votre demande lui correspond.
C’est toute la distinction, et elle porte sur le moment où le texte se trouve en contexte, pas sur ce que le texte dit. Les descriptions sont le droit d’entrée : vous les payez toutes, à chaque tour, indéfiniment. Les instructions d’un skill sont gratuites tant qu’elles ne servent pas. D’où le fait qu’un paragraphe indéfendable dans une description d’outil — trois cents mots sur la façon de trier une pile d’enregistrements de réunions en attente — est parfaitement raisonnable dans un skill.
Cet article porte sur une décision : laquelle de vos instructions va où. Si le protocole lui-même vous est inconnu, ce qu’est un serveur MCP pose d’abord le vocabulaire, et MCP, plugins et intégrations situe MCP par rapport aux anciennes façons de relier les choses.
Dans la spécification MCP, une définition d’outil est une petite forme figée.
Elle porte un name, un title lisible facultatif, une description, un
inputSchema décrivant les arguments, un outputSchema facultatif et des
annotations — des propriétés facultatives décrivant le comportement de
l’outil, par exemple s’il se contente de lire. Le client récupère la liste
entière par un appel tools/list et la place devant le modèle, ce qui fait des
outils MCP des outils pilotés par le modèle : c’est lui qui en choisit un
d’après la conversation.
Cette forme est bonne à exactement une chose : dire au modèle ce que fait un appel unique pour qu’il choisisse le bon. Elle est structurellement mauvaise pour trois autres.
Elle ne peut pas décrire un ordre. Rien dans une définition d’outil ne peut
dire « appelle list_channels avant share_to_channel, parce que le canal doit
exister et que l’utilisateur doit le choisir ». Chaque description est une île.
Elle ne peut pas contenir grand-chose. Chaque description est en contexte pour chaque requête de chaque conversation, y compris toutes celles qui ne toucheront jamais cet outil. Un serveur de quinze outils avec un paragraphe sur chacun a dépensé une part notable de la fenêtre de contexte avant même que l’utilisateur ait tapé quoi que ce soit.
Elle ne peut pas encoder votre jugement. « Étiquette l’enregistrement plutôt que de le partager quand tu ne sais pas qui doit le voir » est une politique, pas la description d’une fonction. Deux équipes différentes voudraient deux politiques différentes du même outil.
Le protocole ménage une soupape : un serveur peut renvoyer une chaîne
instructions à la connexion du client, et celui-ci peut l’ajouter au prompt
système — avant la liste des outils. C’est le bon endroit pour une courte mise
en situation : ce qu’est ce serveur, à quoi il est rattaché, ce à quoi il faut
faire attention. Deux réserves. Ce texte reste présent à chaque session, donc il
reste court. Et la spécification dit que les clients peuvent s’en servir, non
qu’ils le doivent : le fait de le montrer réellement au modèle varie donc d’un
client à l’autre.
Un skill est un répertoire contenant un fichier SKILL.md : un frontmatter YAML
avec un name et une description, puis des instructions en markdown. Il peut
regrouper d’autres éléments à côté — scripts/ pour du code exécutable,
references/ pour de la documentation détaillée, assets/ pour des gabarits —
et l’agent ne les charge que si les instructions l’y envoient.
Ce modèle de chargement s’appelle la divulgation progressive, et la spécification le décrit en trois étapes :
name et la
description de chaque skill disponible — budgétés à une centaine de tokens
par skill. De quoi savoir quand il pourrait être pertinent, rien de plus.SKILL.md. La recommandation est de rester sous
environ 5 000 tokens, et sous 500 lignes pour le fichier principal.Le coût de vingt skills installés, c’est donc vingt courtes descriptions. Le coût de vingt longues descriptions d’outils, c’est vingt longues descriptions d’outils, à chaque tour. Cette asymétrie est la raison d’être de la couche.
Le format n’est pas propre à un client. Agent Skills a été développé par
Anthropic et publié comme standard ouvert, sur agentskills.io ; la vitrine des
clients qui s’y trouve répertorie des dizaines de produits qui lisent le même
dossier, dont Claude Code, Claude, ChatGPT et Codex, Cursor, VS Code, GitHub
Copilot, Gemini CLI, Goose, Roo Code, Kiro, Junie, Amp, Factory, Tabnine,
Snowflake Cortex Code et Databricks Genie Code. Vérifié le 14 août 2026.
Le frontmatter obligatoire est délibérément mince. name fait jusqu’à
64 caractères — minuscules, chiffres et traits d’union — et doit correspondre au
nom du répertoire parent. description fait jusqu’à 1 024 caractères et devrait
dire à la fois ce que fait le skill et quand s’en servir, parce que cette
chaîne est la seule base sur laquelle un agent décide d’ouvrir le fichier. Les
champs facultatifs sont license, compatibility, metadata et le champ
expérimental allowed-tools.
Ce champ de description mérite plus de soin qu’on ne lui en accorde. « Aide avec les notes de réunion » ne correspondra jamais à rien de façon fiable ; « passe en revue et classe les enregistrements récents — les étiquette, nomme les intervenants, partage ceux qui relèvent d’un canal d’équipe ; à utiliser quand l’utilisateur demande de ranger, de trier ou de rattraper son retard » le fera.
Entre les descriptions par appel et les skills à la demande se trouve une couche qui n’est ni l’une ni l’autre : les fichiers qu’un agent lit au début d’une session, quelle que soit votre demande.
AGENTS.md en est la version la plus dépouillée — markdown standard, aucun champ obligatoire, lu depuis le fichier le plus proche en remontant l’arborescence. Son propre site fait état d’un usage par plus de 60 000 projets open source, et liste une prise en charge par OpenAI Codex, Google Jules et Gemini CLI, les agents Claude, l’agent de code de GitHub Copilot, Aider, VS Code, Cursor, Zed, Warp, Factory, goose, Roo Code, Devin et Junie. Vérifié le 14 août 2026.
Les règles Cursor sont la même idée avec un interrupteur. Elles vivent dans
.cursor/rules sous forme de fichiers .mdc, et trois champs du frontmatter
décident de l’inclusion de chacune : alwaysApply: true la place dans chaque
session de chat ; une description laisse l’agent juger de la pertinence ;
globs la rattache à l’ouverture d’un fichier correspondant ; et si aucun n’est
renseigné, la règle n’arrive que si vous la mentionnez avec @. Cursor prend
aussi en charge AGENTS.md, et prend désormais en charge Agent Skills
directement — les skills se trouvent dans .cursor/skills/ ou
.agents/skills/ — avec un outil de migration qui convertit en skills les
règles dynamiques et les commandes slash éligibles. Vérifié le 14 août 2026.
Relisez ces deux paragraphes et le motif saute aux yeux : les formats ont
convergé, pas les modèles de chargement. Tout le monde lit désormais
SKILL.md. Mais une règle alwaysApply et un bloc AGENTS.md ont la portée
d’une session, un skill a la portée d’une tâche, et aucune compatibilité de
format n’y change quoi que ce soit.
La conséquence pratique est une règle empirique qui vaut plus que les détails de format :
| Où cela va | Ce qui y a sa place | Ce que cela coûte |
|---|---|---|
description d’outil |
Une phrase : ce que fait cet appel, ce qu’il modifie | Chaque requête, indéfiniment |
instructions du serveur |
Une courte mise en situation du serveur entier | Chaque session sur ce serveur |
AGENTS.md, règles toujours appliquées |
Des faits vrais pour toutes les tâches de ce dépôt | Chaque session dans ce projet |
SKILL.md |
Procédures, politiques, exemples traités, jugement | Seulement quand la tâche correspond |
Tout ce qui est long, tout ce qui est conditionnel, tout ce qui n’est vrai
qu’une partie du temps : un skill. L’erreur classique consiste à mettre cent
cinquante lignes de procédure propre à un produit dans un AGENTS.md global, où
elles restent en contexte pendant qu’on travaille tout l’après-midi sur un
backend sans rapport.
Speak-Y fournit un serveur MCP, et c’est une illustration convenable, parce qu’on y voit les deux couches faire des métiers différents.
Les descriptions d’outils couvrent les appels : chercher des enregistrements,
lire une transcription, un résumé ou les points d’action, lister les canaux et
les étiquettes — et, avec l’application lancée, étiqueter un enregistrement,
renommer un intervenant, le retitrer, le retranscrire ou le classer dans un
canal d’équipe. Chacune porte une annotation indiquant si elle lit ou si elle
modifie, ce qui permet à un client de demander confirmation avant les secondes,
et fait de --read-only un simple interrupteur plutôt qu’une liste de noms
d’outils à retenir. La lecture se fait localement, sur la bibliothèque de votre
machine ; les commandes qui modifient passent par l’application en cours
d’exécution et y sont journalisées, comme le détaille
ce qui rend l’accès en écriture MCP sûr.
Le skill couvre le métier. Quand vous installez l’intégration depuis
Paramètres → Intégrations, Speak-Y écrit un skill d’organisation à côté de
la configuration du serveur : par où commencer pour trier une pile
d’enregistrements, quand une étiquette est la bonne réponse et quand c’est un
canal, quelles actions confirmer avant de les lancer. Les descriptions ne
pourraient pas contenir cela, et la chaîne instructions du serveur ne devrait
pas essayer.
C’est aussi écrit comme le modèle de chargement le récompense. Un fichier
détaillé vit à un seul endroit, et chaque client reçoit un court renvoi vers
lui, dans le format que ce client lit — un SKILL.md pour Claude Code, une
règle .mdc pour Cursor, un bloc balisé dans AGENTS.md pour Codex, un bloc
balisé dans GEMINI.md pour Gemini CLI. Les clients à portée de session
reçoivent un renvoi précisément parce qu’ils sont à portée de session : cent
cinquante lignes sur les notes de réunion n’ont pas à rester résidentes pendant
que vous déboguez le backend de quelqu’un d’autre. Les blocs sont encadrés par
des marqueurs, si bien qu’une réinstallation ne remplace que cette section et
laisse le reste du fichier intact.
Le serveur MCP lui-même est gratuit sur toutes les formules, y compris Free. L’installation en un clic et la configuration manuelle pour chaque client sont documentées dans Assistants IA (MCP).
Trois questions, dans l’ordre.
L’instruction décrit-elle un seul appel ? Alors c’est une description d’outil, et elle doit tenir en une ou deux phrases. Si vous vous surprenez à en écrire une troisième, vous avez trouvé un skill.
Est-ce vrai de chaque session, quelle que soit la tâche ? Alors cela peut
aller dans AGENTS.md ou dans une règle toujours appliquée — mais vérifiez
honnêtement la partie « quelle que soit la tâche ». « Ce dépôt utilise pnpm »
remplit le critère. « Voici notre processus de tri des réunions », non.
Cela décrit-il une procédure avec des étapes, des choix ou des exceptions ?
Un skill. Passez le nom et la description au crible, parce que ces deux chaînes
assurent tout l’aiguillage, et mettez tout ce qui est long dans un fichier
references/ à côté du SKILL.md plutôt que dedans.
Trompez-vous du côté bon marché et votre agent aura un contexte gonflé et un taux de réussite moindre sur chaque question sans rapport. Trompez-vous du côté coûteux — la procédure entassée dans les descriptions d’outils — et le modèle lira votre politique à chaque tour sans forcément la suivre, parce qu’une description se lit comme la documentation d’une fonction, pas comme une consigne à respecter.
Pour voir la différence concrètement, le test le plus rapide est d’écrire un skill pour un travail que vous répétez vraiment, puis de le comparer aux prompts que vous colliez jusque-là. Des prompts pour interroger une IA sur vos réunions est une bonne source de candidats : ceux que vous lancez plus de deux fois sont ceux qui méritent un fichier.
Une description d’outil est une phrase attachée à une seule fonction appelable, écrite par l’auteur du serveur et envoyée au modèle à chaque requête dans la liste des outils. Un skill est un dossier contenant un fichier SKILL.md qui renferme une procédure — plusieurs étapes, plusieurs outils, des choix à trancher — et seuls son nom et sa description sont en contexte jusqu’à ce que le modèle décide que la tâche lui correspond. Les descriptions répondent à « que fait cet appel » ; les skills, à « comment mène-t-on ce travail ».
Pas pour les tâches en un seul appel. Il en faut un quand un travail demande plusieurs outils dans un ordre précis, quand le bon choix entre deux outils dépend d’un contexte que les descriptions ne peuvent pas porter, ou quand vous voulez que la même procédure se répète à l’identique d’une session à l’autre. De bonnes descriptions rendent chaque appel correct ; un skill rend une suite d’appels cohérente.
Non. Agent Skills a été développé par Anthropic et publié comme standard ouvert sur agentskills.io, et la vitrine des clients qui s’y trouve répertorie des dizaines de produits qui l’ont adopté, parmi lesquels Claude Code, ChatGPT et Codex, Cursor, VS Code, GitHub Copilot, Gemini CLI, Goose, Roo Code, Kiro, Junie et Factory. Vérifié le 14 août 2026.
AGENTS.md est du markdown simple, sans champ obligatoire, qu’un agent lit depuis le répertoire le plus proche dans l’arborescence, et il est chargé pour toute la session quelle que soit votre demande. Le corps d’un skill n’est chargé qu’après que l’agent a rapproché votre demande de sa description. Les deux sont utiles, mais tout ce qui est long relève du skill, car le contenu d’AGENTS.md occupe du contexte à chaque session, y compris celles qui n’ont rien à voir avec lui.
La spécification Agent Skills recommande de garder le fichier SKILL.md principal sous 500 lignes et sous environ 5 000 tokens, et de déplacer la documentation de référence détaillée dans des fichiers séparés que l’agent ne charge qu’au besoin. Le nom et la description sont budgétés à une centaine de tokens, parce que ce sont eux que chaque session paie.