Comment écrire une Claude Skill (structure du SKILL.md + exemples réels)

Voici comment écrire une Claude skill en une phrase : créez un dossier, placez-y un fichier SKILL.md, et rédigez une description assez précise pour que Claude sache quand s'en servir. C'est tout le mécanisme. La partie qui décide réellement si votre skill fonctionne fait 1 024 caractères, et c'est le champ description qu'Anthropic utilise pour repérer votre skill parmi la centaine qui pourrait être chargée. Nous faisons tourner 25 skills en production sur la bibliothèque communautaire de Techsy, et celles qui échouent ne se trompent presque jamais dans leurs instructions. Elles échouent sur cette seule ligne.

Résumé rapide

Pour écrire une Claude skill : (1) créez un dossier portant le nom de la skill, (2) ajoutez un SKILL.md avec un frontmatter YAML (name et description) suivi d'instructions en Markdown, (3) rédigez la description à la troisième personne avec des mots déclencheurs clairs, (4) gardez le corps sous 500 lignes et renvoyez les détails vers des fichiers de référence, et (5) testez-la sur des tâches réelles avant de lui faire confiance.

Ce qu'est réellement une Claude skill

Une skill est un dossier contenant un fichier SKILL.md à sa racine. Rien de plus n'est requis. Ce fichier contient deux choses : des métadonnées qui indiquent à Claude quand utiliser la skill, et des instructions qui lui indiquent comment accomplir la tâche une fois activée.

Si ce système reste économe, c'est grâce à un modèle de chargement qu'Anthropic appelle la divulgation progressive. Au démarrage, Claude ne lit que le name et la description de chaque skill installée, environ 100 tokens chacune. Il ne lit le SKILL.md complet que lorsque votre description correspond à la tâche en cours, et il ne lit les fichiers de référence associés que lorsque les instructions y renvoient. Vous pouvez donc livrer une skill volumineuse et détaillée sans en payer le coût à chaque requête. Vous trouverez un catalogue fonctionnel de ces skills dans notre bibliothèque de Skills.

Le squelette SKILL.md à copier

Chaque skill part de la même forme. Voici la version minimale qui fonctionne :

---
name: reviewing-pull-requests
description: Reviews pull request diffs for bugs, security issues, and style. Use when the user asks for a code review, mentions a PR, or shares a diff.
---

# Reviewing Pull Requests

1. Read the diff and summarize what changed.
2. Flag likely bugs and edge cases, most severe first.
3. Check for hardcoded secrets and injection risks.
4. Note style issues only if they hurt readability.
5. End with a short verdict: approve, or request changes.

Deux marqueurs --- encadrent le frontmatter. En dessous, le corps est du Markdown simple. Sur nos 25 skills, la structure qui a survécu à l'usage réel est ennuyeuse et cohérente : un titre d'une ligne, puis une procédure numérotée ou à puces, puis d'éventuels modèles ou exemples. Quand nous avons voulu faire de la belle prose, Claude l'a survolée. Quand nous avons écrit des étapes, il les a suivies. Si vous voulez étudier des skills terminées, les 25 skills du site communautaire Techsy sont autant de fichiers SKILL.md lisibles que vous pouvez ouvrir et copier.

Règles du frontmatter : name et description

Le frontmatter comporte exactement deux champs obligatoires, et tous deux ont des limites strictes qu'il vaut la peine de mémoriser, car les outils d'Anthropic les valident.

Une convention utile issue du guide de bonnes pratiques d'Anthropic : nommer les skills sous forme gérondive, comme processing-pdfs, writing-documentation, analyzing-spreadsheets. Cela se lit bien dans une liste et décrit l'activité plutôt qu'un nom vague comme helper ou utils. Gardez le name identique au nom du dossier pour que les deux ne divergent jamais. Pour l'ensemble des règles de validation, la documentation des bonnes pratiques d'Anthropic fait référence.

Rédiger une description qui déclenche réellement la skill

C'est la section que la plupart des tutoriels sautent, et c'est pourtant elle qui décide si votre travail sera utilisé. La description est injectée dans le system prompt, et Claude la lit pour décider s'il doit charger votre skill. Un corps parfait derrière une description vague donne une skill qui ne tourne jamais.

Trois règles font la différence :

Rédigez à la troisième personne. La description décrit la skill, pas vous et pas l'utilisateur. Une formulation à la première ou à la deuxième personne brouille la sélection.

# Good
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDFs or when the user mentions forms or document extraction.

# Avoid
description: I can help you work with your PDF files whenever you need.

Précisez le quoi et le quand. « Traite des données » ne dit rien à Claude sur la tâche qui correspond. Nommez la capacité concrète et les déclencheurs concrets.

Incluez les mots qu'un utilisateur taperait réellement. Si les gens disent « PR », « diff » et « code review », placez ces termes dans la description. Claude s'appuie dessus pour faire correspondre. C'est la modification à plus fort impact que vous puissiez apporter à une skill, et elle ne coûte qu'une ligne.

Divulgation progressive et structure des fichiers

Dès qu'une skill dépasse un ou deux écrans, la structure commence à compter. Les recommandations d'Anthropic sont concrètes : gardez le corps du SKILL.md sous 500 lignes, et déplacez tout ce qui dépasse dans des fichiers de référence séparés vers lesquels le corps renvoie. Ces fichiers ne coûtent aucun token tant que Claude ne les lit pas réellement.

Une skill arrivée à maturité ressemble à ceci :

reviewing-pull-requests/
├── SKILL.md            # overview + the core procedure
├── security.md         # detailed security checklist (read when needed)
├── style-guide.md      # house style rules (read when needed)
└── scripts/
    └── diff_stats.py    # executed, never loaded into context

Deux règles font que ça fonctionne. D'abord, gardez les références à un seul niveau de profondeur : liez chaque fichier directement depuis SKILL.md, jamais fichier-vers-fichier-vers-fichier, car Claude ne prévisualise parfois les fichiers profondément imbriqués que par une lecture partielle et peut manquer du contenu. Ensuite, donnez à tout fichier de référence de plus de 100 lignes une table des matières en haut, pour qu'une lecture partielle montre malgré tout l'étendue complète. L'article technique d'Anthropic sur les Agent Skills explique l'architecture derrière tout ça si vous voulez le modèle plus approfondi. Quand votre skill commence à orchestrer des outils, notre catalogue MCP est un bon complément pour brancher des serveurs.

Degrés de liberté (et quand ajouter des scripts)

Toutes les instructions ne doivent pas être aussi strictes les unes que les autres. Adaptez la rigueur avec laquelle vous scriptez une étape à sa fragilité.

Quand une étape est déterministe, livrez un script plutôt que de demander à Claude de générer le code à chaque fois. Un script embarqué est plus fiable, économise des tokens et reste cohérent d'une exécution à l'autre. Deux habitudes gardent les scripts honnêtes : gérez les erreurs à l'intérieur du script plutôt que de les déléguer à Claude, et justifiez chaque constante pour n'avoir aucun nombre magique inexpliqué. C'est aussi là que les skills diffèrent des subagents, qui embarquent leur propre liste d'outils autorisés et leur propre system prompt ; notre bibliothèque d'automatisations rassemble des exemples de subagents, et vous pouvez comparer les deux approches sur la page Techsy AI automations.

Testez-la : le développement de skill piloté par évaluations

Les meilleurs auteurs de skills écrivent les tests avant la documentation. Anthropic recommande de construire d'abord les évaluations : faites tourner Claude sur trois tâches représentatives sans la skill, notez précisément où il échoue, puis n'écrivez que l'instruction nécessaire pour corriger ces échecs. Cela vous garde concentré sur la résolution de problèmes réels plutôt que sur la documentation de problèmes imaginés.

Une boucle pratique :

1. Choisissez trois tâches réelles que la skill doit gérer.
2. Exécutez-les sans skill chargée et notez ce qui casse.
3. Écrivez le SKILL.md minimal qui corrige ces échecs.
4. Testez à nouveau avec la skill chargée, idéalement sur Claude Haiku, Sonnet et Opus, car une skill qui guide bien Opus peut être sous-spécifiée pour Haiku.
5. Observez comment Claude navigue dans les fichiers. S'il ignore une référence, votre lien n'est pas assez visible. S'il relit sans cesse le même fichier, ce contenu a sa place dans SKILL.md.

Pour un tutoriel pratique qui construit une skill de bout en bout, notre site sœur propose un tutoriel complet sur les Claude Skills ; il se marie bien avec les règles d'écriture présentées ici. Vous pouvez aussi suivre votre construction avec nos checklists de build entreprise.

Erreurs courantes qui tuent une skill

La plupart des skills cassées échouent pour l'une des quelques raisons suivantes :

• Une description écrite pour des humains. Un texte marketing se lit joliment et ne déclenche rien. Écrivez pour le modèle : capacités et déclencheurs.
• Trop d'options. « Utilisez pypdf, ou pdfplumber, ou PyMuPDF, ou... » fait hésiter Claude. Donnez un choix par défaut avec une seule échappatoire.
• Références profondément imbriquées. Des fichiers qui renvoient vers des fichiers qui renvoient vers d'autres fichiers ne sont lus que partiellement. Gardez tout à un seul saut de SKILL.md.
• Instructions sensibles au temps. « Avant le mois d'août, faites X » se périme. Placez plutôt les consignes obsolètes dans une note repliable « anciens schémas ».
• Chemins de type Windows. Utilisez toujours des barres obliques ; les antislashs cassent sur les runners Unix.
• Terminologie incohérente. Choisissez un mot pour désigner une chose (« champ », pas « champ/case/élément/contrôle ») et utilisez-le partout.

Le schéma commun à ces six erreurs : une skill est un jeu d'instructions destiné à un lecteur très capable, mais qui n'a aucune patience pour l'ambiguïté. Dites la chose précise, une seule fois.

À propos de l'auteur

Mert Batur Gurbuz est cofondateur de Techsy, University of Birmingham. Avec l'équipe Techsy, il construit des agents IA, des systèmes d'automatisation et des pipelines voix/SDR pour des clients B2B, et maintient la bibliothèque de 25 skills référencée tout au long de ce guide. Retrouvez-le sur LinkedIn. D'autres guides pour builders sont disponibles sur le blog TECHSY.community.

Questions fréquentes

Où se trouvent les fichiers d'une Claude skill ?

Une skill est un dossier contenant un fichier SKILL.md. Dans Claude Code, les skills personnelles se placent dans ~/.claude/skills/{skill-name}/ et les skills de projet dans .claude/skills/{skill-name}/. Sur l'API et claude.ai, vous téléversez le dossier de la skill. Le nom du dossier doit correspondre au champ name du frontmatter.

Le nom de la skill doit-il correspondre au nom du dossier ?

Oui, gardez-les identiques. Le champ name doit compter 64 caractères ou moins, n'utiliser que des lettres minuscules, des chiffres et des traits d'union, et éviter les mots réservés « anthropic » et « claude ». Faire correspondre le nom du dossier évite les divergences et facilite les références à la skill en conversation et dans la documentation.

Quelle longueur peut avoir un SKILL.md ?

Gardez le corps du SKILL.md sous 500 lignes pour une performance fiable. Il n'y a pas de limite stricte de tokens, car les fichiers de référence et les scripts ne coûtent rien tant qu'ils ne sont pas lus, mais un fichier principal trop volumineux entre en concurrence avec tout le reste dans la fenêtre de contexte. Quand vous approchez des 500 lignes, répartissez les détails dans des fichiers de référence liés directement depuis SKILL.md.

Pourquoi ma skill ne se déclenche-t-elle pas ?

Presque toujours à cause de la description. Claude sélectionne les skills en faisant correspondre la tâche au champ description : si la vôtre est vague ou écrite à la première personne, elle ne s'active jamais. Réécrivez-la à la troisième personne, indiquez ce que fait la skill et quand l'utiliser, et incluez les mots exacts qu'un utilisateur taperait pour cette tâche.

Quelle est la différence entre une skill, un subagent et un serveur MCP ?

Une skill est un ensemble d'instructions packagées que Claude charge quand c'est pertinent. Un subagent est un agent distinct, avec sa propre liste d'outils autorisés et son propre system prompt, qui gère une tâche déléguée. Un serveur MCP expose des outils et des données externes via le Model Context Protocol. Les skills décrivent comment faire le travail ; les serveurs MCP fournissent sur quoi agir.

Une Claude skill peut-elle exécuter du code ?

Oui. Les skills peuvent embarquer des scripts exécutables que Claude lance comme des outils plutôt que de les lire dans le contexte, ce qui est plus économique et plus fiable pour un travail déterministe comme la validation ou la conversion de fichiers. Rendez l'intention explicite dans vos instructions : dites « exécutez ce script » pour une exécution, ou « consultez ce script » quand il s'agit d'un document de référence.

Les skills fonctionnent-elles à la fois sur l'API et sur claude.ai ?

Oui, mais l'environnement d'exécution diffère. Sur claude.ai, l'environnement d'exécution de code peut installer des paquets depuis npm et PyPI, alors que l'API Claude n'a ni accès réseau ni installation de paquets à l'exécution. Listez les paquets nécessaires dans votre SKILL.md et confirmez qu'ils sont disponibles dans l'environnement cible avant de vous y fier.

Combien de skills Claude peut-il avoir chargées en même temps ?

Beaucoup, car seuls le name et la description de chaque skill se trouvent dans le contexte au démarrage, environ 100 tokens chacune. C'est pourquoi la description compte autant : Claude peut choisir parmi plus de 100 skills, et une description précise est ce qui lui permet de sélectionner la bonne. Le corps complet ne se charge qu'une fois la skill sélectionnée.