Que sont vraiment les agent skills ?

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

Une compétence d’agent est un répertoire sur disque qui contient un fichier nommé SKILL.md. Ce fichier contient un nom, une courte description et des instructions rédigées en markdown simple. L’agent charge la description au démarrage et 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 répertoire peut contenir autre chose que ce seul fichier. 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 templates et les données. Aucun n’est obligatoire. Un répertoire 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 l’élément que l’on sous-estime le plus. C’est le seul texte que l’agent voit avant de décider d’ouvrir ou non la compétence. Elle doit donc indiquer ce que fait la compétence et quand l’utiliser, avec les termes qu’une personne saisirait réellement dans sa demande.

Pourquoi une compétence 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 ce que la spécification appelle la divulgation progressive.

Au démarrage, l’agent charge uniquement les name et description de chaque compétence installée. La spécification Agent Skills évalue cette charge à environ 100 tokens par compétence (recommandation publiée en août 2026). Installer une douzaine de compétences ne consomme donc qu’à peu près le contexte d’un long paragraphe.

Lorsqu’une requête correspond à une description, l’agent lit le contenu de ce seul 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 inclus fonctionne autrement : 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 entre.

Comparez cela à ce que l’on utilise souvent en premier : un prompt unique et énorme. Chaque ligne d’un system prompt ou d’un fichier d’instructions toujours actif est payée à chaque requête et dans chaque session, que la tâche en ait besoin ou non. Elle concurrence aussi la question réelle pour attirer l’attention de l’agent. 10 000 tokens d’instructions permanentes sont facturés même si vous demandez simplement l’heure. Une douzaine de compétences coûtent environ 1 200 tokens au repos, puis ne s’étendent que pour la tâche qui en a besoin. C’est tout l’intérêt des compétences. Une petite bibliothèque est donc préférable à un prompt plus long.

Un point pose souvent problème. Lorsqu’une compétence est chargée, son contenu reste dans le contexte jusqu’à la fin de la session. Un SKILL.md volumineux 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 prévu par la conception.

Une skill d’agent n’est pas un appel d’outil

Un outil, également appelé function call, est une action que le modèle peut invoquer. Le harness envoie au modèle un schéma : un nom, une description et 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 actions.

Une skill 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 skill comme il le fait à un outil. En revanche, une skill peut indiquer au modèle quels outils utiliser, dans quel ordre et quelles vérifications effectuer ensuite.

En résumé : un outil donne une nouvelle capacité à un agent, tandis qu’une skill lui apporte un cadre de décision pour 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 nécessite d’appliquer systématiquement le même raisonnement, utilisez une skill.

Une skill d’agent n’est pas un serveur MCP

MCP (model context protocol) est un protocole qui permet de connecter un agent à un système externe. Un serveur MCP est un processus qui s’exécute, parle 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 skill est un dossier contenant un fichier Markdown. Il n’y a ni processus, ni port, ni 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 présents dans la requête pendant toute la session, qu’ils soient utilisés ou non. Certains clients ont commencé à récupérer les schémas d’outils à la demande, mais leur chargement initial reste le cas normal. Une skill inactive se résume à 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 skill 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 votre propre serveur, 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

Les deux contiennent des instructions en Markdown, cette confusion est donc compréhensible. La différence tient au moment où ils sont chargés. AGENTS.md, CLAUDE.md et le prompt système sont toujours actifs. Une compétence est chargée à la demande.

Le test tient en une question : serait-il incorrect d’ignorer ce paragraphe pour une tâche qui n’a aucun rapport avec lui ? La convention 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 actif, puisque leur chargement systématique est précisément le but. 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 actif s’est transformée en procédure numérotée, c’est le signe qu’il faut la déplacer.

Ces fichiers ont leurs propres conventions, qu’il est utile de respecter. Consultez ce qui doit figurer dans AGENTS.md et 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 du projet se trouvent dans .claude/skills/<name>/SKILL.md et sont validées dans git. Chaque personne et chaque agent qui travaille dans ce dépôt les a donc à disposition. 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é pris en compte. 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 uniquement contenir des lettres minuscules, des chiffres et des traits d’union simples. La même séquence, rédigée comme une procédure que votre agent peut réexécuter, 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 être un script

Toute étape qui produit toujours une seule réponse correcte doit être un script. La compétence se limite alors à quelques lignes indiquant quand l’exécuter et comment interpréter sa sortie. Deux raisons, toutes deux pratiques, le justifient.

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

Deuxièmement, un script fournit deux fois la même réponse. Un modèle chargé de reconstituer la même règle d’analyse de logs à chaque exécution peut la modifier légèrement un mauvais jour. Vous ne le remarquerez qu’au moment où deux nombres divergeront.

Séparez donc les tâches selon leur nature. « Analyser le CSV et afficher chaque ligne dont le total ne correspond pas aux éléments détaillés » 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 ma skill ne se déclenche-t-elle jamais ?

Parce que son description décrit ce que fait la skill, mais jamais dans quel cas l’utiliser. C’est la seule ligne que l’agent doit comparer à votre demande. « Aide pour les 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 termes qu’une personne saisit réellement. La skill se déclenche donc.

Le problème inverse concerne la skill qui se déclenche constamment. Une description comme « À utiliser pour toute modification de code dans ce repository » correspond à tout. Le corps est donc chargé pour chaque tâche, puis reste dans le contexte pendant le reste de la session. Rendez la description plus précise pour cibler le cas voulu. Dans Claude Code, vous pouvez aussi définir disable-model-invocation: true dans le frontmatter. Cela désactive le chargement automatique, tout en gardant la skill disponible lorsque vous saisissez son nom.

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

Ne cherchez pas à deviner lequel de ces trois problèmes vous rencontrez. Exécutez le même prompt deux fois dans une session vierge : une fois avec la skill disponible, puis une fois avec la skill désactivée. Comparez ensuite les réponses. La session vierge est importante, car la session dans laquelle vous avez écrit la skill contient déjà tout ce qu’elle indique. Cela masque les lacunes de sa 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 la skill, puis mesure la fréquence de chaque déclenchement.

S’agit-il 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 par étapes. Elle fournit également un validateur de référence. Ainsi, skills-ref validate ./my-skill vérifie qu’un dossier respecte la spécification avant que vous le partagiez.

La liste des clients est le véritable indicateur. Le même dossier est lu notamment par Claude Code, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands et opencode. Microsoft publie ses propres skills dans ce format sur github.com/microsoft/skills et fournit un outil de bureau appelé Skill Recorder. Cet outil vous observe effectuer une tâche une fois, la reconstruit sous la forme d’une intention suivie 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 respecte la spécification d’un autre éditeur, cela montre généralement que le format n’est plus une fonctionnalité propre à un seul produit.

À rédiger 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 déplacez ce texte dans un SKILL.md et supprimez le texte collé. Une 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 exemple, et une compétence de recherche appuyée par votre propre instance SearXNG en montre la structure.

Deux habitudes permettent de préserver une bibliothèque saine. Lisez chaque compétence que vous n’avez pas écrite avant de l’installer, scripts compris, car une compétence contient les instructions que votre agent suivra et le code qu’il peut exécuter : traitez-la comme l’installation d’un logiciel provenant d’un inconnu. Gardez également les identifiants hors du dossier, car une compétence est un fichier texte qui peut être versionné et partagé. Garder les secrets à l’écart de vos agents explique plutôt où placer ces valeurs, et la feuille de route pour apprendre à utiliser les agents cette année situe les compétences par rapport au 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. Les définitions de ses outils occupent normalement 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 accès à un système. Utilisez une compétence pour indiquer à l’agent comment utiliser 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é comme 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 change, c’est l’emplacement recherché par chaque client et les champs supplémentaires de frontmatter qu’il comprend. Claude Code lit ~/.claude/skills/ et .claude/skills/, tandis que GitHub Copilot et VS Code lisent .github/skills/ dans le repository. 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 au démarrage, et non un nombre précis. Chaque compétence installée ajoute son nom et sa description, soit environ 100 tokens d’après 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. La première dégradation concerne la sélection, et non la vitesse : lorsque plusieurs compétences ont des descriptions qui se chevauchent, le modèle choisit plus difficilement la bonne. Rédigez des descriptions distinctes et supprimez les compétences que vous n’utilisez plus.

Cette instruction doit-elle être placée dans une compétence ou dans AGENTS.md ?

Demandez-vous si elle s’applique à toutes les tâches du repository. Les commandes de build, les règles de style du projet et les conventions de nommage s’appliquent à toutes les tâches. Elles doivent donc figurer dans le fichier toujours chargé, puisque son chargement à chaque fois est précisément son objectif. 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.