Passer au contenu principal

​
Structure du répertoire

Un Agent Skill est un répertoire contenant au minimum un fichier SKILL.md. Ce format est largement utilisé pour créer des Claude Skills : 
skill-name/
└── SKILL.md          # Requis
Vous pouvez éventuellement inclure des répertoires supplémentaires tels que scripts/, references/ et assets/ pour soutenir votre Agent Skill.

​
Format du fichier SKILL.md

Le fichier SKILL.md est le composant central de chaque Agent Skill. Il doit contenir un frontmatter YAML suivi d’un contenu Markdown, une structure partagée par tous les Claude Skills.

​
Frontmatter (requis)

---
name: skill-name
description: Une description de ce que fait ce skill et quand l'utiliser.
---
Avec des champs optionnels : 
---
name: pdf-processing
description: Extraire du texte et des tableaux de fichiers PDF, remplir des formulaires, fusionner des documents.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---
ChampRequisContraintes
nameOuiMax 64 caractères. Lettres minuscules, chiffres et traits d’union uniquement. Ne doit pas commencer ou se terminer par un trait d’union.
descriptionOuiMax 1024 caractères. Non vide. Décrit ce que fait l’Agent Skill et quand l’utiliser.
licenseNonNom de la licence ou référence à un fichier de licence inclus.
compatibilityNonMax 500 caractères. Indique les exigences de l’environnement (produit visé, packages système, accès réseau, etc.).
metadataNonMappage clé-valeur arbitraire pour des métadonnées supplémentaires.
allowed-toolsNonListe d’outils pré-approuvés délimitée par des espaces que l’Agent Skill peut utiliser. (Expérimental)

​
Champ name

Le champ name requis pour tout Claude Skill :
  • Doit faire entre 1 et 64 caractères
  • Ne peut contenir que des caractères alphanumériques minuscules unicode et des traits d’union (a-z et -)
  • Ne doit pas commencer ou se terminer par -
  • Ne doit pas contenir de traits d’union consécutifs (--)
  • Doit correspondre au nom du répertoire parent
Exemples valides : 
name: pdf-processing

name: data-analysis

name: code-review
Exemples invalides : 
name: PDF-Processing  # majuscules non autorisées

name: -pdf  # ne peut pas commencer par un trait d'union

name: pdf--processing  # traits d'union consécutifs non autorisés

​
Champ description

Le champ description requis :
  • Doit faire entre 1 et 1024 caractères
  • Doit décrire à la fois ce que fait l’Agent Skill et quand l’utiliser
  • Doit inclure des mots-clés spécifiques qui aident les agents utilisant des Claude Skills à identifier les tâches pertinentes
Bon exemple : 
description: Extrait du texte et des tableaux des fichiers PDF, remplit les formulaires PDF et fusionne plusieurs PDF. À utiliser lors du travail avec des documents PDF ou lorsque l'utilisateur mentionne des PDF, des formulaires ou l'extraction de documents.
Mauvais exemple : 
description: Aide avec les PDF.

​
Champ license

Le champ license optionnel :
  • Spécifie la licence appliquée à l’Agent Skill
  • Nous recommandons de rester court (soit le nom d’une licence, soit le nom d’un fichier de licence inclus)
  • C’est une pratique courante pour les Claude Skills portables.
Exemple : 
license: Propriétaire. LICENSE.txt contient les conditions complètes

​
Champ compatibility

Le champ compatibility optionnel :
  • Doit faire entre 1 et 500 caractères si fourni
  • Ne doit être inclus que si votre Agent Skill a des exigences environnementales spécifiques
  • Peut indiquer le produit visé, les packages système requis, les besoins d’accès au réseau, etc.
Exemples : 
compatibility: Conçu pour Claude Code (ou produits similaires)

compatibility: Nécessite git, docker, jq et l'accès à internet
La plupart des Agent Skills et Claude Skills n’ont pas besoin du champ compatibility.

​
Champ metadata

Le champ metadata optionnel :
  • Un mappage des clés de type string vers des valeurs de type string
  • Les clients peuvent l’utiliser pour stocker des propriétés supplémentaires non définies par la spécification Agent Skills. Les Claude Skills utilisent souvent ce champ pour le versionnage personnalisé ou les informations sur l’auteur.
  • Nous recommandons de rendre vos noms de clés raisonnablement uniques pour éviter les conflits accidentels
Exemple : 
metadata:
  author: example-org
  version: "1.0"

​
Champ allowed-tools

Le champ allowed-tools optionnel :
  • Une liste d’outils délimitée par des espaces qui sont pré-approuvés pour s’exécuter
  • Expérimental. Le support de ce champ peut varier selon les implémentations des agents
Exemple : 
allowed-tools: Bash(git:*) Bash(jq:*) Read

​
Contenu du corps

Le corps Markdown après le frontmatter contient les instructions de l’Agent Skill. Il n’y a pas de restrictions de format. Écrivez tout ce qui aide les agents à effectuer la tâche efficacement lors de l’utilisation de cet Agent Skill. Cet ensemble d’instructions est ce qui guide un Claude Skill à travers des flux de travail complexes. Sections recommandées :
  • Instructions étape par étape
  • Exemples d’entrées et de sorties
  • Cas limites courants
Notez que l’agent chargera l’intégralité de ce fichier une fois qu’il aura décidé d’activer un Agent Skill. Envisagez de diviser le contenu SKILL.md plus long en fichiers référencés.

​
Répertoires optionnels

Les Agent Skills peuvent inclure des répertoires optionnels pour soutenir des flux de travail plus complexes.

​
scripts/

Contient du code exécutable que les agents peuvent lancer lors de l’utilisation de l’Agent Skill. Les scripts doivent :
  • Être autonomes ou documenter clairement les dépendances
  • Inclure des messages d’erreur utiles
  • Gérer les cas limites avec élégance
Les langages supportés dépendent de l’implémentation de l’agent. Les options courantes incluent Python, Bash et JavaScript.

​
references/

Contient de la documentation supplémentaire que les agents peuvent lire au besoin :
  • REFERENCE.md - Référence technique détaillée
  • FORMS.md - Modèles de formulaires ou formats de données structurées
  • Fichiers spécifiques au domaine (finance.md, legal.md, etc.)
Gardez les fichiers de référence ciblés. Lorsque les agents utilisent des Agent Skills, ils chargent ces fichiers de référence à la demande—un principe clé pour l’exécution efficace d’un Claude Skill.

​
assets/

Contient des ressources statiques :
  • Modèles (modèles de documents, modèles de configuration)
  • Images (diagrammes, exemples)
  • Fichiers de données (tables de recherche, schémas)

​
Divulgation progressive

Les Agent Skills doivent être structurés pour une utilisation efficace du contexte. Cette structure est essentielle pour les Claude Skills haute performance :
  1. Métadonnées (~100 tokens) : Les champs name et description sont chargés au démarrage pour tous les Agent Skills
  2. Instructions (< 5000 tokens recommandés) : Le corps complet de SKILL.md est chargé lorsque l’Agent Skill ou le Claude Skill est activé
  3. Ressources (au besoin) : Les fichiers (ex: ceux dans scripts/, references/ ou assets/) ne sont chargés que lorsque nécessaire
Gardez votre SKILL.md principal sous 500 lignes. Déplacez le matériel de référence détaillé vers des fichiers séparés.

​
Références de fichiers

Lorsque vous référencez d’autres fichiers dans votre Agent Skill, utilisez des chemins relatifs à partir de la racine du skill : 
Consultez [le guide de référence](references/REFERENCE.md) pour plus de détails.

Exécutez le script d'extraction :
scripts/extract.py
Gardez les références de fichiers à un niveau de profondeur par rapport à SKILL.md. Évitez les chaînes de référence profondément imbriquées.

​
Validation

Utilisez la bibliothèque de référence skills-ref pour valider vos Agent Skills et vous assurer que vos Claude Skills sont correctement formatés : 
skills-ref validate ./my-skill
Cela vérifie que votre frontmatter SKILL.md est valide et suit toutes les conventions de nommage.