Comprendre les skills de Claude Code : chargement, déclenchement et rédaction

Si l'on retire l'aspect marketing, une skill est simplement un répertoire avec un fichier obligatoire. SKILL.md commence par un frontmatter YAML contenant un name et une description, puis se poursuit avec des instructions Markdown classiques. Le dossier peut également contenir des scripts invoqués par les instructions, des documents de référence et des modèles d'assets. C'est tout le format, et c'est volontairement simple : une skill est une procédure mise par écrit et packagée pour qu'un agent puisse la trouver.

---
name: brand-audit
description: Check UI code against the project design system. Use when reviewing components, screens, or PRs for hardcoded colors, off-scale spacing, or fonts that bypass the tokens in DESIGN.md.
---

# Brand audit

1. Read DESIGN.md at the repo root before judging anything.
2. Flag any literal hex value, arbitrary Tailwind color, or font-family
   that does not come from the token set.
3. Report violations as file:line with the token that should be used.

Ce format fonctionne désormais au-delà de Claude Code : il est devenu une convention ouverte pour les skills d'agents, adoptée par Codex d'OpenAI et Cursor avec leurs propres chemins de découverte. C'est pourquoi une skill écrite une fois vous suit désormais partout. Nous détaillons la partie Codex dans Codex skills.

Claude Code ne lit pas vos skills à chaque conversation. Au début de la session, il indexe uniquement le frontmatter : chaque skill apporte son nom et sa description au contexte, soit quelques lignes, rien de plus. Le corps complet, les scripts et les fichiers de référence ne sont chargés que lorsque Claude décide que la tâche actuelle correspond à une description, ou lorsque vous invoquez explicitement la skill. Anthropic appelle cela la « divulgation progressive » (progressive disclosure), et c'est la décision de conception sur laquelle repose toute la fonctionnalité.

Deux conséquences pratiques en découlent. Premièrement, installer cinquante skills ne coûte presque rien en contexte ; accumuler des skills est donc sans risque, car cent descriptions pèsent moins qu'un seul corps de skill chargé. Deuxièmement, et c'est ce que les articles récapitulatifs oublient, une skill avec une description faible est *installée mais inaccessible*. Claude ne peut pas associer une tâche à « Aide pour les trucs de frontend ». Les plaintes qui remplissent les fils Reddit — « j'ai installé vingt skills et rien n'a changé » — viennent généralement de là : le contenu était correct, mais les descriptions ne donnaient jamais au modèle de raison de les ouvrir.

• ~/.claude/skills/<skill-name>/SKILL.md : skills personnelles, disponibles dans chaque projet ouvert.
• .claude/skills/<skill-name>/SKILL.md : skills de projet, commitées dans le repo pour que chaque collaborateur et chaque session d'agent en bénéficie.
• Plugins : un plugin peut regrouper des skills avec des commandes et des agents, permettant aux équipes de distribuer un ensemble complet en une seule installation.

L'emplacement dans le repo est plus important qu'il n'y paraît. Une skill personnelle stabilise vos sessions ; une skill commitée stabilise celles de vos coéquipiers et de votre agent CI. Tout ce qui encode un contrat de projet — comment nous revoyons l'UI, comment nous écrivons les migrations, comment nous appliquons le design system — doit se trouver dans .claude/skills/ à côté du code qu'il régit.

Claude Code propose trois endroits pour stocker des connaissances, et ils répondent à des besoins différents. CLAUDE.md est toujours chargé : il sert aux contraintes s'appliquant à chaque requête, et chaque ligne est payée à chaque prompt, il doit donc rester court. Une skill est chargée à la demande : elle sert aux procédures occasionnellement pertinentes, et peut être longue car elle ne coûte rien tant qu'elle n'est pas déclenchée. Un sous-agent possède un contexte totalement distinct : il est destiné aux travaux dont la sortie intermédiaire polluerait votre session.

La ligne de démarcation pour la taxonomie complète des fichiers, incluant AGENTS.md et DESIGN.md, se trouve dans CLAUDE.md vs AGENTS.md vs SKILL.md vs DESIGN.md.

1. 1

   Partir d'une correction répétitive

   Les meilleurs candidats pour un skill sont les éléments que vous saisissez sans cesse : la checklist de revue que vous collez, la séquence de déploiement que vous réexpliquez. Si vous n'avez jamais dû corriger l'agent deux fois sur un point précis, ce point ne nécessite pas encore de skill.

2. 2

   Écrire la description d'abord, comme conditions de déclenchement

   Avant les instructions, rédigez la phrase qui détermine quand ce skill est chargé : les verbes et les situations qu'une requête correspondante contiendrait. Si vous ne pouvez pas nommer ces situations, le skill ne s'activera pas, et vous le saurez dès le départ.

3. 3

   Faire du corps du texte une procédure exécutable

   Étapes numérotées, commandes exactes, chemins de fichiers précis. Référencez des fichiers dans le dossier du skill pour tout contenu long. Un agent suit une procédure bien plus fidèlement qu'il ne canalise une « ambiance ».

4. 4

   Pointer vers des artefacts, pas des adjectifs

   Un skill qui dit « garder l'UI cohérente » ne sert à rien. Un skill qui dit « lire DESIGN.md et utiliser uniquement ses tokens » fonctionne, car le jugement est externalisé dans un fichier que l'agent peut ouvrir. Placez la connaissance dans un artefact et laissez le skill servir de pointeur.

5. 5

   Tester par la demande, pas par l'invocation

   Ne testez pas avec une invocation explicite ; cela ne prouve rien quant au déclenchement. Formulez une requête comme vous le feriez naturellement et vérifiez si le skill se charge. Si ce n'est pas le cas, c'est la description, et non le corps du texte, qu'il faut modifier.

Le design est le cas d'usage idéal pour un skill, et l'illustration parfaite de la règle des artefacts mentionnée plus haut. Anthropic propose un skill de design frontend pour Claude Code, et il améliore réellement des écrans isolés ; nous l'avons testé et détaillé exactement ce qu'il fait et ce qui lui manque. Ce qui lui manque, c'est la mémoire entre les écrans : le skill apporte du goût, pas vos valeurs, donc l'écran vingt s'éloigne de l'écran un. Le goût se généralise ; l'identité, non.

La solution est le modèle de l'étape quatre : le skill reste une procédure légère, et l'identité réside dans un artefact, un DESIGN.md à la racine du repo avec de vrais tokens, des choix typographiques, des règles d'espacement et des interdictions. Le skill d'audit de marque en haut de cette page ne fait que douze lignes parce que tout ce qu'il impose est défini dans ce seul fichier. C'est cela, un design system pour un agent : non pas un plugin, mais un contrat lisible.

npx --yes identityforge@latest install --client claude-code

Le format de skill a cessé d'être spécifique à Claude d'une manière qui impacte vos investissements. Le Codex d'OpenAI détecte les dossiers SKILL.md sous .agents/skills/ et ~/.agents/skills/ et les invoque avec $; Cursor a ajouté les Agent Skills avec le même chargement à la demande à côté de ses Rules permanentes, et oriente les règles procédurales longues vers des skills. La convention converge vers la même structure partout : un frontmatter qui annonce, un corps qui instruit, un chargement qui attend la pertinence. Les skills que vous écrivez en vous appuyant sur des artefacts dans votre repo, plutôt que sur les particularités d'un outil, survivent au changement d'outils.