Agent Skills 2026 : guide complet

Point de départ vérifiable : la spécification publique impose seulement deux champs obligatoires dans le front matter de SKILL.md — name et description — avec des contraintes respectives de 64 et 1 024 caractères. (github.com)

Conclusion rapide : Agent Skills 2026 n’est pas une nouvelle formation permanente du modèle. C’est un paquet de capacité composé d’instructions, de scripts et de ressources, chargé lorsque la tâche le justifie. Encapsulez donc les processus répétitifs, stables et vérifiables ; ne transformez pas une demande ponctuelle ou un script non audité en Skill.

Cette page est destinée aux développeurs qui découvrent les AI Agent Skills, aux responsables qui veulent transmettre un SOP à un agent et aux chefs de produit qui comparent Prompt, Rules, Skills et Workflow. Si vous cherchez simplement une réponse unique, vous pouvez vous arrêter ici ; si vous voulez rendre une méthode réutilisable par une équipe, poursuivez.

Dernière mise à jour : 12 août 2026. Les éléments normatifs ont été vérifiés à partir de la spécification publique Agent Skills, du dépôt de référence et de la documentation officielle de Claude Code sur les Skills.

Agent Skills 2026 : de quoi parle-t-on exactement ?

Un Agent Skill est un répertoire qu’un agent peut découvrir puis utiliser pour accomplir une famille de tâches. Son entrée principale est un fichier SKILL.md, qui contient des métadonnées et des instructions en Markdown. Le dossier peut également contenir des scripts exécutables, des documents de référence, des modèles, des exemples ou d’autres ressources.

La différence essentielle avec un Prompt classique tient au cycle de vie. Un Prompt transmet une consigne dans une interaction donnée. Une Skill formalise une méthode que vous pouvez partager, maintenir, tester et rappeler dans plusieurs contextes. Elle ne modifie pas les paramètres internes du modèle et ne garantit pas, à elle seule, une exécution correcte.

Dans la pratique, une Skill peut décrire :

• la manière de préparer une branche avant une revue de code ;
• les contrôles à effectuer avant de publier une application ;
• la structure attendue d’un rapport audio ou vidéo ;
• les règles d’analyse d’un fichier de données ;
• les étapes d’un processus administratif interne ;
• les critères de validation d’une documentation technique.

Son intérêt ne vient donc pas de la longueur du fichier, mais de la qualité du processus encapsulé. Une Skill médiocre ne fait que déplacer un Prompt confus dans un dossier ; une bonne Skill réduit les décisions implicites et indique à l’agent comment reconnaître les entrées, les exceptions et les critères d’acceptation.

La spécification publique décrit un format ouvert, tandis que chaque client peut ajouter ses propres mécanismes. Claude Code, par exemple, documente des options d’invocation, des emplacements personnels ou de projet et des fichiers de support. Ces extensions ne doivent pas être présentées comme des champs universels du standard. (github.com)

Pour cadrer un projet d’automatisation avant de choisir une architecture, vous pouvez consulter la présentation de kvmboot et de son approche des environnements de travail distants. Cette étape est utile lorsque l’agent doit accéder à des outils de développement, à des scripts ou à des ressources partagées, mais elle ne remplace pas l’analyse de vos permissions et de vos dépendances.

Les critères qui justifient la création d’une Skill

Le premier risque consiste à créer une Skill parce qu’une tâche semble intéressante. Le bon critère n’est pas la nouveauté, mais la répétition contrôlée. Avant d’écrire SKILL.md, examinez quatre dimensions :

1. Fréquence : l’équipe rencontre-t-elle régulièrement la même catégorie de demande ?
2. Stabilité : les étapes restent-elles relativement constantes d’un projet à l’autre ?
3. Entrées et sorties : pouvez-vous décrire les fichiers, informations ou paramètres reçus, puis le résultat attendu ?
4. Vérifiabilité : existe-t-il un test, une revue humaine ou une règle mesurable pour accepter ou refuser le résultat ?

Un processus de revue de pull request peut souvent devenir une Skill parce que les entrées sont identifiables, les contrôles sont répétables et les sorties peuvent être comparées à une grille. À l’inverse, « trouver une idée originale pour une campagne » est trop ouvert pour être encapsulé sans autre définition.

Tableau de décision initial

Pour les équipes créatives, une Skill peut par exemple imposer une nomenclature de fichiers audio, vérifier la présence de pistes séparées et produire une fiche de livraison. Dans le design, elle peut guider l’export de variantes, les tailles attendues et les contrôles de contraste. L’agent gagne une méthode de travail ; il ne reçoit pas pour autant un jugement esthétique infaillible.

La structure de SKILL.md au moment de la création

La structure minimale est volontairement simple. Selon la spécification publique, un dossier Skill contient au minimum SKILL.md. Les répertoires scripts/, references/ et assets/ sont facultatifs. Le corps Markdown n’est pas limité à une liste de champs imposés ; vous devez y mettre ce qui aide l’agent à exécuter la tâche sans ambiguïté. (github.com)

ma-skill/
├── SKILL.md
├── scripts/
│   └── verifier.sh
├── references/
│   └── procedure-interne.md
└── assets/
    └── modele-rapport.md

Dans SKILL.md, séparez clairement trois fonctions :

• les métadonnées, qui permettent de nommer la Skill et de signaler quand elle est pertinente ;
• les instructions opérationnelles, qui décrivent les étapes, les exceptions et le format de sortie ;
• les renvois vers les ressources, qui indiquent quand consulter un document ou lancer un script.

La spécification publique exige les champs name et description. Le nom doit respecter les contraintes prévues par le format, notamment l’usage de caractères minuscules, de chiffres et de tirets. Le champ description doit dire ce que fait la Skill et dans quels cas elle doit être utilisée. D’autres champs peuvent exister dans certains clients, mais vous ne devez pas les présenter comme obligatoires pour tous les agents.

Exemple minimal

---
name: revue-api
description: Analyse une modification d’API, vérifie les conventions du projet,
les tests associés et les risques de compatibilité. À utiliser avant une revue
de code ou une demande de validation d’endpoint.
---

## Procédure

1. Lire le diff et identifier les endpoints modifiés.
2. Vérifier les schémas de requête et de réponse.
3. Rechercher les tests manquants.
4. Signaler les ruptures de compatibilité.
5. Produire un rapport avec les constats et les commandes exécutées.

## Ressources

- Consulter `references/conventions-api.md` pour les règles détaillées.
- Exécuter `scripts/verifier.sh` uniquement après validation des chemins.

Le champ description mérite une attention particulière : il sert à la découverte et influence la probabilité que l’agent considère la Skill comme pertinente. Il ne s’agit pas d’un entraînement du modèle. Vous améliorez l’index de sélection en indiquant les tâches, les objets manipulés et les formulations attendues.

Le cycle de découverte et de chargement à la demande

Le mécanisme suit généralement une logique de divulgation progressive. Au démarrage, l’agent n’a pas besoin de placer l’intégralité de chaque Skill dans son contexte. Il peut d’abord connaître le nom et la description, puis charger le fichier complet lorsqu’une demande correspond.

Le déroulement peut être résumé ainsi :

1. Découverte : le client indexe les Skills disponibles et leurs descriptions.
2. Correspondance : la demande de l’utilisateur est comparée à ces descriptions.
3. Activation : le client ajoute le contenu de SKILL.md au contexte de travail.
4. Approfondissement : l’agent lit une référence ou exécute un script si les instructions le demandent.
5. Production : il fournit un résultat conforme aux règles décrites.
6. Contrôle : vous vérifiez le livrable avec des tests ou une revue.

La description ne doit donc pas se limiter à « aide au développement ». Une formulation plus utile précise le type d’action, le moment d’utilisation et les objets concernés : « vérifie une modification d’API avant revue, contrôle les schémas et recherche les tests de compatibilité ». Cette précision facilite la sélection sans prétendre améliorer les poids du modèle.

Dans Claude Code, la documentation indique que les Skills peuvent être disponibles au niveau utilisateur, projet, organisation ou plugin, et que le client peut les invoquer automatiquement ou via une commande directe. Elle indique aussi que les fichiers complémentaires sont chargés selon les besoins, ce qui permet de garder le fichier principal concentré sur l’essentiel. (code.claude.com)

Attention sécurité : le chargement progressif économise du contexte, mais il ne transforme pas une ressource externe en contenu fiable. Un fichier de référence peut contenir une instruction trompeuse, un script peut modifier des fichiers ou exfiltrer des données, et une commande apparemment anodine peut dépendre d’un environnement différent du vôtre.

Agent Skills et Prompt classique : la différence opérationnelle

La comparaison devient plus claire si vous séparez le niveau de réutilisation et le niveau de contrôle.

Dans Claude Code, la documentation distingue notamment les instructions permanentes de projet, les Skills utilisées ponctuellement et les mécanismes d’exécution ou de contrôle séparés. Une règle décrit ce qui doit rester vrai ; une Skill explique comment accomplir une tâche spécialisée ; un Workflow coordonne plusieurs opérations, souvent avec des conditions explicites. (code.claude.com)

Une Skill ne remplace pas non plus les permissions. Si une commande peut supprimer des fichiers, publier une version ou accéder à des secrets, la règle de sécurité doit être appliquée par le système d’exécution, les permissions ou un contrôle humain. Une phrase dans SKILL.md peut orienter l’agent, mais elle ne constitue pas une garantie technique.

Compatibilité des Agent Skills entre plusieurs outils

Le format est conçu pour être portable, mais « portable » ne signifie pas « identique partout ». Un autre client peut reconnaître SKILL.md et ses deux champs de base tout en ignorant une extension de front matter, une syntaxe d’injection dynamique, un emplacement de dossier ou une commande particulière.

Vous devez donc distinguer :

• le noyau standard : dossier, SKILL.md, métadonnées principales et contenu Markdown ;
• les extensions du client : invocation automatique, outils autorisés, contexte isolé, variables spéciales ou mécanismes de plugin ;
• l’environnement d’exécution : système de fichiers, interpréteur disponible, dépendances, permissions et accès réseau.

La bonne méthode consiste à conserver un SKILL.md portable, puis à documenter séparément les adaptations nécessaires à chaque client. Si une Skill appelle un script Python ou une commande shell, testez la présence des dépendances et les chemins dans chaque environnement. L’agent qui lit correctement la documentation peut tout de même échouer si l’outil ne prend pas en charge le champ ou le répertoire utilisé.

Le dépôt public de référence présente les Skills comme des dossiers d’instructions, de scripts et de ressources que les agents peuvent découvrir et utiliser. Des clients particuliers ajoutent ensuite leurs propres règles d’installation et d’invocation. (github.com)

Pour un projet d’équipe, conservez la Skill dans le contrôle de version et ajoutez un fichier de compatibilité indiquant :

• les clients validés ;
• les commandes réellement disponibles ;
• les permissions nécessaires ;
• les scripts facultatifs ;
• les différences de sortie observées.

Si vous cherchez un environnement distant pour tester une Skill sans modifier votre poste principal, vérifiez simplement que l’environnement retenu fournit les outils, les dépendances et les droits nécessaires. La compatibilité dépendra surtout de ces conditions d’exécution, pas du seul nom du client. Pour clarifier les modalités générales d’accès et les contraintes techniques avant un premier essai, vous pouvez également consulter le centre d’aide de kvmboot, puis reproduire ces conditions dans le client cible.

La réduction du contexte et la maîtrise des risques pendant l’exécution

Une Skill bien conçue garde SKILL.md suffisamment court pour exposer le chemin critique, puis déplace les détails vers references/. La documentation Claude Code recommande de conserver le fichier principal concis et indique une limite pratique de 500 lignes pour éviter de maintenir un bloc excessivement lourd. (code.claude.com)

Pour chaque ressource, précisez :

• son objectif ;
• le moment où l’agent doit la consulter ;
• les entrées attendues ;
• les effets de bord possibles ;
• la manière de vérifier le résultat.

Un script de conversion vidéo peut produire un fichier utile, mais il peut aussi écraser une sortie existante ou consommer beaucoup de ressources. Un script d’analyse de données peut lire un répertoire entier alors que la demande ne concernait qu’un seul fichier. Dans un contexte audio, vérifiez également les chemins, les codecs et les fichiers temporaires avant de lancer une opération automatisée.

Évitez les formulations absolues comme « exécuter toujours le script ». Préférez une condition vérifiable : « lancer le script après confirmation de l’emplacement du fichier source et afficher la commande avant exécution ». Cette écriture réduit les interprétations dangereuses et facilite la revue par un autre membre de l’équipe.

Pour les actions à effet de bord, vous pouvez prévoir une invocation manuelle, un environnement isolé ou une étape d’approbation. Les extensions permettant de restreindre l’invocation ou les outils autorisés relèvent du client concerné ; elles ne doivent pas être ajoutées au document comme si elles étaient universelles.

La méthode de test et de versionnement après exécution

La validation doit commencer avant la mise à disposition de l’équipe. Une Skill est un composant logiciel et mérite un cycle de test comparable à celui d’un script ou d’une intégration.

Procédure en six étapes

1. Écrire un cas nominal documenté.

Préparez une entrée représentative et décrivez le résultat attendu, y compris le format du fichier ou du rapport.

1. Ajouter au moins un cas limite.

Testez un fichier vide, une extension inattendue, une information manquante ou une permission insuffisante.

1. Vérifier la sélection.

Employez une formulation naturelle qui devrait déclencher la Skill, puis une demande voisine qui ne devrait pas la déclencher.

1. Observer les outils utilisés.

Notez les commandes lancées, les fichiers lus, les modifications effectuées et les erreurs rencontrées.

1. Faire relire la sortie.

Un développeur, un responsable métier ou un référent qualité doit comparer le résultat au standard attendu.

1. Versionner avec un journal de changements.

Toute modification de procédure, de script, de référence ou de critère de sortie doit être identifiable et réversible.

Ne confondez pas une réponse convaincante avec une validation. Le résultat d’une Skill doit être accepté par une vérification exécutable, une comparaison structurée ou un contrôle humain compétent. Pour une Skill de tests, vous pouvez exiger la présence de la commande exécutée et du statut de retour. Pour une Skill documentaire, vérifiez les sections, les liens et les éléments obligatoires. Pour une Skill de design, contrôlez les formats d’export et les contraintes visuelles ; pour une Skill audio, contrôlez la fréquence d’échantillonnage ou la présence des pistes uniquement si ces paramètres font partie de votre spécification de production.

Conservez aussi les échecs. Une erreur d’activation indique souvent une description trop vague ; une erreur d’exécution peut signaler une dépendance implicite ; une sortie incohérente peut révéler des instructions contradictoires. Ces observations sont plus utiles qu’une simple note « fonctionne ».

Pour les équipes qui veulent transformer un SOP en procédure agentique, documentez les responsabilités humaines restantes : approbation, accès aux secrets, publication, suppression et arbitrage métier. La validation de votre Skill doit rester fondée sur vos propres tests, vos propres exigences et les limites documentées du client utilisé. Les documents techniques du fournisseur retenu peuvent servir de point de référence opérationnel, sans remplacer vos essais dans le client cible.

Les bons candidats et les processus à laisser hors Skill

Les meilleurs candidats combinent répétition, structure et contrôle. Dans le développement, cela concerne la revue d’API, la préparation d’une version, la génération de tests ou la vérification d’un dépôt. Dans la documentation, une Skill peut appliquer un plan éditorial, contrôler les références et signaler les sections manquantes.

Dans l’audio et la vidéo, les cas créatifs sont également intéressants lorsque le livrable est clairement défini : préparation d’un dossier de mixage, vérification de pistes, transcodage vers des formats convenus ou génération d’une fiche de livraison. Dans le design, la préparation de déclinaisons et le contrôle des exports se prêtent mieux à une Skill que la création libre d’une direction artistique.

Évitez en revanche :

• les demandes totalement uniques ;
• les décisions qui dépendent d’un jugement non documenté ;
• les procédures dont les étapes changent chaque semaine ;
• les scripts récupérés sans audit ;
• les actions irréversibles sans approbation ;
• les connaissances générales qui ne déclenchent aucune action identifiable.

Le compromis recommandé est souvent hybride : garder les conventions permanentes dans les Rules, placer la procédure répétée dans une Skill, et réserver au Workflow l’orchestration de plusieurs Skills ou outils. Cette séparation évite de transformer un fichier unique en manuel illisible et difficile à sécuriser.

Le choix final : construire, adapter ou ne pas utiliser une Skill ?

Utilisez ce filtre avant de commencer :

• Processus répété, entrées connues et sortie vérifiable : créez une Skill.
• Convention qui doit s’appliquer à presque chaque tâche : utilisez plutôt une règle de projet.
• Demande unique ou exploratoire : restez sur un Prompt.
• Suite d’étapes avec dépendances, validations et publication : concevez un Workflow.
• Action sensible ou irréversible : ajoutez une permission, un contrôle humain ou une exécution isolée ; ne comptez pas uniquement sur le texte de la Skill.
• Compatibilité avec plusieurs clients : limitez-vous au noyau standard et testez les extensions séparément.

Si votre solution actuelle repose sur des Prompts copiés entre projets, des scripts lancés manuellement et des consignes dispersées dans plusieurs conversations, elle souffre probablement d’un manque de versionnement, de traçabilité et de contrôle des permissions. À l’inverse, si vous avez besoin d’un environnement stable pendant plusieurs mois, d’un accès permanent à des périphériques physiques ou d’un traitement lourd et prévisible, une Skill ne remplacera pas une infrastructure dédiée.

Pour une prochaine étape raisonnable, commencez par un seul processus à faible risque, écrivez son SKILL.md, testez trois cas d’entrée et faites relire les sorties. Vous pourrez ensuite approfondir la création de Skills pour Claude Code ou comparer les approches de règles, de Skills et de Workflows dans votre propre équipe. L’objectif n’est pas d’ajouter une couche d’IA à chaque tâche, mais de transformer uniquement les procédures qui gagnent réellement à être répétées, contrôlées et partagées.