Modèles Claude Code Skills : le guide complet

Symptôme : Claude Code modifie trop de fichiers, saute les tests ou rédige une documentation qui ne correspond pas au comportement réel du projet.

Solution la plus rapide : créez des modèles Claude Code Skills courts, chacun consacré à un seul processus vérifiable, avec un périmètre, des entrées, des conditions d’arrêt et une preuve d’acceptation clairement définis.

À qui s’adresse ce guide ?

Ce guide s’adresse aux développeurs qui souhaitent constituer rapidement une bibliothèque personnelle de Skills réutilisables, aux responsables techniques qui veulent harmoniser les pratiques d’une équipe et aux plateformes qui confient des tests, des contrôles de publication ou de la documentation à un agent distant.

Si vous cherchez encore à installer Claude Code ou à comprendre son fonctionnement général, commencez par le centre d’aide Macstripe, puis revenez ici pour structurer vos processus.

Point de contrôle : un modèle n’est pas une garantie officielle de résultat. Il constitue un point de départ éditorial. Le comportement réel doit être vérifié dans le dépôt, avec les outils et les droits effectivement disponibles.

Commencez par une architecture de Skills limitée

Les meilleurs modèles Claude Code Skills ne sont pas les plus longs. Ils sont suffisamment précis pour répondre à une situation, mais assez courts pour que l’agent distingue les instructions importantes des détails secondaires.

La structure Agent Skills impose au minimum un dossier contenant un fichier SKILL.md, avec un en-tête YAML comprenant notamment name et description. Le champ name est limité à 64 caractères, tandis que description peut atteindre 1 024 caractères et doit expliquer à la fois la fonction du Skill et les situations qui doivent le déclencher. Ces contraintes sont précisées dans la spécification officielle du format Agent Skills.

Le corps du fichier doit ensuite répondre à cinq questions :

Quelles demandes activent le Skill ?
Quelles entrées sont obligatoires ?
Quelles étapes l’agent doit-il suivre ?
Dans quelles situations doit-il s’arrêter ?
Quel résultat permet à un humain de déclarer la tâche acceptée ?

La spécification recommande de conserver le fichier principal sous 500 lignes et sous 5 000 tokens, puis de déplacer les références détaillées, scripts et modèles dans des dossiers séparés. Cette organisation repose sur la divulgation progressive : le nom et la description sont découverts d’abord, puis les instructions complètes seulement lorsque le Skill est activé. Consultez les bonnes pratiques de conception des Skills pour éviter de remplir chaque fichier avec des explications que l’agent connaît déjà.

Le squelette commun à réutiliser

Vous pouvez partir de cette ossature courte, sans la transformer en consigne universelle :

---
name: nom-du-skill
description: Décrit la tâche et les demandes qui doivent activer ce Skill.
---

## Périmètre

- Fichiers autorisés :
- Fichiers exclus :
- Outils autorisés :

## Entrées obligatoires

- Diff, ticket ou spécification :
- Commandes de validation :
- Contraintes particulières :

## Procédure

1. Vérifier les entrées.
2. Établir l’état initial.
3. Exécuter les étapes dans l’ordre.
4. Produire les preuves demandées.

## Arrêt immédiat

- Une entrée obligatoire manque.
- Une modification sort du périmètre.
- Un test non lié échoue.
- Une permission nécessaire n’est pas accordée.

## Acceptation

- Résultat attendu :
- Commandes exécutées :
- Fichiers modifiés :
- Limites restantes :

L’intérêt de ce squelette n’est pas de dicter chaque décision technique. Il empêche surtout l’agent de commencer une tâche dont les conditions de réussite ne sont pas définies.

Première série : les Skills de développement et de correction

Développement d’une fonctionnalité

Un Skill de développement doit refuser le mode « construisez quelque chose de cohérent » lorsqu’aucun critère d’acceptation n’est fourni. Il commence par reformuler la demande, rechercher les interfaces concernées et proposer un plan limité aux fichiers nécessaires.

Le modèle doit imposer les étapes suivantes :

Lire la spécification, le ticket ou la demande utilisateur.
Lister les critères d’acceptation observables.
Identifier les fichiers candidats et les fichiers explicitement exclus.
Proposer un plan avant toute modification.
Implémenter la plus petite modification compatible.
Exécuter les tests et contrôles associés.
Résumer les fichiers modifiés et les points non vérifiés.

Si la demande ne contient aucun comportement attendu, le Skill doit s’arrêter et poser une question. Cette règle est plus importante qu’un paragraphe supplémentaire sur les conventions de code, car elle réduit le risque de faire passer une interprétation de l’agent pour une décision produit.

Avantages :

bon contrôle de la surface de modification ;
plan lisible avant l’édition ;
résultat plus facile à relire dans une demande de fusion.

Limites :

moins adapté aux prototypes exploratoires ;
nécessite des critères de réussite suffisamment concrets ;
peut interrompre fréquemment les demandes volontairement ouvertes.

Correction d’un test ou d’un défaut

Un Skill de correction doit séparer le symptôme, la cause supposée et la preuve. Il ne doit jamais partir directement d’un correctif imaginé à partir du nom d’un test.

Le processus conseillé est le suivant :

Reproduire l’échec avec la commande exacte.
Enregistrer le message d’erreur, la trace et le contexte d’exécution.
Vérifier si l’échec est déterministe ou intermittent.
Localiser la cause la plus proche du comportement incorrect.
Appliquer le correctif minimal.
Rejouer le test initial.
Lancer les tests de régression pertinents.
Signaler séparément les échecs préexistants ou non liés.

Le fichier doit interdire explicitement la suppression d’un test, la réduction d’une assertion, l’augmentation artificielle d’un délai ou la modification d’un seuil uniquement pour obtenir un succès. Une réussite fabriquée est plus dangereuse qu’un test rouge, puisqu’elle masque une régression derrière un résultat apparemment rassurant.

Deuxième série : contrôler la revue et la sécurité

Construire un Skill de revue de code

Pour écrire un bon Skill de revue de code, commencez par définir son entrée : diff Git, fichiers modifiés, description du changement et résultats de tests disponibles. Sans ces éléments, le Skill doit produire un rapport d’insuffisance plutôt qu’une revue inventée.

Le rapport peut être organisé par niveaux :

Bloquant : risque de perte de données, faille exploitable, rupture d’interface ou échec reproductible.
Important : défaut probable, comportement non couvert ou dépendance mal maîtrisée.
À vérifier : hypothèse nécessitant une reproduction ou une information supplémentaire.
Suggestion : amélioration de lisibilité ou de maintenance sans impact démontré.

Chaque remarque doit indiquer le fichier, la zone concernée, le risque, l’élément de preuve et l’action recommandée. Le Skill doit aussi distinguer une observation confirmée par un outil statique d’une suspicion issue de la lecture du code. Cette distinction évite de présenter une possibilité théorique comme une vulnérabilité avérée.

Le guide officiel consacré à l’optimisation des descriptions rappelle que la description est le principal mécanisme de déclenchement. Pour un Skill de revue, utilisez donc des déclencheurs précis comme « examiner un diff », « chercher une régression dans les fichiers modifiés » ou « contrôler les risques d’une demande de fusion », plutôt qu’une formule vague telle que « améliorer le code ».

Dans Claude Code, les modifications de fichiers, l’exécution de tests et les commandes supplémentaires peuvent nécessiter une autorisation explicite. Les règles de sécurité officielles doivent donc être prises en compte dans le champ de périmètre et dans les conditions d’arrêt du Skill.

Troisième série : refactoriser sans laisser l’agent réécrire le projet

Un Skill de refactorisation contrôlée doit être plus strict qu’un Skill de développement. Son objectif est de préserver le comportement, pas de profiter d’une modification locale pour réorganiser toute l’architecture.

Avant le premier changement, demandez à l’agent de constituer une base de comportement :

tests existants exécutés ;
commandes de compilation ou de typage ;
interfaces publiques observées ;
fichiers inclus dans le périmètre ;
résultats de référence conservés dans le rapport.

Ensuite, imposez des lots courts. Après chaque lot, l’agent doit relancer les contrôles pertinents et montrer le diff. Le Skill doit s’arrêter dans les cas suivants :

une API publique change sans décision humaine ;
un fichier hors périmètre devient nécessaire ;
un test non lié échoue ;
la modification demande une migration de données non prévue ;
l’agent propose une nouvelle architecture pour résoudre un problème local.

La documentation sur les scripts intégrés aux Skills montre comment déplacer une validation répétitive dans scripts/, avec des chemins relatifs au dossier du Skill. Vous pouvez ainsi ajouter un script de contrôle du périmètre, à condition de documenter ses dépendances et ses messages d’erreur.

Expérience de terrain : si le Skill contient à la fois « simplifier ce module », « moderniser les dépendances » et « améliorer l’architecture », il possède déjà trois périmètres concurrents. Séparez-les avant de lancer l’agent.

Quatrième série : transformer les différences réelles en documentation

Un Skill de documentation utile ne rédige pas une présentation générale du projet. Il part des différences effectivement produites : fichiers modifiés, interfaces ajoutées, commandes exécutées et tests réussis.

Pour une note de version ou une documentation technique, demandez au Skill de :

lire le diff final plutôt que le ticket initial uniquement ;
identifier les changements d’interface et de comportement ;
vérifier les exemples contre le code réellement exécuté ;
mentionner les limites et migrations nécessaires ;
relier chaque affirmation importante à un fichier ou à un test ;
séparer les éléments vérifiés des éléments encore à confirmer.

Il doit refuser d’écrire qu’une fonctionnalité est disponible lorsque le code n’a pas été exécuté ou lorsque son chemin principal n’est pas couvert par une validation. C’est particulièrement important pour les projets audio, vidéo et design : une interface peut sembler complète dans le code alors qu’un format, un codec ou une interaction avec un logiciel créatif n’a pas été testé.

Pour les ressources plus longues, utilisez references/ plutôt que d’allonger systématiquement SKILL.md. La structure officielle prévoit précisément des fichiers de référence chargés à la demande, ce qui évite de consommer le contexte de l’agent pour des informations inutiles à chaque exécution.

Cinquième série : publication et livraison sous contrôle humain

Le Skill de publication doit regrouper les vérifications mécaniques sans transformer la mise en production en action entièrement automatique. Un modèle fiable distingue les opérations préparatoires des décisions qui exigent une confirmation humaine.

Peuvent généralement être automatisés, selon vos droits :

vérifier l’état du dépôt ;
contrôler la version déclarée ;
construire le projet ;
exécuter les tests convenus ;
générer une synthèse des changements ;
préparer les artefacts ou notes de version.

Doivent rester manuellement déclenchés :

publication d’un paquet ;
déploiement en production ;
migration irréversible ;
modification des secrets ou permissions ;
validation finale d’une rupture d’interface.

Le référentiel de commandes Claude Code peut vous aider à documenter précisément les commandes acceptées, les modes non interactifs et les limites de chaque environnement. La commande utilisée dans un terminal local ne doit pas être copiée telle quelle dans un agent distant sans vérifier les droits, les variables disponibles et la présence des dépendances.

Choisissez le bon modèle avec des conditions de décision

Utilisez les branches suivantes pour éviter de créer un Skill trop général :

Si la tâche modifie moins de quelques zones connues et possède des critères d’acceptation écrits, choisissez un Skill de développement ciblé ; sinon, revenez à une étape de clarification.
Si un test échoue avec une commande reproductible, choisissez un Skill de correction ; sinon, utilisez d’abord un Skill d’investigation et ne promettez pas de correctif.
Si le comportement doit rester identique, choisissez une refactorisation contrôlée avec base de référence ; sinon, traitez la demande comme une évolution fonctionnelle.
Si vous disposez d’un diff et de résultats vérifiables, choisissez le Skill de revue de code ; sinon, demandez les entrées manquantes.
Si la documentation doit refléter un changement déjà réalisé, choisissez le Skill de documentation ; sinon, ne faites pas rédiger de fonctionnalité non validée.
Si une action modifie un système externe ou produit un effet irréversible, choisissez un Skill de livraison avec confirmation humaine ; sinon, automatisez uniquement la préparation.

Cette logique est plus robuste qu’un unique « Skill ingénieur logiciel » qui tenterait de planifier, coder, tester, commenter et publier dans une seule session.

Validez chaque Skill dans un projet minimal

Avant de partager un modèle Claude Skills dans votre équipe, créez un petit dépôt de validation contenant un cas nominal, un échec attendu et une demande volontairement ambiguë.

Vérifiez au minimum :

le déclenchement sur une demande pertinente ;
l’absence de déclenchement sur une demande voisine mais hors sujet ;
le respect des fichiers autorisés ;
l’arrêt lorsque l’entrée obligatoire manque ;
la conservation des tests et assertions ;
la qualité des preuves dans le rapport final ;
la capacité à signaler un échec au lieu de le dissimuler.

La validation de structure peut être automatisée avec l’outil de référence skills-ref validate, recommandé par la documentation de spécification Agent Skills. Cette commande ne prouve pas que le processus produit une bonne décision, mais elle détecte les erreurs de nommage, de métadonnées et de format qui empêcheraient le chargement du Skill.

Pour une équipe, versionnez les Skills comme du code : revue des changements, historique, propriétaire, environnement compatible et exemples d’utilisation. Ajoutez une règle de retrait lorsqu’un modèle déclenche trop souvent, produit des rapports difficiles à vérifier ou dépend d’une commande qui n’existe plus.

Déployer ces Skills sur un environnement Mac distant

Un poste local convient aux essais ponctuels, mais les équipes qui exécutent régulièrement des tests, des constructions ou des publications rencontrent vite des contraintes différentes : dépendances non identiques entre développeurs, machine indisponible, droits trop larges, processus concurrent et absence de séparation entre deux tâches.

Avant de déplacer vos Skills vers un environnement distant, vérifiez :

que chaque tâche possède son répertoire de travail isolé ;
que les secrets ne sont pas écrits dans les instructions du Skill ;
que les commandes destructrices demandent une confirmation ;
que les journaux et artefacts sont conservés ;
que la version de Claude Code et les outils locaux sont documentés ;
que les tests peuvent être relancés après une interruption.

Vous pouvez consulter la page configuration et commande Macstripe pour préparer un environnement adapté à vos contraintes, puis utiliser le centre juridique Macstripe si votre équipe doit clarifier les conditions d’accès, de données ou de confidentialité.

Le poste actuel ou une machine virtuelle généraliste peut rester pertinent pour une expérimentation courte, mais il présente souvent trois défauts dans ce scénario : environnement difficile à reproduire, concurrence pour les ressources et accès incomplet aux outils Apple nécessaires aux projets audio, vidéo ou design. Pour des tâches répétées avec des dépendances spécifiques, louer un Mac auprès de Macstripe peut donc offrir une base plus prévisible, surtout lorsque vous avez besoin d’un environnement temporaire pour tester plusieurs versions d’un Skill plutôt que de modifier immédiatement l’infrastructure permanente de l’équipe.

L’objectif n’est pas de louer un Mac dans tous les cas. Un achat local reste plus logique pour une charge lourde et stable, un accès physique permanent ou un usage quotidien sans contrainte de durée. En revanche, pour un projet de validation, une campagne de tests, une chaîne de construction ponctuelle ou une comparaison de modèles Claude Code Skills, un environnement Mac isolé évite de mélanger les essais de l’agent avec votre poste de production.

Dernière mise à jour : 12 août 2026. Les informations ont été vérifiées à partir de la spécification Agent Skills, des guides officiels de création de Skills et de la documentation Claude Code disponible à cette date. Les modèles proposés restent des bases éditoriales : testez-les dans votre propre dépôt avant toute utilisation automatisée.

Questions fréquemment posées

Quels modèles de Claude Code Skills faut-il créer en premier ?

Commencez par cinq Skills à périmètre étroit : revue de code, correction de tests, refactorisation contrôlée, documentation des changements et contrôle de publication. Ils couvrent des tâches répétitives, produisent des preuves faciles à vérifier et limitent les risques mieux qu’un modèle généraliste chargé de gérer tout le cycle de développement.

Comment concevoir un Skill de revue de code fiable ?

Un bon Skill de revue de code précise les fichiers examinés, les catégories de risque, les commandes autorisées et le format du rapport. Il doit séparer les problèmes confirmés par un outil des simples hypothèses, indiquer l’emplacement exact de chaque preuve et s’arrêter lorsque les entrées nécessaires, comme le diff ou les tests, sont absentes.

Quelles étapes inclure dans un Skill de correction de tests ?

Le processus doit couvrir la reproduction, la collecte des journaux, l’identification de la cause, la modification minimale, l’exécution du test concerné puis la régression sur la suite pertinente. Le Skill doit interdire la suppression d’un test, la diminution d’une assertion ou la modification d’un seuil uniquement pour obtenir un résultat positif.

Comment empêcher un Skill de refactorisation de dépasser son périmètre ?

Définissez une liste de fichiers autorisés, un comportement de référence, une taille maximale de lot et des conditions d’arrêt explicites. Le Skill doit revenir à l’état précédent dès qu’un test non lié échoue, qu’une interface publique change sans validation ou que l’agent propose une réécriture architecturale non demandée.

Comment partager des modèles Claude Skills dans une équipe ?

Versionnez chaque Skill dans un dépôt interne, imposez une structure commune de dossier et ajoutez un projet minimal de validation. Les descriptions doivent préciser le moment du déclenchement, les dépendances et les exclusions. Avant diffusion, chaque version doit être testée sur plusieurs tâches représentatives et accompagnée d’un historique des changements.

À qui s’adresse ce guide ?