Spécification des Agent Skills

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"
---

Champ	Requis	Contraintes
`name`	Oui	Max 64 caractères. Lettres minuscules, chiffres et traits d’union uniquement. Ne doit pas commencer ou se terminer par un trait d’union.
`description`	Oui	Max 1024 caractères. Non vide. Décrit ce que fait l’Agent Skill et quand l’utiliser.
`license`	Non	Nom de la licence ou référence à un fichier de licence inclus.
`compatibility`	Non	Max 500 caractères. Indique les exigences de l’environnement (produit visé, packages système, accès réseau, etc.).
`metadata`	Non	Mappage clé-valeur arbitraire pour des métadonnées supplémentaires.
`allowed-tools`	Non	Liste 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 :

Métadonnées (~100 tokens) : Les champs name et description sont chargés au démarrage pour tous les Agent Skills
Instructions (< 5000 tokens recommandés) : Le corps complet de SKILL.md est chargé lorsque l’Agent Skill ou le Claude Skill est activé
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.

​Structure du répertoire

​Format du fichier SKILL.md

​Frontmatter (requis)

​Champ name

​Champ description

​Champ license

​Champ compatibility

​Champ metadata

​Champ allowed-tools

​Contenu du corps

​Répertoires optionnels

​scripts/

​references/

​assets/

​Divulgation progressive

​Références de fichiers

​Validation

Structure du répertoire

Format du fichier SKILL.md

Frontmatter (requis)

Champ `name`

Champ `description`

Champ `license`

Champ `compatibility`

Champ `metadata`

Champ `allowed-tools`

Contenu du corps

Répertoires optionnels

scripts/

references/

assets/

Divulgation progressive

Références de fichiers

Validation