Quelle différence faut-il faire entre un Agent Skill et un Prompt classique ?

Un Prompt classique donne généralement des instructions pour une interaction ou une tâche ponctuelle. Un Agent Skill forme plutôt un paquet versionné, découvrable et réutilisable, avec une description de déclenchement, des consignes opératoires et, si nécessaire, des références ou des scripts. Il ne remplace pas le contrôle des permissions et ne possède pas automatiquement un accès indépendant aux systèmes externes.

Que doit contenir un fichier SKILL.md bien conçu ?

Le fichier doit commencer par un frontmatter YAML contenant au minimum un nom et une description. Le corps doit ensuite préciser le déroulement, les conditions d’entrée, les sorties attendues, les cas limites et les critères de validation. Les détails volumineux, les exemples spécialisés et les procédures rarement utilisées doivent plutôt être déplacés vers des fichiers du dossier references.

Un Agent Skill peut-il exécuter des scripts ?

Oui, un Skill peut embarquer des scripts dans un dossier scripts, mais cette possibilité dépend de l’agent qui l’exécute et de ses règles d’autorisation. Un script doit être inspecté avant installation, documenter ses dépendances, limiter ses chemins d’écriture et échouer proprement. Une exécution sans confirmation ou avec des droits excessifs transforme un paquet de consignes en risque opérationnel.

Comment les Agent Skills et MCP doivent-ils coopérer ?

Le Skill décrit quand employer une méthode et comment interpréter le résultat, tandis que MCP expose généralement des outils ou des ressources connectés à un système externe. Le Skill ne doit donc pas prétendre posséder lui-même l’accès à une base, un navigateur ou une API. Il peut demander l’utilisation d’un outil MCP autorisé, préciser les paramètres attendus et imposer une vérification avant toute écriture.

Guide complet des Agent Skills : savoir-faire réutilisable

Conclusion opérationnelle — 17 août 2026 : un Agent Skill doit être conçu comme un paquet de capacité comprenant une description de déclenchement, des instructions d’exécution et, au besoin, des références ou des scripts. Il convient d’y placer les règles stables et les procédures vérifiables, tandis que les faits dynamiques doivent rester dans une source actualisable et que toute action externe doit passer par des outils et des permissions maîtrisées.

Cette approche est recommandée cette semaine pour les développeurs qui découvrent SKILL.md, pour les utilisateurs de Claude Code souhaitant réutiliser un processus d’équipe, ainsi que pour les responsables techniques qui préparent un dépôt interne de Skills. Elle évite de confondre un Skill avec un simple Prompt, une base de connaissances ou un serveur d’outils. Pour distinguer un environnement de test temporaire d’un poste de production, il est possible de consulter la présentation générale de Vuncloud, puis de revenir aux critères techniques détaillés ci-dessous.

Dernière mise à jour : 17 août 2026. Les éléments de format ont été vérifiés à partir de la spécification officielle des Agent Skills, du dépôt officiel de Skills et de la documentation de référence de Claude Code. Les comportements peuvent varier selon le produit compatible utilisé.

Le problème des consignes accumulées

Un Prompt système permanent semble pratique au début : les règles de revue de code, les conventions de nommage, les étapes de livraison et les critères de validation sont réunis dans un seul emplacement. Cette méthode devient cependant difficile à maintenir lorsque plusieurs domaines se superposent.

Le premier coût est contextuel. Une règle de traitement audio n’a pas besoin d’être chargée lors d’une tâche de migration SQL, et une procédure de préparation vidéo n’est pas pertinente pour une revue de sécurité. Si toutes les consignes restent toujours présentes, l’agent doit trier une quantité de contexte qui ne correspond pas à la demande en cours.

Le deuxième coût concerne la maintenance. Une modification de procédure oblige à rechercher la règle dans un long Prompt, à vérifier ses doublons et à contrôler ses interactions avec d’autres instructions. Le risque n’est pas seulement la contradiction : une ancienne règle peut continuer à influencer une réponse alors que l’équipe pense l’avoir remplacée.

Le troisième coût est organisationnel. Un Prompt personnel est rarement versionné avec la même rigueur qu’un dépôt de code. Il est donc difficile d’identifier le responsable, la date de modification, les tâches de test et les conditions de retrait.

Un Agent Skill répond à ces limites en séparant les capacités. La découverte repose sur la description, l’activation charge les instructions pertinentes, puis les ressources complémentaires sont consultées lorsque le travail le demande. La spécification décrit cette logique de divulgation progressive et recommande de conserver le fichier principal sous 500 lignes, en déplaçant les détails vers des références spécialisées. La spécification et ses recommandations de structure

L’anatomie d’un Skill réutilisable

Le dossier minimal contient un fichier SKILL.md. Des répertoires scripts, references et assets peuvent ensuite être ajoutés selon le besoin :

revue-accessibilite/
├── SKILL.md
├── references/
│   ├── criteres-wcag.md
│   └── exemples-rapport.md
├── scripts/
│   └── verifier-contraste.py
└── assets/
    └── modele-rapport.md

Élément	Rôle principal	Ce qui doit y rester
`name`	Identifiant du Skill	Nom court, stable et lisible
`description`	Déclenchement et périmètre	Ce que le Skill fait et quand l’utiliser
`SKILL.md`	Méthode opératoire	Étapes, entrées, sorties et contrôles
`references/`	Documentation consultée à la demande	Détails, normes, exemples et cas particuliers
`scripts/`	Exécution déterministe	Vérifications ou transformations bornées
`assets/`	Ressources de production	Modèles, schémas, fichiers de configuration

Le frontmatter de SKILL.md doit contenir au minimum name et description. Selon la spécification, le nom doit respecter des règles de formatage strictes, tandis que la description doit expliquer à la fois la fonction du Skill et les situations qui justifient son activation. Les champs license, compatibility, metadata et allowed-tools sont optionnels, et le dernier reste expérimental avec une compatibilité variable selon les agents. Les champs et règles du fichier SKILL.md

Un exemple minimal peut prendre cette forme :

---
name: revue-accessibilite
description: Analyse une interface web selon les critères d’accessibilité,
propose des corrections et génère un rapport. À utiliser lors d’une revue
d’interface, d’un audit avant livraison ou lorsqu’une anomalie d’accessibilité
est signalée.
compatibility: Requiert un environnement capable de lire le dépôt du projet.
---

## Objectif

Évaluer l’interface sans modifier les fichiers avant validation.

## Procédure

1. Identifier les pages et composants concernés.
2. Vérifier la structure sémantique et la navigation au clavier.
3. Lancer les contrôles disponibles.
4. Classer les anomalies par gravité.
5. Générer un rapport avec preuve et recommandation.

## Sortie attendue

Le rapport doit distinguer les problèmes confirmés, les hypothèses et les
éléments qui nécessitent une vérification manuelle.

Le nom identifie le paquet ; il ne doit pas porter toute l’intelligence du Skill. La description sert à la découverte ; le corps explique l’exécution. Les fichiers references doivent rester ciblés, car leur fonction est d’apporter du détail au moment où il devient utile, non de recréer un second manuel permanent.

Pour un flux audio ou vidéo, par exemple, le Skill principal peut décrire la séquence de préparation, de contrôle et d’export, tandis qu’un fichier de référence conserve les profils de livraison, les conventions de nommage ou les critères de qualité. Cette séparation facilite les mises à jour sans réécrire le processus complet.

Le déclenchement et ses frontières

La description est le premier mécanisme de sélection. Une formulation vague comme « aide à améliorer les projets » ne donne pas à l’AI Agent assez d’indices pour distinguer ce Skill d’un outil de revue, de documentation ou de génération. Une formulation exploitable indique :

l’action réalisée ;
les objets concernés ;
les expressions ou demandes qui signalent le besoin ;
les limites du périmètre ;
les cas où le Skill ne doit pas être choisi.

Il est préférable d’écrire « vérifie les sous-titres, la structure des pistes et les fichiers d’export lors de la préparation d’une vidéo destinée à la publication » plutôt que « optimise les contenus multimédias ». La première phrase décrit une tâche observable ; la seconde empile des capacités générales.

La vérification doit se faire avec trois groupes de demandes :

Cas positifs : demandes qui doivent activer le Skill ;
Cas négatifs : demandes proches mais qui appartiennent à un autre processus ;
Cas concurrents : demandes pouvant légitimement correspondre à deux Skills.

Un déclenchement fiable n’est pas celui qui s’active le plus souvent. C’est celui qui choisit le bon paquet lorsque le coût d’une mauvaise activation est supérieur au coût d’une question de clarification. Pour une tâche de design, un Skill d’export vidéo ne devrait pas s’activer uniquement parce que la demande mentionne une image, un format ou une livraison.

La description doit également éviter de promettre une capacité que l’environnement n’autorise pas. Un Skill peut expliquer comment interroger un dépôt ou vérifier un fichier, mais il ne doit pas présenter cette opération comme garantie si aucun outil de lecture, aucun accès au répertoire ou aucune permission n’est disponible.

La séparation entre savoir, méthode et action

La plupart des erreurs de conception proviennent d’un mauvais partage entre trois couches.

Le savoir stable comprend une méthode de diagnostic, une convention de rédaction, une séquence de validation ou une règle métier qui change rarement. Cette matière appartient au Skill, dans SKILL.md ou dans une référence associée.

Le savoir dynamique comprend une version logicielle actuelle, un tarif, une disponibilité, une liste de dépendances ou une politique susceptible d’être modifiée. Ces éléments doivent rester dans une source mise à jour, un fichier de configuration géré séparément ou une base de connaissances contrôlée. Les incorporer définitivement dans le Skill crée une information périmée qui peut être appliquée avec assurance.

L’action externe comprend la lecture d’un service, l’écriture dans un dépôt, l’envoi d’un fichier, l’exécution d’une commande ou l’appel à une API. Ces opérations appartiennent à des outils autorisés. Le Skill peut donner le mode opératoire et les contrôles préalables, mais il ne dispose pas automatiquement d’un pouvoir autonome.

Cette distinction est essentielle avec MCP. Le protocole peut fournir des outils ou des ressources à un agent, alors que le Skill fournit une méthode spécialisée pour les employer. Dans Claude Code, la configuration MCP est traitée séparément par les commandes et paramètres dédiés, notamment via la commande claude mcp. La référence officielle de Claude Code sur l’utilisation de la ligne de commande

Une formulation saine ressemble à ceci :

1. Lire les données disponibles avec l’outil autorisé.
2. Vérifier que le projet ciblé correspond à la demande.
3. Ne modifier aucun fichier avant d’avoir présenté le plan.
4. Exécuter l’action approuvée.
5. Relire le résultat et fournir la preuve de validation.

Une formulation risquée serait : « connectez-vous au système, corrigez les données et publiez le résultat ». Elle masque les permissions, les limites de chemin, les effets irréversibles et la preuve attendue.

Les scripts et les risques d’exécution

Un Skill peut contenir des scripts, mais cette possibilité ne doit jamais être interprétée comme une autorisation générale d’exécuter du code. La spécification prévoit un dossier scripts pour du code exécutable, avec des dépendances documentées, des messages d’erreur utiles et une gestion explicite des cas limites. Les langages pris en charge dépendent toutefois de l’implémentation de l’agent. Les règles officielles relatives aux scripts et aux ressources

Avant d’installer un Skill tiers, le responsable doit contrôler :

l’origine du dépôt et la réputation du mainteneur ;
la licence et les fichiers inclus ;
les commandes exécutées par les scripts ;
les dépendances téléchargées ;
les domaines réseau contactés ;
les chemins lus ou modifiés ;
les secrets récupérés dans l’environnement ;
la présence d’un mécanisme de journalisation ;
la possibilité de supprimer ou de désactiver rapidement le Skill.

Le test initial doit être réalisé dans un environnement isolé, avec un projet sans données sensibles et des permissions minimales. Pour un Skill de traitement vidéo, il est préférable de fournir un petit jeu de fichiers de test et de vérifier la destination exacte des exports. Pour un Skill de design, le contrôle doit porter sur les fichiers créés, les polices chargées et les ressources externes sollicitées.

Claude Code permet de limiter les outils autorisés, d’en interdire certains et de choisir un mode de permission adapté. La documentation officielle signale également l’option qui contourne les demandes de confirmation et recommande de l’utiliser avec prudence. Les paramètres d’autorisation de Claude Code

La bonne pratique consiste à traiter un script comme une dépendance logicielle, et non comme une simple annexe documentaire. Il doit avoir un propriétaire, une version, une procédure de test et une méthode de retrait.

La construction du premier Skill

Pour obtenir un résultat exploitable sans transformer le projet en catalogue, la séquence suivante est plus robuste qu’une rédaction directement centrée sur le Prompt.

1. Choisir une tâche vérifiable

Sélectionnez une tâche fréquente dont la sortie peut être contrôlée : rapport d’audit, structure de projet, export de fichiers, analyse de logs ou génération d’un livrable. Évitez les formulations comme « être meilleur en développement », trop larges pour définir un périmètre.

2. Décrire les entrées et les sorties

Indiquez les fichiers attendus, les informations manquantes, le format de sortie et les critères d’acceptation. Une tâche de création de diagramme doit préciser si la sortie attendue est un fichier source modifiable, une image finale ou les deux.

3. Rédiger la description de déclenchement

Formulez ce que le Skill accomplit et quand il doit être utilisé. Ajoutez des termes métier réellement employés par les utilisateurs, mais excluez les promesses générales qui créeraient un chevauchement avec d’autres Skills.

4. Écrire le parcours nominal

Décomposez le travail en étapes ordonnées : inspection, planification, exécution, vérification et restitution. Chaque étape doit préciser ce qui est observé et ce qui doit être produit avant de passer à la suivante.

5. Ajouter les cas limites

Documentez les fichiers absents, les formats incompatibles, les droits insuffisants, les résultats ambigus et les données contradictoires. Un Skill qui ne décrit que le cas idéal donne souvent une impression de fiabilité supérieure à sa capacité réelle.

6. Déplacer les détails volumineux

Placez les références normatives, exemples longs, tableaux de paramètres et guides spécialisés dans references. Les ressources chargées à la demande limitent l’encombrement du fichier principal et permettent une mise à jour plus ciblée. Les recommandations de structure de la spécification

7. Tester avec des demandes concurrentes

Utilisez les cas positifs, négatifs et concurrents afin de repérer les activations erronées. Conservez les demandes de test dans le dépôt : elles deviennent un filet de sécurité lors de toute modification de la description.

8. Valider le paquet avant publication

La bibliothèque de référence skills-ref fournit une commande de validation de la structure et du frontmatter. Cette vérification ne juge pas la qualité métier du processus, mais elle élimine les erreurs élémentaires de nommage et de format.

La gouvernance d’un dépôt d’équipe

Un dépôt de Skills ne doit pas être organisé autour du nombre de dossiers créés. La priorité revient aux procédures qui sont fréquentes, coûteuses à expliquer et suffisamment déterministes pour être évaluées.

Chaque Skill devrait disposer d’un propriétaire identifié, d’une version, d’un journal de modification, d’un ensemble de tâches de test et d’une règle de retrait. Une modification de description peut changer le déclenchement sans toucher au corps du fichier ; elle mérite donc la même attention qu’un changement de code.

Une organisation minimale peut inclure :

skills/
├── revue-accessibilite/
├── export-video/
├── audit-dependances/
└── catalogue.md

Le catalogue doit préciser le périmètre, les incompatibilités, les outils nécessaires et le statut de maintenance. Les Skills concurrents doivent être testés ensemble, car un paquet peut être correct isolément et devenir ambigu après l’ajout d’un nouveau dossier.

La compatibilité ne doit pas être supposée. Le format est ouvert et plusieurs produits déclarent prendre en charge des répertoires de consignes, de scripts et de ressources, mais les chemins d’installation, les mécanismes de découverte et les permissions peuvent différer. Des environnements compatibles ne partagent donc pas automatiquement le même comportement. La documentation GitHub sur les Agent Skills

Pour Claude Code, il est pertinent de conserver le Skill avec le projet lorsqu’il décrit une convention de dépôt, et de réserver l’installation globale aux capacités réellement personnelles ou transversales. L’objectif est de rendre la source d’autorité visible dans le même espace que le code, les tests et les règles de livraison.

La checklist d’acceptation

Avant de rendre un Skill disponible à une équipe, vérifiez chaque point :

[ ] Le nom du dossier et le champ name sont cohérents et stables.
[ ] La description indique ce que le Skill fait et dans quelles situations il s’active.
[ ] Le périmètre exclut explicitement les tâches voisines qui appartiennent à un autre Skill.
[ ] Le fichier SKILL.md décrit les entrées, les étapes, les sorties et les critères de validation.
[ ] Les faits susceptibles de changer sont stockés dans une source actualisable.
[ ] Les références longues sont séparées du fichier principal.
[ ] Chaque script documente ses dépendances et ses chemins d’écriture.
[ ] Aucun secret n’est requis sans mécanisme d’autorisation explicite.
[ ] Les cas positifs, négatifs et concurrents ont été testés.
[ ] Le Skill fonctionne avec les outils effectivement disponibles dans l’environnement cible.
[ ] La licence et l’origine des ressources tierces sont connues.
[ ] Un propriétaire, une version et une procédure de retrait sont enregistrés.
[ ] Le résultat peut être contrôlé par une personne ou par un test reproductible.

Pour un essai isolé, un environnement Mac distant peut compléter un poste local lorsque plusieurs versions doivent être comparées, qu’un script tiers doit être inspecté ou qu’une session de recette doit être séparée des données de travail. Les informations sur la location de Mac distant proposée par Vuncloud peuvent être consultées uniquement si ce besoin opérationnel est réel. Il faut cependant évaluer séparément les accès, la confidentialité, la durée de conservation des fichiers et la possibilité de réinitialiser l’environnement après le test.

Les limites à conserver

Un Agent Skill n’est ni une base de connaissances complète, ni un modèle spécialisé, ni un serveur MCP, ni un Prompt magique. Il décrit une capacité que l’agent peut découvrir et appliquer ; il ne garantit pas la vérité des informations dynamiques, la disponibilité d’un outil ou la réussite d’une commande.

La qualité dépend donc de quatre conditions : une description précise, une procédure testable, des ressources à jour et des permissions proportionnées. Si l’une de ces conditions manque, l’augmentation du nombre de Skills ne résout pas le problème ; elle peut au contraire multiplier les déclenchements concurrents et rendre les erreurs plus difficiles à diagnostiquer.

Pour cette raison, la conversion intégrale d’un livre ou d’un PDF doit faire l’objet d’un processus distinct. Le présent guide fixe le cadre général : comment isoler une méthode, comment la rendre découvrable et comment l’administrer. Il ne remplace pas une procédure complète d’extraction, de structuration et de validation documentaire.

FAQ pratique

Agent Skills et Prompt

Un Prompt fournit des instructions directement dans une interaction ou une configuration générale. Un Agent Skill ajoute une structure de fichiers, une description destinée à la découverte, une procédure réutilisable et des ressources séparées. Il est donc mieux adapté à une capacité d’équipe qui doit être versionnée, testée et maintenue, alors qu’un Prompt reste souvent le meilleur choix pour une consigne ponctuelle ou une expérimentation rapide.

Le contenu de `SKILL.md`

Un bon SKILL.md contient le frontmatter requis, une description précise du déclenchement, un objectif, les préconditions, les étapes opératoires, les sorties attendues et les cas limites. Il doit aussi expliquer les contrôles à réaliser avant une modification. Les références détaillées, normes et exemples volumineux doivent être placés dans references afin de préserver la lisibilité du fichier principal.

Scripts et permissions

Un Skill peut appeler un script lorsque l’agent et son environnement l’autorisent. Cette capacité ne doit toutefois pas être confondue avec un droit permanent. L’exécution doit être limitée par les permissions, testée dans un espace isolé et accompagnée d’une vérification des fichiers modifiés, des commandes lancées et des connexions réseau. Un script tiers doit être traité comme du code à auditer.

Coopération avec MCP

MCP et Agent Skills répondent à des besoins différents. MCP fournit une interface vers des outils ou des ressources externes ; le Skill décrit la méthode pour les utiliser dans un cas métier précis. Une architecture saine indique donc quel outil est nécessaire, quelles données peuvent être lues, quelles actions exigent une confirmation et comment vérifier le résultat après l’appel.

Vers un environnement de test maîtrisé

Un poste local convient lorsque le développement est quotidien, que les dépendances sont connues et que les données peuvent rester sur la machine de l’équipe. Il devient moins confortable lorsqu’il faut tester plusieurs versions d’un Skill, isoler un script tiers, partager une session de validation ou fournir temporairement un environnement identique à plusieurs collaborateurs.

Dans ces situations, un Mac distant peut simplifier l’essai, mais il ne remplace pas la gouvernance du Skill : les droits, les secrets, les journaux et les règles de retrait doivent rester définis au niveau du projet. La location est surtout pertinente pour une phase courte de prototypage, de compatibilité ou de recette. Pour une charge permanente et prévisible, l’achat et l’administration d’une machine dédiée peuvent être plus cohérents ; pour une tâche nécessitant des interfaces physiques locales, une machine distante peut également être inadaptée.

Le poste local conserve néanmoins plusieurs limites : il est difficile à reproduire exactement, il mélange parfois données personnelles et tests de sécurité, et il mobilise la machine principale pendant les essais. Un environnement séparé peut donc offrir une meilleure maîtrise pour expérimenter un Skill, comparer son comportement et le retirer sans modifier le poste de travail habituel.