Comment créer votre propre skill d’agent

Écrivez votre propre skill d’agent à partir d’un échec réel

La meilleure façon d’écrire votre propre skill d’agent consiste à la tirer d’un échec réel. Trouvez une tâche que votre agent de codage a mal exécutée deux fois, notez la correction que vous avez saisie à chaque fois, puis enregistrez cette correction dans un fichier SKILL.md que l’agent peut charger lui-même. Tout le reste relève de la mise en œuvre : la structure des fichiers et la ligne qui détermine si la skill sera déclenchée.

Cet ordre est important. Une skill imaginée décrit un problème que vous n’avez jamais rencontré et consomme malgré tout du contexte à chaque session. Une skill tirée d’un échec observé est fournie avec son propre test : posez de nouveau la même question et vérifiez si l’agent répond correctement cette fois-ci. Si ce format est nouveau pour vous, lisez d’abord ce que sont les skills d’agent et comment un agent en charge une, puis revenez écrire la vôtre.

Commencez par une tâche que l’agent a mal exécutée deux fois

Une fois peut être un hasard. Deux fois, c’est un schéma, et un schéma mérite d’être consigné.

Voici un échec qui se répète sur des serveurs réels. Vous demandez à l’agent d’ajouter un bloc de reverse proxy à nginx. Il modifie /etc/nginx/conf.d/app.conf, puis exécute sudo systemctl restart nginx. La modification contient une erreur, nginx refuse donc de démarrer et le site reste indisponible jusqu’à ce que vous corrigiez le problème :

nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.

Vous corrigez le problème dans le chat. Testez la configuration avec sudo nginx -t avant de toucher au service, puis appliquez-la avec reload au lieu de restart. Une semaine plus tard, une autre tâche présente la même erreur. La deuxième occurrence est le signal.

Notez deux éléments tant que l’échec est encore sous vos yeux : la demande que vous avez saisie et la correction que vous avez donnée, avec vos propres mots. Ces deux lignes deviennent la skill. La demande indique ce que le déclencheur doit détecter. La correction constitue tout le contenu.

Les recommandations de rédaction d’Anthropic placent cette étape en premier. Exécutez l’agent sur des tâches représentatives sans skill, relevez les points où il échoue, puis rédigez les instructions minimales qui corrigent ces échecs. Les échecs constituent la spécification. Une skill que vous ne pouvez pas rattacher à un échec précis est généralement une skill dont personne n’avait besoin.

Pour voir un exemple détaillé de cette même démarche de synthèse, Ponytail transforme un échec répété, un agent qui réécrit bien plus que demandé, en skill que vous pouvez lire intégralement avant de rédiger la vôtre.

Anatomie d’une skill

Une skill est un répertoire qui contient un fichier obligatoire.

.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│   └── proxy-headers.md
└── scripts/
    └── check-and-reload.sh

SKILL.md commence par un bloc de frontmatter contenant quelques paramètres écrits en YAML, le même format de configuration que celui utilisé par les fichiers Docker Compose, entre les marqueurs ---. Les instructions en markdown viennent ensuite. Voici la skill complète correspondant à l’échec précédent.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---

## Rules

Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.

Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.

If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.

For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).

Ce fichier fait moins de vingt lignes et constitue une skill complète. Voici ses éléments :

• name : 64 caractères au maximum, uniquement des lettres minuscules, des chiffres et des tirets. Il ne peut pas contenir les mots claude ou anthropic. Dans une skill personnelle ou de projet, il s’agit uniquement du libellé affiché. La commande que vous saisissez vient du nom du répertoire ; celle-ci répond donc à /nginx-config-changes.
• description : décrit ce que fait la skill et quand l’utiliser, avec 1 024 caractères au maximum. Cette ligne assure l’essentiel du fonctionnement. La section suivante porte uniquement sur ce point.
• Le corps : les instructions, chargées uniquement lorsque la skill est effectivement déclenchée.
• reference/ : les fichiers supplémentaires que l’agent lit à la demande. Référencez-les depuis SKILL.md et limitez les liens à un niveau de profondeur, car un fichier référencé depuis un autre fichier référencé n’est souvent lu que partiellement.
• scripts/ : les fichiers que l’agent exécute au lieu de les lire. Seule leur sortie consomme du contexte ; un script de 300 lignes reste donc peu coûteux.

Une compétence évolue vers une structure complète lorsque le comportement qu’elle corrige est suffisamment tenace pour le justifier, et la compétence unlazy utilise cet espace pour un arbre de profondeur, un ensemble de fichiers gates et un contrat PLAN.md afin d’empêcher un agent d’annoncer qu’il a terminé alors que des branches entières du travail restent intactes.

L’emplacement du répertoire détermine les utilisateurs de la skill.

• .claude/skills/<name>/SKILL.md dans le dépôt : uniquement pour ce projet, et distribué à toutes les personnes qui clonent le dépôt.
• ~/.claude/skills/<name>/SKILL.md : pour tous les projets sur votre machine, mais pour personne d’autre.
• <plugin>/skills/<name>/SKILL.md : fourni dans un plugin, disponible partout où ce plugin est activé.

Créez-en une avec mkdir -p .claude/skills/nginx-config-changes, puis écrivez le fichier. Claude Code surveille ces répertoires. La modification d’une skill existante prend donc effet dans la session en cours. La création d’un répertoire skills à la racine qui n’existait pas au démarrage de la session nécessite un redémarrage, car rien ne pouvait être surveillé au lancement de la session.

Le champ de description est la ligne la plus déterminante du fichier

Au démarrage, l’agent charge le name et le description de chaque skill disponible dans son contexte. Il ne charge pas leur contenu. Lorsque votre demande arrive, cette seule ligne constitue la base complète permettant de déterminer si ce skill est pertinent. Un contenu parfait associé à une description vague ne sera donc jamais lu.

Rédigez la description à la troisième personne. « Teste et recharge nginx en toute sécurité » convient. « Je peux vous aider avec nginx » ne convient pas, car le texte est injecté dans le system prompt et la première personne donne l’impression que le modèle parle de lui-même.

Indiquez-y deux éléments : ce que fait le skill et la condition dans laquelle il s’applique. Placez le cas d’usage important en premier, car Claude Code tronque l’entrée de la liste à 1,536 caractères. Le champ when_to_use est facultatif. Il permet d’ajouter des expressions de déclenchement et des exemples de demandes. Son contenu est ajouté à la description dans la même limite.

Utilisez ensuite les mots que vous saisirez réellement. description: Helps with nginx ne correspond à rien, car personne ne saisit « aide avec ». La version précédente nomme /etc/nginx, server block, reverse proxy et TLS (transport layer security) certificate path, ce qui correspond approximativement au vocabulaire de toute demande qui devrait déclencher ce skill.

Voici le test à appliquer à une description. Donnez cette seule ligne à une personne qui n’a jamais vu le contenu du skill, avec la demande que vous vous apprêtez à saisir, puis demandez-lui si le skill s’applique. Si elle ne peut pas le déterminer, le modèle ne le pourra pas non plus.

Gardez le corps concis, car il reste dans le contexte

Lorsqu’une skill est invoquée, son contenu rendu entre dans la conversation sous la forme d’un message et y reste pendant toute la session. Claude Code ne relit pas le fichier aux tours suivants. Chaque ligne que vous écrivez représente un coût pour toute la session, et pas pour une seule réponse.

Anthropic recommande de maintenir SKILL.md sous 500 lignes et de déplacer les détails dans des fichiers séparés. La compaction montre pourquoi ce nombre n’est pas arbitraire. Lorsque la conversation est résumée pour libérer du contexte, Claude Code rattache la dernière invocation de chaque skill, ne conserve que les 5 000 premiers tokens de chacune et remplit un budget combiné de 25 000 tokens en commençant par la skill invoquée le plus récemment. Une skill longue est tronquée en cours de route. Plusieurs skills longues peuvent s’exclure entièrement les unes les autres.

Écrivez donc uniquement ce que le modèle ne connaît pas déjà. Il sait ce qu’est nginx et ce que fait un reverse proxy. En revanche, il ne connaît pas votre règle interne concernant reload au-delà de restart, et cette règle est la seule raison d’être de ce fichier.

Si la skill demande à l’agent d’exécuter un script inclus, indiquez le chemin avec ${CLAUDE_SKILL_DIR} afin qu’il soit résolu quel que soit l’emplacement d’installation de la skill, et préautorisez la même commande pour que son exécution ne s’arrête pas sur une demande d’autorisation.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---

L’autorisation couvre le tour qui a invoqué la skill et est supprimée lorsque vous envoyez votre message suivant. Elle ne devient donc pas discrètement une autorisation permanente.

Comment prouver que la skill se déclenche

Observer le chargement d’une skill montre que l’agent l’a trouvée. Cela ne montre pas que la réponse a changé. Vérifiez les deux points, et faites-le dans une nouvelle session, car la session dans laquelle vous avez écrit la skill contient déjà tout ce que vous avez indiqué pendant sa rédaction. Ce contexte résiduel masque les lacunes du fichier.

1. Démarrez une nouvelle session avec claude dans le projet.
2. Saisissez la demande comme vous le feriez lors d’une journée de travail ordinaire, avec vos propres mots, sans nommer la skill.
3. Surveillez l’invocation. Si la skill ne se déclenche pas, corrigez sa description. Le corps n’est pas encore en cause.
4. Invoquez-la manuellement avec /nginx-config-changes pour disposer d’un contrôle. Si le comportement est correct lors de l’invocation manuelle, mais incorrect avec la demande, le problème vient du déclencheur et non des instructions.
5. Exécutez la même demande avec la skill désactivée et comparez les deux réponses. Dans le menu /skills, sélectionnez la skill, appuyez sur Space pour faire défiler son état jusqu’à off, puis sur Enter pour enregistrer. Cela ajoute une entrée skillOverrides dans .claude/settings.local.json. Appuyez de nouveau sur Space pour revenir à on lorsque vous avez terminé.
6. Rédigez quelques demandes qui ne doivent pas déclencher la skill et vérifiez qu’elle reste silencieuse dans ces cas.

Pour automatiser cette boucle, installez le plugin skill-creator depuis la marketplace officielle.

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

Si la sortie de l’installation indique Run /reload-plugins to activate., exécutez cette commande. Demandez ensuite à Claude d’évaluer votre skill par son nom. Le plugin stocke les cas de test dans evals/evals.json, dans le répertoire de la skill, et exécute chaque cas dans son propre sous-agent. Chaque exécution démarre ainsi avec un contexte vierge. Il produit ensuite une comparaison with-skill contre without-skill. C’est la mesure pertinente : l’amélioration du taux de réussite, rapportée aux tokens et au temps consommés par la skill.

Une skill peut aussi contenir sa propre preuve, au lieu de laisser cette tâche à une exécution d’évaluation séparée. C’est ce que fait la skill Old Coder lorsqu’elle demande à l’agent de renvoyer un rapport de preuves que vous pouvez réexécuter vous-même.

Mode d’échec : la compétence ne se déclenche jamais

Vous saisissez la demande, l’agent effectue l’ancienne mauvaise action et aucune ligne de compétence n’apparaît. Vérifiez les points suivants dans l’ordre.

• La description indique ce que fait la compétence, mais jamais quand l’utiliser. Rien dans votre demande ne lui correspond donc.
• La description n’emploie pas les mots que vous saisissez. Si vous dites « nginx », la description doit contenir « nginx ».
• disable-model-invocation: true est défini dans les métadonnées frontmatter. La description est alors entièrement exclue du contexte du modèle, et la compétence ne peut être invoquée que par vous avec /name.
• Un motif glob paths dans les métadonnées frontmatter limite l’activation aux fichiers correspondants, et le fichier sur lequel vous travaillez ne correspond pas à ce motif.
• La compétence se trouve dans un répertoire .claude/skills/ imbriqué sous votre répertoire de départ. Ces compétences ne sont chargées qu’après que l’agent a lu ou modifié un fichier dans ce sous-répertoire. Elles ne sont donc pas disponibles avant cela.

Mode d’échec : le skill se déclenche constamment

Le problème inverse apparaît lorsque la description est trop générale et que le skill se déclenche pour des tâches sans rapport. « À utiliser pour toute intervention sur le serveur » correspond à presque toutes les demandes dans un dépôt serveur. Le corps du skill est alors chargé pour des tâches auxquelles il ne peut pas contribuer, et reste dans le contexte pendant le reste de la session.

Limitez la description à la condition réellement pertinente et indiquez les fichiers ou les commandes concernés. Ajoutez un glob paths lorsque le skill ne s’applique qu’à certains fichiers. Pour toute opération ayant des effets de bord, comme un déploiement ou un commit, définissez disable-model-invocation: true et invoquez vous-même le skill avec /name. L’agent ne décidera ainsi jamais seul que le moment est approprié pour effectuer un déploiement.

Mode d’échec : la compétence doit figurer dans votre fichier de règles

Un fichier de règles tel que CLAUDE.md ou AGENTS.md est chargé au début de chaque session et s’applique à chaque tâche. Le contenu d’une compétence n’est chargé que lorsque la compétence est activée. Tout dépend de la fréquence. Un élément qui s’applique à chaque tâche du dépôt, comme le gestionnaire de paquets utilisé, doit figurer dans le fichier de règles. Une procédure qui ne s’applique qu’à une petite partie des tâches, comme la règle nginx ci-dessus, doit figurer dans une compétence. Elle ne coûte rien les jours où personne ne modifie nginx.

La véritable erreur consiste à le placer aux deux endroits. Les deux copies finissent par diverger et, lorsque l’agent agit incorrectement, vous ne pouvez pas déterminer quelle copie il a suivie. Choisissez un seul emplacement pour chaque instruction. Lorsqu’une règle figure déjà dans un seul emplacement et qu’elle est tout de même ignorée, le problème est différent. Il est utile de vérifier les mécanismes qui expliquent pourquoi une instruction est ignorée avant de la déplacer dans une compétence en espérant que ce déplacement résoudra le problème. La distinction entre les compétences, les serveurs MCP et les fichiers de règles permet de traiter les cas plus complexes, notamment lorsque la bonne solution est un serveur MCP (model context protocol) qui fournit à l’agent un nouvel outil plutôt qu’une nouvelle instruction.

Partagez-la une fois qu’elle a fait ses preuves

Une compétence qui reste utile après une semaine de travail réel mérite d’être enregistrée. Les compétences de projet dans .claude/skills/ sont révisées comme du code et incluses avec le dépôt. Un collègue qui le clone récupère donc votre correction sans étape de configuration. Déplacer une compétence d’un dépôt à un autre sans copier-coller est un autre problème, traité dans le partage des compétences d’agent entre dépôts.

Une remarque sur la portabilité. Claude Code accepte une longue liste de champs frontmatter, mais le standard Agent Skills n’en autorise que six : name, description, license, compatibility, metadata et allowed-tools. Si vous téléversez une compétence vers claude.ai ou la préparez pour l’API Skills avec un autre champ dans le frontmatter, le chargement échoue au lieu d’ignorer ce champ :

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Limitez-vous à ces six champs. Le même fichier pourra alors être chargé par Claude Code et par les autres outils qui lisent le standard. L’environnement dans lequel le fichier est chargé détermine toutefois ce qu’il peut faire, car Cowork s’exécute dans un sandbox Anthropic, tandis que Claude Code s’exécute sur votre propre machine ou VPS. La compétence nginx ci-dessus mérite donc d’être transférée dans le checkout d’un collègue, mais elle ne sert à rien dans un sandbox qui ne peut pas joindre le serveur. Écrire des instructions qui restent efficaces avec un autre modèle est un travail distinct. Écrire des compétences compatibles avec tous les modèles traite ce sujet.

FAQ

Quelle doit être la longueur d’un fichier SKILL.md ?

Limitez-le à 500 lignes, et prévoyez que la plupart des skills utiles soient bien plus courts. Le contenu est ajouté à la conversation lorsque le skill est invoqué et y reste jusqu’à la fin de la session. Chaque ligne représente donc un coût récurrent, et non un coût ponctuel. Placez les longues références dans des fichiers séparés du répertoire du skill, puis référencez-les depuis SKILL.md, avec un seul niveau de profondeur. L’agent ne les lira ainsi que lorsqu’il en aura besoin. Les scripts inclus sont exécutés au lieu d’être lus ; seul leur résultat est donc pris en compte.

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

La description est généralement en cause, car c’est la seule partie du skill présente dans le contexte lorsque le modèle prend sa décision. Indiquez quand utiliser le skill, et pas seulement ce qu’il fait. Utilisez aussi les termes que vous saisissez réellement dans vos requêtes. Si la description semble correcte, vérifiez la présence de disable-model-invocation: true dans le frontmatter. Ce paramètre masque complètement le skill au modèle. Vérifiez également la présence d’un glob paths qui le limite aux fichiers que vous ne modifiez pas. Un skill placé dans un répertoire .claude/skills/ imbriqué sous votre répertoire de départ constitue une autre cause possible. Il n’est chargé qu’après que l’agent a lu ou modifié un fichier dans ce sous-répertoire.

Ce contenu doit-il être un skill ou une ligne de mon fichier de règles ?

Demandez-vous à combien de vos tâches il s’applique. Un fichier de règles est chargé à chaque session. Il doit donc contenir des informations valables pour toutes les tâches, comme le gestionnaire de paquets ou la convention de nommage des branches. Un skill n’est chargé que lorsqu’il se déclenche. Il convient donc à une procédure utile pour une faible proportion des tâches. N’écrivez jamais la même instruction aux deux endroits. Les deux copies finiraient par diverger et vous ne sauriez plus laquelle l’agent a suivie.

Comment savoir si un skill m’a réellement aidé ?

Comparez-le à une référence de base. Rassemblez quelques requêtes réelles, exécutez chacune dans une nouvelle session avec le skill disponible, puis recommencez avec le skill désactivé depuis le menu /skills. Comparez ensuite les deux réponses côte à côte. Une nouvelle session est importante, car la conversation dans laquelle vous avez écrit le skill contient encore vos explications. Un fichier incomplet peut ainsi sembler complet. Le plugin skill-creator effectue cette comparaison à votre place et indique le taux de réussite à côté du coût en tokens.

Puis-je utiliser le même SKILL.md avec un autre agent ?

Oui, à condition de rester dans les champs définis par le standard Agent Skills : name, description, license, compatibility, metadata et allowed-tools. Claude Code accepte beaucoup d’autres champs et prend également en charge des fonctions dans le corps du fichier, comme l’injection de commandes shell, que les autres outils n’exécutent pas. Le chargement d’un skill contenant un champ non défini par le standard échoue avec une erreur explicite qui liste les propriétés autorisées. Décidez donc dès le départ si le skill doit rester dans Claude Code ou être portable.