Skills IA : documenter un process pour qu’un agent l’exécute

Vous avez écrit un process pour votre agent, il l’exécute correctement la première semaine, puis une règle manque, un champ est mal rempli et vous ne savez plus où corriger. C’est là que les skills IA d’un agent deviennent utiles : un skill est un dossier qui décrit une tâche, et il se corrige comme n’importe quel document de travail.

Documenter un process destiné à un agent comme Claude Code, puis le maintenir dans la durée, tient en six étapes. Elles s’appuient sur la documentation d’Anthropic, sur un article de Sam McLeod et sur mes propres skills en production, dont je date les corrections.

L’essentiel

• Un skill est un dossier avec un SKILL.md dont seuls le nom et la description sont chargés d’office : la description décide du déclenchement.
• Selon Anthropic, des étapes claires évitent à l’agent de sauter une validation et un script rend le répétitif déterministe ; les chemins d’échec écrits d’avance sont une pratique maison.
• Tester sur le plus petit cas réel avant de valider, puis ajouter une règle datée après chaque incident.
• Archiver un skill obsolète avec son historique plutôt que le supprimer, et auditer tout skill tiers avant de l’installer.

AFFICHER LE SOMMAIRE

Prérequis : ce qu’est un skill et ce qu’il coûte en contexte

Selon Anthropic Engineering, un skill est un répertoire qui contient un fichier SKILL.md, lequel commence par un en-tête YAML avec deux champs obligatoires : name et description. Ces deux champs sont chargés au démarrage dans le prompt système. Le corps du fichier n’est lu que si le skill semble pertinent, et les fichiers liés seulement au besoin. Cette divulgation progressive en trois niveaux limite la consommation de contexte.

La conséquence est concrète : la description de chaque skill pèse à chaque session. Mon dossier de skills compte 62 entrées au 16 octobre 2026, et le CLAUDE.md de mon vault interdit d’en recopier la liste, car elle « dérive et double le coût en tokens ».

Pour suivre le tutoriel, il vous faut :

• un agent qui gère les skills, par exemple Claude Code ;
• un process que vous refaites régulièrement, car mon critère est qu’un skill ne se justifie que si la tâche est répétitive ;
• un cas réel, le plus petit possible, pour le test de l’étape 4.

Étape 1 : rédiger une description qui déclenche le skill

La description permet à l’agent de choisir le bon skill parmi potentiellement plus de cent. La documentation officielle d’Anthropic la limite à 1 024 caractères, demande qu’elle dise ce que fait le skill et quand l’utiliser, et la veut rédigée à la troisième personne. Son contre-exemple : « Helps with documents ».

Sam McLeod ajoute que la description ne sert qu’à indiquer quand charger le skill, pas à le résumer. Il la veut courte (environ 30 à 55 mots), à l’impératif, avec les déclencheurs précis. Les deux sources divergent sur la personne grammaticale et s’accordent sur le point central : nommer les situations de déclenchement.

Conseil : relisez votre description en vous demandant quelle phrase de l’utilisateur doit l’activer. Si vous n’en trouvez aucune, réécrivez-la.

Étape 2 : numéroter les étapes et confier le répétitif à un script

Anthropic recommande de découper les opérations complexes en étapes séquentielles claires, avec une checklist que l’agent copie et coche pour les workflows longs, afin qu’il ne saute pas une validation. Le fichier SKILL.md reste sous 500 lignes, et les fichiers liés se trouvent à un seul niveau de profondeur : l’agent peut ne lire qu’une partie d’un fichier appelé depuis un autre fichier.

Pour les tâches déterministes, Anthropic et McLeod convergent : un petit script testable est plus fiable que du code regénéré à chaque fois. Anthropic ajoute qu’il économise des tokens, et McLeod cite Python standard exécuté via uv run.

En pratique, à titre de conseil de rédaction :

1. Une étape = une action.
2. Chaque validation devient une étape à part entière.
3. Les détails propres à un scénario partent dans un fichier lié, avec une phrase qui dit quand le lire.
4. Tout ce qui est répétitif et précis passe dans un script.

Étape 3 : écrire d’avance les chemins d’échec et la section « Ne fait PAS »

Dans mon vault, presque tous les skills suivent la même structure : Rôle, Invocation, Process, puis « Ne fait PAS », une liste négative que je trouve souvent plus utile que la liste positive pour borner le périmètre.

Chaque module de mon pipeline d’articles ajoute un tableau de chemins d’échec. Celui de la recherche en compte sept (F1 à F7) et couvre une page introuvable, moins de trois sources ou un vécu personnel manquant. L’agent sait alors quoi faire hors du cas nominal au lieu d’improviser. Une ligne du module de planification ressemble à ceci :

Échec	Comportement	Destination
Aucun candidat ne passe les filtres	Sortie aucun_slot avec les rejets motivés	Journal de run et tâche au backlog

La règle qui encadre l’ensemble tient en une phrase, écrite dans le skill : un module bloqué ne se contourne jamais en passant au suivant.

Étape 4 : tester sur un cas réel avant de valider

Anthropic demande de créer les évaluations avant d’écrire une documentation étendue : faire tourner l’agent sans skill sur des tâches représentatives, noter ses échecs, écrire trois scénarios, mesurer une base de référence, puis rédiger le minimum d’instructions qui corrige ces échecs. La même documentation décrit un duo : « Claude A » aide à concevoir le skill, « Claude B » le teste sur des tâches réelles. Son exemple : l’agent oublie de filtrer des comptes de test malgré la règle écrite, et la règle est reformulée plus fermement.

Mon process de création de skills contient une règle voisine : ne jamais valider « à froid », donc faire tourner le skill une fois en entier sur le plus petit cas réel. Un piège observé le 4 septembre 2026 sur /audit-projet : juste après l’écriture du fichier, un premier appel a échoué avec « Unknown skill », et le skill est apparu un peu plus tard dans le registre. Conseil : si l’appel échoue juste après la création, relancez-le avant de chercher une faute dans le fichier.

Étape 5 : corriger chaque incident par une règle datée

Dans mes skills de planification et de recherche d’articles, quatre incidents réels, parmi ceux consignés dans ces skills, ont laissé une règle, avec leur date dans le texte du skill :

Date	Incident	Règle ajoutée
19 juillet 2026	Le champ pageId restait vide ; un champ External ID pré-rempli à la migration portait un slug sans rapport avec l’article	Le skill écrit toujours le pageId et écrase l’External ID par le slug de l’article
22 juillet 2026	Un article qui engageait mon vécu a failli partir avec un dossier uniquement issu du web, évité de justesse par une intervention manuelle	Détection de la première personne et étape « source personnelle »
27 juillet 2026	La valeur du champ Site écrite en minuscules a pollué une ligne réelle	Casse et accent exacts précisés, vérifiés sur plus de 549 lignes existantes
1er août 2026	Des formats produits en session humaine n’étaient jamais comptés et une date de mise en ligne était devenue obsolète : trois articles sont retombés sur deux jours (les 3 et 4 août)	Vérification du calendrier réel côté WordPress avant de proposer un jour

Le skill le dit en une formule : « c’est un process, pas un coup de chance ». Je ne dispose d’aucune mesure chiffrée du gain de fiabilité, ni taux d’erreur avant et après, ni comptage des déclenchements. Ces dates montrent seulement que ces quatre incidents se sont terminés par une règle écrite.

Conseil : la date sert de trace d’origine de la règle, pas de condition d’expiration. Notez la cause en une ligne. Anthropic déconseille les informations sensibles au temps, du type « avant août 2025, utilisez l’ancienne API », et propose de ranger l’historique dans une section « old patterns ».

Étape 6 : archiver plutôt que supprimer, et préférer les spécialistes

Le 5 septembre 2026, /prep-article a été absorbé par les modules de planification, de recherche et de pilotage. Il a été déplacé vers un dossier d’archives avec son journal de run, sans être supprimé, et sa ligne du catalogue est passée dans « Skills archivés ».

Sur la granularité, McLeod met en garde contre plusieurs skills proches et mal différenciés. Le 3 septembre 2026, j’ai de mon côté préféré deux skills distincts à un seul skill à deux modes, pour obtenir une description de déclenchement plus nette.

Erreurs fréquentes à éviter

• Une description qui résume au lieu de nommer les déclencheurs (McLeod).
• Un SKILL.md trop long ou des fichiers qui en appellent d’autres : restez sous 500 lignes et à un niveau de référence (Anthropic).
• Faire faire à l’agent le travail d’un script, alors que l’étape est répétitive et exige de la précision (McLeod).
• Installer un skill tiers sans l’auditer. Anthropic Engineering prévient qu’un skill peut introduire des vulnérabilités ou inciter l’agent à exfiltrer des données, et demande d’examiner ses dépendances, ses scripts et ses connexions réseau. McLeod recommande le moindre privilège.
• Règle maison : éviter le parallèle. Dans mes skills qui traitent plusieurs unités, la règle est séquentielle : si la session est coupée pendant un run parallèle, rien n’est intégré, alors qu’en séquentiel chaque unité traitée est définitivement acquise.

Brancher le skill dans le reste de votre pile

Un skill est une pièce parmi d’autres. Dans un pipeline éditorial IA pour son site, mes modules de planification, de recherche et de pilotage sont des skills : chacun renvoie à sa spec de référence, et tant que le skill est au premier palier d’autonomie, je valide chaque slot avant toute écriture, la publication restant un geste humain. Côté prise en main de l’outil, voir aussi Claude Code pour le SEO sans coder.

Pour les tâches qui reviennent chaque semaine, la question de l’automatisation se pose ensuite : automatiser ses tâches SEO hebdomadaires avec n8n est une suite possible. L’ensemble forme une stack IA solopreneur dont le skill documente la procédure.

Conseil : gardez les règles valables à chaque session dans le fichier de contexte de l’agent, et les procédures à la demande dans les skills, puisque seule la description de ceux-ci est chargée d’office.

Résultat attendu

Si vous avez suivi les six étapes, vous disposez d’un skill testé en entier sur un cas réel, aux étapes numérotées, avec ses chemins d’échec écrits et un historique daté. Prochaine action : prenez la tâche que vous avez refaite trois fois ce mois-ci et écrivez d’abord sa description.

FAQ

Faut-il tester un skill sur plusieurs modèles ?

La documentation d’Anthropic le recommande, car l’efficacité d’un skill dépend du modèle sous-jacent. Elle pose une question par modèle : avec Haiku, le skill donne-t-il assez de consignes ? Avec Sonnet, est-il clair et efficace ? Avec Opus, évite-t-il d’en dire trop ? Conseil : testez-le sur les modèles que vous utilisez réellement.

Quelle liberté laisser à l’agent dans un skill ?

Anthropic distingue trois niveaux selon la fragilité de la tâche : liberté élevée (consignes en texte) quand plusieurs approches se valent, moyenne (pseudo-code ou script paramétré) quand un schéma est préférable, faible (un script précis) quand une erreur coûte cher. La documentation déconseille aussi de multiplier les options : donnez une méthode par défaut et une alternative de secours.

Où les skills sont-ils pris en charge ?

Selon Anthropic Engineering, les skills sont disponibles dans Claude.ai, Claude Code, le Claude Agent SDK et la plateforme développeur, et Anthropic a publié Agent Skills comme standard ouvert le 18 décembre 2025 pour la portabilité entre plateformes. Conseil : vérifiez la prise en charge dans l’outil que vous utilisez avant de migrer un skill.