Qu’est-ce qu’une compétence d’agent, au juste ?

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 brut. L’agent charge la description au démarrage. Il ne lit les instructions que si votre demande correspond à cette description ou si vous invoquez la compétence par son nom. Presque tout le reste concernant les 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 au besoin et assets/ pour les modèles et les données. Aucun de ces répertoires 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 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.

Pourquoi une compétence ne 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, et non les fonctionnalités. Le chargement s’effectue par étapes. La spécification appelle ce mécanisme la divulgation progressive.

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

Lorsqu’une requête correspond à une description, l’agent lit le contenu de ce 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 encore rien à ce stade. Un fichier de référence n’est chargé que si les instructions y renvoient. Un script fourni avec la compétence fonctionne autrement : l’agent l’exécute via le shell. Le code source du script n’entre donc jamais dans la fenêtre de contexte ; seule sa sortie y est ajoutée.

Comparez cela avec ce vers quoi on se tourne souvent 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. Ces lignes se disputent aussi l’attention avec la question réelle. Dix mille tokens d’instructions permanentes représentent un coût que vous payez même pour demander l’heure. Une douzaine de compétences consomment 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 plus efficace qu’un prompt plus long.

Un point piège souvent les utilisateurs. 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 fonctionnement prévu par le mécanisme.

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

Un outil, également appelé appel de fonction, est une fonction que le modèle peut invoquer. Le harness lui envoie 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 effectuent des actions. Les deux parties de cet échange relèvent du harness, le programme qui exécute la boucle autour du modèle, qui lit également les descriptions de 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 en revanche indiquer au modèle quels outils utiliser, dans quel ordre et quelles vérifications effectuer ensuite. Déléguer 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 cette délégation est utile et quelles informations transmettre.

En bref : un outil donne une nouvelle capacité à un agent, tandis qu’une compétence lui donne surtout un jugement sur les capacités dont il dispose déjà. Lorsqu’une compétence ajoute une capacité, elle le fait au moyen d’un script inclus que l’agent exécute avec le shell dont il disposait 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 le même raisonnement de manière cohérente, utilisez une compétence. Une compétence peut se limiter au jugement et rester celle que vous utilisez le plus, comme le montre Ponytail, qui pousse un agent de code à 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 jugement peut aussi mener dans l’autre direction : 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 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. Dans un client qui les charge au préalable, ces éléments restent dans la requête pendant toute la session, qu’ils soient utilisés ou non. Claude Code ne fonctionne plus ainsi par défaut : depuis octobre 2026, sa recherche d’outils est activée par défaut. Au démarrage de la session, seuls les noms des outils et les instructions des serveurs sont chargés. Les définitions complètes sont chargées lorsque Claude les recherche. Une skill 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 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 vos propres serveurs, 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 compétence minimale

Dans Claude Code, les compétences personnelles se trouvent dans ~/.claude/skills/<name>/SKILL.md et s’appliquent à tous vos projets. Les compétences 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 possède donc. GitHub Copilot et VS Code lisent les compétences du projet depuis .github/skills/ et .agents/skills/, ainsi que depuis .claude/skills/. Le fichier qu’ils contiennent est le même.

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.

Cette compétence est complète. Le nom du répertoire devient la commande que vous saisissez. Ici, il s’agit donc de /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, vérifiez d’abord les noms : le fichier doit s’appeler SKILL.md. La spécification Agent Skills exige aussi que le nom utilise uniquement des lettres minuscules, des chiffres et des traits d’union simples, et qu’il corresponde au répertoire. La même procédure, écrite pour pouvoir être relancée par votre agent, accompagne naturellement les sauvegardes restic planifiées sur un VPS, car une sauvegarde qui s’exécute n’est pas nécessairement une sauvegarde qui se restaure.

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.

S’agit-il du format d’un fournisseur ou d’un standard ?

Anthropic a publié ce format fin 2025, puis l’a proposé comme standard ouvert sur agentskills.io. En octobre 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 l’indicateur le plus pertinent. 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. Celui-ci 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 fournisseur crée un recorder dont le format de sortie relève de la spécification d’un autre éditeur, cela indique 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. La définition complète de ses outils occupe le contexte pendant toute la session, sauf si le client en diffère le chargement, comme le fait désormais Claude Code par défaut. 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 la procédure à suivre pour 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 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/, .claude/skills/ ou .agents/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 plutôt qu’un nombre précis. Chaque compétence installée ajoute son nom et sa description, soit environ 100 tokens selon les recommandations 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. Le premier problème concerne la sélection, pas la vitesse : lorsque plusieurs compétences ont des descriptions qui se chevauchent, le modèle a plus de mal à choisir la bonne. Rédigez des descriptions distinctes et supprimez les compétences que vous n’utilisez plus.

Cette instruction doit-elle figurer 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 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 systématique est précisément son rôle. Une procédure exécutée seulement à l’occasion, comme une checklist de release ou un exercice de restauration, doit être une compétence. Elle ne coûte alors que la description d’une ligne pour les tâches qui n’en ont pas besoin. Une section de AGENTS.md qui s’est transformée en étapes numérotées est généralement une compétence qu’il faut déplacer.