Un Claude Skill sert à transformer une instruction répétée en configuration permanente.

Au lieu de recopier à chaque session les mêmes règles de ton, de format, de méthode ou de workflow, ces règles sont stockées une fois dans un fichier dédié que Claude peut mobiliser automatiquement lorsque la demande correspond.

L’enjeu n’est donc pas seulement d’écrire de meilleurs prompts, mais de réduire la répétition opérationnelle. Une tâche devient réellement exploitable lorsqu’elle est :

décrite avec précision
déclenchée par des formulations reconnaissables
testée sur des cas concrets
et maintenue comme un élément réutilisable du système de travail.

Distinction centrale repose sur trois niveaux :

les Projects servent de base de connaissances
les Skills définissent des procédures d’exécution
et MCP connecte Claude à des sources de données vivantes comme un calendrier, une base de données ou une boîte mail.

Un Skill indique ensuite quoi faire avec ces informations.

Un bon critère de décision est simple : lorsqu’une même consigne a été tapée au début de plus de trois conversations, elle peut être transformée en Skill.

Ce qu’est réellement un Claude Skill

Un Skill est un dossier local contenant un fichier nommé exactement SKILL.md. Ce fichier contient des instructions permanentes décrivant comment Claude doit accomplir une tâche précise. Il ne s’agit pas d’un prompt temporaire, ni d’un fichier de contexte, ni d’une base documentaire statique.

La logique est procédurale : un Skill décrit une manière de faire. Il peut encadrer une tâche comme nettoyer un CSV, reformater un e-mail, appliquer une voix de marque, analyser des données ou produire un livrable selon une structure stable.

La structure minimale est la suivante :

your-skill-name/
├── SKILL.md
└── references/
    └── your-ref.md

Le nom du dossier suit une convention en kebab-case : minuscules, mots séparés par des tirets, sans espaces, sans underscores et sans majuscules. Le fichier principal doit impérativement s’appeler SKILL.md, avec la casse exacte.

Le dossier references/ est optionnel. Il accueille les documents de support trop longs pour être intégrés directement dans le fichier principal : guide de marque, modèle de sortie, règles éditoriales, documentation de référence ou fiche de style.

Le Skill est placé dans :

~/.claude/skills/

Claude le détecte ensuite automatiquement. Il n’est pas nécessaire de l’activer manuellement si la demande correspond aux déclencheurs définis.

Projects, Skills et MCP : trois fonctions différentes

Les Projects correspondent à une base de connaissances. Ils contiennent des documents, des références et des éléments stables que Claude doit connaître. Leur rôle est informationnel : ils répondent à la question “que faut-il savoir ?”.

Les Skills correspondent à une méthode d’exécution. Ils indiquent à Claude comment réaliser une tâche, dans quel ordre, avec quelles règles, quels formats de sortie et quelles limites. Leur rôle est procédural : ils répondent à la question “comment faut-il faire ?”.

MCP joue le rôle de couche de connexion. Il relie Claude à des sources dynamiques : calendrier, inbox, base de données ou autres systèmes vivants. Le Skill peut alors définir ce que Claude doit faire avec les données accessibles.

Cette séparation évite de mélanger connaissance, procédure et connexion. Une base de connaissances seule ne suffit pas à produire un workflow fiable. Une procédure seule manque parfois de contexte. Une connexion seule ne décide pas quoi faire des données.

Définir le travail avec précision

La qualité d’un Skill dépend d’abord de la précision de sa définition. Une instruction vague produit un comportement vague. Une instruction claire permet à Claude de savoir quand agir, quoi produire et comment évaluer la qualité du résultat.

Trois questions structurent la définition :

Que fait exactement ce Skill ?
Quand doit-il se déclencher ?
À quoi ressemble un bon résultat ?

Une formulation faible serait du type “aider avec les données”. Elle ne précise ni le type de données, ni la transformation attendue, ni le format de sortie, ni les limites.

Une formulation opérationnelle serait : transformer des fichiers CSV désordonnés en tableaux propres, corriger les en-têtes, imposer un format de date YYYY-MM-DD et supprimer les lignes vides.

La différence se joue dans la spécificité. Le Skill doit décrire un travail observable, testable et vérifiable.

Les déclencheurs doivent reprendre les formulations que l’utilisateur taperait réellement : “Clean up this CSV”, “Fix these headers”, “Format this data”. Ces formulations servent à guider l’activation automatique.

Le standard de qualité doit inclure un avant/après concret. Une description abstraite est moins utile qu’un exemple montrant l’entrée attendue et le résultat final.

Le rôle décisif du YAML

Le fichier SKILL.md commence par un bloc de métadonnées YAML placé entre deux lignes ---. Ce bloc indique à Claude quand le Skill doit être activé.

Exemple :

---
name: csv-cleaner
description: Transforms messy CSV files into clean spreadsheets with proper headers. Use this skill whenever the user says 'clean up this CSV', 'fix the headers', 'format this data', or 'organise this spreadsheet'. Do NOT use for PDFs, Word documents, or image files.
---

Le champ description est l’élément le plus important pour l’activation. S’il est trop faible, le Skill ne se déclenche pas. S’il est trop large, il se déclenche à tort.

Trois règles structurent une bonne description :

Elle doit être écrite à la troisième personne.
Elle doit inclure plusieurs formulations de déclenchement explicites.
Elle doit fixer des limites négatives.

Les limites négatives sont essentielles. Elles indiquent quand le Skill ne doit pas être utilisé. Un Skill destiné aux CSV doit exclure les PDF, les documents Word ou les images si ces formats ne relèvent pas de son périmètre.

Une description efficace ne se contente donc pas de dire ce que le Skill fait. Elle précise aussi ce qu’il ne doit pas faire.

Construire les instructions d’exécution

Après le bloc YAML, le fichier contient les instructions proprement dites. Elles doivent être rédigées en langage direct, structurées par étapes et suffisamment précises pour éviter les interprétations multiples.

Une bonne instruction utilise l’impératif : “Read the file”, “Identify the header row”, “Remove empty rows”. Chaque étape doit correspondre à une action claire.

Une structure utile comprend généralement :

## Workflow

1. Read the provided file to understand its structure.
2. Identify the row containing the true column headers.
3. Remove any empty rows or rows containing only commas.
4. Enforce proper data types.
5. Output the cleaned file with a summary of changes made.

## Output Format

Return a cleaned CSV file and a brief summary listing:
- Number of rows removed
- Number of date formats corrected
- Any columns with mixed data types that need manual review

## Edge Cases

- If the file has no clear header row, use the first non-empty row and flag it for confirmation.
- If a date column contains values that cannot be parsed, keep the original value and mark it with `[REVIEW]`.
- If the file is not a CSV, indicate that the format is incorrect.

L’objectif est d’empêcher les consignes floues. Une phrase comme “format nicely” laisse trop de marge. Une consigne comme “Use H2 headings for each section, bold the first sentence, keep paragraphs to 3 lines max” devient vérifiable.

Les exemples jouent un rôle central. Un exemple réel d’entrée et de sortie attendue vaut davantage qu’une longue description abstraite. Il permet de fixer le niveau de qualité, la structure, les limites et les cas particuliers.

Gérer les références sans saturer le contexte

Lorsqu’un Skill dépend d’un guide de marque, d’un modèle ou d’un document trop long, ces éléments peuvent être placés dans le dossier references/.

Exemple :

Before beginning the task, read the brand voice guide at references/brand-voice-guide.md.

La règle importante est celle du niveau unique : les fichiers de référence ne doivent pas renvoyer vers d’autres fichiers de référence. Claude risque sinon de tronquer sa lecture ou de manquer des informations.

Une référence volumineuse doit être compressée avant d’être intégrée. Il ne s’agit pas de conserver un document complet si seules quelques pages sont réellement utiles au Skill. Les éléments pertinents doivent être extraits dans une version courte et directement exploitable.

Le principe est de fournir assez d’information pour guider l’exécution, sans charger inutilement le contexte.

Déploiement et activation

Une fois le dossier prêt, il suffit de le placer dans :

~/.claude/skills/

Claude lit les descriptions disponibles, les compare à la demande utilisateur et sélectionne le Skill le plus pertinent.

L’activation repose donc sur la correspondance entre la demande et le champ description. Il n’est pas nécessaire d’écrire “utilise ce Skill” si les déclencheurs sont bien définis.

Les Skills fonctionnent dans Claude Code et dans Claude Desktop/Cowork, mais leur contexte d’exécution diffère. Claude Code peut accéder au système de fichiers et exécuter du code. Claude Desktop/Cowork fonctionne davantage comme une interface agentique orientée environnement de bureau.

Tester au lieu de supposer

Un Skill qui fonctionne deux fois n’est pas nécessairement fiable. Les cas limites apparaissent souvent après les premiers essais. Tester un Skill permet de vérifier qu’il respecte réellement les règles de ton, de format, de structure et de périmètre.

Les évaluations permettent de générer des prompts de test, d’exécuter le Skill et de vérifier si les sorties respectent les instructions. Le résultat peut indiquer, par exemple, qu’un Skill passe 7 tests sur 9 et préciser où il échoue.

La boucle correcte est la suivante :

lancer l’évaluation ;
lire les échecs ;
modifier le Skill pour corriger le problème précis ;
relancer l’évaluation ;
répéter jusqu’à obtention d’un comportement stable.

Le benchmarking A/B permet de comparer une sortie produite avec Skill et une sortie produite sans Skill. Cette comparaison est importante parce qu’un Skill ancien peut devenir moins performant qu’un modèle plus récent utilisé sans contrainte. Dans ce cas, le Skill rigidifie inutilement la production.

L’optimisation de la description cible le problème d’activation. Si le Skill ne se déclenche pas au bon moment, le défaut vient souvent du YAML. Une description enrichie en déclencheurs, contextes et exclusions améliore la précision.

Organiser plusieurs Skills sans conflit

Les conflits apparaissent lorsque plusieurs Skills couvrent des territoires proches. Une demande d’e-mail peut déclencher un Skill de reformulation de contenu au lieu d’un Skill de rédaction d’e-mail. Un extrait de code peut activer un Skill de revue de code alors que la demande porte seulement sur le formatage.

Trois règles limitent ce problème :

chaque Skill doit avoir un territoire clairement distinct ;
chaque description YAML doit exclure les territoires des autres Skills ;
les formulations de déclenchement doivent être différenciées.

Un Skill de voix de marque vérifie la conformité du ton. Un Skill de rédaction d’e-mail compose des e-mails. Un Skill de repurposing transforme un contenu vers un autre format. Ces périmètres ne doivent pas se recouvrir.

Les exclusions explicites évitent les activations erronées. Un Skill de rédaction d’e-mail peut préciser : ne pas utiliser pour les vérifications de voix de marque ou la transformation de contenu. Un Skill de voix de marque peut préciser : ne pas utiliser pour rédiger un e-mail depuis zéro.

Ajouter des scripts lorsque le langage ne suffit pas

Certaines tâches nécessitent du calcul, du parsing ou une manipulation précise de fichiers. Un Skill peut alors contenir un dossier scripts/ avec des fichiers Python.

Structure possible :

data-analyser/
├── SKILL.md
├── references/
│   └── analysis-template.md
└── scripts/
    ├── parse-csv.py
    └── calculate-stats.py

Le fichier SKILL.md doit indiquer exactement quand et comment exécuter les scripts :

Run scripts/parse-csv.py [input_file] [output_file] to clean the data.

Les scripts doivent rester ciblés : un script, une fonction principale. Ils doivent accepter des arguments en ligne de commande plutôt que contenir des chemins codés en dur. Ils doivent aussi prévoir des messages d’erreur clairs que Claude peut lire et restituer.

La logique est partagée : les scripts assurent la précision technique, tandis que les instructions du Skill assurent l’interprétation, le jugement et la structuration du résultat.

Charger les références de façon conditionnelle

Un Skill peut devenir trop lourd s’il charge systématiquement un guide de marque de 50 pages, un manuel de style de 30 pages et une bibliothèque de modèles.

La solution consiste à fractionner les références en fichiers ciblés et à définir des conditions de chargement.

Exemples de logique :

si la demande porte sur le ton, charger la référence courte sur la voix ;
si la demande porte sur la mise en forme visuelle, charger la référence de style ;
si les références courtes ne suffisent pas, charger le document complet.

Cette logique évite de consommer inutilement le contexte et améliore la précision du Skill.

Maintenir la continuité entre sessions

Lorsqu’un Skill sert à gérer un travail long — écrire un livre, construire une application, suivre un projet sur plusieurs semaines — le contexte finit par se remplir. Claude peut perdre la trace de ce qui a été décidé ou terminé.

Le modèle de passage de relais repose sur un fichier de suivi :

At the start of every session, read context-log.md to see what we completed last time. At the end of every session, write a summary of what you finished and what's still pending.

Le fichier context-log.md sert de mémoire de transition. Il indique ce qui a été accompli, ce qui reste à faire et les décisions à conserver. Le Skill peut ainsi reprendre le travail sans repartir de zéro.

Les cinq modes d’échec

Un Skill peut échouer de cinq façons principales.

Le Skill silencieux ne se déclenche pas. La description YAML ne correspond pas assez fortement aux formulations de l’utilisateur. La correction consiste à ajouter des déclencheurs, des contextes et des formulations plus explicites.

Le Skill pirate se déclenche sur de mauvaises demandes. La description est trop large ou manque d’exclusions. La correction consiste à resserrer le périmètre et à ajouter des limites négatives.

Le Skill dérivant se déclenche correctement mais produit une sortie incorrecte. Les instructions sont ambiguës. La correction consiste à remplacer chaque phrase interprétable de plusieurs manières par une instruction vérifiable.

Le Skill fragile fonctionne sur les cas simples mais échoue sur les entrées dégradées. La correction consiste à tester les pires scénarios : champs manquants, formats incorrects, données corrompues, demandes ambiguës.

Le Skill surproductif ajoute des éléments non demandés. Les instructions disent quoi faire, mais pas quoi ne pas faire. La correction consiste à ajouter des contraintes de périmètre : ne pas ajouter de commentaire, d’explication ou de suggestion si cela n’est pas demandé.

Le mode le plus dangereux est la dérive. Le Skill semble fonctionner, la sortie paraît correcte, mais elle s’écarte progressivement des standards attendus.

Mise en pratique

Identifier la consigne répétée le plus souvent.
La priorité doit aller à une tâche déjà récurrente : formatage, rédaction, analyse, nettoyage, synthèse, production d’un livrable ou application d’une méthode stable.
Décrire la tâche en une phrase précise.
La phrase doit contenir l’action, le type d’entrée, la transformation attendue et le résultat final. Une tâche vague doit être resserrée avant toute création de Skill.
Lister les déclencheurs réels.
Les formulations doivent correspondre aux phrases que l’utilisateur tape naturellement. Il faut inclure plusieurs variantes, pas une seule formule idéale.
Définir les limites négatives.
Chaque Skill doit dire clairement ce qui ne relève pas de son périmètre. Cette étape évite les activations abusives.
Écrire le YAML.
Le champ name doit être en kebab-case. Le champ description doit résumer l’usage, contenir les déclencheurs et fixer les exclusions.
Rédiger le workflow.
Les étapes doivent être numérotées, impératives et testables. Chaque instruction doit réduire l’ambiguïté.
Ajouter le format de sortie.
Le Skill doit indiquer exactement ce qu’il doit produire : fichier, résumé, liste de changements, structure Markdown, tableau ou autre format attendu.
Prévoir les cas limites.
Les entrées incomplètes, les formats inattendus et les ambiguïtés doivent être traités explicitement.
Ajouter les références nécessaires seulement.
Les fichiers longs doivent être compressés. Les références doivent rester à un seul niveau. Les URLs ou chemins utiles doivent rester proches des éléments qu’ils justifient.
Tester et corriger.
Un Skill doit être évalué, comparé et ajusté. La fiabilité vient de l’itération, pas de la première version.

Erreurs à éviter

Transformer une consigne vague en Skill

Un Skill ne compense pas une définition imprécise. Automatiser une instruction floue ne fait que stabiliser un mauvais comportement.

Négliger le champ `description`

Le YAML détermine l’activation. Une description trop faible rend le Skill invisible. Une description trop large le rend intrusif.

Oublier les exclusions

Un Skill doit dire quand il ne doit pas s’activer. Sans limites négatives, plusieurs Skills peuvent se concurrencer ou répondre à la mauvaise tâche.

Écrire des instructions interprétables

Les formulations comme “bien structurer”, “améliorer”, “rendre propre” ou “formater joliment” laissent trop d’espace. Une instruction utile décrit un comportement observable.

Mettre trop de références

Charger des documents volumineux par défaut consomme le contexte et affaiblit l’exécution. Les références doivent être courtes, ciblées et chargées selon le besoin.

Créer des références imbriquées

Un fichier de référence ne doit pas pointer vers un autre fichier de référence. La structure doit rester lisible en un seul niveau.

Ne pas tester les cas dégradés

Un Skill qui fonctionne seulement sur des entrées propres reste fragile. Les cas limites doivent être prévus dès la conception.

Garder un Skill devenu moins performant

Un modèle plus récent peut parfois produire de meilleurs résultats sans Skill. Le benchmarking permet de repérer les Skills devenus trop rigides.

Multiplier les Skills sans architecture

À partir de plusieurs Skills, les périmètres doivent être clairement séparés. Sinon, les déclencheurs se chevauchent et le mauvais Skill peut prendre la main.

La synthèse utile

Un Claude Skill est une procédure permanente destinée à exécuter une tâche récurrente avec moins de répétition, plus de cohérence et davantage de contrôle. Sa valeur dépend de quatre éléments : une définition précise, une description YAML robuste, des instructions testables et une boucle d’évaluation.

Le bon arbitrage consiste à transformer uniquement les tâches réellement répétées, pas toutes les tâches possibles. Un Skill doit être assez spécifique pour se déclencher au bon moment, assez cadré pour éviter les dérives, et assez testé pour résister aux cas imparfaits.

La méthode correcte suit une progression simple : définir la tâche, écrire les déclencheurs, fixer les exclusions, structurer le workflow, ajouter les références nécessaires, déployer, tester, corriger. Les scripts peuvent compléter le Skill lorsque la précision technique dépasse ce que le langage seul peut garantir.

L’erreur principale consiste à confondre accumulation d’instructions et système fiable. Un Skill n’est pas meilleur parce qu’il est long. Il devient utile lorsqu’il décrit clairement quoi faire, quand le faire, comment le faire, quoi produire et quoi éviter.