Référence du format SKILL.md

Une skill est un dossier qui contient un fichier SKILL.md : un en-tête YAML (le frontmatter) suivi d'instructions en Markdown. Cette page résume le format défini par la spécification Agent Skills et les champs ajoutés par Claude Code.

Exemple minimal

---
name: relecture-pr
description: Relit une pull request et signale bugs, oublis de tests et problèmes de lisibilité. À utiliser quand l'utilisateur demande une relecture de code ou cite une PR.
---

# Relecture de pull request

1. Lire le diff complet.
2. Lister les risques par ordre de gravité.
3. Proposer un correctif pour chacun.

Le fichier doit commencer par la ligne ---. Le dossier qui le contient doit porter le même nom que le champ name.

Champs de la spécification

Ces champs sont communs à tous les agents qui suivent la spécification.

Règles de nommage

Le champ name accepte seulement des lettres minuscules, des chiffres et des tirets. Il ne commence ni ne finit par un tiret, ne contient pas deux tirets de suite et doit être identique au nom du dossier parent. Valides : pdf-processing, code-review. Invalides : PDF-Processing, -pdf, pdf--processing.

Rédiger la description

C'est la seule partie que l'agent lit pour décider de charger la skill. Dites ce qu'elle fait et dans quels cas l'utiliser, avec les mots que vous emploieriez dans une demande. « Aide pour les PDF » est trop vague ; « Extrait le texte et les tableaux des PDF, remplit des formulaires. À utiliser quand l'utilisateur parle de PDF » fonctionne. Voir aussi le déclenchement des skills.

Champs ajoutés par Claude Code

Dans Claude Code, tous les champs sont facultatifs et ceux qu'il ne connaît pas sont ignorés. Parmi ceux qu'il reconnaît en plus de la spécification :

• when_to_use : contexte de déclenchement supplémentaire, ajouté à la description. Ensemble, ils sont tronqués à 1 536 caractères dans la liste des skills.
• argument-hint et arguments : aide à l'autocomplétion et arguments nommés pour une skill appelée avec /nom.
• disable-model-invocation : à true, Claude ne charge pas la skill de lui-même ; vous la lancez à la main.
• user-invocable : à false, la skill disparaît du menu / mais Claude peut encore la charger.
• disallowed-tools, model, effort : limiter des outils, choisir le modèle ou le niveau d'effort pour le tour en cours.
• context: fork et agent : exécuter la skill dans un sous-agent.
• paths : motifs de fichiers ; la skill se charge seulement quand Claude travaille sur des fichiers correspondants.
• hooks et shell : hooks liés à la skill, et shell (bash ou powershell) des commandes intégrées.

Si name est omis, le nom du dossier devient la commande. Si description est omise, la première ligne non vide du corps la remplace. Les champs license et compatibility sont acceptés mais sans effet. Ces champs propres à Claude Code ne sont pas portables : sur claude.ai et via l'API Skills, seuls les champs de la spécification passent.

Structure du dossier

ma-skill/
├── SKILL.md
├── references/
├── assets/
└── scripts/

• SKILL.md : obligatoire.
• references/ : documentation détaillée, lue à la demande (par exemple REFERENCE.md). Gardez des fichiers courts et ciblés.
• assets/ : modèles, images, fichiers de données.
• scripts/ : code exécutable. La spécification le prévoit, mais les ressources du catalogue PalateKit n'en livrent pas ; voir la sécurité des skills.

Appelez chaque fichier depuis SKILL.md par un chemin relatif à la racine de la skill, par exemple references/REFERENCE.md, pour que l'agent sache quand l'ouvrir. Restez à un seul niveau de profondeur.

Taille et chargement progressif

Les agents chargent une skill en trois temps :

1. Métadonnées (environ 100 jetons) : name et description de toutes les skills, au démarrage.
2. Instructions (moins de 5 000 jetons recommandés) : le corps de SKILL.md, quand la skill est activée.
3. Ressources : fichiers de references/, assets/ ou scripts/, seulement quand la tâche les demande.

Gardez SKILL.md sous 500 lignes et déplacez le détail dans des fichiers séparés. Une skill installée pèse donc très peu tant qu'elle ne sert pas.

Valider et installer

Le dépôt de la spécification fournit l'outil skills-ref : skills-ref validate ./ma-skill vérifie le frontmatter et les règles de nommage. Pour placer le dossier chez votre agent, voir installer votre première ressource et les catalogues de skills.