Create Skill — Créateur de skills Claude Code

Guide la création de skills de qualité pour Claude Code — de l'idée au fichier prêt à l'emploi.

Anatomie d'une skill

skills/
└── ma-skill/
    └── SKILL.md          # Requis — frontmatter YAML + instructions
    └── reference/        # Optionnel — guides, exemples, données

Format SKILL.md

---

name: ma-skill description: "Quand et pourquoi cette skill se charge — inclure les déclencheurs, contextes et mots-clés pour que Claude sache quand l'activer automatiquement."

Titre — Sous-titre court

Phrase d'introduction : ce que fait la skill et pourquoi elle existe.

Sections d'instructions

Instructions que Claude suivra quand la skill est active.

Règles du frontmatter

Champ	Format	Obligatoire
name	kebab-case, lowercase	Oui
description	Guillemets doubles, une phrase dense	Oui

Scope — Où créer la skill

Scope	Chemin	Quand
Plugin codebloom	skills/<name>/SKILL.md (racine codebloom)	Skill distribuée avec le plugin
Projet	skills/<name>/SKILL.md (racine du projet courant)	Skill spécifique à ce projet
Global	~/.claude/skills/<name>/SKILL.md	Skill active sur tous les projets

Par défaut, proposer le scope projet. Demander si l'utilisateur veut un autre scope.

Process

1. Interview — Comprendre le besoin

Poser ces 4 questions (adapter selon le contexte, ne pas poser celles dont la réponse est évidente) :

1. Quoi — Que doit faire la skill ? Quel comportement Claude doit-il adopter ?
2. Quand — Dans quels contextes doit-elle se déclencher ? (actions utilisateur, types de fichiers, patterns de code, phrases-clés)
3. Format — Quel est le résultat attendu ? (texte, modifications de fichiers, checklist, rapport)
4. Scope — Projet, global, ou plugin codebloom ?

Creuser les cas limites :

• Quand la skill ne doit PAS se déclencher (faux positifs)
• Interactions avec d'autres skills existantes (complémentarité, chevauchement)
• Niveau d'intervention : bloquant (impose) ou consultatif (signale et guide)

Ne pas avancer tant que le besoin n'est pas clair. Un besoin flou produit une skill inutile.

2. Recherche — Vérifier le contexte

Avant d'écrire :

• Lister les skills existantes dans le scope cible (éviter les doublons)
• Vérifier les conventions du projet (CLAUDE.md, DESIGN_SYSTEM.md)
• Identifier si une skill existante pourrait être étendue plutôt qu'une nouvelle créée

Si une skill existante couvre 80%+ du besoin, proposer de l'enrichir au lieu d'en créer une nouvelle.

3. Rédaction — Écrire la skill

La description (frontmatter) — C'est le déclencheur

La description est ce que Claude lit pour décider s'il charge la skill. C'est le champ le plus critique.

Structure efficace :

"[Rôle] qui se charge quand [liste de déclencheurs concrets]. [Capacités clés]. Ne se charge PAS quand [exclusions]."

Principes :

• Toujours écrire en 3e personne — la description est injectée dans le system prompt. "Se charge quand..." et non "Activer quand..."
• TRIGGER CONDITIONS ONLY — la description doit dire quand charger la skill, jamais comment elle fonctionne. Si la description résume le workflow, Claude risque de suivre la description au lieu de lire le contenu complet. Mauvais : "Review en 2 passes avec scoring". Bon : "Se charge quand du code est modifié pour review qualité et sécurité."
• Décrire les contextes concrets, pas des abstractions ("quand Claude modifie du HTML/JSX" > "quand du code UI est impliqué")
• Inclure les variantes de formulation ("créer", "ajouter", "générer", "build", "make")
• Lister les exclusions explicites pour éviter les faux positifs
• Préférer le sur-déclenchement — une description légèrement "pushy" vaut mieux qu'une skill qui ne se charge jamais. En cas de doute, élargir les contextes plutôt que les restreindre
• Max 1024 caractères — pas de balises XML dans la description

Le corps — Ce sont les instructions

Règles d'écriture :

1. Impératif — "Vérifie que..." pas "Il faudrait vérifier que..."
2. Expliquer le pourquoi — Chaque règle importante explique son raisonnement. "Ne pas imbriquer plus de 3 niveaux — au-delà, la complexité cognitive explose" > "Ne JAMAIS imbriquer plus de 3 niveaux". ⚠️ Si la skill accumule les MAJUSCULES, "JAMAIS", "TOUJOURS" — c'est un signal de reformulation. Remplacer l'absolutisme par le raisonnement
3. Concret — Exemples de code, tableaux, templates. Pas de principes abstraits sans illustration
4. Progressif — Les informations essentielles d'abord, les détails ensuite. Claude charge d'abord le frontmatter (~100 mots), puis le corps si pertinent
5. Autonome — La skill doit fonctionner sans contexte externe. Si elle dépend d'un fichier, le mentionner explicitement

Structure recommandée :

Titre — Sous-titre

Phrase d'intro (quoi + pourquoi).

Activation (optionnel — si les conditions sont complexes)

• Contextes de déclenchement
• Contextes d'exclusion

Principes / Règles

Les comportements attendus, organisés par thème.

Process (si la skill est procédurale)

Étapes numérotées.

Anti-patterns (optionnel)

Ce qu'il ne faut PAS faire, avec le pourquoi.

Taille : Viser < 500 lignes. Au-delà, extraire les détails dans un dossier reference/ (progressive disclosure — un seul niveau de profondeur depuis SKILL.md). Claude charge le SKILL.md entier — un fichier trop long dilue les instructions critiques.

Skill garde-fou vs. skill procédurale

Type	Comportement	Exemples
Garde-fou	Se charge en fond, signale et guide sans bloquer	code-quality, security, ui-design
Procédurale	Suit un process étape par étape quand invoquée	discovery, wp-pack

Un garde-fou ne doit jamais bloquer le travail — il alerte, propose des alternatives, et laisse l'utilisateur décider. Une skill procédurale peut imposer un ordre d'étapes.

4. Test mental — Vérifier le déclenchement

Avant d'écrire le fichier, rédiger :

• 2-3 prompts qui DOIVENT déclencher la skill (cas d'usage typiques)
• 2-3 prompts qui NE DOIVENT PAS déclencher (faux positifs probables)

Relire la description avec ces prompts en tête. Si un cas légitime ne déclencherait pas, élargir. Si un faux positif déclencherait, ajouter une exclusion.

Si les cas de test révèlent un travail répétitif commun (ex: les 3 prompts mènent au même type de fichier généré), c'est un signal fort : bundler ce pattern dans la skill comme template ou reference.

Pressure testing (pour les skills de discipline)

Les tests simples ne suffisent pas pour les skills qui imposent un comportement (qualité, sécurité, TDD). Tester avec 3+ pressions simultanées :

• Temps : "Il est 18h, deadline demain matin"
• Coût : "Bug en prod, $500/min de downtime"
• Sunk cost : "J'ai déjà 2h de travail dessus"
• Autorité : "Le tech lead dit de juste patcher"
• Fatigue : "C'est le 5e fix de la journée"

Si la skill résiste sous 3 pressions combinées, elle est solide. Si l'agent rationalise pour la contourner, renforcer avec une table d'anti-rationalisation :

Excuse verbatim	Contre-argument
"Trop simple pour ce process"	Les erreurs les plus coûteuses viennent du code "simple"
"Juste cette fois"	Chaque exception crée un précédent
"Je connais déjà cette skill"	Relire — la version en mémoire peut être incomplète

5. Création — Écrire le fichier

1. Créer le dossier skills/<name>/
2. Écrire SKILL.md avec frontmatter + corps
3. Si la skill a des ressources (guides, exemples), les placer dans reference/

6. Vérification — Valider la skill

Checklist avant de confirmer :

• name en kebab-case, unique parmi les skills existantes
• description contient des déclencheurs concrets ET des exclusions
• Le corps est < 500 lignes (ou les détails sont dans reference/)
• Les cas de test (étape 4) valident le déclenchement et les exclusions
• Chaque règle importante explique son pourquoi
• Pas de chevauchement majeur avec une skill existante
• Le scope est correct (projet / global / plugin)
• La skill ne bloque pas le travail (garde-fou) ou a un process clair (procédurale)

7. Documentation — Mettre à jour les références

Selon le scope :

• Plugin codebloom : Mettre à jour CLAUDE.md (tableau Skills) et README.md
• Projet : Mentionner dans le CLAUDE.md du projet
• Global : Informer l'utilisateur que la skill est active sur tous ses projets

Exemples de bonnes descriptions

Trop vague — se déclenche partout

description: "Aide avec le code"

Trop restrictive — ne se déclenche jamais

description: "Se charge uniquement quand l'utilisateur tape exactement /check-types"

Juste — 3e personne, contextes concrets + exclusions

description: "Garde-fou TypeScript strict qui se charge quand Claude écrit ou modifie du TypeScript : types any, assertions non-null, enums, interfaces. Couvre l'inférence, les generics, les utility types et les discriminated unions. Ne se charge pas pour du JavaScript pur ou du code non-TypeScript."

Règles

• Ne pas deviner — Si le besoin est flou, poser des questions. Mieux vaut 2 minutes d'interview que 10 minutes de réécriture.
• Une skill = une responsabilité — Si la skill fait deux choses distinctes, c'est deux skills.
• Enrichir > Créer — Vérifier si une skill existante peut absorber le besoin avant d'en créer une nouvelle.
• La description fait le travail — 80% de l'efficacité d'une skill dépend de sa description. Investir le temps là-dessus.