Claude Skills : guide complet des Agent Skills (SKILL.md)

Un Claude Skill est un dossier contenant un fichier SKILL.md qui apprend à Claude comment réaliser une tâche précise : une procédure, des conventions, un savoir-faire métier. Claude ne lit ce fichier que lorsque votre demande correspond à sa description, ce qui permet d’installer des dizaines de skills sans alourdir la conversation.

Le format a changé d’échelle en un an. Le 22 octobre 2026, Anthropic a confié le standard Agent Skills à l’Agentic AI Foundation, la fondation de la Linux Foundation qui héberge déjà MCP. Au moment de l’annonce, Anthropic recense plus de 70 plateformes compatibles, 1 million de skills publiés et près de 280 millions d’installations, dont ChatGPT, Cursor, GitHub Copilot et VS Code.

J’utilise les skills au quotidien : la chaîne éditoriale de ce blog repose sur une quinzaine de skills Claude Code (rédaction, relecture, illustrations, publication). Ce guide reprend ce que j’aurais aimé lire avant d’écrire le premier : la structure exacte d’un skill, où l’installer selon votre produit Claude, un premier skill pas à pas, la frontière avec MCP, les hooks et les mods, et la question de sécurité que trop de tutoriels ignorent.

Qu’est-ce qu’un Claude Skill exactement ?

Un skill est un dossier, pas un fichier isolé. Au minimum, il contient un SKILL.md ; il peut aussi embarquer des scripts, de la documentation de référence et des modèles de fichiers. La spécification officielle recommande cette organisation :

mon-skill/
├── SKILL.md          # Obligatoire : métadonnées + instructions
├── scripts/          # Optionnel : code exécutable
├── references/       # Optionnel : documentation détaillée
└── assets/           # Optionnel : modèles, images, données

Anthropic compare un skill à un guide d’intégration que vous remettriez à un nouveau collaborateur : plutôt que de réexpliquer votre façon de travailler à chaque conversation, vous la consignez une fois dans un dossier versionné.

L’en-tête YAML : name et description

Le fichier SKILL.md commence obligatoirement par un bloc YAML entre deux lignes ---. Deux champs sont requis par la spécification :

La description est le champ qui conditionne tout. Si elle se limite à « Aide avec les PDF », Claude ne saura pas quand déclencher le skill.

La documentation d’Anthropic recommande d’y inclure à la fois l’action et les déclencheurs : « Extrait le texte et les tableaux des fichiers PDF, remplit des formulaires, fusionne des documents. À utiliser quand l’utilisateur mentionne un PDF, un formulaire ou une extraction de document. »

Deux règles moins connues : le nom ne peut pas contenir les mots réservés « anthropic » et « claude », et la description doit être rédigée à la troisième personne, car elle est injectée dans le prompt système.

Seules les métadonnées (~100 tokens par skill) sont chargées au démarrage ; le corps du SKILL.md et les ressources n’entrent dans le contexte qu’à la demande.

Le chargement progressif en trois niveaux

C’est le mécanisme qui distingue un skill d’un simple prompt système. Claude ne charge pas tout d’un coup : il procède en trois étapes, et seule l’information utile occupe la fenêtre de contexte.

Le point le plus intéressant concerne les scripts : quand Claude exécute scripts/valider.py, le code du script n’entre jamais dans le contexte. Seule sa sortie (« Validation réussie » ou un message d’erreur) consomme des tokens. C’est ce qui rend un skill avec scripts plus fiable et moins coûteux que de demander à Claude de régénérer le même code à chaque fois.

Conséquence pratique : la documentation Agent Skills recommande de garder le corps de SKILL.md sous 500 lignes et de déplacer le reste dans des fichiers référencés, à un seul niveau de profondeur. Au-delà, Claude a tendance à ne lire que le début des fichiers imbriqués.

Où utiliser les skills : Claude Code, claude.ai, API et Agent SDK

Les skills fonctionnent sur les quatre surfaces de l’écosystème Claude, mais ils ne se synchronisent pas automatiquement de l’une à l’autre. Un skill importé sur claude.ai n’est pas disponible via l’API, et inversement. Voici où les placer selon votre usage.

Dans Claude Code

C’est l’environnement le plus souple. Claude Code lit les skills à six emplacements, par ordre de priorité : le dossier géré par votre organisation, ~/.claude/skills/ pour vos skills personnels, .claude/skills/ à la racine du projet, les sous-dossiers .claude/skills/ d’un monorepo, les répertoires passés avec --add-dir, et le dossier skills/ d’un plugin (accessible sous la forme /plugin:skill).

Depuis 2026, les skills remplacent les anciennes commandes slash personnalisées : .claude/commands/deploy.md et .claude/skills/deploy/SKILL.md créent tous deux la commande /deploy. Les anciens fichiers continuent de fonctionner, mais la documentation désigne les skills comme successeur. Si vous débutez, mon guide complet de Claude Code couvre l’installation et le fichier CLAUDE.md, qui reste le bon endroit pour le contexte permanent du projet (le skill, lui, est contextuel).

Claude Code ajoute une dizaine de champs YAML propres à l’outil : disable-model-invocation (seul vous pouvez lancer le skill), user-invocable: false (seul Claude peut le déclencher), context: fork (exécution dans un sous-agent), model et effort (surcharge pour le tour en cours), hooks, paths (activation limitée à certains fichiers) ou encore arguments pour des paramètres nommés. Ces champs sont ignorés par les autres plateformes.

Sur claude.ai

Anthropic fournit quatre skills prêts à l’emploi, actifs sans configuration : PowerPoint (pptx), Excel (xlsx), Word (docx) et PDF (pdf). Ils s’activent dès que vous demandez la création d’un document.

Pour vos propres skills, compressez le dossier en .zip (le dossier du skill doit être la racine de l’archive) et importez-le dans Personnaliser > Skills. Le centre d’aide de Claude indique une disponibilité sur tous les plans, Free compris, dès lors que l’exécution de code est activée ; la documentation développeur mentionne encore Pro, Max, Team et Enterprise. Les skills activés sur votre compte claude.ai se synchronisent ensuite dans Claude Code, en lecture seule, dans ~/.claude/skills/synced/.

Via l’API Claude et l’Agent SDK

Dans l’API, les skills s’exécutent dans le conteneur de l’outil d’exécution de code (code_execution_20250825), qui est un prérequis. Vous envoyez vos fichiers sur POST /v1/skills (30 Mo maximum, décompressé), puis vous référencez le skill_id obtenu dans le paramètre container d’un appel Messages. Un conteneur accepte jusqu’à 20 skills par requête, et chaque nouvelle version est un instantané complet : les fichiers omis ne sont pas reportés. Si vous n’avez jamais appelé l’API, mon guide de l’API Claude détaille la création de clé et le premier appel.

import anthropic
from anthropic.lib import files_from_dir

client = anthropic.Anthropic()
skill = client.skills.create(files=files_from_dir("analyse-financiere"))

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={"skills": [{"type": "custom", "skill_id": skill.id, "version": "latest"}]},
    messages=[{"role": "user", "content": "Analyse les ventes du trimestre"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Avec l’Agent SDK (Python ou TypeScript), les skills restent des fichiers sur disque : il n’existe pas d’API programmatique pour les enregistrer. Vous activez leur découverte avec setting_sources=["user", "project"], puis l’option skills accepte "all", une liste de noms, ou [] pour tout désactiver.

Créer son premier skill pas à pas

Comptez 15 minutes pour un premier skill fonctionnel dans Claude Code. Je prends un cas que je rencontre chaque semaine : rédiger des notes de version en français à partir de l’historique git. C’est le type de tâche répétitive, aux conventions stables, qui justifie un skill.

Étape 1 : identifier une tâche que vous réexpliquez sans cesse

La documentation d’Anthropic recommande de partir d’un besoin observé, pas imaginé : faites la tâche une fois avec Claude en prompt classique, notez ce que vous avez dû préciser (format, ton, exclusions), et ce sont ces précisions qui forment le skill. Si vous n’avez rien eu à préciser, vous n’avez pas besoin de skill.

Étape 2 : créer le dossier et le fichier SKILL.md

mkdir -p .claude/skills/notes-de-version

Puis créez .claude/skills/notes-de-version/SKILL.md :

---
name: notes-de-version
description: Rédige des notes de version en français à partir des commits récents. À utiliser quand l'utilisateur demande un changelog, des release notes ou un résumé des changements depuis le dernier tag.
---

## Commits depuis le dernier tag

!`git log $(git describe --tags --abbrev=0)..HEAD --oneline || git log -20 --oneline`

## Instructions

1. Regroupe les commits en trois sections : Nouveautés, Corrections, Technique.
2. Rédige chaque entrée en une phrase à l'infinitif, sans jargon interne.
3. Ignore les commits de merge et les mises à jour de dépendances.
4. Termine par une ligne « Mise à jour recommandée : oui/non » avec une justification.

Si aucun commit n'est trouvé, indique-le et n'invente rien.

La ligne !`git log ...` est une spécificité Claude Code : la commande s’exécute avant que Claude ne lise le skill, et sa sortie remplace la ligne. Le || git log -20 évite qu’un dépôt sans tag fasse échouer le skill, car une commande en erreur annule toute l’invocation.

Étape 3 : tester les deux modes de déclenchement

Lancez Claude Code dans le projet et testez d’abord l’invocation directe avec /notes-de-version. Ensuite, testez le déclenchement automatique avec une phrase naturelle : « Qu’est-ce qui a changé depuis la dernière version ? ». Si Claude n’active pas le skill, c’est presque toujours parce que la description manque des mots-clés que vous emploieriez spontanément.

Les modifications du SKILL.md sont rechargées à chaud dans la session. Seule la création d’un nouveau dossier skills/ demande /reload-skills.

Étape 4 : enrichir avec des références et des scripts

Quand le corps dépasse une centaine de lignes, déplacez le détail dans des fichiers référencés depuis SKILL.md : un references/glossaire.md pour les termes métier, un scripts/verifier.py pour une validation déterministe. Indiquez explicitement si Claude doit exécuter le script (« Lance scripts/verifier.py ») ou le lire comme référence : l’ambiguïté est une cause fréquente de comportement erratique.

Étape 5 : valider et partager

La commande claude plugin validate .claude/skills vérifie que l’en-tête YAML de chaque skill est bien formé (Claude Code 2.1.233 ou plus récent). Pour le standard ouvert, la bibliothèque de référence skills-ref validate ./mon-skill fait la même chose indépendamment de la plateforme.

Pour partager, trois options : versionner .claude/skills/ dans le dépôt (toute l’équipe en bénéficie), l’empaqueter dans un plugin distribué via un marketplace, ou le déployer via les paramètres gérés de l’organisation.

Skill, MCP, hook, mod : quatre briques complémentaires, et un plugin peut combiner les trois premières avec un mod.

Skills vs MCP vs hooks vs mods : quelle brique pour quel besoin

C’est la confusion la plus fréquente dans les discussions que je lis. Les quatre mécanismes étendent Claude, mais à des niveaux différents : un skill est un savoir, un serveur MCP est un accès, un hook est une règle, un mod est une interface.

Deux précisions utiles. D’abord, skills et MCP se complètent : j’ai détaillé dans mon guide du Model Context Protocol comment un serveur MCP donne accès à GitHub ou Notion ; un skill, lui, peut décrire à Claude comment enchaîner ces outils pour un workflow complet, en utilisant les noms qualifiés (GitHub:create_issue) pour éviter les erreurs « outil introuvable ».

Ensuite, la frontière skill/hook tient en une question : la règle doit-elle s’appliquer même si Claude l’oublie ? Un skill est une instruction que le modèle suit avec jugement, et qu’il peut perdre après une compaction de contexte. Un hook s’exécute mécaniquement à chaque événement. La documentation de Claude Code est explicite : si Claude saute une règle qui doit tenir à chaque fois, déplacez-la dans un hook, éventuellement déclaré dans le champ hooks du skill lui-même.

Les mods, lancés le 1er octobre 2026 avec Claude Code 2.1.287, sont la brique la plus récente. Ils tournent dans le processus de Claude Code, peuvent dessiner un panneau à côté de la transcription, intercepter un appel d’outil ou ajouter une commande sans tour de modèle. Un plugin peut contenir à la fois un skill, un serveur MCP et un mod.

Sécurité : auditer un skill avant de l’installer

Un skill s’exécute avec les droits de l’agent qui le charge. Dans Claude Code, cela signifie l’accès complet à votre machine et au réseau. Il faut donc traiter l’installation d’un skill tiers comme l’installation d’un logiciel, pas comme la lecture d’un article.

Les chiffres justifient cette prudence. Une étude publiée sur arXiv en février 2026 par Yi Liu et ses coauteurs a analysé 98 380 skills issus de deux registres publics : 157 skills malveillants confirmés, 632 vulnérabilités, 13 techniques d’attaque distinctes, et une moyenne de 4,03 vulnérabilités par skill malveillant. Plus de la moitié des cas provenaient d’un seul acteur pratiquant l’usurpation de marque à grande échelle. Les deux stratégies dominantes : vol d’identifiants par exécution de code distant, et manipulation de l’agent par des instructions cachées dans la documentation.

Une seconde étude, publiée en juillet 2026 par David Boram Hong, Aaron Imani et Iftekhar Ahmed sur 238 skills réels, montre que plus de 99 % des fichiers SKILL.md contiennent au moins un « skill smell », c’est-à-dire une violation des bonnes pratiques d’écriture, et que ces défauts disparaissent rarement au fil des versions.

L’OWASP a formalisé ces risques dans son Agentic Skills Top 10 (édition 1.0-2026, dernière mise à jour en mars 2026 ; la fondation prévoit la version 1.0 finale au quatrième trimestre 2026). Les trois premiers : skills malveillants (AST01), compromission de la chaîne d’approvisionnement (AST02) et skills surprivilégiés (AST03), ce dernier étayé par un relevé de Snyk de février 2026 qui a identifié plus de 280 skills exposant des identifiants. Le septième, « update drift » (AST07), est celui que l’on oublie : un skill approuvé en janvier peut avoir été modifié en mars sans que rien ne vous alerte.

Cinq vérifications avant d’installer un skill tiers : sur 98 380 skills analysés, 157 étaient malveillants avec 632 vulnérabilités au total.

Ma checklist avant toute installation

1. Identifier l’éditeur et figer la révision. Vérifiez qui contrôle le dépôt et notez le hash du commit audité. Un nom de branche peut bouger, pas un commit.
2. Lister tous les fichiers avant d’en ouvrir un. SKILL.md, scripts, images, fichiers de configuration, sous-modules. Un script référencé mais absent est un signal d’alerte.
3. Tracer chaque instruction vers son effet. Que lit-elle, qu’écrit-elle, où envoie-t-elle des données ? Recherchez les appels réseau (curl, requests, fetch) et les accès à ~/.ssh, aux variables d’environnement ou aux fichiers de configuration.
4. Comparer les permissions au besoin. Dans Claude Code, lisez le champ allowed-tools : il s’applique même dans un dossier non approuvé. Un skill de mise en forme Markdown n’a aucune raison de pré-approuver Bash(curl *).
5. Tester en environnement jetable. Données synthétiques, pas de secrets de production, réseau restreint.

Pour les équipes, Anthropic propose un scan de contenu des skills importés sur claude.ai et Cowork pour les organisations Enterprise, et les administrateurs peuvent restreindre les skills via les permissions (Skill(nom)) ou les paramètres gérés. J’ai couvert ces mécanismes de gouvernance dans mon guide de sécurisation de Claude Code en entreprise.

Ce que change le passage à l’Agentic AI Foundation

Depuis le 22 octobre 2026, Agent Skills n’appartient plus à Anthropic. Le standard, son nom, son logo, l’organisation GitHub et le domaine agentskills.io ont été transférés à l’Agentic AI Foundation, cofondée en décembre 2025 par Anthropic, Block et OpenAI au sein de la Linux Foundation. La fondation héberge désormais 10 projets, contre 3 à sa création, dont MCP, AGENTS.md, goose, Open Responses (contribué par OpenAI) et OpenSandbox (Alibaba).

Pour un utilisateur, rien ne change à court terme : vos fichiers SKILL.md restent valides, et Claude Code, claude.ai et l’API continuent de les lire. Ce qui change, c’est la gouvernance. Le standard sera maintenu par des ingénieurs d’Anthropic, de Google, d’OpenAI et d’autres entreprises à titre individuel, avec David Soria Parra et Mahesh Murag comme mainteneurs principaux. Toute organisation peut utiliser ou contribuer au standard sans adhérer à la fondation. Dans le communiqué de la Linux Foundation du 22 octobre 2026, le responsable du projet résume l’intention :

« Nous donnons Agent Skills à l’AAIF pour que quiconque construit avec des skills puisse façonner la suite. » David Soria Parra, co-créateur et mainteneur principal de MCP, Anthropic

La feuille de route proposée comprend trois chantiers : des versions numérotées de la spécification, un processus formel de proposition de changements, et un guide de sécurité pour les auteurs et les installateurs de skills. Ce dernier point répond directement aux études citées plus haut.

Mon analyse : c’est le même mouvement que pour MCP un an plus tôt, et il a les mêmes effets. Une gouvernance neutre rassure les éditeurs concurrents (Microsoft l’a ajouté à VS Code 1.108 dès décembre 2025, OpenAI l’a repris dans Codex puis ChatGPT), ce qui explique le passage de quelques milliers de skills GitHub à un million en douze mois. Le revers, visible dans les chiffres de sécurité, est qu’un écosystème ouvert sans contrôle de provenance attire les mêmes abus que npm ou PyPI à leurs débuts. Le guide de sécurité promis par la fondation sera le vrai test.

Ce qu’il faut retenir

Un skill est le moyen le plus simple et le plus portable de transmettre un savoir-faire à Claude : un dossier, un fichier Markdown, une description précise. Il ne remplace ni MCP (l’accès aux systèmes), ni les hooks (les règles strictes), ni le CLAUDE.md (le contexte permanent du projet) : il les complète.

Mon conseil pour démarrer : prenez la tâche que vous réexpliquez le plus souvent à Claude, écrivez-la en 30 lignes dans un SKILL.md placé dans .claude/skills/, testez le déclenchement automatique, puis itérez sur la description. Pour tout skill que vous n’avez pas écrit vous-même, appliquez la checklist d’audit avant de l’installer ; le format est désormais aussi ouvert que MCP, avec les avantages et les risques que cela implique.