Skills, agents, plugins : ces trois mots reviennent sans cesse dans la documentation de Claude Code, et pourtant ils désignent trois mécanismes bien distincts. Une skill est une recette de savoir-faire que Claude charge à la demande. Un subagent est un assistant spécialisé qui travaille dans son propre contexte, comme un collègue à qui vous délégueriez une tâche précise. Un plugin est un paquet installable qui peut contenir des skills, des subagents, des commandes et bien plus. Si vous utilisez déjà Claude Code au quotidien, vous avez sans doute croisé ces trois notions sans toujours savoir laquelle choisir pour personnaliser votre installation. Ce guide démêle les trois et vous montre comment les mettre en place concrètement, avec des exemples de fichiers que vous pouvez copier tels quels.
Les skills : des recettes de savoir-faire chargées à la demande
Une skill (ou « agent skill ») est un dossier contenant un fichier SKILL.md. Ce fichier décrit une compétence : comment relire un diff, comment générer un changelog, comment appliquer votre convention de nommage maison. La différence avec un simple prompt que vous tapez à chaque fois, c’est que la skill vit sur disque, se déclenche automatiquement quand le contexte correspond, et peut embarquer des fichiers annexes (scripts, références) que Claude ne charge que s’il en a besoin.
Les skills peuvent vivre à deux niveaux : ~/.claude/skills/nom-de-la-skill/SKILL.md pour une skill personnelle disponible sur tous vos projets, ou .claude/skills/nom-de-la-skill/SKILL.md à la racine d’un projet pour une skill partagée avec l’équipe via le dépôt Git. Le fichier commence par un frontmatter YAML. Seul le champ description est vraiment déterminant : c’est lui que Claude Code garde en mémoire en permanence pour décider quand déclencher la skill, donc mieux vaut y décrire précisément le déclencheur (« quand l’utilisateur demande X, mentionne Y ») plutôt que de rester vague. Le corps du fichier, lui, n’est chargé que lorsque la skill est effectivement invoquée : c’est ce qu’on appelle la divulgation progressive, un principe pensé pour ne pas saturer le contexte avec des instructions inutiles la plupart du temps.
Voici un exemple minimal et fonctionnel :
---
description: Résume les changements non commités et signale les points risqués. À utiliser quand l'utilisateur demande ce qui a changé, veut un message de commit, ou demande une relecture de son diff.
---
## Changements actuels
!`git diff HEAD`
## Instructions
Résume les changements ci-dessus en deux ou trois puces, puis liste les
risques observés (gestion d'erreur manquante, valeurs codées en dur,
tests à mettre à jour). Si le diff est vide, dis-le simplement.
Ce fichier suffit. Aucune commande de scaffolding officielle n’existe pour générer une skill : vous créez le dossier et le fichier à la main, ou vous demandez directement à Claude de l’écrire pour vous, ce qui revient souvent au même en pratique. Une skill peut aussi référencer d’autres fichiers dans son dossier (un reference.md, un script Python) que Claude ira lire seulement s’il en a besoin pour la tâche en cours, ce qui garde les skills légères même quand le sujet est complexe.
Les subagents : des assistants spécialisés avec leur propre contexte
Un subagent va plus loin qu’une skill : ce n’est pas seulement un savoir-faire, c’est un agent complet qui tourne dans sa propre fenêtre de contexte, avec éventuellement un modèle différent et un accès restreint à certains outils. L’intérêt principal est d’isoler une tâche lourde ou répétitive (recherche exhaustive dans le code, revue de sécurité, génération de tests) sans polluer votre conversation principale avec tout le détail intermédiaire : le subagent travaille de son côté et ne renvoie que le résultat.
Les subagents se définissent en Markdown dans ~/.claude/agents/nom-du-subagent.md pour un usage personnel, ou .claude/agents/nom-du-subagent.md à la racine du projet pour un usage partagé en équipe. Le frontmatter attend deux champs obligatoires, name et description, et plusieurs champs optionnels utiles au quotidien : tools pour restreindre les outils accessibles, model pour fixer le modèle (sonnet, opus, haiku, fable, ou inherit pour hériter du modèle de la conversation principale, qui est la valeur par défaut), et permissionMode pour le niveau de confirmation attendu.
---
name: code-improver
description: Analyse les fichiers modifiés et suggère des améliorations de lisibilité, de performance et de bonnes pratiques. À utiliser après avoir écrit ou modifié du code.
tools: Read, Grep, Glob
model: sonnet
---
Vous êtes un spécialiste de l'amélioration de code. Lors d'une revue :
1. Vérifiez la lisibilité et la clarté
2. Repérez les opportunités d'optimisation de performance
3. Identifiez les manquements aux bonnes pratiques
4. Proposez des améliorations concrètes et applicables
5. Expliquez le raisonnement derrière chaque suggestion
Concentrez-vous sur des améliorations pratiques, sans refonte majeure.
Claude Code peut invoquer un subagent tout seul, en se basant sur le champ description pour juger si la tâche en cours lui correspond, exactement comme pour une skill. Vous pouvez aussi le solliciter explicitement en le mentionnant dans votre message. La commande /agents vous donne un aperçu des subagents disponibles dans votre installation (personnels, projet, ceux fournis par des plugins) et vous guide pour en créer un nouveau ; pour des ajustements fins, l’édition directe du fichier Markdown reste la méthode la plus rapide.
Les plugins : des paquets tout-en-un installables
Le plugin est le niveau au-dessus. Un plugin Claude Code est un dossier distribuable qui peut regrouper plusieurs skills, plusieurs subagents, des commandes personnalisées, des hooks, et même un serveur MCP, le tout packagé pour être installé en une commande sur n’importe quelle machine. C’est le format à choisir dès que vous voulez partager une personnalisation complète, que ce soit avec votre équipe ou avec la communauté, plutôt que de demander à chacun de copier des fichiers un par un.
Les plugins se découvrent et s’installent via des marketplaces, des catalogues déclarés par un fichier marketplace.json placé dans un dossier .claude-plugin/ à la racine d’un dépôt Git. La commande /plugin ouvre une interface interactive pour parcourir les marketplaces disponibles, installer un plugin, ou gérer ceux déjà en place. Pour ajouter une marketplace, il suffit d’un /plugin marketplace add suivi d’une référence GitHub (organisation/depot) ou d’une URL Git complète ; pour installer un plugin qui s’y trouve, /plugin install nom-du-plugin@nom-de-la-marketplace. Anthropic maintient elle-même une marketplace officielle ajoutée automatiquement au premier lancement, ce qui donne un point de départ simple pour explorer le format avant de créer la vôtre.
Lequel choisir selon votre besoin
- Une seule recette, personnelle, à déclencher automatiquement : une skill dans
~/.claude/skills/. - Une convention d’équipe versionnée avec le code : une skill dans
.claude/skills/du dépôt. - Une tâche lourde à isoler dans son propre contexte, avec un modèle ou des outils différents : un subagent dans
.claude/agents/ou~/.claude/agents/. - Un ensemble cohérent de skills, subagents et outils à distribuer largement : un plugin, publié via une marketplace.
Dans la pratique, ces trois briques se combinent souvent : un plugin peut embarquer plusieurs skills et un subagent dédié, comme une boîte à outils complète autour d’un même besoin.
Mise en pratique : créer sa première skill en 5 minutes
Le plus simple pour se faire une idée reste de créer une skill personnelle. Dans un terminal, à la racine de votre système de fichiers utilisateur :
mkdir -p ~/.claude/skills/resume-pr
Puis créez le fichier ~/.claude/skills/resume-pr/SKILL.md avec un éditeur de texte, ou plus simplement en demandant à Claude Code lui-même : « crée-moi une skill qui résume mes pull requests ouvertes sur GitHub ». Décrivez dans le champ description le déclencheur précis que vous voulez (« quand je demande un résumé de mes PR ouvertes »), puis rédigez dans le corps les instructions exactes que vous donneriez à un collègue pour faire ce travail : quelles commandes lancer, quel format de sortie attendre. Relancez une conversation, tapez une phrase qui correspond au déclencheur, et observez si la skill se déclenche bien. Si ce n’est pas le cas, la description est probablement trop vague : c’est la première chose à retravailler.
Ce cycle court, écrire, tester, ajuster la description, est la meilleure façon d’apprendre le format sans avoir à tout lire la documentation en une fois.
En résumé
Skills, subagents et plugins répondent chacun à un besoin différent malgré leur nom qui prête à confusion. Les skills sont légères et parfaites pour capitaliser sur des recettes récurrentes. Les subagents apportent l’isolation de contexte quand une tâche mérite d’être traitée à part. Les plugins permettent de packager et distribuer tout ça d’un coup. Si vous découvrez encore comment utiliser Claude Code au quotidien, commencez par une skill simple : c’est la porte d’entrée la plus rapide vers la personnalisation, et vous pourrez toujours migrer vers un subagent ou un plugin une fois le besoin plus clair. Pour aller plus loin sur les champs de frontmatter et les cas avancés, la documentation officielle de Claude Code reste la référence à consulter en premier.