Anatomie d'un fichier SKILL.md#

Le frontmatter decide quand ta skill se declenche, le corps decide comment elle travaille : deux jobs differents, deux facons d'ecrire.

Temps de lecture : 15 min | Niveau : Intermediaire

Ce que tu sauras faire apres#

• Ecrire un frontmatter valide du premier coup.
• Choisir les champs utiles parmi tous ceux disponibles.
• Rediger une description qui declenche la skill au bon moment, et seulement a ce moment.
• Decider ce qui reste dans le SKILL.md et ce qui part en fichier de reference.
• Injecter le resultat d'une commande shell et des arguments dans ta skill.

1. La structure minimale#

---
name: ma-skill
description: Ce que fait la skill, et quand l'utiliser.
---

# Ma skill

## Instructions

Les etapes que l'agent doit suivre.

Piege numero 1. Le premier --- doit etre la toute premiere ligne du fichier. Pas de ligne vide avant, pas de commentaire. Sinon le fichier entier est traite comme du contenu de skill, et ton frontmatter devient du texte inutile.

2. 🏷️ Le champ name#

Regles de validation officielles : 64 caracteres maximum, uniquement des lettres minuscules, chiffres et tirets, pas de balises XML, pas de mots reserves (anthropic, claude).

Attention, francophones. « lettres minuscules » veut dire a-z. Pas d'accents, pas de cedille, pas d'espaces. Ecris controle-qualite-donnees, jamais contrôle-qualité-données.

Dans Claude Code, name est optionnel : par defaut, le nom du dossier devient la commande (deploy/ donne /deploy). Pour le standard Agent Skills et pour l'API, name et description sont tous les deux obligatoires.

Deux noms sont reserves dans Claude Code : synced, et anthropic-skills (ou anthropic-skills:*).

La doc recommande une forme qui decrit l'activite (en anglais, le gerondif en -ing). En francais, un nom d'action ou un verbe a l'infinitif fait le meme travail.

3. ✍️ Le champ description : le plus important#

C'est ce que l'agent lit en permanence pour decider s'il ouvre ta skill. Floue, elle ne se declenchera jamais ; trop large, elle se declenchera tout le temps.

Les deux chiffres a connaitre#

Tu vas croiser deux limites differentes. Elles ne se contredisent pas : elles ne parlent pas de la meme chose.

Ce qu'il faut en retenir. Vise 2 a 3 phrases, soit environ 300 caracteres. Tu restes largement sous les deux limites et tu ne te poses plus la question. Une description trop longue n'ameliore pas le declenchement : elle le dilue.

Trois regles de redaction :

1. Toujours a la troisieme personne. La description est injectee dans le prompt systeme, et melanger les points de vue perturbe la selection. Bien : Analyse les fichiers Excel. A eviter : Je peux t'aider a... ou Tu peux utiliser ceci pour....
2. Dire ce que ca fait ET quand l'utiliser, dans la meme description.
3. Inclure les mots declencheurs : les termes exacts que tu tapes quand le besoin arrive (noms d'outils, extensions, jargon metier).

AVANT / APRES#

description: Aide avec les donnees

Pourquoi c'est mauvais : aucun terme declencheur, aucun « quand ». L'agent ne saura pas si « ecris-moi un modele dbt » entre dans ce perimetre. Avec 30 skills installees, celle-ci sera choisie au hasard ou jamais.

description: Verifie un modele dbt contre les conventions de l'equipe (nommage des CTE, tests obligatoires, documentation des colonnes). A utiliser quand l'utilisateur ecrit ou revoit un fichier .sql dans models/, parle de dbt, de staging, de marts ou de schema.yml.

Pourquoi c'est mieux : on lit ce que ca fait, le detail, et quand (fichiers .sql dans models/, mots dbt, staging, marts, schema.yml). Un agent peut trancher sans hesiter.

4. 📋 Tous les champs du frontmatter (Claude Code)#

Dans Claude Code, tous les champs sont optionnels et seul description est recommande.

Attention a la portabilite. La plupart de ces champs sont specifiques a Claude Code. Hors de Claude Code (televersement sur claude.ai, API Skills, autres agents qui suivent le standard), seuls six champs sont acceptes : name, description, license, compatibility, metadata et allowed-tools. Si tu comptes reutiliser ta skill ailleurs, limite-toi a ces six-la.

Le tableau de synthese du controle d'invocation :

5. 🔌 Injection dynamique et arguments#

La syntaxe !`commande` execute une commande avant que l'agent voie la skill, et remplace le placeholder par sa sortie. Il existe aussi une forme multi-lignes : un bloc de code dont le langage declare est !.

## Etat du depot

!`git diff HEAD --stat`

## Modeles dbt modifies

!`git diff --name-only HEAD -- models/`

Limite documentee. Ces commandes ne s'executent pas dans les skills synchronisees depuis claude.ai (restriction de securite). Un reglage disableSkillShellExecution permet aussi de desactiver l'execution shell dans les skills.

Les substitutions disponibles :

6. Le corps : des instructions permanentes#

Une fois invoquee, la skill reste dans le contexte des tours suivants : Claude Code ne relit pas le fichier a chaque message. Tu ecris donc des consignes permanentes, pas une sequence a usage unique.

• Bien : « Quand tu revois une requete SQL, verifie le filtre sur les lignes de test et le nommage des CTE. »
• A eviter : « D'abord, lis le fichier models/staging/stg_commandes.sql. »

Les autres regles du corps, toutes documentees :

• Moins de 500 lignes. Au-dela, decoupe en fichiers de reference.
• Pas d'information datee. Pas de « avant aout 2025, fais ceci ». Mets plutot une section « anciens usages » a la fin.
• Vocabulaire constant : toujours « colonne », jamais « champ » puis « attribut ».
• Un defaut, pas un menu. « Utilise pandas. Au-dela de 5 Go, polars. » plutot que cinq options.
• Chemins en slash avant, meme sous Windows : reference/guide.md, jamais reference\guide.md.
• References a un seul niveau : tous les fichiers annexes lies directement depuis SKILL.md. En cascade, l'agent risque de ne lire qu'un extrait et de rater l'information.
• Sommaire dans tout fichier de plus de 100 lignes, pour que le perimetre reste visible sur une lecture partielle.

7. 🧪 Exemple complet et commente#

Une skill projet qui verifie les DAG Airflow de l'equipe.

.claude/skills/verifier-dag-airflow/
├── SKILL.md
└── reference/
    └── conventions-airflow.md

---
name: verifier-dag-airflow
description: Verifie qu'un DAG Airflow respecte les conventions de l'equipe (nommage,
  owner, retries, SLA, tags, absence de code lourd au niveau module). A utiliser quand
  l'utilisateur ecrit, modifie ou revoit un fichier dans dags/, parle d'Airflow, de DAG,
  d'operateur, de scheduling ou de backfill.
argument-hint: [chemin-du-dag]
paths: dags/**/*.py
allowed-tools: Read, Grep, Glob
---

# Verification d'un DAG Airflow

## Fichiers modifies dans dags/

!`git diff --name-only HEAD -- dags/`

## Procedure

Copie cette liste dans ta reponse et coche au fur et a mesure.

- [ ] Etape 1 : lire le DAG cible. Si $ARGUMENTS contient un chemin, analyser ce
      fichier ; sinon, analyser les fichiers listes ci-dessus.
- [ ] Etape 2 : verifier les 6 regles bloquantes
- [ ] Etape 3 : verifier les 4 regles de style
- [ ] Etape 4 : rendre le rapport

Le detail des regles, avec les valeurs attendues, est dans
[reference/conventions-airflow.md](reference/conventions-airflow.md). Lis ce fichier
avant de juger.

## Format du rapport

Rends toujours un tableau : Regle | Statut | Ligne | Correction proposee.
Termine par un verdict unique : BLOQUANT, A CORRIGER ou OK.

Ce qui est fait, et pourquoi :

8. Template a copier-coller#

---
name: [NOM_EN_MINUSCULES_AVEC_TIRETS_SANS_ACCENT]
description: [VERBE_3E_PERSONNE] [CE_QUE_CA_FAIT]. A utiliser quand l'utilisateur
  [SITUATION_1], [SITUATION_2], ou mentionne [MOT_DECLENCHEUR_1], [MOT_DECLENCHEUR_2].
argument-hint: [ARGUMENT_ATTENDU]
paths: [MOTIF_GLOB_OPTIONNEL]
allowed-tools: [OUTILS_A_PREAUTORISER]
---

# [TITRE_LISIBLE]

## Contexte automatique

!`[COMMANDE_SHELL_QUI_DONNE_L_ETAT_ACTUEL]`

## Regles a appliquer

1. [REGLE_1]
2. [REGLE_2]
3. [REGLE_3]

## Procedure

- [ ] Etape 1 : [ACTION]
- [ ] Etape 2 : [ACTION]
- [ ] Etape 3 : [VERIFICATION_QUI_REBOUCLE_SI_ELLE_ECHOUE]

## Format de sortie attendu

[DECRIS_LE_FORMAT_EXACT]

## Ressources

- Detail complet : [reference/[FICHIER].md](reference/[FICHIER].md)

A retenir#

• Le premier --- doit etre la premiere ligne du fichier, sans exception.
• name : minuscules, chiffres, tirets. Pas d'accents. 64 caracteres max.
• description : troisieme personne, ce que ca fait et quand l'utiliser, avec les mots declencheurs. Vise 2 a 3 phrases : la validation refuse au-dela de 1 024 caracteres, et Claude Code tronque l'affichage a 1 536 caracteres avec when_to_use.
• disable-model-invocation: true sur tout ce qui a un effet de bord.
• Pour rester portable hors de Claude Code, limite-toi a name, description, license, compatibility, metadata et allowed-tools.
• Le corps contient des consignes permanentes, moins de 500 lignes.
• Les fichiers annexes se lient directement depuis SKILL.md, jamais en cascade.
• !`commande` injecte l'etat reel du depot avant que l'agent lise la skill.

Sources#

• Agent Skills in Claude Code
• Skill authoring best practices
• Agent Skills - Overview
• agentskills.io
• anthropics/skills - le squelette de frontmatter (template/SKILL.md) et la spec du format (spec/agent-skills-spec.md)
• anthropics/claude-cookbooks - un SKILL.md avec scripts bundles : skills/custom_skills/analyzing-financial-statements/