Chapitre 9.2 — Écrire une skill
⏱️ TL;DR — Écrire une bonne skill, c’est surtout bien la cadrer : une description précise avec ses déclencheurs (c’est elle qui décide de l’activation), un périmètre focalisé (une skill = un job), et le progressive disclosure (l’essentiel dans le
SKILL.md, le lourd en ressources). La philosophie qui marche : petit, adaptable, composable — une skill qui encode un workflow que tu répètes, pas un couteau suisse. La skillwrite-a-skillt’assiste pour la structure ; ton job, c’est le contenu et le cadrage.
🎯 Objectifs
- Écrire une description qui déclenche au bon moment.
- Cadrer une skill focalisée et composable.
- Utiliser le progressive disclosure (ressources) à bon escient.
- Savoir quand une skill est le bon outil (vs commande/CLAUDE.md/subagent).
Utilise write-a-skill
Ne pars pas de zéro : la skill write-a-skill crée une skill avec la bonne structure (front-matter, progressive disclosure, ressources bundle). Tu lui décris ce que tu veux automatiser ; elle scaffolde. Ton apport reste le cadrage (déclencheurs, périmètre) et le contenu (les étapes réelles).
« Avec
write-a-skill, crée une skillnew-featurepour TaskFlow qui génère le squelette d’une feature (queries.ts, actions.ts, schema.ts, components/) selon nos conventions. »
La description : l’interface de la skill
Répétons-le (9.1) car c’est le point : la description décide de l’activation par le modèle. Une bonne description dit quoi et quand, avec des déclencheurs explicites.
| ❌ Description faible | ✅ Description forte |
|---|---|
| « Aide pour les features » | « Scaffolde une nouvelle feature TaskFlow (queries/actions/schema/components) selon nos conventions. Utiliser quand on démarre une feature ou qu’on dit “nouvelle feature”, “ajoute une entité”. » |
| « Utilitaire de tests » | « Génère les tests Vitest d’une server action à partir de son schéma Zod. Utiliser après avoir créé/modifié une action dans actions.ts. » |
La forte contient des mots-déclencheurs que tes demandes réelles emploieront. Sans eux, la skill dort quand tu en aurais besoin.
💡 Réflexe d’architecte — Écris la description depuis les phrases que tu diras vraiment. Imagine tes prompts (« ajoute une entité », « génère les tests de cette action ») et mets ces formulations dans la description. Une skill se déclenche par correspondance : elle doit parler ta langue de tous les jours.
Petit, adaptable, composable
La philosophie qui distingue les bonnes collections de skills (celle de Matt Pocock, notamment) : une skill doit être petite (un job clair), adaptable (facile à ajuster à ton projet) et composable (elle coopère avec les autres, ne réinvente pas tout). Concrètement :
- Un job par skill. Pas de « méga-skill » qui fait feature + tests + revue. Trois skills focalisées valent mieux — tu les composes.
- Des instructions prescriptives, comme un bon
CLAUDE.md(3.2) : étapes claires, tranchables, pas de blabla. - Le lourd en ressources : un guide détaillé, une checklist, un template vont dans
reference/— chargés seulement si la skill en a besoin (progressive disclosure), pour garder leSKILL.mdléger.
Quand une skill est-elle le bon outil ?
Rappel de l’arbre de décision (1.4), affiné pour les skills :
| Besoin | Outil |
|---|---|
| Une capacité réutilisable, invoquée quand pertinente | Skill |
| Un simple raccourci vers un prompt figé | Commande (peut être fournie par une skill) |
| Une convention vraie pour presque toute tâche | CLAUDE.md |
| Un automatisme garanti à chaque événement | Hook |
| Une sous-tâche déléguée à contexte isolé | Subagent |
Une skill brille quand un workflow (une séquence d’étapes que tu répètes) mérite d’être encodé et rejoué fidèlement. « Générer une feature au bon gabarit » est un workflow → skill. « Ne pas utiliser any » est une convention → CLAUDE.md.
⚠️ Piège — Emballer en skill quelque chose qui n’est pas répétable, ou qui serait mieux en hook/CLAUDE.md. Une skill a un coût de maintenance : ne crée que celles qui capturent un vrai workflow récurrent. Une skill jamais déclenchée (mauvaise description) ou redondante (double d’une convention) est du bruit. Moins de skills, mieux cadrées.
Tester une skill
Une skill n’est bonne que si elle se déclenche et fait le bon travail. Test minimal :
- Déclenchement : formule une demande réelle et vérifie que la skill s’active (sinon, la description manque de déclencheurs).
- Résultat : vérifie que le livrable respecte tes conventions (sinon, resserre les instructions ou pointe le fichier-modèle).
🧭 Sur TaskFlow — En 9.5, on écrira
new-featurepour TaskFlow, avec une description riche en déclencheurs (« nouvelle feature », « ajoute une entité »), unSKILL.mdprescriptif (le triptyque queries/actions/schema + tests), et un template en ressource. On la testera : dit-on « ajoute une entité Projet » → la skill scaffolde-t-elle au bon gabarit ?
✏️ Exercices
Exercice 1 — Écris la description d’abord. Choisis un workflow que tu répètes. Écris uniquement sa description de skill (quoi + quand + déclencheurs), avec les phrases que tu dis vraiment. Fais-la relire : déclencherait-elle au bon moment ?
✅ Solution
Une bonne description contient les formulations réelles de tes prompts et le « quand ». Si tu n’arrives pas à lister les déclencheurs, c’est peut-être que le workflow n’est pas assez net pour une skill (ou relève d’une convention). La description est le test décisif : écris-la avant le corps.
Exercice 2 — Une skill, un job. Prends une idée de « grosse » skill et découpe-la en 2-3 skills focalisées et composables. Laquelle des deux approches serait plus maintenable ?
✅ Solution
Presque toujours, 2-3 skills focalisées (scaffold / générer tests / réviser) battent une méga-skill : chacune se déclenche précisément, se maintient seule, et se compose. La méga-skill se déclenche mal (description trop large) et devient un fourre-tout. Petit + composable gagne.
🧠 Quiz de révision
1. Quelle est la pièce la plus importante d’une skill, et pourquoi ?
La description : c’est elle qui décide de l’activation par le modèle. Elle doit dire quoi et quand, avec des déclencheurs repris de tes phrases réelles. Vague, elle ne matchera jamais.
2. Que signifie « petit, adaptable, composable » ?
Un job par skill, facile à ajuster à ton projet, et coopérant avec les autres. On préfère 2-3 skills focalisées composables à une méga-skill fourre-tout.
3. Où mettre le contenu lourd d’une skill ?
Dans des ressources (reference/, scripts/), chargées à la demande (progressive disclosure), pour garder le SKILL.md court et prescriptif.
4. Quand une skill est-elle le bon outil (vs CLAUDE.md/hook) ?
Quand un workflow répétable mérite d’être encodé et rejoué (« scaffolder une feature »). Une convention universelle va en CLAUDE.md ; un automatisme garanti en hook.
5. Comment teste-t-on une skill ?
Sur deux axes : déclenchement (une demande réelle l’active-t-elle ?) et résultat (le livrable respecte-t-il les conventions ?). Si elle ne se déclenche pas, la description manque de déclencheurs.
Chapitre suivant : Les skills à connaître — panorama des skills utiles, des tiennes aux incontournables communautaires.