Comment créer votre propre skill d’agent

Rédigez votre propre skill d’agent à partir d’un échec réel

La meilleure façon de rédiger votre propre skill d’agent consiste à la tirer d’un échec réel. Trouvez une tâche que votre coding agent a mal exécutée deux fois, notez la correction que vous avez saisie dans les deux cas, puis enregistrez cette correction dans un fichier SKILL.md que l’agent pourra charger seul. Tout le reste relève de la mécanique : la structure du fichier et la ligne qui détermine si la skill se déclenche.

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

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 un fichier.

Voici un échec qui se répète sur de vrais serveurs. 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 faute de syntaxe, 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 d’intervenir sur le service, puis appliquez-la avec reload au lieu de restart. Une semaine plus tard, la même erreur se produit dans le cadre d’une autre tâche. C’est la deuxième occurrence qui constitue le signal.

Notez deux éléments pendant que l’échec est encore visible : la demande que vous avez saisie et la correction que vous avez donnée, avec vos propres formulations. Ces deux lignes deviennent la skill. La demande indique ce que le déclencheur doit détecter. La correction constitue l’intégralité du contenu.

Les recommandations d’Anthropic sur la rédaction commencent par cette étape. Exécutez l’agent sur des tâches représentatives sans skill, relevez ses échecs, puis rédigez les instructions minimales qui corrigent ces problèmes. Les échecs constituent la spécification. Une skill que vous ne pouvez pas relier à un échec précis est généralement une skill dont personne n’avait besoin.

Pour voir un exemple détaillé de la même méthode de synthèse, vous pouvez lire de bout en bout Ponytail transforme en skill un échec répété : un agent réécrit beaucoup plus que ce que vous avez demandé.

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 ---, suivi des instructions en markdown. 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 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 : indique ce que fait la skill et quand l’utiliser, dans une limite de 1 024 caractères. Cette ligne fait l’essentiel du travail, et la section suivante porte uniquement sur ce point.
• Le corps : les instructions, chargées uniquement lorsque la skill se déclenche réellement.
• reference/ : les fichiers supplémentaires que l’agent lit à la demande. Référencez-les depuis SKILL.md et limitez les liens à un seul niveau, car un fichier référencé depuis un autre fichier lui-même 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 coûte donc peu.

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

• .claude/skills/<name>/SKILL.md dans le dépôt : ce projet uniquement, et la skill est distribuée à toutes les personnes qui clonent le dépôt.
• ~/.claude/skills/<name>/SKILL.md : tous les projets sur votre machine, et personne d’autre.
• <plugin>/skills/<name>/SKILL.md : intégrée à un plugin, elle est 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 début de la session.

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

Au démarrage, l’agent charge les name et description de chaque skill disponible dans son contexte. Il n’en charge pas le contenu. Lorsque votre requête arrive, cette seule ligne sert de base pour déterminer si le skill est pertinent. Un contenu parfait derrière 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, où la première personne donne l’impression que le modèle parle de lui-même.

Faites-y figurer deux éléments : ce que fait le skill et dans quelles conditions il s’applique. Placez d’abord le cas d’usage important, car Claude Code tronque l’entrée de la liste à 1,536 caractères. Un champ when_to_use facultatif permet d’ajouter des expressions de déclenchement et des exemples de requêtes ; son contenu est ajouté à la description dans cette 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 mentionne /etc/nginx, server block, reverse proxy et TLS (transport layer security) certificate path, ce qui correspond à peu près au vocabulaire de toute requête 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 requête que vous êtes sur le point de 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 du skill concis, car il reste dans le contexte

Lorsqu’un skill est invoqué, 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 à moins de 500 lignes et de déplacer les détails dans des fichiers distincts. La compaction explique 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, conserve uniquement les 5 000 premiers tokens de chacun et remplit un budget combiné de 25 000 tokens en commençant par le skill invoqué le plus récemment. Un skill long est tronqué en cours de route. Plusieurs skills longs peuvent s’exclure entièrement les uns les autres.

Écrivez donc uniquement ce que le modèle ne sait 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-dessus de restart. Cette règle est la seule raison d’être de ce fichier.

Si le 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 du skill, puis préautorisez la même commande pour que l’exécution ne soit pas interrompue par 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é le skill et est supprimée lorsque vous envoyez votre message suivant. Elle ne devient donc pas silencieusement une permission permanente.

Comment vérifier que la skill se déclenche

Observer le chargement d’une skill confirme que l’agent l’a trouvée. Cela ne signifie pas que la réponse a changé. Vérifiez les deux points, dans une session vierge, car la session dans laquelle vous avez écrit la skill contient déjà tout ce que vous avez dit 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 son invocation. Si la skill ne se déclenche pas, corrigez sa description. Le corps de la skill n’est pas encore en cause.
4. Invoquez-la manuellement avec /nginx-config-changes pour effectuer un contrôle. Si le comportement est correct lors de l’invocation manuelle, mais incorrect lors de 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, puis 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 inactive.

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 subagent. Chaque exécution démarre ainsi avec un contexte vierge. Le plugin génère ensuite une comparaison with-skill/without-skill. C’est la mesure pertinente : l’amélioration du taux de réussite rapportée au nombre de tokens et au temps consommés par la skill.

Mode d’échec : le skill ne se déclenche jamais

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

• La description indique ce que fait le skill, mais jamais quand l’utiliser. Aucun élément de votre demande ne correspond donc à cette description.
• 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 le frontmatter. La description est alors entièrement exclue du contexte du modèle, et le skill peut uniquement être invoqué par vous avec /name.
• Un glob paths dans le frontmatter limite l’activation aux fichiers correspondants. Le fichier sur lequel vous travaillez ne correspond pas à ce glob.
• Le skill se trouve dans un répertoire .claude/skills/ imbriqué sous votre répertoire de départ. Ces skills ne sont chargés qu’après que l’agent a lu ou modifié un fichier situé dans ce sous-répertoire. Tant que cela ne s’est pas produit, le skill n’est pas disponible.

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

Le problème inverse vient d’une description trop large, qui déclenche le skill pour des tâches sans rapport. « Utiliser lors de 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 pour le reste de la session.

Limitez la description à la condition réellement concernée, et indiquez les fichiers ou les commandes couverts. Ajoutez un glob paths lorsque le skill ne s’applique qu’à certains fichiers. Pour toute action ayant des effets de bord, comme un déploiement ou un commit, définissez disable-model-invocation: true et appelez vous-même le skill avec /name, afin que l’agent ne décide jamais seul que le moment est venu de déployer.

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

Un fichier de règles comme CLAUDE.md ou AGENTS.md est chargé au début de chaque session et s’applique à toutes les tâches. Le contenu d’une compétence n’est chargé que lorsque celle-ci est activée. La fréquence est le seul critère de décision. Un élément valable pour toutes les tâches 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 adopte un comportement incorrect, vous ne pouvez pas déterminer quelle copie il a suivie. Choisissez un emplacement unique pour chaque instruction. la distinction entre les compétences, les serveurs MCP et les fichiers de règles traite les cas plus complexes, notamment lorsque la bonne réponse est un serveur MCP (model context protocol) qui fournit un nouvel outil à l’agent plutôt qu’une nouvelle instruction.

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

Une compétence qui résiste à une semaine de travail réel mérite d’être validée dans le dépôt. Les compétences de projet dans .claude/skills/ sont révisées comme du code et sont livrées 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 entre des dépôts sans copier-coller est un autre problème, traité dans la procédure de 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 envoyez une compétence vers claude.ai ou si vous la préparez pour la Skills API avec d’autres champs dans le frontmatter, l’opération échoue complètement au lieu d’ignorer le champ :

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

Restez dans le cadre de ces six champs. Le même fichier se chargera alors dans Claude Code et dans tout autre outil qui lit le standard. Rédiger les instructions elles-mêmes pour qu’elles restent compatibles avec un autre modèle est une tâche distincte. Rédiger des compétences compatibles avec tous les modèles l’explique.

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 corps du fichier est ajouté à la conversation lorsque le skill est invoqué et y reste pendant toute la session. Chaque ligne représente donc un coût récurrent, et non un coût ponctuel. Placez les documents de référence volumineux 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, afin que l’agent ne les lise que lorsqu’il en a besoin. Les scripts inclus sont exécutés au lieu d’être lus. Leur coût se limite donc à leur sortie.

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

La description en est généralement la 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 demandes. Si la description semble correcte, vérifiez la présence de disable-model-invocation: true dans le frontmatter. Ce champ masque complètement le skill au modèle. Vérifiez également la présence d’un glob paths qui le limite à des 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 dans mon fichier de règles ?

Déterminez le nombre de tâches auxquelles 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 est chargé uniquement lorsqu’il se déclenche. Il convient donc à une procédure utile pour une faible part 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. Rassemblez quelques demandes réelles, exécutez chacune d’elles dans une nouvelle session avec le skill disponible, puis recommencez avec le skill désactivé depuis le menu /skills, et comparez les deux réponses côte à côte. Une nouvelle session est nécessaire, car la conversation dans laquelle vous avez écrit le skill contient encore vos explications. Un fichier incomplet peut alors sembler complet. Le plugin skill-creator effectue cette comparaison pour vous 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, tant que vous restez dans les champs définis par le standard Agent Skills : name, description, license, compatibility, metadata et allowed-tools. Claude Code accepte de nombreux autres champs. Il prend également en charge des fonctionnalités 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 absent du standard échoue avec une erreur explicite qui liste les propriétés autorisées. Déterminez donc dès le départ si le skill doit rester dans Claude Code ou être utilisé avec d’autres outils.