Configuration et skills multi-fichiers

Un skill de trois lignes rend déjà service. Mais dès qu’une procédure a des effets de bord, des outils à lancer, de la documentation de référence ou des scripts, l’en-tête de SKILL.md et l’organisation du dossier font la différence entre un skill qui marche chez vous et un skill fiable chez tout le monde. Cette leçon passe en revue les champs de l’en-tête, l’art d’écrire une description qui déclenche, la pré-approbation d’outils, puis la structure multi-fichiers et les scripts.

L’en-tête, champ par champ

Le standard ouvert Agent Skills ne définit que quelques champs ; Claude Code en accepte une vingtaine, tous facultatifs. Les noms s’écrivent en minuscules avec des tirets, et un champ inconnu est ignoré sans erreur.

Écrire une description qui déclenche

Imaginez qu’on vous embauche en vous disant « votre rôle est d’aider avec la doc ». Vous ne sauriez pas par où commencer. Claude réagit de la même manière face à une description vague : il n’a aucun moyen de savoir dans quelles situations vous attendez son intervention. Une description utile répond à deux questions, dans cet ordre : que fait le skill, et quand l’utiliser ? Le guide d’agentskills.io ajoute trois conseils : formulez à l’impératif (« à utiliser quand… »), décrivez l’intention de l’utilisateur plutôt que la mécanique interne, et soyez explicite, jusqu’à lister les cas où l’utilisateur ne nomme pas le domaine (« même s’il ne dit pas “CSV” »).

# Trop vague : ne se déclenche jamais
description: Aide avec les PDF.

# Ce que fait le skill, puis quand l'utiliser, avec les mots des demandes réelles
description: Extrait le texte et les tableaux des PDF, remplit des formulaires PDF et fusionne des fichiers. À utiliser dès qu'on parle de PDF, de formulaire ou d'extraction de document.

Si votre skill de profilage reste muet alors que vous l’attendiez, relisez sa description en la comparant à la façon dont vous formulez vos demandes : « analyse les performances » ne reconnaîtra pas « pourquoi c’est lent ? » ; le même, enrichi de ces mots, se déclenchera. Mettez le cas d’usage principal en premier : au-delà de 1 536 caractères, la liste coupe.

Pré-approuver des outils avec allowed-tools

Le champ allowed-tools accorde la permission des outils listés pendant le tour qui invoque le skill, pour que Claude n’ait pas à vous demander à chaque appel. La documentation est nette sur ce qu’il ne fait pas : il ne restreint rien. Tous les autres outils restent appelables, sous votre mode de permission habituel ; pour retirer des outils, c’est disallowed-tools. L’accord expire à votre message suivant.

---
name: commit
description: Prépare et crée un commit des changements en cours.
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

Deux conséquences pratiques. D’abord, c’est un bon réglage pour un skill d’action que vous lancez vous-même (/commit, /deploy) : il tourne sans friction, et disable-model-invocation empêche Claude de le déclencher parce que le code lui semble prêt. Ensuite, la prudence : ce champ s’applique même dans un dossier que vous n’avez pas encore marqué comme de confiance, y compris en mode non interactif. Un skill commité dans un dépôt peut s’accorder un large accès ; relisez les allowed-tools des skills d’un dépôt que vous n’avez pas écrit avant d’y lancer Claude Code.

Le chargement progressif

Un skill partage la fenêtre de contexte avec votre conversation. Un SKILL.md de deux mille lignes pose deux problèmes à la fois : il occupe une part considérable de la fenêtre dès qu’il s’active, et il devient pénible à maintenir. Le remède est de ne garder dans SKILL.md que les instructions essentielles (la spécification recommande moins de 500 lignes et 5 000 tokens) et de déporter le reste dans des fichiers annexes que Claude ne lira qu’en cas de besoin :

mon-skill/
  SKILL.md          # obligatoire : instructions et table des matières
  references/       # documentation lue à la demande
  scripts/          # code exécuté, jamais lu
  assets/           # gabarits, données, images

Le lien entre les deux niveaux se fait par une instruction qui dit quand charger : « Si la question porte sur la base de données, lis references/schema.md » vaut mieux qu’un vague « voir references/ ». Claude ouvrira ce fichier le jour où la question sera posée, et seulement ce jour-là. Deux garde-fous de la documentation : évitez les références imbriquées (un fichier annexe qui renvoie à un autre) et donnez une table des matières aux fichiers longs.

Le contenu d’un skill chargé reste dans la conversation pour les tours suivants. Après une compaction, Claude Code ne conserve que les 5 000 premiers tokens de chaque skill invoqué (25 000 au total) : mettez le plus important en haut de SKILL.md.

Faire travailler des scripts

Le répertoire scripts/ obéit à une économie plus favorable encore : un script s’exécute sans que son contenu entre en contexte, seule sa sortie consomme des tokens. Tout repose sur une formulation précise, où vous dites à Claude d’exécuter le script et non de le lire. Pour qu’il le trouve quel que soit le répertoire courant, utilisez la variable ${CLAUDE_SKILL_DIR}, que Claude Code remplace par le dossier du skill, à la fois dans le corps et dans allowed-tools :

---
name: codebase-visualizer
description: Génère une vue arborescente interactive de la base de code. À utiliser pour explorer un dépôt inconnu, comprendre sa structure ou repérer les gros fichiers.
allowed-tools: Bash(python3 *)
---

Exécute `python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .` puis ouvre le fichier HTML produit.

Ce mécanisme sert à trois familles de besoins : la validation d’environnement, les transformations qui doivent donner un résultat rigoureusement identique d’une exécution à l’autre, et toute opération plus fiable sous forme de code testé que de code généré à la volée. Le guide de bonnes pratiques ajoute une règle : résolvez, ne déléguez pas. Un script qui gère lui-même les erreurs et les nouvelles tentatives vaut mieux qu’une instruction « gère les erreurs ». Pour un outil tiers, une commande ponctuelle épinglée (npx eslint@9 --fix ., uvx [email protected] check .) évite d’installer quoi que ce soit globalement, et le champ compatibility déclare ce que le skill exige (« Requiert git et jq »).

Les autres substitutions disponibles : $ARGUMENTS, $0, $1 ou un argument nommé pour ce que vous tapez après la commande ; ${CLAUDE_PROJECT_DIR} pour la racine du projet ; ${CLAUDE_SESSION_ID} et ${CLAUDE_EFFORT} pour adapter le comportement à la session.

À vous de jouer

1. Reprenez le skill pr-description et ajoutez disable-model-invocation: true, puis allowed-tools: Bash(git diff *) Bash(git log *). Lancez-le : plus aucune demande de permission pour ces commandes, et Claude ne le charge plus seul.
2. Écrivez deux descriptions pour un même skill, l’une qui décrit la mécanique, l’autre l’intention de l’utilisateur ; testez trois formulations de demande sur chacune.
3. Créez un skill avec un dossier scripts/ contenant un script qui liste les fichiers de plus de 500 lignes ; appelez-le avec ${CLAUDE_SKILL_DIR} et vérifiez dans /context que le script n’a pas été lu.
4. Déplacez une section de référence dans references/ avec une consigne « lis ce fichier si… », et vérifiez que Claude ne l’ouvre pas quand la question ne s’y prête pas.

Sources officielles : Extend Claude with skills · Spécification Agent Skills · Best practices for skill creators · Skill authoring best practices (API Claude)

Points clés à retenir

• Tous les champs sont facultatifs ; description décide du déclenchement : ce que fait le skill, puis quand l’utiliser, avec les mots des demandes réelles
• allowed-tools pré-approuve des outils pour le tour, il ne restreint rien (disallowed-tools retire) ; il s’applique même dans un dossier non approuvé
• SKILL.md court (moins de 500 lignes), références chargées à la demande avec une consigne « lis si… », scripts exécutés et jamais lus
• ${CLAUDE_SKILL_DIR} localise les scripts du skill ; $ARGUMENTS, $0, ${CLAUDE_PROJECT_DIR} sont les autres substitutions
• Un skill chargé reste en contexte ; après compaction, seuls ses 5 000 premiers tokens survivent