Zilmac Blog
← Retour à la pratique technique

Comment créer des Skills personnalisés pour Claude Code ? Tutoriel complet, de la rédaction de SKILL.md à la configuration des dossiers et à l’appel réel

AIDevelopment ·~15 min de lecture

Deux emplacements officiels, une règle de validation

>

La documentation officielle distingue notamment deux emplacements locaux pour les Skills : le dossier du projet et le dossier personnel de l’utilisateur. Ce repère conduit à une méthode simple pour créer des Skills personnalisés pour Claude Code : rédiger un fichier SKILL.md conforme, le placer dans un emplacement pris en charge, puis vérifier son identification et son exécution avec une tâche réelle. Les chemins, les champs de métadonnées et les mécanismes de déclenchement pouvant évoluer, la documentation officielle des Skills Claude Code reste la référence à consulter avant toute configuration.

Ce guide s’adresse aux développeurs qui souhaitent réutiliser un processus de programmation, aux équipes qui veulent harmoniser certaines consignes et aux spécialistes des agents qui doivent vérifier qu’un Skill se déclenche pour la bonne raison. Il convient moins à celles et ceux qui cherchent une introduction générale à Claude Code : l’objectif est ici de créer, placer, tester et corriger un Skill.

Un Skill n’est considéré comme prêt que si trois contrôles passent ensemble : le fichier s’appelle bien SKILL.md, il se trouve dans un emplacement que Claude Code sait prendre en compte, et le résultat d’un test montre que les consignes utiles ont été appliquées. Un fichier présent sur le disque mais jamais chargé n’est pas une configuration validée ; un Skill appelé mais dont les consignes sont trop vagues n’est pas davantage prêt à être partagé.

Choix du dossier selon la portée recherchée

>

Avant de rédiger le contenu, il faut choisir où le Skill doit être disponible. La documentation des Skills décrit notamment les deux chemins suivants :

Portée visée Chemin du Skill Évaluation pratique
Un projet précis, à partager avec son dépôt .claude/skills/<nom-du-skill>/SKILL.md Adéquation forte lorsque les consignes dépendent du code ou des conventions de ce projet
Plusieurs projets du même utilisateur ~/.claude/skills/<nom-du-skill>/SKILL.md Adéquation forte pour une procédure personnelle réutilisable d’un dépôt à l’autre

Ces chemins et la structure attendue sont décrits dans la documentation officielle consacrée aux Skills. Le dossier du projet est généralement le meilleur choix pour une procédure liée à ses scripts, à son architecture ou à ses règles de revue : le Skill peut alors évoluer avec le dépôt. Le dossier personnel convient davantage à une méthode qui reste pertinente dans des projets distincts, par exemple une façon de préparer une analyse de bogue ou de produire un compte rendu technique.

Dans les deux cas, le nom du répertoire identifie le Skill et le fichier d’instructions doit porter exactement le nom SKILL.md. Une structure minimale ressemble à ceci :

.claude/
└── skills/
    └── revue-correctif/
        └── SKILL.md

Pour un Skill personnel, la même structure se place sous ~/.claude/skills/ plutôt que sous le projet. Le nom revue-correctif est un exemple de rédaction, pas une exigence universelle de nommage. Il vaut mieux retenir un nom explicite, distinct des autres Skills, puis confirmer dans la documentation actuelle les restrictions de nom et de chemin applicables à la version utilisée.

Ne confondez pas un Skill avec les fichiers de mémoire ou d’instructions générales du projet. Les consignes de projet et fichiers mémoire servent à conserver un contexte plus large ; un Skill, lui, décrit une procédure spécialisée qui peut être sollicitée quand une tâche correspond à son domaine. Cette séparation évite de transformer un fichier de contexte général en longue liste de procédures rarement pertinentes.

Rédaction de SKILL.md orientée vers une action

>

Un SKILL.md associe un frontmatter — les métadonnées en tête de fichier — à un corps contenant les instructions. Dans un premier Skill, concentrez-vous sur les éléments que la documentation met au cœur de l’identification et de l’usage : un nom clair, une description utile et des consignes opératoires dans le corps. La documentation détaille les champs disponibles et leurs effets ; certains champs facultatifs peuvent influer sur l’invocation, les outils ou le contexte, et ne doivent donc pas être copiés sans comprendre leur fonction.

Exemple pédagogique, à adapter puis à tester dans le projet concerné :

---
name: revue-correctif
description: Analyse un correctif ciblé et relève les risques de régression, les cas limites et les tests manquants. À utiliser lors d’une revue de modification ; ne pas l’utiliser pour concevoir une fonctionnalité complète.
---

# Revue d’un correctif

Examinez uniquement les fichiers modifiés et leurs dépendances immédiates.

Procédure :
- Résumez le comportement modifié en une phrase.
- Recherchez les cas limites et les erreurs possibles.
- Vérifiez si les tests couvrent le comportement et les régressions plausibles.
- Présentez les constats par gravité, avec le fichier ou le passage concerné.
- Si aucun problème n’est identifié, indiquez les limites de l’examen au lieu d’affirmer que le correctif est exempt de défaut.

L’exemple ne garantit pas un résultat particulier ; il montre comment rendre l’objectif et les limites visibles. Le nom est court et orienté vers une tâche. La description précise à la fois quand le Skill est pertinent et quand il ne l’est pas. Le corps transforme cette intention en étapes et impose un format de constat. Cette combinaison donne au système des indices utiles pour sélectionner le Skill et réduit le risque qu’une procédure de revue soit appliquée à une demande de conception sans rapport.

Évitez les descriptions comme « aide au développement » ou « améliore le code ». Elles couvrent trop de demandes, donc elles aident peu à distinguer ce Skill d’autres instructions. À l’inverse, une description trop spécialisée — liée à un seul fichier temporaire ou à un problème déjà résolu — rend le Skill difficile à réutiliser. Une formulation efficace nomme la tâche, son déclencheur habituel et une limite de portée.

Dans le corps, privilégiez des verbes observables : examiner, comparer, exécuter, signaler, résumer. Indiquez les entrées attendues si elles ne sont pas évidentes, les fichiers à consulter et les critères d’un résultat acceptable. Si la tâche doit produire un diff, un rapport ou une liste de tests, écrivez-le explicitement. Les instructions devraient aussi préciser quoi faire en l’absence d’informations suffisantes : demander une clarification, signaler l’incertitude ou s’arrêter plutôt que d’inventer une conclusion.

Le Skill officiel de création de Skills constitue un exemple de structure et de méthode, pas une raison de recopier ses consignes dans tous les projets. De même, la spécification du format Agent Skills peut aider à comprendre les conventions de format ; pour déterminer ce que Claude Code prend effectivement en charge, privilégiez toutefois sa documentation officielle, car une spécification générale et une implémentation peuvent différer.

Vérifications de configuration avant le premier appel

>

Après avoir enregistré le fichier, contrôlez le chemin depuis le bon point de départ. Pour un Skill de projet, la racine est celle du projet ouvert ; pour un Skill personnel, vérifiez le répertoire de l’utilisateur qui lance Claude Code. Un Skill placé dans skills/ à la racine, dans un dossier arbitraire, ou à un niveau de profondeur différent de celui attendu peut rester ignoré, même si son contenu semble correct.

Vérifiez ensuite ces éléments dans l’ordre :

  • Le dossier du Skill porte un nom cohérent avec la valeur name utilisée dans les métadonnées.
  • Le fichier s’appelle exactement SKILL.md, avec la casse attendue, et n’a pas reçu une extension cachée telle que .txt.
  • Le frontmatter commence et se termine avec les délimiteurs YAML attendus ; les deux-points, guillemets et retours à la ligne ne rendent pas les champs ambigus.
  • La description indique un cas d’usage reconnaissable, au lieu de reprendre une formule générique.
  • Les consignes dans le corps correspondent à ce que l’équipe souhaite réellement déléguer.
  • Les options facultatives ont été ajoutées uniquement après vérification de leur prise en charge et de leur effet dans la documentation actuelle.

Un contrôle des réglages peut être utile lorsqu’un Skill semble soumis à une configuration particulière. La documentation des réglages de Claude Code explique les fichiers et options de configuration associés. Elle ne remplace pas l’inspection du dossier du Skill : il faut distinguer une erreur de portée ou de frontmatter d’une restriction définie par les réglages.

Attention : des exemples trouvés dans des dépôts ou des guides anciens peuvent décrire une syntaxe ou un comportement qui a changé. En cas d’écart, vérifiez d’abord la documentation officielle correspondant à Claude Code, puis testez dans l’environnement réellement utilisé avant de diffuser la règle à une équipe.

Une équipe qui distribue des Skills comme partie d’un plugin doit aussi distinguer le chemin local d’un Skill autonome de la structure d’un plugin. Les règles officielles sur la structure des plugins décrivent cette organisation séparée. Ne déplacez pas un exemple de plugin dans .claude/skills/ sans vérifier si sa structure et son mode de chargement restent valides.

Invocation et test observable

>

Il est utile de tester séparément l’appel explicite et l’éventuelle sélection automatique. Un Skill peut être rendu accessible comme commande à partir de son nom ; les métadonnées peuvent également limiter ou guider les façons de l’invoquer. La sélection automatique dépend de la pertinence perçue de la description et de la demande, elle ne doit donc pas être supposée sur la seule base de la présence du fichier. Consultez les règles actuelles d’invocation dans la documentation des Skills, en particulier avant d’ajouter des champs facultatifs qui changent le comportement.

Pour un premier test, choisissez une modification bénigne et visible, par exemple demander une revue d’un petit correctif déjà connu. L’objectif n’est pas de faire confiance à une impression générale, mais de vérifier des critères précis : le Skill a-t-il été invoqué par le moyen testé ? Le résultat suit-il les étapes prévues ? Les constats renvoient-ils aux fichiers pertinents ? Les limites de l’examen sont-elles signalées plutôt que masquées ?

Procédez de manière contrôlée :

  • Ouvrez le projet qui contient le Skill, ou l’environnement où le Skill personnel doit être disponible.
  • Demandez explicitement une tâche qui correspond à la description et indiquez le nom du Skill si la syntaxe d’appel documentée le permet.
  • Comparez la réponse aux exigences du fichier, en vérifiant les éléments observables plutôt que le ton ou la longueur.
  • Recommencez avec une demande clairement hors périmètre pour vérifier que la description ne pousse pas à utiliser le Skill à tort.
  • Testez ensuite une formulation naturelle sans nommer le Skill ; ce contrôle porte sur l’éventuelle correspondance automatique, pas sur l’appel explicite.
  • Notez le résultat et toute modification effectuée, afin de pouvoir reproduire le test après un changement de fichier ou de version.

Cette séparation évite une conclusion trompeuse. Si l’appel explicite fonctionne mais que la demande naturelle ne déclenche pas le Skill, la cause la plus plausible à examiner est la description ou la correspondance entre la demande et son domaine. Si les deux échouent, commencez par l’emplacement, le nom du fichier et le frontmatter. Si le Skill se lance mais produit un résultat hors consigne, son identification n’est probablement pas le seul problème : reprenez les étapes du corps et remplacez les demandes vagues par des critères contrôlables.

Pour une chaîne d’équipe, conserver une tâche de test courte dans la documentation du dépôt facilite la validation après un changement. Une consigne de revue peut, par exemple, exiger un constat lié à un fichier, une vérification des tests et une mention explicite lorsqu’aucune anomalie n’a été trouvée. Ce type de contrôle est particulièrement utile pour les équipes qui examinent du code généré, mais aussi pour des tâches créatives impliquant des scripts audio ou vidéo, où la procédure doit distinguer les opérations effectivement réalisées des recommandations qui restent à valider.

Diagnostic des Skills absents ou imprévisibles

>

Quand un Skill n’apparaît pas, ne modifiez pas immédiatement son contenu. Commencez par confirmer le dossier actif : projet ouvert, racine correcte et portée choisie. Ensuite, vérifiez l’orthographe et la casse de SKILL.md, puis l’arborescence. Une erreur de niveau de dossier est fréquente, car un fichier bien écrit peut rester invisible s’il est rangé sous un chemin qui n’est pas pris en charge.

Si le chemin est correct, examinez la forme du frontmatter. Une valeur mal délimitée, un champ dupliqué ou une indentation incorrecte peuvent empêcher l’interprétation attendue. Reprenez les noms de champs depuis la documentation officielle plutôt que depuis un ancien extrait. Vérifiez ensuite que la description distingue le cas d’usage du Skill des demandes voisines ; une description trop générale rend l’activation moins prévisible, tandis qu’une description qui ne mentionne pas la tâche testée fournit peu de signal.

Si le Skill est disponible mais ne se déclenche pas automatiquement, comparez la demande au texte de la description. Reformulez la description pour nommer explicitement la tâche et ses indices, puis retestez avec la même demande. Si un appel explicite échoue également, vérifiez les réglages qui peuvent affecter son invocabilité, ainsi que la compatibilité des champs facultatifs avec la documentation actuelle. Ne concluez pas qu’une option est prise en charge simplement parce qu’elle apparaît dans un exemple trouvé ailleurs.

Enfin, lorsqu’un Skill se déclenche mais répond à côté, identifiez la consigne qui laisse trop de latitude : entrée attendue non précisée, procédure incomplète, limite absente ou format de sortie implicite. Modifiez un seul élément à la fois, relancez le cas nominal, puis le cas hors périmètre. Ce cycle — hypothèse, petite modification, test comparable — permet de savoir si le problème vient du chargement, du choix du Skill ou de la qualité de ses instructions.

FAQ sur la création de Skills

>

Quelle structure minimale faut-il préparer ?

Créez un dossier dédié au Skill dans l’emplacement correspondant à sa portée, puis ajoutez-y un fichier nommé SKILL.md. Celui-ci contient un frontmatter et un corps de consignes. Pour éviter les erreurs de compatibilité, confirmez les chemins et champs pris en charge dans la documentation officielle au moment de la configuration.

Un Skill personnel est-il préférable à un Skill de projet ?

Choisissez un Skill de projet lorsque les instructions dépendent du dépôt, de ses outils ou de ses conventions, ou lorsqu’elles doivent être partagées avec l’équipe. Choisissez un Skill personnel si la procédure reste valable dans plusieurs projets et n’a pas besoin d’être versionnée avec un dépôt particulier. Le critère déterminant est la portée souhaitée, pas une différence de qualité entre les deux options.

L’invocation automatique peut-elle être considérée comme garantie ?

Non. Une description pertinente aide Claude Code à faire correspondre une tâche au Skill, mais un test isolé ne garantit pas le même comportement pour toutes les formulations. Validez séparément un appel explicite et une demande naturelle, puis rendez la description plus distinctive si la sélection automatique est importante pour votre flux de travail.

Faut-il redémarrer Claude Code après une modification ?

Ne présumez pas d’un comportement uniforme sans vérifier la documentation de la version utilisée. Après une modification, enregistrez le fichier et relancez le test dans les conditions prévues ; si le changement n’est pas pris en compte, consultez les instructions officielles de chargement avant d’adopter une procédure de redémarrage issue d’un ancien guide.

Mise en pratique et choix de l’environnement

>

La validation la plus utile consiste à partir d’une tâche répétée réellement rencontrée, puis à écrire un Skill qui en précise le déclencheur, les étapes et le résultat attendu. Si ce cycle révèle qu’il faut aussi un environnement de développement distant pour exécuter des tâches ou tester des projets, examinez séparément les contraintes de votre flux : accès aux fichiers, continuité de l’environnement, gestion des dépendances et modalités de livraison. Une machine locale peut rester préférable pour un travail durable qui dépend de périphériques physiques ; un environnement distant n’est pas automatiquement adapté à tous les usages.

Pour vérifier si cette option correspond à vos besoins, consultez la présentation des solutions proposées par Zilmac ainsi que les informations sur la location de Mac dans le cloud, puis comparez-les à votre flux de travail avant de décider. La création du Skill doit d’abord être validée dans le contexte où il sera réellement utilisé ; l’environnement distant ne devient pertinent que si une contrainte de développement le justifie.

Questions fréquentes

Comment rédiger un fichier SKILL.md utile pour une tâche récurrente ?

Décrivez une tâche précise, indiquez les situations où le Skill doit s’appliquer et celles où il ne doit pas s’appliquer, puis donnez une procédure vérifiable. Le champ description du frontmatter aide Claude Code à déterminer la pertinence du Skill ; le corps du fichier doit donc fournir des consignes concrètes plutôt qu’une présentation générale de votre projet.

Où placer un Skill pour qu’il soit disponible dans Claude Code ?

Pour un seul projet, la documentation indique le dossier .claude/skills//SKILL.md ; pour un usage personnel entre projets, elle indique ~/.claude/skills//SKILL.md. Vérifiez le chemin depuis la racine concernée et consultez la documentation officielle avant de copier une structure trouvée dans un ancien exemple.

Comment Claude Code repère-t-il et lance-t-il un Skill personnalisé ?

Un Skill peut être lancé explicitement avec son nom lorsqu’il est exposé comme commande, et certains Skills peuvent aussi être sélectionnés automatiquement si leur description correspond à la demande. Ces comportements dépendent des métadonnées et des réglages du Skill : testez les deux voies séparément et ne déduisez pas l’activation automatique de la seule présence du fichier.

Que vérifier si un Skill personnalisé ne se déclenche pas ?

Contrôlez d’abord le nom exact du fichier, l’emplacement du dossier, la syntaxe du frontmatter et la description. Vérifiez ensuite que la demande de test correspond bien au cas d’usage décrit et que les métadonnées n’empêchent pas l’invocation concernée. Modifiez un élément à la fois, puis relancez la même tâche pour isoler la cause.

Testez vos Skills Claude Code sur un Mac à distance

Avec Zilmac, louez un Mac mini M4 dédié sous macOS pour développer et tester vos automatisations dans un environnement complet.

Connectez-vous à votre machine à distance en SSH ou en VNC et gardez vos outils de développement à portée de main. — Voir les options de forfait

Offre limitée

Zilmac

Avec Zilmac, louez un Mac mini M4 dédié sous macOS pour développer et tester vos automatisations dans un environnement complet.

Retour à l'accueil
Offre limitée Voir les forfaits