Créer des Skills pour Claude Code : de l'architecture aux tests

1. Qu'est-ce qu'un Skill et pourquoi il s'agit d'un artefact logiciel à part entière

Un Skill (compétence) dans Claude Code est un paquet modulaire de connaissances standardisé, contenant une description du workflow, un ensemble de règles métier, des procédures ou des scripts exécutables que l'agent IA charge automatiquement pour résoudre une classe spécifique de tâches. Au lieu de copier manuellement de longues instructions dans chaque nouvelle session, l'agent reconnaît lui-même l'intention de l'utilisateur et active le Skill correspondant.

La principale différence entre un Skill et du code traditionnel réside dans le fait que la décision d'activation est prise par le modèle linguistique lui-même, sur la base d'une correspondance sémantique entre la description de la compétence et la requête de l'utilisateur. Cette décision est probabiliste : il n'y a pas de compilateur ni de typage strict, c'est donc la précision des métadonnées qui détermine directement si la compétence sera activée au bon moment.

Pourquoi un Skill est un artefact d'ingénierie et non un simple texte

1. Versionnement et modularité : Une compétence se compose de fichiers standards de dépôt, est stockée dans git et évolue selon les mêmes lois que le code applicatif.
2. Séparation interface/implémentation : Le champ description dans le frontmatter constitue l'interface publique de la compétence, tandis que le corps de SKILL.md et les scripts inclus en sont l'implémentation interne.
3. Composabilité : Une compétence peut appeler des outils externes via MCP, lancer des utilitaires console et déléguer des sous-tâches à d'autres compétences ou subagents.
4. Vulnérabilité aux régressions : Une modification maladroite de la description peut entraîner un « silence » (la compétence cesse de s'activer) ou des hallucinations lors de l'exécution des étapes.

2. Structure des fichiers et répertoires : SKILL.md, scripts et ressources de référence

Une compétence est un dossier structuré dans le système de fichiers, dont le noyau obligatoire est le fichier SKILL.md. Selon la complexité de la tâche, la compétence peut être complétée par des scripts auxiliaires, des guides de référence et des templates.

Architecture de la compétence : interface, implémentation, ressources incluses et outils externes ЗбільшитиArchitecture de la compétence : interface, implémentation, ressources incluses et outils externes

Niveaux de stockage des Skills dans Claude Code

• Skills globaux (~/.claude/skills/) : Disponibles pour le développeur dans tous les projets de la machine actuelle. Idéal pour les utilitaires personnels, les templates de commit personnalisés ou les scripts analytiques.
• Skills projet (.claude/skills/) : Stockés directement dans le dépôt du projet et commités dans git. Disponibles pour tous les membres de l'équipe, garantissant des standards uniques d'architecture et de test.

Structure recommandée pour une compétence complexe

Une compétence minimale peut ne consister qu'en un seul fichier SKILL.md. Les systèmes plus importants regroupent dans le dossier de la compétence leurs propres scripts d'automatisation et leur documentation, permettant ainsi de maintenir une logique compacte et autonome.

3. Règles de rédaction du Frontmatter : name et description

Le fichier SKILL.md commence obligatoirement par un bloc de métadonnées au format YAML Frontmatter. C'est la seule partie de la compétence que Claude lit lors de l'initialisation de la session pour construire le catalogue des actions disponibles.

Contraintes formelles sur le nom (name)

• Longueur maximale de 64 caractères.
• Seuls les lettres minuscules latines, les chiffres et les tirets ([a-z0-9-]) sont autorisés.
• L'utilisation de balises XML/HTML est interdite.
• Il est interdit d'utiliser des noms réservés par l'entreprise (claude, anthropic).

Contraintes formelles sur la description (description)

• Champ obligatoire non vide.
• Longueur maximale de 1024 caractères.
• L'utilisation de balises XML est interdite.
• Doit décrire clairement à la fois la fonctionnalité de la compétence et les déclencheurs contextuels pour son activation.

4. Chargement progressif (Progressive Disclosure) et fenêtre de contexte

Les Skills ne sont pas entièrement chargés dans la fenêtre de contexte du modèle au démarrage de la session. Claude Code utilise le principe du chargement progressif (Progressive Disclosure), divisé en trois niveaux distincts.

Pipeline linéaire de traitement de la requête par le modèle et fenêtre de contexte ЗбільшитиPipeline linéaire de traitement de la requête par le modèle et fenêtre de contexte

Les trois niveaux de chargement

1. Niveau 1 — Métadonnées (Metadata) : Les noms et descriptions de toutes les compétences disponibles sont chargés dans le contexte système au début de la session. Le coût est d'environ 100 tokens par compétence. Cela permet d'ajouter des dizaines de compétences au projet sans risque d'épuiser la limite de contexte.
2. Niveau 2 — Corps du fichier (Body) : Lorsque le modèle décide que la requête utilisateur correspond à la description de la compétence, il lit le contenu de SKILL.md. La taille recommandée du corps est de moins de 500 lignes, afin de ne pas évincer l'historique de travail de la conversation.
3. Niveau 3 — Fichiers inclus et scripts (Resources) : Les fichiers de référence (references/) ne sont lus que lorsque l'instruction y fait directement référence. Les scripts sont généralement exécutés via l'interpréteur bash : leur code n'entre jamais dans la fenêtre de contexte, seul le résultat final de l'exécution est retourné.

5. Formulation de la description : créer des déclencheurs d'activation fiables

Puisque description est le principal déclencheur probabiliste, sa formulation mérite une attention particulière.

Règles pour une description efficace

• Troisième personne uniquement : Rédigez la description à la troisième personne (Generates, Performs, Audits). Le modèle perçoit la description comme une spécification système de l'outil ; les pronoms de première ou deuxième personne (I will, You can) dégradent la qualité de la correspondance.
• Formule « Quoi + Quand » : La description doit répondre clairement à deux questions : ce que fait exactement la compétence et dans quelles situations elle doit être appliquée.
• Mots-clés réels : Incluez des termes techniques spécifiques, des noms de fichiers ou de commandes que l'utilisateur mentionnera probablement dans sa requête.

6. Anatomie d'un Skill exemplaire : analyse étape par étape du pipeline release-notes

Examinons l'architecture pratique d'une compétence d'automatisation de documentation de release nommée release-notes.

Pipeline d'exécution étape par étape de la compétence release-notes avec arguments et ressources ЗбільшитиPipeline d'exécution étape par étape de la compétence release-notes avec arguments et ressources

Composantes du workflow

• Paramètres d'entrée : Arguments utilisateur (plage de tags v1.2.0..v1.3.0), guide de style de référence changelog-style.md, script auxiliaire gather-prs.py.
• Séquence étape par étape dans SKILL.md :
  1. Identifier la plage de tags de release dans git.
  2. Lancer le script python scripts/gather-prs.py pour obtenir une liste structurée des commits.
  3. Regrouper les changements par catégories (Features, Fixes, Performance, Breaking Changes).
  4. Préparer le brouillon conformément au style défini dans changelog-style.md.
  5. Écrire le bloc mis à jour dans CHANGELOG.md et afficher un résumé court.
• Artefacts de sortie : Fichier CHANGELOG.md mis à jour et message concis pour l'équipe.

Règles architecturales pour le corps du fichier

1. Ne répétez pas les évidences : Considérez que Claude est déjà un ingénieur qualifié. Décrivez uniquement les spécificités de votre projet et les exigences corporatives strictes.
2. Profondeur de référence limitée à un niveau : Les fichiers de référence ne doivent pas chaîner vers d'autres fichiers. Tous les matériaux doivent être directement liés à SKILL.md.
3. Chemins cross-platform : Utilisez toujours des slashes avant (/) dans tous les chemins vers les fichiers et configurations.

7. Panorama des mécanismes de personnalisation : Skills, CLAUDE.md, Slash-commands, MCP, hooks et plugins

Dans Claude Code, plusieurs outils permettent de contrôler le comportement de l'agent. Un choix erroné du mécanisme est la cause la plus fréquente d'instabilité du système.

Matrice des mécanismes de personnalisation de Claude Code : qui initie l'exécution vs force d'influence ЗбільшитиMatrice des mécanismes de personnalisation de Claude Code : qui initie l'exécution vs force d'influence

8. Skills contre Hooks : équilibre entre recommandations et garanties runtime

Les débutants tentent souvent d'utiliser les Skills pour des tâches de sécurité ou de formatage de code forcé. C'est une erreur conceptuelle : une compétence ne garantit pas l'exécution, elle enseigne simplement au modèle la bonne approche.

Cycle de vie de l'exécution d'une session Claude Code et points d'intégration des hooks et skills ЗбільшитиCycle de vie de l'exécution d'une session Claude Code et points d'intégration des hooks et skills

Points du cycle de vie d'exécution

• SessionStart (Hook) : Se déclenche à l'ouverture de la session. Garantit l'initialisation des variables d'environnement ou la vérification préalable de la branche git.
• Raisonnement du modèle (Lecture potentielle du Skill) : Le modèle analyse la tâche et prend la décision de charger le corps de SKILL.md.
• PreToolUse (Hook, bloquant) : S'exécute juste avant l'appel de tout outil. Peut vérifier une commande bash et bloquer son exécution (code retour 2) si elle viole les règles de sécurité.
• PostToolUse (Hook) : Analyse le résultat de l'exécution d'une commande ou la modification d'un fichier (par exemple, lance automatiquement Prettier après écriture d'un fichier).
• Stop (Hook) : Se déclenche après la fin de la génération de la réponse par le modèle.

9. Processus de développement piloté par l'évaluation (Evaluation-Driven Development)

Créer une compétence fiable nécessite des tests itératifs sur des scénarios réels avant même de rédiger le texte final des instructions.

Les quatre étapes de création d'une compétence

1. Établir la baseline : Lancez Claude Code sur des tâches types sans compétence. Notez précisément où le modèle se trompe, manque des étapes ou demande des clarifications supplémentaires.
2. Créer la suite de tests (Eval Suite) : Transformez les erreurs notées en une liste de tâches de contrôle avec des résultats attendus clairement définis.
3. Rédiger le MVP : Formulez un ensemble minimal d'instructions dans SKILL.md, suffisant pour réussir les tests.
4. Affinage itératif : Ajoutez des règles et exceptions uniquement en réponse à des échecs spécifiques des cas de test, en évitant de gonfler le contexte.

Workflow avec deux instances du modèle

Lors de la conception d'une compétence, il est recommandé d'utiliser deux terminaux parallèles :

• Instance éditeur : Session où vous collaborez avec Claude pour formuler, compléter et structurer le texte de la nouvelle compétence.
• Instance testeur : Session propre où vous lancez les requêtes de test et vérifiez : si la compétence est captée automatiquement, si les étapes sont correctement interprétées et si les fichiers résultants sont valides.

10. Patterns de conception courants et antipatterns lors de la création de Skills

L'expérience communautaire a identifié plusieurs templates éprouvés et erreurs typiques à éviter.

Patterns d'ingénierie efficaces

• Séquences numérotées déterministes : Pour les actions multi-étapes complexes, structurez toujours les étapes sous forme 1. ..., 2. ..., 3. ....
• Checklists de validation intégrées : Pour les opérations critiques, ajoutez une checklist que le modèle doit copier dans sa réponse et cocher au fur et à mesure de l'exécution.
• Boucles d'auto-vérification (Verify & Fix) : Définissez la règle : « Lancer le linter -> corriger les erreurs -> revérifier jusqu'à un output propre ».
• Planification avant actions destructives : Pour les suppressions en masse ou réécritures de fichiers, exigez d'abord de générer un plan de modifications dans un tableau markdown et de demander confirmation.

Antipatterns courants

• Paralysie du choix : Description d'un nombre excessif de bibliothèques ou approches alternatives sans indiquer l'option par défaut.
• Dépendances système non déclarées : Utilisation d'utilitaires CLI tiers ou de paquets npm sans instruction préalable sur leur installation ou vérification de présence.
• Backslashes dans les chemins : Utilisation de backslashes style Windows (src\utils\), causant des pannes sur Linux et macOS.
• Nombres magiques non expliqués : Utilisation de constantes ou timeouts sans commentaire sur leur nature.

11. Sécurité et audit des Skills tiers avant installation

Toute compétence tierce est du code exécutable dans votre environnement de travail. Puisque Claude Code a accès au système de fichiers, au terminal et au réseau, un Skill non vérifié présente des risques de sécurité sérieux.

Checklist d'audit d'une compétence tierce avant usage

• Analyse du corps de SKILL.md : Vérifiez le texte pour détecter d'éventuelles instructions cachées de prompt injection, tentatives de vol de fichiers .env ou désactivation de mécanismes de protection.
• Audit des scripts inclus : Étudiez attentivement tous les fichiers dans le dossier scripts/. Assurez-vous que les scripts n'effectuent pas de requêtes réseau suspectes vers des serveurs tiers.
• Vérification des URLs externes : Prêtez attention à tout lien téléchargeant des binaires externes ou des configurations dynamiques.
• Test isolé : Le premier lancement d'une compétence tierce doit toujours se faire dans un dépôt de test ou un sandbox sans accès aux secrets de production.