Guide de référence · Agent Skills
11 min de lecture
Mis à jour le
SKILL.md : créer une Agent Skill utile, déclenchable et testable
Une méthode complète pour passer d’une procédure répétée à une skill que l’agent sait découvrir, exécuter et vérifier.
Réponse directe
Crée une Agent Skill lorsque tu veux rendre une procédure réutilisable et détectable. Le dossier contient au minimum SKILL.md : un frontmatter avec name et description, puis des instructions opérationnelles. Ajoute des scripts, références ou modèles seulement s’ils rendent l’exécution plus fiable. Une bonne skill se juge à trois preuves : elle se déclenche sur les bonnes demandes, reste silencieuse sur les autres et produit un résultat vérifiable.
Glossary
Termes expliqués ici
Ouvre un terme pour lire sa définition courte, puis poursuis vers sa fiche sourcée si nécessaire.
01
Une skill n’est pas un prompt plus long
Un prompt répond à une situation présente. Une skill formalise un savoir-faire destiné à être retrouvé et appliqué dans plusieurs tâches. Son nom et sa description permettent à l’agent d’évaluer sa pertinence avant de charger les instructions complètes.
Une skill n’est pas non plus un outil. L’outil fournit une capacité d’action — lire un fichier, appeler une API, exécuter un test. La skill explique quand utiliser ces capacités, dans quel ordre, avec quelles limites et quelle preuve de réussite. Enfin, l’agent reste le système qui choisit, agit, observe et décide de poursuivre ou de s’arrêter.
- Prompt : instruction ponctuelle liée à la conversation en cours.
- Skill : procédure réutilisable chargée lorsqu’une demande correspond.
- Outil : opération que l’agent peut appeler pour observer ou modifier un système.
- Agent : boucle de décision qui mobilise instructions, skills et outils.
Si la procédure ne mérite ni réutilisation ni test, un prompt clair suffit probablement.
02
L’anatomie minimale de SKILL.md
La spécification Agent Skills impose un dossier contenant au minimum SKILL.md. Le fichier commence par un frontmatter YAML. name identifie la skill ; description explique à la fois ce qu’elle accomplit et les situations où elle doit être activée. Le corps Markdown contient les instructions que l’agent lit après activation.
Garde ce fichier orienté décision. Place les procédures longues ou les connaissances détaillées dans references/, les opérations déterministes dans scripts/ et les modèles réutilisables dans assets/. Ce chargement progressif évite d’occuper le contexte avec des ressources inutiles à la demande présente.
---
name: interface-qa
description: Audit a web interface after a UI change. Use when a task asks to verify responsive behavior, keyboard access, or visual regressions.
---
# Interface QA
1. Inspect the changed routes and existing test conventions.
2. List the user journeys affected by the change.
3. Run the narrowest relevant automated checks.
4. Record every unverified browser or device gate explicitly.
5. Report evidence, failures, and remaining work separately.03
Écrire des instructions que l’agent peut réellement suivre
Commence par le résultat attendu, puis décris les décisions dans l’ordre où elles surviennent. Une instruction comme « vérifier la qualité » est trop vague. Précise les surfaces à inspecter, les signaux à rechercher, les commandes autorisées et la forme de la preuve finale.
Ajoute les exceptions qui changent le parcours : fichier manquant, environnement non authentifié, sortie ambiguë, test impossible ou action destructive. Indique également ce qui ne doit pas être fait. Les limites explicites empêchent une procédure utile de devenir une autorisation générale.
- Définir une entrée observable et un résultat attendu.
- Utiliser des verbes d’action et un ordre d’exécution clair.
- Séparer inspection, modification, validation et compte rendu.
- Prévoir les branches d’erreur et les conditions d’arrêt.
- Référencer les fichiers relativement à la racine de la skill.
04
Le déclenchement se conçoit comme une frontière
La description est le principal signal de découverte. Elle doit nommer la capacité et les formulations de demande qui la rendent pertinente. Une description trop étroite rate des cas utiles ; une description trop large charge la skill sur des tâches qu’elle ne sait pas traiter.
Constitue deux petits corpus : des demandes qui doivent activer la skill et des demandes voisines qui ne doivent pas l’activer. Les faux négatifs révèlent un vocabulaire absent. Les faux positifs indiquent qu’il faut mieux décrire le périmètre ou réserver certaines variantes à une autre skill.
Une bonne description explique autant le « quand » que le « quoi ».
05
Tester la procédure, pas seulement le format
La validation syntaxique du frontmatter est nécessaire mais insuffisante. Exécute la skill sur des cas représentatifs, vérifie ses artefacts et compare le résultat à des critères observables. Les scripts doivent avoir des entrées bornées, des erreurs lisibles et un comportement déterministe lorsque c’est possible.
Versionne la skill avec ses exemples et ses tests. Lorsqu’une instruction change, rejoue les cas qui avaient motivé l’ancienne règle. Une skill fiable conserve aussi une sortie honnête : elle distingue ce qui a été vérifié, ce qui reste manuel et ce qui est bloqué par une permission ou un environnement absent.
- Activation : demandes positives, négatives et ambiguës.
- Exécution : chemin nominal, données manquantes et échec d’un outil.
- Sortie : format, exhaustivité, provenance et critères de réussite.
- Sécurité : permissions minimales, secrets absents des logs, actions destructives confirmées.
- Régression : cas réels rejoués à chaque modification importante.
06
Charge seulement la référence utile
Pour une skill qui contrôle des factures, garde le déclencheur et les étapes essentielles dans SKILL.md ; place les exemples détaillés dans un fichier référencé. Essaie une facture puis une demande sans rapport. Note quelle référence a réellement été nécessaire.
Le chargement progressif organise les instructions ; il ne donne pas de permissions aux outils et ne prouve pas qu’un hôte a chargé une référence. Vérifie le comportement observé avant de compter sur la skill.
À conserver
Checklist avant de partager une Agent Skill
- 01Le nom est stable, descriptif et conforme au format attendu.
- 02La description dit ce que fait la skill et quand l’utiliser.
- 03Les instructions commencent par un résultat observable.
- 04Les outils, permissions, limites et conditions d’arrêt sont explicites.
- 05Les longues références et les scripts sont chargés seulement si nécessaire.
- 06Les chemins sont relatifs à la racine de la skill.
- 07Des tests couvrent activation, non-activation, erreurs et sortie finale.
- 08Le compte rendu sépare les preuves obtenues des validations encore manuelles.
Sources primaires
Les affirmations techniques de ce guide sont reliées aux spécifications et documentations first-party.
- Agent Skills specification (nouvel onglet)Agent Skills · Spécification du dossier, de SKILL.md, du frontmatter et des ressources optionnelles.
- Optimizing skill descriptions (nouvel onglet)Agent Skills · Documentation du rôle de la description dans la découverte et le déclenchement.
- Agent Skills overview (nouvel onglet)Anthropic · Documentation primaire sur les skills réutilisables, leur chargement et leurs ressources.
Continuer
Guides et outils associés
Agent IA, chatbot ou workflow ?
Situer la skill dans l’architecture complète d’un agent.
OuvrirLe vocabulaire UI pour mieux guider une IA
Appliquer la même précision aux demandes de construction d’interface.
OuvrirMéthode éditoriale
Voir comment SkillCodex relie les affirmations à des sources vérifiables.
OuvrirComprendre → Reconnaître → Choisir → Comparer
Pack pour ton agent
Instruction pré-écrite par SkillCodex — ta demande n’est ni envoyée ni utilisée pour adapter ce texte ; aucun contenu n’est généré et copier n’exécute rien.
Implémenter correctement
Applique « SKILL.md : créer une Agent Skill utile, déclenchable et testable » pas à pas
# Applique le guide « SKILL.md : créer une Agent Skill utile, déclenchable et testable » dans ton agent ## Objectif Crée une Agent Skill lorsque tu veux rendre une procédure réutilisable et détectable. Le dossier contient au minimum SKILL.md : un frontmatter avec name et description, puis des instructions opérationnelles. Ajoute des scripts, références ou modèles seulement s’ils rendent l’exécution plus fiable. Une bonne skill se juge à trois preuves : elle se déclenche sur les bonnes demandes, reste silencieuse sur les autres et produit un résultat vérifiable. ## Prérequis - Inspecte le dépôt, la documentation et les conventions existantes. - Confirme que le besoin correspond au périmètre du guide : Une méthode complète pour passer d’une procédure répétée à une skill que l’agent sait découvrir, exécuter et vérifier. - Préserve les décisions correctes déjà en place. ## Étapes du guide - 1. Une skill n’est pas un prompt plus long — Si la procédure ne mérite ni réutilisation ni test, un prompt clair suffit probablement. - 2. L’anatomie minimale de SKILL.md — La spécification Agent Skills impose un dossier contenant au minimum SKILL.md. Le fichier commence par un frontmatter YAML. name identifie la skill ; description explique à la fois ce qu’elle accomplit et les situations où elle doit être activée. Le corps Markdown contient les instructions que l’agent lit après activation. - 3. Écrire des instructions que l’agent peut réellement suivre — Commence par le résultat attendu, puis décris les décisions dans l’ordre où elles surviennent. Une instruction comme « vérifier la qualité » est trop vague. Précise les surfaces à inspecter, les signaux à rechercher, les commandes autorisées et la forme de la preuve finale. - 4. Le déclenchement se conçoit comme une frontière — Une bonne description explique autant le « quand » que le « quoi ». - 5. Tester la procédure, pas seulement le format — La validation syntaxique du frontmatter est nécessaire mais insuffisante. Exécute la skill sur des cas représentatifs, vérifie ses artefacts et compare le résultat à des critères observables. Les scripts doivent avoir des entrées bornées, des erreurs lisibles et un comportement déterministe lorsque c’est possible. - 6. Charge seulement la référence utile — Pour une skill qui contrôle des factures, garde le déclencheur et les étapes essentielles dans SKILL.md ; place les exemples détaillés dans un fichier référencé. Essaie une facture puis une demande sans rapport. Note quelle référence a réellement été nécessaire. ## Critères d’acceptation — Checklist avant de partager une Agent Skill - Le nom est stable, descriptif et conforme au format attendu. - La description dit ce que fait la skill et quand l’utiliser. - Les instructions commencent par un résultat observable. - Les outils, permissions, limites et conditions d’arrêt sont explicites. - Les longues références et les scripts sont chargés seulement si nécessaire. - Les chemins sont relatifs à la racine de la skill. - Des tests couvrent activation, non-activation, erreurs et sortie finale. - Le compte rendu sépare les preuves obtenues des validations encore manuelles. ## Garde-fous - Montre d’abord les changements envisagés avant toute action externe. - Ne publie, n’envoie, ne supprime, ne paie et ne modifie aucun état distant sans autorisation explicite. - Préserve les changements sans rapport et arrête-toi si le périmètre devient ambigu. ## Format de sortie - Résultat obtenu ou verdict. - Fichiers ou actions concernés. - Vérifications exécutées et preuves observables. - Blocages ou limites restantes.
- Prérequis · Le contexte réel du projet : dépôt, documentation et contraintes existantes
Pourquoi ça marche
- Les étapes viennent d’un guide publié et sourcé, pas d’une improvisation.
- La checklist transforme le conseil en critères vérifiables.
- Le périmètre déclaré évite d’étendre le guide au-delà de ses preuves.
À essayer ensuite
Ancre le guide dans le projet
# Ancre le guide dans le projet ## Objectif Transforme les étapes appliquées en conventions durables du dépôt. ## Contrôles - Relie chaque décision prise à l’étape du guide qui la justifie. - Ajoute la checklist aux revues concernées. - Note les cas hors périmètre pour les guides voisins. ## Garde-fous - Montre d’abord les changements envisagés avant toute action externe. - Ne publie, n’envoie, ne supprime, ne paie et ne modifie aucun état distant sans autorisation explicite. - Préserve les changements sans rapport et arrête-toi si le périmètre devient ambigu. ## Format de sortie - Résultat obtenu ou verdict. - Fichiers ou actions concernés. - Vérifications exécutées et preuves observables. - Blocages ou limites restantes.
sha256:c2e9bd9c66a72b5875e5fb9cad8444889a520565b5d76a3cc55087b9f29f856e
Diagnostiquer un problème
Diagnostique un écart au guide « SKILL.md : créer une Agent Skill utile, déclenchable et testable »
# Diagnostique une application ratée du guide « SKILL.md : créer une Agent Skill utile, déclenchable et testable » ## Symptôme observé [DÉCRIS ICI LE SYMPTÔME] ## Contrôles observables - Rejoue les étapes dans l’ordre et note la première qui diverge : - 1. Une skill n’est pas un prompt plus long — Si la procédure ne mérite ni réutilisation ni test, un prompt clair suffit probablement. - 2. L’anatomie minimale de SKILL.md — La spécification Agent Skills impose un dossier contenant au minimum SKILL.md. Le fichier commence par un frontmatter YAML. name identifie la skill ; description explique à la fois ce qu’elle accomplit et les situations où elle doit être activée. Le corps Markdown contient les instructions que l’agent lit après activation. - 3. Écrire des instructions que l’agent peut réellement suivre — Commence par le résultat attendu, puis décris les décisions dans l’ordre où elles surviennent. Une instruction comme « vérifier la qualité » est trop vague. Précise les surfaces à inspecter, les signaux à rechercher, les commandes autorisées et la forme de la preuve finale. - 4. Le déclenchement se conçoit comme une frontière — Une bonne description explique autant le « quand » que le « quoi ». - 5. Tester la procédure, pas seulement le format — La validation syntaxique du frontmatter est nécessaire mais insuffisante. Exécute la skill sur des cas représentatifs, vérifie ses artefacts et compare le résultat à des critères observables. Les scripts doivent avoir des entrées bornées, des erreurs lisibles et un comportement déterministe lorsque c’est possible. - 6. Charge seulement la référence utile — Pour une skill qui contrôle des factures, garde le déclencheur et les étapes essentielles dans SKILL.md ; place les exemples détaillés dans un fichier référencé. Essaie une facture puis une demande sans rapport. Note quelle référence a réellement été nécessaire. ## Causes possibles - Une étape a été sautée ou exécutée hors ordre. - Le besoin réel sort du périmètre du guide. - Un critère de la checklist n’a jamais été vérifié. ## Corrections bornées - Reprends uniquement l’étape divergente et ce qui en dépend. - Documente l’écart si le périmètre du guide ne couvre pas le besoin. ## Vérification finale — Checklist avant de partager une Agent Skill - Le nom est stable, descriptif et conforme au format attendu. - La description dit ce que fait la skill et quand l’utiliser. - Les instructions commencent par un résultat observable. - Les outils, permissions, limites et conditions d’arrêt sont explicites. - Les longues références et les scripts sont chargés seulement si nécessaire. - Les chemins sont relatifs à la racine de la skill. - Des tests couvrent activation, non-activation, erreurs et sortie finale. - Le compte rendu sépare les preuves obtenues des validations encore manuelles. ## Garde-fous - Montre d’abord les changements envisagés avant toute action externe. - Ne publie, n’envoie, ne supprime, ne paie et ne modifie aucun état distant sans autorisation explicite. - Préserve les changements sans rapport et arrête-toi si le périmètre devient ambigu. ## Format de sortie - Résultat obtenu ou verdict. - Fichiers ou actions concernés. - Vérifications exécutées et preuves observables. - Blocages ou limites restantes.
- Prérequis · Le contexte réel du projet : dépôt, documentation et contraintes existantes
Pourquoi ça marche
- Le diagnostic rejoue des étapes ordonnées au lieu de chercher au hasard.
- Les corrections restent bornées à la première divergence réelle.
- La checklist sert de vérification finale reproductible.
À essayer ensuite
Préviens la prochaine dérive
# Préviens la prochaine dérive ## Objectif Fais de la première étape divergente un contrôle explicite du projet. ## Contrôles - Ajoute un contrôle ciblé sur l’étape qui a divergé. - Vérifie la checklist sur un second cas réel. - Documente la limite de périmètre rencontrée. ## Garde-fous - Montre d’abord les changements envisagés avant toute action externe. - Ne publie, n’envoie, ne supprime, ne paie et ne modifie aucun état distant sans autorisation explicite. - Préserve les changements sans rapport et arrête-toi si le périmètre devient ambigu. ## Format de sortie - Résultat obtenu ou verdict. - Fichiers ou actions concernés. - Vérifications exécutées et preuves observables. - Blocages ou limites restantes.
sha256:155d6b69a76da62565643137e06645300fdaed2909c5a1fa8393c4b1981783f4
Digest du Pack: sha256:bfb7f697d1ac611164c3489e8249f2d1e35cd4155926132acff1b9071e1da299