Compétences d’agent : définition et fonctionnement réel

Ce qu’est réellement une compétence d’agent

Une compétence d’agent est un dossier sur le disque qui contient un fichier nommé SKILL.md. Ce fichier contient un nom, une brève description et des instructions rédigées en Markdown standard. L’agent charge la description au démarrage, puis ne lit les instructions que si votre demande correspond à cette description. Presque tout le reste du fonctionnement des compétences découle de ces deux phrases.

Le dossier peut contenir plusieurs fichiers. La spécification Agent Skills définit trois répertoires facultatifs : scripts/ pour le code exécuté par l’agent, references/ pour les documents qu’il lit lorsqu’il en a besoin, et assets/ pour les modèles et les données. Aucun n’est obligatoire. Un dossier qui ne contient qu’un fichier SKILL.md constitue une compétence complète.

restore-drill/
  SKILL.md
  references/retention-policy.md
  scripts/verify_snapshot.sh

La description est la partie que l’on sous-estime le plus. C’est le seul texte que l’agent voit avant de décider s’il doit ouvrir la compétence. Elle doit donc indiquer ce que fait la compétence et quand l’utiliser, avec les termes qu’une personne emploierait réellement dans sa demande.

Pourquoi une skill coûte presque rien tant qu’elle n’est pas utilisée

C’est l’argument qui justifie l’intérêt de ce format. Il concerne le contexte, pas les fonctionnalités. Le chargement s’effectue par étapes, selon un mécanisme que la spécification appelle la divulgation progressive.

Au démarrage, l’agent charge uniquement les name et description de chaque skill installée. La spécification Agent Skills estime cette quantité à environ 100 tokens par skill (recommandation publiée en août 2026). Si vous installez une douzaine de skills, vous utilisez à peu près le contexte d’un long paragraphe.

Lorsqu’une requête correspond à une description, l’agent lit le contenu de cette SKILL.md. La spécification recommande de limiter ce contenu à 5 000 tokens et le fichier à 500 lignes. Les fichiers situés dans references/ et scripts/ ne coûtent toujours rien à ce stade. Un fichier de référence n’est chargé que si les instructions y renvoient. Un script fourni avec la skill fonctionne encore différemment : l’agent l’exécute via le shell, de sorte que le code source du script n’entre jamais dans la fenêtre de contexte ; seule sa sortie y est ajoutée.

Comparez cela avec la solution vers laquelle on se tourne généralement en premier : un prompt énorme. Chaque ligne d’un system prompt ou d’un fichier d’instructions toujours actif est prise en compte à chaque requête et dans chaque session, que la tâche en ait besoin ou non. Elle entre aussi en concurrence avec la question réelle pour attirer l’attention de l’agent. Dix mille tokens d’instructions permanentes constituent un coût que vous payez même pour demander l’heure. Une douzaine de skills utilisent environ 1 200 tokens au repos et ne s’étendent que pour la tâche qui en a besoin. C’est tout l’intérêt des skills, et c’est pourquoi une petite bibliothèque est préférable à un prompt plus long.

Un point mérite votre attention. Lorsqu’une skill est chargée, son contenu reste dans le contexte jusqu’à la fin de la session. Un SKILL.md long représente donc un coût récurrent, et non un coût ponctuel. Déplacer les détails dans references/ n’est pas une simple question de rangement. C’est le mécanisme qui fonctionne comme prévu.

Une compétence d’agent n’est pas un appel d’outil

Un outil, également appelé appel de fonction, est une opération que le modèle peut invoquer. L’environnement d’exécution lui fournit un schéma composé d’un nom, d’une description et de la structure des arguments. Le modèle émet un appel, votre code l’exécute, puis le résultat revient sous forme de message. Les outils exécutent des opérations. Les deux parties de cet échange relèvent de l’environnement d’exécution, le programme qui orchestre la boucle autour du modèle, qui lit également les descriptions de vos compétences au démarrage et décide quand en ouvrir une.

Une compétence n’exécute rien par elle-même. L’agent la lit, puis agit avec les outils dont il dispose déjà. Le modèle ne peut pas transmettre d’arguments à une compétence comme il le fait à un outil. Une compétence peut indiquer au modèle quels outils utiliser, dans quel ordre et quelles vérifications effectuer ensuite. Confier une tâche à un second agent en est l’exemple le plus clair : une session Claude Code peut déjà envoyer un message à une autre, et la compétence indique quand cela vaut la peine de le faire et quelles informations transmettre.

En résumé : un outil donne une nouvelle capacité à un agent, tandis qu’une compétence lui indique comment utiliser une capacité dont il dispose déjà. Si une étape doit produire à chaque fois un résultat exact et validé, utilisez un outil ou un script. Si une étape exige d’appliquer systématiquement le même raisonnement, utilisez une compétence. Une compétence peut se limiter au raisonnement et rester celle que vous utilisez le plus, comme le montre Ponytail, qui pousse un agent de programmation à effectuer la plus petite modification fonctionnelle : elle n’ajoute aucune capacité et modifie uniquement la façon dont l’agent utilise celles dont il dispose déjà. Ce raisonnement peut aussi orienter l’agent dans l’autre sens : la compétence unlazy, qui parcourt un Depth Tree pour empêcher un agent de déclarer trop tôt qu’une tâche est terminée, applique le même principe à l’exhaustivité plutôt qu’à la retenue.

Une compétence d’agent n’est pas un serveur MCP

MCP (model context protocol) est un protocole qui connecte un agent à un système externe. Un serveur MCP est un processus qui s’exécute, utilise ce protocole et expose des outils à l’agent. Il nécessite généralement une configuration, des identifiants et soit une commande locale, soit un endpoint réseau. Une compétence est un dossier contenant un fichier Markdown. Elle n’implémente aucun processus, n’utilise aucun port et ne suit aucun protocole.

Le coût en contexte diffère de la même manière. Chaque outil exposé par un serveur MCP comporte un nom, une description et un schéma d’arguments. Par défaut, ces éléments sont inclus dans la requête pendant toute la session, qu’ils soient utilisés ou non. Certains clients commencent à récupérer les schémas d’outils à la demande, mais leur chargement initial reste le cas normal. Une compétence au repos tient sur une ligne de texte.

Les deux sont complémentaires, et les configurations les plus efficaces utilisent les deux. Le serveur MCP fournit l’accès. La compétence fournit la procédure : quels outils appeler pour le workflow réel de votre équipe, dans quel ordre et à quoi ressemble un résultat correct. Si vous hébergez vos propres serveurs, la section exécuter des serveurs MCP sur un VPS couvre cet aspect.

Une compétence d’agent n’est ni un prompt système ni un fichier AGENTS.md

Ce sont tous deux des instructions en Markdown, cette confusion est donc compréhensible. La différence tient au moment où elles sont chargées. AGENTS.md, CLAUDE.md et le prompt système sont toujours actifs. Une compétence est chargée à la demande. Les styles de sortie de Claude Code se situent à l’extrémité « toujours actifs », car le choix de l’un d’eux modifie directement le prompt système. Il influence donc toutes les réponses de la session, y compris celles auxquelles aucune compétence ne s’applique.

Le test tient en une question : serait-il incorrect d’ignorer ce paragraphe pour une tâche sans rapport avec lui ? Les conventions de style, la commande de build et la règle de nommage des branches s’appliquent à toutes les tâches. Elles doivent donc figurer dans le fichier toujours chargé, puisque c’est précisément son rôle. La checklist de release que vous exécutez deux fois par mois ne s’applique pas à toutes les tâches. Elle doit donc figurer dans une compétence. Lorsqu’une section de votre fichier toujours chargé devient une procédure numérotée, c’est le signe qu’il faut la déplacer.

Ces fichiers ont eux aussi des conventions qu’il est utile de respecter. Consultez ce qui doit figurer dans AGENTS.md et ce qui doit figurer dans le fichier destiné aux humains ainsi que un fichier design.md qui explique la structure d’une base de code pour voir les deux formats que nous utilisons.

À quoi ressemble une skill minimale

Dans Claude Code, les skills personnelles se trouvent dans ~/.claude/skills/<name>/SKILL.md et s’appliquent à tous vos projets. Les skills de projet se trouvent dans .claude/skills/<name>/SKILL.md et sont versionnées dans git. Chaque personne et chaque agent qui travaille dans ce dépôt les possède donc. GitHub Copilot et VS Code lisent plutôt les skills de l’espace de travail depuis .github/skills/. Le fichier qu’il contient est identique.

mkdir -p ~/.claude/skills/restore-drill

---
name: restore-drill
description: Run a restic restore drill and report what was recovered. Use when the user asks to test backups, verify a restore, or check that a snapshot is readable.
---

# Restore drill

1. Run `restic snapshots` and pick the newest snapshot for the host in question.
2. Restore it into a scratch directory under `/tmp`, never over live data.
3. Compare the restored file count and total size against the snapshot summary.
4. Report the snapshot ID and anything that failed to restore.

If `restic snapshots` prints `Fatal: unable to open config file`, the repository path or the password is wrong. Stop and report that instead of guessing.

Il s’agit d’une skill complète. Le nom du répertoire devient la commande que vous saisissez. Dans cet exemple, c’est donc /restore-drill. Dans Claude Code, le menu /skills répertorie les éléments installés. C’est le moyen le plus rapide de vérifier que le fichier a bien été détecté. S’il n’apparaît pas dans ce menu, un nom est incorrect : le fichier doit s’appeler SKILL.md, et le nom du répertoire doit contenir uniquement des lettres minuscules, des chiffres et des traits d’union simples. La même procédure, rédigée pour pouvoir être relancée par votre agent, accompagne naturellement les sauvegardes restic planifiées sur un VPS, car l’exécution de la sauvegarde ne garantit pas sa restauration.

Quand une compétence doit devenir un script

Toute étape qui produit toujours une réponse correcte unique doit être un script. La compétence peut alors se limiter à quelques lignes indiquant quand l’exécuter et comment interpréter sa sortie. Deux raisons expliquent ce choix, et elles sont toutes les deux pratiques.

Premièrement, le code source d’un script n’entre jamais dans la context window. Un parseur de 300 lignes ne coûte que sa sortie, alors que la même logique rédigée sous forme d’instructions Markdown coûte toute sa longueur à chaque chargement de la compétence.

Deuxièmement, un script produit deux fois la même réponse. Si vous demandez à un modèle de redériver la même règle d’analyse des logs à chaque exécution, il l’implémentera légèrement différemment un mauvais jour. Vous ne vous en apercevrez qu’au moment où deux nombres ne correspondront plus.

Il faut donc répartir le travail selon sa nature. « Analyser le CSV et afficher chaque ligne dont le total ne correspond pas à la somme des éléments » relève d’un script. « Examiner les lignes affichées par le script et expliquer lesquelles ressemblent à une erreur de saisie » relève d’une instruction de compétence. Conserver le jugement dans le Markdown et le déterminisme dans le code relève de la même discipline que construire une boucle qu’un agent peut exécuter sans que vous la surveilliez.

Pourquoi mon skill ne se déclenche-t-il jamais ?

Parce que son description indique ce que fait le skill, mais jamais dans quel cas l’utiliser. C’est la seule ligne que l’agent doit comparer à votre demande. « Aide pour les tâches liées aux bases de données » ne correspond à rien de précis. « Exécute une migration de schéma sur la base de données de staging. À utiliser lorsque l’utilisateur demande de migrer une table, d’ajouter une colonne ou de modifier un schéma » contient les mots qu’une personne saisit réellement. Le skill peut donc se déclencher.

Le problème inverse concerne le skill qui se déclenche constamment. Une description comme « À utiliser pour toute modification de code dans ce dépôt » correspond à tout. Le contenu est donc chargé pour chaque tâche, puis reste dans le contexte pendant toute la session. Limitez la description au cas prévu. Dans Claude Code, vous pouvez également définir disable-model-invocation: true dans le frontmatter. Le chargement automatique est alors désactivé, tout en gardant le skill disponible lorsque vous saisissez son nom.

Le troisième problème concerne le skill qui duplique un outil. Des instructions demandant à l’agent de curl une API déjà exposée par son serveur MCP, ou de parcourir les fichiers avec grep alors que le harness dispose d’un outil de recherche, ajoutent un chemin plus lent ainsi que deux ensembles d’instructions susceptibles de se contredire. Supprimez le doublon et décrivez plutôt l’intention.

Ne cherchez pas à deviner lequel de ces trois problèmes vous rencontrez. Exécutez deux fois le même prompt dans une nouvelle session : une fois avec le skill disponible, puis une fois avec le skill désactivé. Comparez ensuite les réponses. La nouvelle session est importante : la session dans laquelle vous avez écrit le skill contient déjà tout ce qu’il indique, ce qui masque les lacunes de la version écrite. Le plugin skill-creator d’Anthropic automatise cette comparaison dans Claude Code. Il génère notamment des prompts qui doivent ou non déclencher le skill et mesure la fréquence de chaque déclenchement. Si le skill se charge, mais que l’agent n’applique toujours pas ses instructions, le problème ne vient pas de la description. Consultez plutôt les raisons pour lesquelles un agent passe à côté d’instructions qu’il a déjà lues.

Il s’agit du format d’un éditeur ou d’un standard ?

Anthropic a publié ce format fin 2025, puis l’a diffusé comme standard ouvert sur agentskills.io. En août 2026, cette spécification définit les champs obligatoires name et description, les champs facultatifs license, compatibility, metadata et allowed-tools, les trois répertoires facultatifs et le comportement de chargement progressif. Elle fournit également un validateur de référence. Ainsi, skills-ref validate ./my-skill vérifie qu’un dossier est conforme à la spécification avant que vous le partagiez.

La liste des clients est l’indicateur le plus pertinent. Claude Code, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands et opencode, entre autres, lisent le même dossier. Microsoft publie ses propres skills dans ce format sur github.com/microsoft/skills et propose un outil desktop appelé Skill Recorder. Celui-ci observe l’exécution d’une tâche, la reconstruit sous la forme d’une intention et d’une suite d’étapes ordonnées, puis écrit le résultat sous forme de skill. Lorsqu’un éditeur développe un recorder dont le format de sortie relève de la spécification d’un autre éditeur, cela indique généralement que le format n’est plus une fonctionnalité propre à un seul produit.

Ce qu’il faut écrire en premier

Ne planifiez pas une bibliothèque. Attendez de vous surprendre à coller les mêmes instructions dans un chat pour la troisième fois, puis placez ce texte dans un SKILL.md et supprimez le texte collé. La répétition que vous avez déjà constatée est le seul déclencheur fiable pour identifier une compétence qui mérite d’être conservée. Une procédure de recherche constitue un bon premier choix, et une compétence de recherche reposant sur votre propre instance SearXNG en illustre la structure.

Deux habitudes permettent de préserver la qualité de la bibliothèque. Lisez chaque compétence que vous n’avez pas écrite avant de l’installer, y compris les scripts, car une compétence contient les instructions que votre agent suivra et le code qu’il pourra exécuter : traitez-la comme un logiciel installé depuis une source inconnue. Gardez également les identifiants hors du dossier, car une compétence est un fichier texte qui peut être commité et partagé. Garder les secrets à l’écart de vos agents explique où placer ces valeurs, et la feuille de route pour apprendre aux agents cette année ordonne les compétences avec le reste de la configuration.

FAQ

Quelle est la différence entre une compétence d’agent et un serveur MCP ?

Un serveur MCP (model context protocol) est un processus en cours d’exécution qui expose des outils à un agent via un protocole. Il nécessite donc une configuration et des identifiants, et les définitions de ses outils occupent généralement du contexte pendant toute la session, qu’elles soient utilisées ou non. Une compétence d’agent est un dossier contenant un fichier SKILL.md. Elle n’utilise ni processus ni protocole et coûte environ 100 tokens jusqu’à ce que l’agent décide de la lire. Utilisez un serveur MCP pour donner à un agent l’accès à un système. Utilisez une compétence pour lui indiquer la procédure à suivre pour exploiter correctement cet accès. De nombreuses configurations utilisent les deux.

Les compétences d’agent fonctionnent-elles uniquement avec Claude Code ?

Non. Anthropic a développé ce format, puis l’a publié en tant que standard ouvert sur agentskills.io. Le même dossier est lu par Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands et d’autres clients. Ce qui diffère, c’est l’emplacement où chaque client recherche les compétences et les champs de frontmatter supplémentaires qu’il comprend. Claude Code lit ~/.claude/skills/ et .claude/skills/, tandis que GitHub Copilot et VS Code lisent .github/skills/ dans le dépôt. Le fichier SKILL.md lui-même peut passer de l’un à l’autre sans modification.

Combien de compétences puis-je installer avant de ralentir le système ?

La contrainte concerne le budget de démarrage, pas le nombre de compétences. Chaque compétence installée ajoute son nom et sa description, soit environ 100 tokens selon les indications publiées dans la spécification. Trente compétences coûtent donc environ 3 000 tokens avant même que l’une d’elles soit utilisée. Ce qui se dégrade en premier, c’est la sélection, pas la vitesse : de nombreuses compétences aux descriptions similaires compliquent le choix de la bonne compétence par le modèle. Rédigez des descriptions qui ne se chevauchent pas et supprimez les compétences que vous n’utilisez plus.

Cette instruction doit-elle se trouver dans une compétence ou dans AGENTS.md ?

Demandez-vous si elle s’applique à toutes les tâches du dépôt. Les commandes de build, les conventions de style et les règles de nommage s’appliquent à toutes les tâches. Elles doivent donc figurer dans le fichier toujours chargé, puisque son chargement systématique est précisément son rôle. Une procédure exécutée occasionnellement, comme une checklist de release ou un exercice de restauration, doit être une compétence. Elle ne coûte ainsi rien pour les tâches qui n’en ont jamais besoin. Une section de AGENTS.md qui s’est transformée en étapes numérotées est généralement une compétence qui attend d’être déplacée.