Chapitre 9.1 — Anatomie d’une skill

⏱️ TL;DR — Une skill est un dossier contenant un SKILL.md : un front-matter (nom + description) et des instructions en Markdown, plus, éventuellement, des ressources (fichiers de référence, scripts) chargées seulement si besoin. Sa propriété clé est le progressive disclosure : seule la description est connue en permanence ; le contenu n’entre dans le contexte que lorsque la skill est jugée pertinente. D’où : coût quasi nul au repos, puissance à la demande. Une skill s’invoque par le modèle (quand ça matche) ou par toi (/nom).

🎯 Objectifs

Décrire la structure d’une skill (SKILL.md, ressources).
Comprendre le progressive disclosure et pourquoi il rend les skills « gratuites » au repos.
Distinguer invocation par le modèle vs par l’utilisateur.
Situer la skill parmi les briques (rappel 1.4).

La structure

Une skill, c’est un dossier (dans ~/.claude/skills/<nom>/ ou .claude/skills/<nom>/) avec au minimum un SKILL.md :


---
name: mon-skill
description: Ce que fait la skill et QUAND l'utiliser — sert à décider si elle est pertinente.
---
 
# Instructions
 
Les étapes/règles que l'agent suit quand cette skill est active.
Peut référencer des ressources : voir reference/DETAILS.md pour les cas avancés.

Éventuellement, à côté du SKILL.md, des ressources :


mon-skill/
├── SKILL.md
├── reference/
│   └── DETAILS.md        ← chargé seulement si la skill en a besoin
└── scripts/
    └── helper.mjs        ← exécutable appelé par la skill

Ta config réelle illustre les deux : caveman = un SKILL.md seul ; diagnose embarque un script (hitl-loop.template.sh) ; prototype embarque des références (LOGIC.md, UI.md). Une skill peut être minimale ou riche.

Le progressive disclosure : le cœur du système

C’est la propriété qui rend les skills si utiles. Le mécanisme, en trois niveaux :

Niveau 1 : seule la description est en permanence dans le contexte. C’est pour ça que tu peux avoir 10, 30, 100 skills installées sans saturer : au repos, elles ne coûtent qu’une ligne chacune.
Niveau 2 : quand ta demande matche la description (ou que tu invoques la skill), son corps entre dans le contexte.
Niveau 3 : les ressources lourdes ne se chargent que si la skill les référence au moment voulu.

C’est l’inverse du CLAUDE.md (toujours tout chargé, 3.1). D’où la règle de répartition (1.4) : universel et permanent → CLAUDE.md ; capacité ponctuelle et spécialisée → skill.

💡 Réflexe d’architecte — La description d’une skill est sa pièce la plus importante : c’est elle qui décide si la skill se déclenche. Une description vague (« aide pour le code ») ne matchera jamais au bon moment ; une description précise avec les déclencheurs (« Utiliser quand… ») s’active pile quand il faut. On y revient en 9.2 — retiens que la description est l’interface de la skill.

Invocation : par le modèle ou par toi

Une skill peut se déclencher de deux façons :

Par le modèle : quand ta demande correspond à la description, l’agent charge et applique la skill de lui-même (ex. tu décris un graphe → dataviz s’active).
Par toi : tu tapes /nom-de-skill pour la déclencher explicitement (ex. /caveman, /handoff).

Certaines skills sont réglées pour n’être **qu’**invoquées par l’utilisateur (disable-model-invocation), quand on veut garder le contrôle du déclenchement (c’est le cas de setup-matt-pocock-skills et zoom-out dans ta config).

⚠️ Piège — Confondre skill et commande (rappel du glossaire, CONTEXT.md). Une commande /nom est un raccourci ; une skill est une capacité (souvent invocable via une commande /nom, mais qui peut aussi s’activer toute seule et embarquer des ressources/scripts). Toute commande n’est pas une skill ; toute skill n’est pas qu’une commande.

Où vivent les skills

Utilisateur (~/.claude/skills/) : tes skills perso, disponibles sur tous tes projets.
Projet (.claude/skills/) : des skills spécifiques au repo, versionnées, partagées avec l’équipe.
Via un plugin : une skill peut être distribuée dans un plugin installé depuis une marketplace (9.4).

🧭 Sur TaskFlow — En 9.5, on écrira une skill de projet pour TaskFlow (versionnée dans .claude/skills/), qui encode un workflow répétitif propre à TaskFlow. Tout contributeur du repo — toi, un agent, un collègue — en héritera. La skill devient une convention exécutable, pas juste écrite.

✏️ Exercices

Exercice 1 — Dissèque tes skills. Ouvre 3 de tes skills installées (~/.claude/skills/). Repère pour chacune : la description (le déclencheur), le corps, et d’éventuelles ressources. Laquelle a la description la plus précise ?

✅ Solution

Tu verras que les bonnes skills ont une description qui dit quoi et quand (« Use when… »), et que certaines embarquent des ressources (scripts, références) chargées à la demande. La précision de la description prédit la qualité du déclenchement — une leçon directe pour écrire les tiennes (9.2).

Exercice 2 — Permanent ou à la demande ? Prends 4 « choses que tu veux que l’agent sache/sache faire ». Classe : CLAUDE.md (permanent) vs skill (à la demande). Sur quel critère tranches-tu ?

✅ Solution

Critère : s’applique-t-il à presque toute tâche (→ CLAUDE.md, permanent) ou seulement dans un cas précis (→ skill, à la demande) ? « Réponds en français » = permanent. « Génère un rapport de perf formaté » = ponctuel = skill. Le progressive disclosure fait qu’une skill ne coûte rien tant qu’on ne l’utilise pas.

🧠 Quiz de révision

1. Que contient au minimum une skill ?

Un dossier avec un SKILL.md : un front-matter (nom + description) et des instructions en Markdown. Éventuellement des ressources (références, scripts) à côté.

2. Qu’est-ce que le progressive disclosure ?

Un chargement en niveaux : seule la description est toujours en contexte (coût minuscule) ; le corps ne se charge que si la skill est pertinente ; les ressources, que si elle les demande. D’où « gratuit au repos, puissant à la demande ».

3. Pourquoi peut-on avoir beaucoup de skills sans saturer le contexte ?

Parce qu’au repos, chacune ne coûte qu’une ligne (sa description). Le contenu n’entre en contexte que lorsqu’elle s’active. C’est l’inverse du CLAUDE.md, toujours tout chargé.

4. Quelles sont les deux façons d’invoquer une skill ?

Par le modèle (quand la demande matche la description) et par toi (/nom). Certaines sont réglées pour n’être qu’invoquées manuellement (disable-model-invocation).

5. Skill ou CLAUDE.md pour une capacité ponctuelle et spécialisée ?

Skill (chargée à la demande). Le CLAUDE.md est réservé à l’universel et permanent ; mettre du ponctuel dedans le fait grossir inutilement.

Chapitre suivant : Écrire une skill — en créer une bonne, prévisible et réutilisable.