Compétences d’agent

Une compétence est une procédure opérationnelle conditionnée qu’un agent peut découvrir et charger pour une tâche correspondante. La spécification partagée définit un cœur portable autour d’un répertoire et de SKILL.md ; au-delà, chaque hôte gère à sa façon la découverte, les métadonnées, l’activation, les outils et l’exécution de code.

Qu’une compétence serve ou non dépend d’une ou deux phrases de description. Au démarrage, l’agent ne place dans son contexte que le name et la description de chaque compétence ; quand votre demande correspond à une description, il lit le SKILL.md en entier ; les fichiers de references/ ne s’ouvrent que lorsque ce corps lui demande de les lire. Prenons verify-release ci-dessous : en temps normal, seule la phrase « Check a release candidate after code is already staged; do not deploy. » est dans le contexte. Demandez « vérifie ce candidat à la publication », et l’agent charge ses cinq étapes. Ce chargement par couches, à la demande, s’appelle la divulgation progressive : un agent qui a installé des dizaines de compétences ne porte par défaut que des dizaines de descriptions.

Une compétence est une convention et un ensemble de contenus, pas une sandbox isolée ni la preuve qu’une procédure fonctionne.

Anatomie d’un paquet

Un répertoire my-skill/ typique contient :

• SKILL.md pour le déclencheur, les limites, le flux et les vérifications ;
• scripts/ pour la mécanique déterministe lorsqu’elle est justifiée ;
• references/ pour le contenu détaillé chargé à la demande ;
• assets/ pour les modèles ou exemples non secrets ;
• d’éventuelles métadonnées propres à l’hôte.

Au 1er octobre 2026, Claude Code, ChatGPT et Codex, Gemini CLI, Cursor et GitHub Copilot documentent tous la prise en charge de ce format ouvert, et les différences apparaissent justement dans la façon de lister les descriptions, de charger le corps et d’activer les compétences.

C’est Codex qui montre le plus nettement la conséquence. Par défaut, il limite la liste initiale des compétences à 2 % de la fenêtre de contexte du modèle, ou à 8 000 caractères si la taille de la fenêtre est inconnue ; quand beaucoup de compétences sont installées, il raccourcit d’abord les descriptions et peut en omettre certaines, si bien qu’une description vague peut rendre une compétence introuvable. Ce budget se règle avec skills.max_context_tokens, jusqu’à 10 000 tokens ; il ne concerne que la liste initiale, et une fois une compétence choisie, Codex lit quand même tout son SKILL.md.

Les autres hôtes diffèrent par l’activation et les extensions. Gemini CLI demande une confirmation avant de charger une compétence, puis ajoute son répertoire aux chemins que l’agent peut lire. Claude Code ajoute ses propres champs au format : disable-model-invocation: true réserve une compétence à l’appel manuel, et context: fork l’exécute dans un sous-agent. OpenAI lit des réglages facultatifs d’apparence, de politique d’invocation et de dépendances dans agents/openai.yaml. Une compétence qui s’appuie sur les extensions d’un hôte n’est portable que dans son noyau.

Où placer sa première compétence, et les limites de son nom et de sa description

Un hôte ne trouve un dossier de compétence que s’il est rangé là où il cherche :

Hôte	Emplacement dans le projet	Emplacement personnel	Appel manuel	Désactiver le chargement automatique
Claude Code	.claude/skills/<name>/SKILL.md, cherché depuis le répertoire de lancement jusqu’à la racine du dépôt	~/.claude/skills/<name>/SKILL.md	/name	disable-model-invocation: true
Codex	.agents/skills, parcouru dans chaque répertoire du répertoire courant jusqu’à la racine du dépôt	$HOME/.agents/skills	$name	allow_implicit_invocation: false dans agents/openai.yaml
Pi	.agents/skills/, cherché depuis le répertoire courant jusqu’à la racine du dépôt	~/.agents/skills/	/skill:name	disable-model-invocation: true

Selon la spécification, les métadonnées de SKILL.md n’ont que deux champs obligatoires :

• name compte au plus 64 caractères : lettres minuscules, chiffres et traits d’union ; il ne peut ni commencer ni finir par un trait d’union, ne peut pas contenir -- et doit porter le même nom que le dossier.
• description compte au plus 1 024 caractères et dit ce que fait la compétence et quand l’utiliser.
• Les champs facultatifs sont license, compatibility, metadata et allowed-tools, ce dernier marqué comme expérimental.
• Gardez le corps sous 500 lignes et 5 000 tokens ; déplacez les longues références dans references/.

La commande skills-ref validate ./my-skill fournie par la spécification vérifie le format. Claude Code ajoute sa propre limite : dans la liste des compétences, description plus when_to_use est tronqué à 1 536 caractères, donc placez l’usage principal en tête. Ses anciennes commandes personnalisées .claude/commands/ ont aussi été fusionnées dans les compétences, et la compétence l’emporte quand les deux portent le même nom.

Ce qui a sa place dans une compétence

• une méthode répétée d’une session ou d’un dépôt à l’autre ;
• des règles de domaine qui influent sensiblement sur la sécurité de l’exécution ;
• une séquence bornée avec entrées, sorties, conditions d’arrêt et vérifications ;
• des scripts déterministes qu’il est plus sûr de réutiliser que de régénérer.

Conservez les règles d’autorité stables dans les instructions du dépôt/de l’utilisateur. Conservez les faits ordinaires dans la documentation. Lorsque ce qui manque est une connectivité active plutôt qu’une procédure, branchez un serveur Model Context Protocol (MCP) ou une autre intégration. Les deux peuvent aussi aller ensemble. L’extension Skills officielle de MCP (io.modelcontextprotocol/skills, SEP-2640, désormais finalisée) permet à un serveur de distribuer des dossiers de compétences avec le service qu’ils décrivent. Les clients découvrent et lisent ces compétences par les Resources, et l’hôte peut toujours exiger l’accord de l’utilisateur avant d’en charger une. La prise en charge de l’extension par les hôtes est encore en cours.

Squelette illustré

---
name: verify-release
description: Check a release candidate after code is already staged; do not deploy.
---

# Verify release

1. Read the repository release policy completely.
2. Confirm the working tree and target version.
3. Run the smallest checks, then the full offline baseline.
4. Record commands, exit states, and skipped live checks.
5. Stop on credentials, destructive migration, or deployment request.

La description contient à la fois le déclencheur et l’exclusion : le déclencheur est « le code est déjà indexé et un candidat à la publication doit être vérifié », l’exclusion est « ne pas déployer ». Le corps contient des preuves et des conditions d’arrêt, pas de prose incitative.

Tester une compétence

Testez plus que la validité du dossier :

Test	Question
déclencheur positif	Une demande correspondante charge-t-elle la compétence ?
déclencheur négatif	Une tâche voisine l’évite-t-elle ?
cas limite	S’arrête-t-elle avant un travail non autorisé ?
exécution de la tâche	L’agent peut-il produire l’artefact et les vérifications attendus ?
référence obsolète	Une commande ou API déplacée échoue-t-elle visiblement ?
portabilité	Que change un autre hôte, modèle ou ensemble d’outils ?

Conservez les exemples d’activation échouée. Sinon, les descriptions s’élargissent avec le temps parce que seules les démonstrations réussies sont observées.

Risques et compromis

• les instructions peuvent entrer en conflit avec une politique prioritaire ou les règles du dépôt ;
• scripts et paquets peuvent s’exécuter avec la pleine autorité de l’utilisateur ;
• les compétences longues peuvent consommer le contexte et encourager le rituel plutôt que le jugement ;
• une description trop large charge la compétence pour des tâches sans rapport ; une description trop étroite la laisse de côté quand elle devrait servir ;
• les fonctionnalités propres à un hôte peuvent rendre non portable une compétence prétendument portable ;
• les compétences copiées vieillissent, divergent et créent un risque de chaîne d’approvisionnement.

Inspectez les compétences tierces comme du code, figez leur provenance quand c’est utile, gardez les secrets hors du paquet et testez dans un espace de travail isolé. Une compétence doit réduire le raisonnement répétitif tout en préservant les décisions visibles, et non devenir une seconde application cachée dans Markdown.

Revenir au parcours