Créer et packager votre propre skill

Une Skill est un dossier contenant un fichier SKILL.md à sa racine, et ce seul fichier fait la différence entre un Claude qui connaît vaguement votre travail et un Claude qui fait votre travail de façon fiable, comme votre équipe l'attend. Vous savez déjà que Claude peut suivre des instructions dans un prompt. Une Skill rend ces instructions portables, réutilisables et chargées automatiquement uniquement quand c'est pertinent.

Cette leçon vous montre l'anatomie d'une Skill personnalisée, en détaille une vraie (le modèle de rapport de votre entreprise) et vous donne un `SKILL.md` propre que vous pouvez copier.

Ce qu'est réellement une Skill

Une Skill est un ensemble packagé d'instructions, et éventuellement de fichiers de support, que Claude charge à la demande quand une tâche correspond à sa description. Voyez-la comme un dossier que Claude peut « ouvrir » quand il estime que le travail l'exige.

La Skill minimale viable est un seul fichier :

report-template/
└── SKILL.md

C'est une Skill complète et valide. Tout le reste est optionnel.

Le mécanisme clé à comprendre : Claude ne lit pas en permanence le contenu intégral de chaque Skill. Il lit les métadonnées (nom et description) des Skills disponibles, et ne charge le corps complet du SKILL.md et les fichiers annexes dans le contexte que lorsqu'une requête correspond. Cela s'appelle le progressive disclosure, et c'est pourquoi les Skills passent mieux à l'échelle qu'un system promptsystem promptLes instructions cachées qui définissent le comportement d'un assistant IA avant toute question : son rôle, son ton, ses limites et ses règles.Voir la définition complète → géant. Vous pouvez avoir vingt Skills installées et ne payer le coût en contexte que pour celles qu'une tâche donnée déclenche.

La référence officielle se trouve sur docs.claude.com/en/docs/agents-and-tools/agent-skills. Mettez-la en favori : le format évolue.

L'anatomie de SKILL.md

SKILL.md est un fichier Markdown avec un bloc de frontmatter YAML en haut (la section délimitée par des lignes ---) suivi d'instructions Markdown libres.

Le frontmatter porte les deux champs les plus importants :

• `name` : un identifiant court et lisible.
• `description` : une ou deux phrases qui disent CE QUE fait la Skill et, surtout, QUAND l'utiliser.

Cette deuxième partie est la règle que la plupart des gens rate. La description n'est pas un texte marketing pour les humains. C'est la logique de routage que Claude utilise pour décider s'il charge la Skill. Si votre description dit « Met en forme des rapports », Claude n'a aucun déclencheur. Si elle dit « À utiliser quand l'utilisateur demande de rédiger, mettre en forme ou finaliser un rapport d'activité trimestriel ou mensuel au format maison Acme », alors Claude sait exactement quand y recourir.

Écrivez la description comme un aiguilleur : nommez les déclencheurs, les types de documents, les verbes.

Le corps

Sous le frontmatter, le corps Markdown contient les instructions réelles : les règles, la structure, ce qu'il faut faire et ne pas faire, des exemples. C'est là que vous mettez la substance que Claude lit une fois la Skill déclenchée.

Restez concentré. Si le corps enfle, déplacez le détail dans des fichiers annexes et référencez-les.

Fichiers annexes

Une Skill peut embarquer des fichiers de support dans son dossier :

• Un template.md ou template.docx auquel vos rapports doivent correspondre.
• Un dossier examples/ avec deux ou trois sorties modèles.
• Des scripts, comme un validate.py qui vérifie un brouillon par rapport aux règles de mise en forme.
• Des données de référence, comme un approved-language.md de formulations validées par la conformité.

Claude peut lire ces fichiers quand la Skill est active et, dans des environnements d'exécution comme Claude Code ou l'Agent SDK, peut exécuter les scripts que vous incluez. Vous les référencez depuis le corps pour que Claude sache qu'ils existent et à quoi chacun sert.

report-template/
├── SKILL.md
├── template.md
├── examples/
│   └── q3-sample.md
└── scripts/
    └── validate.py

Une Skill concrète : le modèle de rapport de l'entreprise

Admettons que votre entreprise produise une revue d'activité mensuelle. Chacune a les mêmes sections, le même ton, un executive summary obligatoire limité à cinq puces, et une règle voulant que tous les montants en dollars affichent les écarts en glissement annuel. Les nouvelles recrues se trompent pendant des mois.

Vous pourriez coller ces règles dans chaque prompt. Une Skill fait mieux parce que les règles vivent dans un seul endroit versionné, se chargent automatiquement quand quelqu'un rédige un rapport, et se mettent à jour pour tout le monde quand vous éditez le fichier.

Voici un SKILL.md propre et complet pour cela :

---
name: acme-monthly-report
description: >
  Use when the user asks to write, draft, format, or finalize Acme's
  monthly business review (MBR) or any monthly/quarterly business report
  in Acme house style. Applies the standard section structure, tone, and
  financial formatting rules.
---

# Acme Monthly Business Review

Apply these rules when producing an Acme MBR.

## Required structure (in order)

1. **Executive Summary** — max 5 bullets, each one sentence.
2. **Key Metrics** — table of metric, current value, YoY delta.
3. **Wins** — 3 to 5 items, outcome-focused.
4. **Risks & Mitigations** — each risk paired with an owner.
5. **Next Month's Priorities** — max 3, each with a measurable target.

## Formatting rules

- Every dollar or percentage figure must show a year-over-year delta
  in parentheses, e.g. `$1.2M (+14% YoY)`.
- Use the company template in `template.md` as the skeleton.
- Tone: direct, no hedging. Cut filler adjectives.
- Never invent numbers. If a metric is missing, write `[TK: source needed]`.

## Before finishing

Run `scripts/validate.py` against the draft and fix any flagged issues.

Remarquez ce que fait la description. Elle liste les verbes (« write, draft, format, finalize »), le nom du document et son acronyme (« monthly business review (MBR) ») et les variantes (« monthly/quarterly business report »). Cela donne à Claude plusieurs façons de matcher une vraie demande utilisateur.

Remarquez ce que fait le corps. Il est spécifique et vérifiable. « Cut filler adjectives » est une règle sur laquelle Claude peut agir. « Fais quelque chose de bien » ne l'est pas.

Quand une Skill vaut mieux que de bourrer le prompt

Les deux approches placent des instructions devant Claude. Les différences sont opérationnelles.

Réutilisation. Un prompt meurt quand la conversation se termine. Une Skill vit dans un dossier et s'applique chaque fois, dans chaque chat, pour tous ceux qui l'ont installée.

Déclenchement automatique. Avec un prompt, l'utilisateur doit penser à inclure les règles. Avec une Skill, Claude les charge quand la tâche correspond à la description. La nouvelle recrue qui ne sait pas que les règles existent les voit tout de même appliquées.

Efficacité du contexte. Coller un guide de style de 2 000 mots dans chaque prompt brbrLe pourcentage de visiteurs qui repartent après avoir vu une seule page, souvent le signe d'une pertinence insuffisante, d'un décalage d'intention ou d'une expérience utilisateur faible.Voir la définition complète →ûle des tokenstokensUn token est l'unité de base de texte que traitent les modèles de langage : le plus souvent un fragment de mot, un mot entier ou un signe de ponctuation, plutôt qu'un simple caractère.Voir la définition complète → à chaque tour, même quand la conversation dérive vers des sujets sans rapport. Une Skill ne se charge que quand elle est déclenchée, donc votre fenêtre de contexte reste légère.

Versioning et propriété. Une Skill est un dossier, donc elle vit dans Git. Vous relisez les changements dans une pull request, revenez sur une mauvaise édition et gardez une source unique de vérité. Les prompts éparpillés dans les notes de chacun divergent.

Assets et code embarqués. Un prompt, c'est du texte seulement. Une Skill peut transporter un vrai template.docx, des exemples de sorties et des scripts de validation exécutables.

L'arbitrage honnête : une Skill demande plus de mise en place. Pour une tâche unique que vous ne répéterez jamais, contentez-vous d'un prompt. Passez à une Skill quand une tâche est récurrente, a une bonne réponse, et que les règles sont assez stables pour valoir la maintenance.

Où tourne votre Skill

Le même format SKILL.md fonctionne sur toutes les surfaces Anthropic, et c'est tout l'intérêt de le packager une fois.

• Dans les applications Claude (web, desktop, mobile), vous pouvez ajouter des Skills pour qu'elles s'appliquent dans vos chats et Projects.
• Dans Claude Code, les Skills se placent à côté de votre repo et se déclenchent pendant les tâches de code et de documents dans le terminal.
• Via le Claude Agent SDK et l'API Messages, les Skills font partie de la façon dont vous donnez à un agent managé ou personnalisé des capacités durables sans réécrire le system prompt à chaque appel.

Cette portabilité est la raison pour laquelle la description et la structure comptent autant. Vous écrivez la logique de routage une fois, et elle fonctionne partout où la Skill est chargée.

Une note sur les voisins de cet écosystème. Une Skill, ce sont des instructions et des assets. Le Model Context Protocol (MCP), documenté sur modelcontextprotocol.io, est la façon dont Claude se connecte à des outils et sources de données en direct (votre base de données, votre système de ticketing) via les Connectors. Ils se composent : une Skill peut dire à Claude *comment* mettre en forme un rapport, tandis qu'un Connector MCPMCPUn standard ouvert qui permet aux assistants IA de se connecter aux outils et données de l'entreprise de façon cohérente et gouvernée, sans intégration sur mesure à chaque fois.Voir la définition complète → donne à Claude les métriques en direct à y mettre. N'utilisez pas une Skill pour simuler une connexion de données, et n'utilisez pas un Connector pour porter des règles de style.

Packager et livrer

Une fois le dossier au point, le packaging relève surtout de la discipline.

Gardez `SKILL.md` court, poussez le détail plus bas. Le corps doit être scannable. Si une section dépasse un écran, déplacez-la dans un fichier annexe référencé. Claude lit le corps pour s'orienter, puis ouvre les annexes au besoin.

Testez le déclencheur, pas seulement la sortie. Écrivez trois demandes réalistes qu'un utilisateur pourrait taper, et vérifiez que Claude charge effectivement la Skill pour chacune. Si elle ne se déclenche pas sur « prépare la MBR de ce mois-ci », votre description manque d'une phrase déclencheur. Corrigez la description avant de toucher au corps.

Rendez les scripts exécutables et légers en dépendances. Un validate.py qui a besoin de dix packages échouera dans la moitié de vos environnements. La bibliothèque standard quand c'est possible.

Versionnez dans Git. Traitez le dossier de la Skill comme du code. Les repos officiels d'Anthropic sur github.com/anthropics contiennent des exemples de Skills et les SDK, qui valent le coup d'être étudiés pour la structure et les conventions.

Écrivez pour les modes de défaillance du modèle. Si Claude tend à trop nuancer, votre corps doit dire « no hedging ». S'il tend à inventer des chiffres, ajoutez une règle explicite « never invent numbers » avec une convention de placeholder [TK], comme dans l'exemple ci-dessus. Vous encodez les corrections que vous taperiez sinon chaque fois.

Une boucle d'itération rapide

La façon la plus rapide de bien faire une Skill :

1. Rédigez SKILL.md avec une description tranchante et un corps minimal.
2. Balancez-lui trois vraies demandes et regardez si elle se déclenche.
3. Lisez la sortie face à votre vrai standard. Notez chaque écart.
4. Transformez chaque écart en une règle spécifique dans le corps, ou en un nouveau fichier annexe.
5. Répétez jusqu'à ce que la sortie passe sans votre intervention.

Vous avez terminé quand un collègue qui n'a jamais vu les règles obtient un rapport correct simplement en le demandant.

Points clés

• Une Skill est un dossier avec un SKILL.md à sa racine ; un fichier unique avec un frontmatter name et description est déjà une Skill valide.
• La description est une logique de routage, pas une étiquette : nommez les verbes, les types de documents et les déclencheurs pour que Claude charge la Skill exactement quand il le faut.
• Choisissez une Skill plutôt qu'un long prompt quand la tâche est récurrente, a une bonne réponse, et que les règles sont assez stables pour être maintenues dans Git.
• Gardez SKILL.md court et poussez le détail dans des fichiers annexes (templates, exemples, scripts de validation) que le corps référence par leur nom.
• Testez le déclencheur avec de vraies formulations d'utilisateurs avant de polir le corps, et livrez le dossier sous contrôle de version à côté de votre autre code.