Comment créer une compétence de code Claude prête pour la production

1.

L’écosystème Claude Code Skill se développe rapidement. En mars 2026, le référentiel anthropique/compétences atteignait plus de 87 000 étoiles sur GitHub et de plus en plus de personnes créent et partagent des compétences chaque semaine.

Comment pouvons-nous construire une compétence à partir de zéro, de manière structurée ? Cet article explique la conception, la création et la distribution d’une compétence à partir de zéro. J’utiliserai ma propre expérience pour envoyer une compétence d’évaluation du commerce électronique (Lien) comme exemple courant tout au long.

2. Qu’est-ce qu’une compétence Claude ?

Une compétence Claude est un ensemble d’instructions qui enseigne à Claude comment gérer des tâches ou des flux de travail spécifiques. Les compétences sont l’un des moyens les plus puissants de personnaliser Claude selon vos besoins spécifiques.

Les compétences se construisent autour de la divulgation progressive. Claude récupère les informations en trois étapes :

• Métadonnées (nom + description) : Toujours dans le contexte de Claude. Environ 100 jetons. Claude décide de charger ou non une compétence en se basant uniquement sur cela.
• Corps SKILL.md : Chargé uniquement lorsqu’il est déclenché.
• Ressources groupées (scripts/, références/, ressources/) : Chargé à la demande en cas de besoin.

Avec cette structure, vous pouvez installer de nombreuses compétences sans faire exploser la fenêtre contextuelle. Si vous continuez à copier-coller la même longue invite, transformez-la simplement en compétence.

3. Compétences vs MCP vs sous-agents

Avant de créer une compétence, laissez-moi vous expliquer en quoi les compétences, le MCP et les sous-agents sont différents, afin que vous puissiez vous assurer qu’une compétence est le bon choix.

• Compétences Apprenez à Claude comment se comporter : flux de travail d’analyse, normes de codage, directives de marque.
• Serveurs MCP donnez à Claude de nouveaux outils : envoyer un message Slack, interroger une base de données.
• Sous-agents laissez Claude diriger un travail indépendant dans un contexte séparé.

Une analogie qui m’a aidé : MCP, c’est la cuisine : couteaux, casseroles, ingrédients. Une compétence est la recette qui vous indique comment les utiliser. Vous pouvez les combiner. La compétence de révision de code de Sentry, par exemple, définit le flux de travail d’analyse des relations publiques dans une compétence et récupère les données d’erreur via MCP. Mais dans de nombreux cas, une seule compétence suffit pour démarrer.

4. Planification et conception

Je me suis lancé directement dans l’écriture de SKILL.md la première fois et j’ai rencontré des problèmes. Si la description n’est pas bien conçue, la compétence ne se déclenchera même pas. Je dirais de consacrer du temps à la conception avant d’écrire les invites ou le code.

4a. Commencez par les cas d’utilisation

La première chose à faire est de définir 2 à 3 cas d’utilisation concrets. Il ne s’agit pas d’une « compétence utile » dans l’abstrait, mais d’un véritable travail répétitif que vous observez dans la pratique.

Permettez-moi de partager mon propre exemple. J’ai remarqué que de nombreux collègues et moi répétions les mêmes revues d’activité mensuelles et trimestrielles. Dans le commerce électronique et la vente au détail, le processus de décomposition des KPI a tendance à suivre un schéma similaire.

C’était le point de départ. Au lieu de créer une « compétence d’analyse de données » générique, je l’ai définie comme ceci : « Une compétence qui prend les données CSV en ordre, décompose les KPI en une arborescence, résume les résultats avec des priorités et génère un plan d’action concret. »

Ici, il est important d’imaginer comment les utilisateurs formuleront réellement leurs demandes :

• « faire un examen de ma boutique en utilisant ce fichier commandes.csv »
• « Analysez les données de ventes des 90 derniers jours et expliquez pourquoi les revenus ont chuté »
• « Comparez le troisième trimestre au quatrième trimestre, trouvez les 3 principales choses que je devrais corriger »

Lorsque vous écrivez d’abord des invites concrètes comme celles-ci, la forme de la compétence devient claire. L’entrée est CSV. L’axe d’analyse est la décomposition des KPI. Le résultat est un rapport d’examen et un plan d’action. L’utilisateur n’est pas un data scientist : c’est quelqu’un qui dirige une entreprise et il veut savoir quoi faire ensuite.

Ce niveau de détail façonne tout le reste : nom de la compétence, description, formats de fichier, format de sortie.

Questions à poser lors de la définition des cas d’utilisation :

• Qui va l’utiliser ?
• Dans quelle situation ?
• Comment vont-ils formuler leur demande ?
• Quelle est l’entrée ?
• Quel est le résultat attendu ?

4b. Frontière YAML

Une fois les cas d’utilisation clairs, écrivez le nom et la description. Il décide si votre compétence se déclenche réellement.

Comme je l’ai mentionné plus tôt, Claude ne voit les métadonnées que pour décider quelle compétence charger. Lorsqu’une demande d’utilisateur arrive, Claude décide quelles compétences charger en fonction de ces seules métadonnées. Si la description est vague, Claude n’atteindra jamais la Compétence, quelle que soit la qualité des instructions données dans le corps.

Pour rendre les choses plus compliquées, Claude a tendance à gérer seule des tâches simples sans consulter Skills. Par défaut, il ne se déclenche pas. Votre description doit donc être suffisamment précise pour que Claude reconnaisse « c’est un travail pour la compétence, pas pour moi ».

La description doit donc être quelque peu « insistante ». Voici ce que je veux dire.

# Bad — too vague. Claude does not know when to trigger.
name: data-helper
description: Helps with data tasks

# Good — specific trigger conditions, slightly "pushy"
name: sales-data-analyzer
description: >
  Analyze sales/revenue CSV and Excel files to find patterns,
  calculate metrics, and create visualizations. Use when user
  mentions sales data, revenue analysis, profit margins, churn,
  ad spend, or asks to find patterns in business metrics.
  Also trigger when user uploads xlsx/csv with financial or
  transactional column headers.

La chose la plus importante est d’être explicite sur ce que fait la Skill et sur les entrées qu’elle attend : « Analyser les fichiers CSV et Excel des ventes/revenus » ne laisse aucune ambiguïté. Après cela, répertoriez les mots-clés déclencheurs. Revenez aux invites de cas d’utilisation que vous avez écrites en 4a et extrayez les mots que les utilisateurs disent réellement : données de ventes, analyse des revenus, marges bénéficiaires, désabonnement. Enfin, pensez aux cas où l’utilisateur ne mentionne pas nommément votre Skill. « Déclenchez également lorsque l’utilisateur télécharge des fichiers xlsx/csv avec des en-têtes de colonnes financières ou transactionnelles » détecte ces correspondances silencieuses.

Les contraintes sont les suivantes : nom jusqu’à 64 caractères, description jusqu’à 1 024 caractères (conformément à la spécification de l’API Agent Skills). Vous avez de la place, mais donnez la priorité aux informations qui affectent directement le déclenchement.

5. Modèles de mise en œuvre

Une fois la conception définie, passons à la mise en œuvre. Tout d’abord, comprenez la structure du fichier, puis choisissez le bon modèle.

5a. Structure du fichier

La structure physique d’une Compétence est simple :

my-skill/
├── SKILL.md              # Required. YAML frontmatter + Markdown instructions
├── scripts/              # Optional. Python/JS for deterministic processing
│   ├── analyzer.py
│   └── validator.js
├── references/           # Optional. Loaded by Claude as needed
│   ├── advanced-config.md
│   └── error-patterns.md
└── assets/               # Optional. Templates, fonts, icons, etc.
    └── report-template.docx

Seul SKILL.md est requis. Cela seul constitue une compétence fonctionnelle. Essayez de garder SKILL.md sous 500 lignes. S’il devient plus long, déplacez le contenu dans le répertoire references/ et dites à Claude dans SKILL.md où chercher. Claude ne lira pas les fichiers de référence à moins que vous ne le pointiez là.

Pour les compétences qui se regroupent par domaine, l’approche variable fonctionne bien :

cloud-deploy/
├── SKILL.md              # Shared workflow + selection logic
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

Claude lit uniquement le fichier de référence pertinent en fonction du contexte de l’utilisateur.

5b. Modèle A : invite uniquement

Le modèle le plus simple. Juste des instructions Markdown dans SKILL.md, pas de scripts.

Bon pour : directives de marque, normes de codage, listes de contrôle de révision, formatage des messages de validation, application du style d’écriture.

Quand utiliser : Si les capacités linguistiques et le jugement de Claude sont suffisants pour la tâche, utilisez ce modèle.

Voici un exemple compact :

---
name: commit-message-formatter
description: >
  Format git commit messages using Conventional Commits.
  Use when user mentions commit, git message, or asks to
  format/write a commit message.
---

# Commit Message Formatter

Format all commit messages following Conventional Commits 1.0.0.

## Format
<type>(<scope>): <description>

## Rules
- Imperative mood, lowercase, no period, max 72 chars
- Breaking changes: add `!` after type/scope

## Example
Input: "added user auth with JWT"
Output: `feat(auth): implement JWT-based authentication`

C’est ça. Pas de scripts, pas de dépendances. Si le jugement de Claude suffit à la tâche, c’est tout ce dont vous avez besoin.

5c. Modèle B : invite + scripts

Instructions Markdown et code exécutable dans le répertoire scripts/.

Bon pour : transformation/validation de données, traitement PDF/Excel/image, génération de documents basés sur des modèles, rapports numériques.

Langues prises en charge: Python et JavaScript/Node.js. Voici un exemple de structure :

data-analysis-skill/
├── SKILL.md
└── scripts/
    ├── analyze.py          # Main analysis logic
    └── validate_schema.js  # Input data validation

Dans SKILL.md, vous spécifiez quand appeler chaque script :

## Workflow

1. User uploads a CSV or Excel file
2. Run `scripts/validate_schema.js` to check column structure
3. If validation passes, run `scripts/analyze.py` with the file path
4. Present results with visualizations
5. If validation fails, ask user to clarify column mapping

Le SKILL.md définit le « quand et pourquoi ». Les scripts gèrent le « comment ».

5j. Modèle C : Compétence + MCP / Sous-agent

Ce modèle appelle des serveurs MCP ou des sous-agents à partir du flux de travail de la compétence. Idéal pour les flux de travail impliquant des services externes : pensez à créer un problème → créer une branche → corriger le code → ouvrir les relations publiques. Plus de pièces mobiles signifie plus de choses à déboguer, je vous recommande donc de vous familiariser d’abord avec le modèle A ou B.

Choisir le bon modèle

Si vous ne savez pas quel modèle choisir, suivez cet ordre :

• Besoin d’une communication en temps réel avec des API externes ? → Oui → Modèle C
• Besoin de traitements déterministes comme des calculs, une validation ou une conversion de fichiers ? → Oui → Modèle B
• La capacité linguistique et le jugement de Claude suffisent-ils ? → Oui → Modèle A

En cas de doute, commencez par le modèle A. Il est facile d’ajouter des scripts plus tard et d’évoluer vers le modèle B. Mais simplifier une compétence trop complexe est plus difficile.

6. Tests

L’écriture du SKILL.md n’est pas la fin. Ce qui rend une compétence bonne, c’est la quantité de tests et d’itérations que vous faites.

6a. Écriture d’invites de test

« Test » ici ne signifie pas tests unitaires. Cela signifie lancer de véritables invites sur la compétence et vérifier si elle se comporte correctement.

La seule règle pour les invites de test : écrivez-les de la manière dont les vrais utilisateurs parlent réellement.

# Good test prompt (realistic)
"ok so my boss just sent me this XLSX file (its in my downloads,
called something like 'Q4 sales final FINAL v2.xlsx') and she wants
me to add a column that shows the profit margin as a percentage.
The revenue is in column C and costs are in column D i think"

# Bad test prompt (too clean)
"Please analyze the sales data in the uploaded Excel file
and add a profit margin column"

Le problème avec les invites de test claires est qu’elles ne reflètent pas la réalité. Les vrais utilisateurs font des fautes de frappe, utilisent des abréviations occasionnelles et oublient les noms de fichiers. Une compétence testée uniquement avec des invites claires se brisera de manière inattendue en production.

6b. La boucle d’itération

La boucle de test de base est simple :

1. Exécutez la compétence avec des invites de test
2. Évaluez si le résultat correspond à ce que vous avez défini comme un bon résultat en 4a.
3. Corrigez le SKILL.md si nécessaire
4. Revenir à 1

Vous pouvez exécuter cette boucle manuellement, mais le créateur de compétences d’Anthropic peut être d’une grande aide. Il automatise semi-automatisé la génération, l’exécution et la révision des cas de test. Il utilise une répartition train/test pour l’évaluation et vous permet d’examiner les sorties dans une visionneuse HTML.

6c. Optimiser la description

Pendant vos tests, vous constaterez peut-être que la compétence fonctionne bien lorsqu’elle est déclenchée, mais ne se déclenche pas assez souvent. Le créateur de compétences dispose d’une boucle d’optimisation intégrée pour cela : il divise les cas de test 60/40 en entraînement/test, mesure le taux de déclenchement, génère des descriptions améliorées et sélectionne le meilleur par score de test.

Une chose que j’ai apprise : Claude déclenche rarement des compétences pour des requêtes courtes et simples. Assurez-vous donc que votre ensemble de tests comprend des invites suffisamment complexes.

7. Répartition

Une fois votre compétence prête, vous devez la transmettre aux utilisateurs. La meilleure méthode dépend si elle s’adresse uniquement à vous, à votre équipe ou à tout le monde.

Transmettre vos compétences aux utilisateurs

Pour la plupart des gens, deux méthodes couvrent tout :

Téléchargement ZIP (claude.ai) : ZIP le dossier Skill et téléchargez-le via Paramètres > Personnaliser > Compétences. Un problème : le ZIP doit contenir le dossier lui-même à la racine, pas seulement le contenu.

Répertoire .claude/skills/ (Claude Code) : Placez la compétence dans le dépôt de votre projet sous .claude/skills/. Lorsque les coéquipiers clonent le dépôt, tout le monde obtient la même compétence.

Au-delà de celles-ci, il existe d’autres options à mesure que vos besoins de distribution augmentent : le Plugin Marketplace pour la distribution open source, l’Anthropic Official Marketplace pour une portée plus large, le Vercel’s npx skills add pour les installations multi-agents et l’API Skills pour la gestion programmatique. Je n’entrerai pas dans les détails de chacun ici – la documentation les couvre bien.

Avant de partager, vérifiez trois choses : le ZIP a le dossier à la racine (pas seulement le contenu), le sujet principal a à la fois le nom et la description dans les limites de caractères, et il n’y a pas de clé API codée en dur.

Et encore une chose : modifiez le champ de version lors de la mise à jour. Sinon, la mise à jour automatique ne démarrera pas. Traitez les commentaires des utilisateurs comme « cela ne s’est pas déclenché à cette invite » comme de nouveaux cas de test. La boucle d’itération de la section 6 ne s’arrête pas au lancement.

Conclusion

Une compétence est une invite réutilisable avec une structure. Vous regroupez ce que vous savez sur un domaine dans quelque chose que d’autres peuvent installer et exécuter.

Le flux : décidez si vous avez besoin d’une compétence, d’un MCP ou d’un sous-agent. Concevez à partir de cas d’utilisation et rédigez une description qui déclenche réellement. Choisissez le modèle le plus simple qui fonctionne. Testez avec des invites désordonnées et réalistes. Expédiez-le et continuez à itérer.

Les compétences sont encore nouvelles et il y a beaucoup de place. Si vous continuez à faire la même analyse, la même révision, le même travail de formatage, encore et encore, cette répétition est votre compétence qui attend d’être construite.

Si vous avez des questions ou souhaitez partager ce que vous avez construit, retrouvez-moi sur LinkedIn.