Configuration et Skills multi-fichiers

Configuration et Skills multi-fichiers · 4 min

RésuméTranscription

Cette vidéo présente les techniques avancées qui rendent les skills plus puissants : les champs de métadonnées clés, la manière de rédiger des descriptions qui se déclenchent de manière fiable, la préapprobation des outils dont un skill a besoin, et l'organisation de skills plus volumineux sur plusieurs fichiers à l'aide de la divulgation progressive. Vous apprendrez à garder vos skills efficaces tout en prenant en charge des cas d'usage complexes.

Points clés à retenir

Chaque champ du frontmatter est facultatif dans Claude Code, et seul description est recommandé. allowed-tools et model sont deux des ajouts les plus utiles
Une bonne description répond à deux questions : Que fait le skill ? Quand Claude doit-il l'utiliser ?
allowed-tools préapprouve les outils répertoriés pendant que le skill est actif, de sorte que Claude puisse les utiliser sans demander d'autorisation, et cela ne limite pas Claude à ces seuls outils
Divulgation progressive : gardez SKILL.md sous la barre des 500 lignes et créez des liens vers des fichiers d'appui (références, scripts, ressources) que Claude ne lit qu'en cas de besoin
Les scripts s'exécutent sans que leur contenu soit chargé dans le contexte — seule la sortie consomme des jetons, ce qui permet de garder un contexte efficace

Un skill basique fonctionne avec seulement un nom et une description, mais il existe plusieurs techniques avancées qui peuvent rendre vos skills beaucoup plus efficaces dans Claude Code. Passons en revue les champs clés, les bonnes pratiques pour les descriptions, les autorisations d'outils, et comment structurer des skills plus volumineux.

Champs de métadonnées de skill

La norme ouverte des Skills d'agent définit les champs principaux du frontmatter de SKILL.md, et Claude Code en ajoute plusieurs autres, comme model. Dans Claude Code, tous les champs sont facultatifs, et seul description est recommandé. Ces quatre champs constituent un bon point de départ (la référence du frontmatter répertorie les autres) :

name (facultatif) — Identifie votre skill. Par défaut, il s'agit du nom du répertoire. Si vous téléversez le skill sur Claude.ai ou sur Claude API, ce champ est requis et limité aux lettres minuscules, aux chiffres et aux traits d'union, jusqu'à 64 caractères.
description (recommandé) — Indique à Claude quand utiliser le skill. Si vous téléversez le skill sur Claude.ai ou sur Claude API, ce champ est requis et limité à 1 024 caractères. C'est le champ le plus important, car Claude l'utilise pour la mise en correspondance.
allowed-tools (facultatif) — Préapprouve les outils répertoriés, de sorte que Claude puisse les utiliser sans demander d'autorisation pendant que le skill est actif.
model (facultatif) — Spécifie le modèle Claude à utiliser pour le skill.

Rédiger des descriptions efficaces

Soyez explicite dans vos instructions. Si quelqu'un vous disait « votre travail consiste à aider avec la documentation », vous ne sauriez pas quoi faire — et Claude raisonne de la même manière.

Une bonne description répond à deux questions :

Que fait le skill ?
Quand Claude doit-il l'utiliser ?

Si votre skill ne se déclenche pas quand vous vous y attendez, essayez d'ajouter davantage de mots-clés correspondant à la façon dont vous formulez réellement vos requêtes. C'est la description que Claude utilise pour décider si un skill est pertinent, donc la formulation compte.

Préapprouver des outils avec allowed-tools

Il arrive qu'un skill repose à chaque exécution sur la même poignée d'outils, et vous ne souhaitez pas approuver chaque appel manuellement. Le champ allowed-tools préapprouve les outils que vous répertoriez, de sorte que Claude puisse les utiliser sans invite d'autorisation pour le reste du tour qui a invoqué le skill. Cette autorisation s'efface lorsque vous envoyez votre message suivant.

Le fichier SKILL.md codebase-onboarding dans un éditeur, avec la ligne allowed-tools mise en surbrillance, présentée dans le bloc de code ci-dessous.

Dans cet exemple, le champ allowed-tools est défini sur Read, Grep, Glob, Bash. Lorsque ce skill est actif, Claude peut utiliser ces quatre outils sans demander d'autorisation. Il ne perd l'accès à rien d'autre : si les instructions du skill amènent Claude à modifier ou écrire un fichier, cela passe par vos paramètres d'autorisation habituels, comme pour tout autre appel d'outil. Une mise en garde : répertorier Bash seul préapprouve les commandes shell en général, réservez donc cela aux skills auxquels vous faites confiance, ou restreignez-le à un motif tel que Bash(git status *).

yaml

---
name: codebase-onboarding
description: Helps new developers understand the system works.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

Si vous omettez entièrement allowed-tools, rien n'est préapprouvé et Claude utilise son modèle d'autorisation habituel pour chaque outil. Pour faire l'inverse et retirer des outils pendant qu'un skill est actif, utilisez un champ distinct du frontmatter de Claude Code, disallowed-tools, qui retire les outils que vous répertoriez de l'ensemble que Claude peut utiliser.

Divulgation progressive

Les skills partagent la fenêtre de contexte de Claude avec votre conversation. Lorsque Claude active un skill, il charge le contenu de ce SKILL.md dans le contexte. Mais il arrive que vous ayez besoin de références, d'exemples ou de scripts utilitaires dont dépend le skill.

Tout entasser dans un seul fichier de 2 000 lignes pose deux problèmes : cela occupe beaucoup d'espace dans la fenêtre de contexte, et ce n'est pas agréable à maintenir.

La divulgation progressive résout ce problème. Conservez les instructions essentielles dans SKILL.md et placez la documentation de référence détaillée dans des fichiers distincts que Claude ne lit qu'en cas de besoin.

La norme ouverte suggère d'organiser votre répertoire de skill de la manière suivante :

scripts/ — Code exécutable
references/ — Documentation supplémentaire
assets/ — Images, modèles ou autres fichiers de données

Ensuite, dans SKILL.md, créez des liens vers les fichiers d'appui avec des instructions claires sur le moment où les charger :

Les sections de niveau 2 et de niveau 3 du SKILL.md créent des liens vers architecture-guide.md et deep-dive-guide.md, à charger uniquement sur demande.

Dans cet exemple, Claude ne lit architecture-guide.md que lorsque quelqu'un pose une question sur la conception du système. Si on lui demande où ajouter un composant, il ne charge jamais ce fichier. C'est comme avoir une table des matières dans la fenêtre de contexte plutôt que le document entier.

Une bonne règle empirique : gardez SKILL.md sous la barre des 500 lignes. Si vous dépassez cette limite, demandez-vous si le contenu devrait être divisé en fichiers de référence distincts.

Utiliser les scripts efficacement

Les scripts de votre répertoire de skill peuvent s'exécuter sans que leur contenu soit chargé dans le contexte. Le script s'exécute et seule la sortie consomme des jetons. L'instruction clé à inclure dans votre SKILL.md est de dire à Claude d'exécuter le script, et non de le lire.

Ceci est particulièrement utile pour :

La validation de l'environnement
Les transformations de données qui doivent être cohérentes
Les opérations plus fiables sous forme de code testé que de code généré

Réflexion sur la leçon

Pensez à un skill que vous aimeriez créer et qui implique plusieurs fichiers. Comment structureriez-vous le SKILL.md par rapport aux fichiers de référence d'appui ?
Pour un skill partagé par votre équipe, quels outils préapprouveriez-vous avec allowed-tools, et pour lesquels préféreriez-vous que Claude continue de demander une autorisation ?

Et ensuite ?

Dans la prochaine leçon, nous comparerons les skills aux autres façons de personnaliser Claude Code — CLAUDE.md, subagents, hooks et serveurs MCP — afin que vous puissiez choisir le bon outil pour chaque situation.