Comment fonctionnent les plugins Claude Code et leur coût

Qu'est-ce qu'un plugin Claude Code

Un plugin Claude Code est un répertoire de composants que Claude Code charge et gère comme une unité unique. Ces composants sont des skills, des agents, des hooks, des serveurs MCP, des serveurs LSP et des moniteurs en arrière-plan. L'installation d'un plugin ajoute toutes ses parties simultanément sous un nom unique, et sa désactivation les supprime de la même manière.

Un plugin ne confère à l'agent aucune capacité qu'il ne possédait déjà. Chaque élément contenu dans un plugin est quelque chose que vous pouvez écrire manuellement dans un répertoire .claude/. Le plugin est la couche de packaging : un moyen de versionner ces éléments, de les distribuer à quinze personnes et de les mettre à jour ultérieurement sans demander à chacun de copier des fichiers. C'est le concept fondamental, et la plupart des confusions concernant les plugins viennent du fait qu'on s'attend à ce qu'ils représentent un nouveau type de fonctionnalité.

Le manifeste optionnel situé dans .claude-plugin/plugin.json nomme le plugin, et ce nom devient un namespace. Un skill dans un plugin nommé commit-commands est invoqué via /commit-commands:commit, ce qui permet à deux plugins de proposer chacun un skill nommé commit sans qu'aucun ne masque l'autre. Les agents de plugin sont isolés de la même manière dans la liste des @-mentions, sous la forme plugin-name:agent-name.

Plugin, skill, serveur MCP ou fichier de règles

Ces quatre termes sont souvent utilisés comme s'ils étaient en concurrence. Ce n'est pas le cas, et il est utile de définir leurs limites une fois pour toutes.

• Une skill est une unité d'instruction que Claude charge lorsque la tâche le nécessite. Voir ce qu'est réellement une Agent Skill.
• Un serveur MCP est un processus distinct qui expose des outils à l'agent via un protocole, souvent un service réseau que vous exécutez vous-même.
• Un fichier de règles tel que CLAUDE.md constitue le contexte du projet ; il est lu au démarrage de la session et s'applique à l'ensemble de celle-ci.
• Un plugin est un conteneur capable de regrouper des skills, des agents, des hooks et des définitions de serveurs MCP, le tout accompagné d'un numéro de version et d'un canal de distribution.

Ainsi, la question à laquelle répond un plugin n'est pas « que peut faire l'agent ? ». C'est « comment puis-je distribuer ceci à mon équipe et le mettre à jour le mois prochain ? ». Si vous hésitez entre les trois premiers, la comparaison entre skills, serveurs MCP et fichiers de règles détaille cette décision. Si la partie MCP vous intéresse particulièrement, l'exécution de vos propres serveurs MCP sur un VPS couvre l'aspect hébergement.

Emplacement des plugins et structure interne

Un plugin installé depuis une marketplace est copié dans un cache local situé à ~/.claude/plugins/cache plutôt que d'être exécuté depuis son emplacement de clonage. Chaque version installée possède son propre répertoire. Lors d'une mise à jour ou d'une désinstallation, l'ancien répertoire est marqué comme orphelin et supprimé environ deux semaines plus tard. Cela permet à une session ayant déjà chargé l'ancienne version de continuer à fonctionner sans échouer en cours de tâche.

Comme le chemin change à chaque mise à jour, un plugin ne doit jamais coder en dur son propre emplacement. Les hooks et les configurations MCP au sein d'un plugin utilisent ${CLAUDE_PLUGIN_ROOT}, qui pointe vers le répertoire d'installation actuel. Les données d'état devant persister après une mise à jour doivent être placées dans ${CLAUDE_PLUGIN_DATA}, qui pointe vers un répertoire stable sous ~/.claude/plugins/data/.

Seul le répertoire du plugin est copié dans le cache, ce qui entraîne une conséquence fréquente. Un chemin pointant en dehors de la racine du plugin, comme ../shared-utils, fonctionne lors du développement avec un chemin local, mais échoue après l'installation car ces fichiers n'ont jamais été copiés.

La structure se présente comme suit.

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── code-review/
│       └── SKILL.md
├── agents/
├── hooks/
│   └── hooks.json
├── .mcp.json
└── bin/

Seul plugin.json doit se trouver dans .claude-plugin/. Tout le reste doit être placé à la racine du plugin. Placer skills/ ou hooks/ dans .claude-plugin/ est la raison la plus courante pour laquelle un plugin s'installe correctement mais ne produit aucun effet : Claude Code recherche ces répertoires à la racine, ne les trouve pas et charge un plugin sans aucun composant.

Le manifeste lui-même est léger.

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0"
}

Comment installer un plugin Claude Code

L'installation se déroule en deux étapes, dont la première n'installe rien. Vous ajoutez une marketplace, qui est un catalogue de plugins, puis vous installez les plugins individuels depuis celle-ci. La marketplace officielle d'Anthropic, claude-plugins-official, est enregistrée automatiquement lors du premier lancement interactif de Claude Code. Vous ajoutez les autres vous-même.

/plugin marketplace add anthropics/claude-code
/plugin install commit-commands@claude-code-plugins

Notez que le dépôt est anthropics/claude-code alors que la marketplace se nomme claude-code-plugins. Le nom provient du fichier de catalogue situé dans le dépôt, et non du chemin du dépôt. Lisez donc le nom de la marketplace dans l'onglet Marketplaces de /plugin avant de saisir une commande d'installation.

Après l'installation, lisez la ligne de résumé. Plugin is now active. signifie que les composants sont chargés pour cette session. Run /reload-plugins to activate. signifie qu'ils ne le sont pas et que vous devez exécuter cette commande. Si /reload-plugins vous avertit qu'il relirait la conversation, relancez-la avec /reload-plugins --force. Vérifiez ensuite que le plugin est bien présent : /plugin l'affiche sous l'onglet Installed, /help liste ses compétences sous Custom commands, et tout élément ayant échoué lors du chargement apparaît sous l'onglet Errors avec le motif de l'échec.

L'installation demande une portée (scope), qui détermine qui bénéficie du plugin. La portée utilisateur (user) vous concerne, dans chaque projet. La portée projet (project) écrit le plugin dans le fichier .claude/settings.json du dépôt sous enabledPlugins, afin que tous ceux qui clonent le dépôt se voient proposer son installation. La portée locale (local) vous concerne uniquement dans ce dépôt.

Pour un script, un Dockerfile ou toute session où un panneau interactif n'est pas disponible, utilisez plutôt la forme shell. Elle installe le plugin avec une portée utilisateur, sauf si vous passez --scope.

claude plugin install commit-commands@claude-code-plugins --scope project
claude plugin list

claude plugin install s'exécute en dehors d'une session. Par conséquent, une session déjà ouverte ne verra pas le nouveau plugin tant que vous n'aurez pas exécuté /reload-plugins ou démarré une nouvelle session.

La gestion des plugins suit le même modèle dans les deux cas. /plugin list affiche les éléments installés et accepte --enabled ou --disabled. /plugin disable name@marketplace désactive un plugin sans le supprimer, /plugin enable le réactive et /plugin uninstall le supprime. Les commandes slash ouvrent le panneau des plugins pour appliquer le changement ; c'est pourquoi les équivalents shell claude plugin ... doivent être utilisés dans les scripts.

Pour distribuer une marketplace à toute une équipe, placez-la dans le fichier .claude/settings.json du projet. Les membres seront invités à l'installer dès qu'ils auront approuvé le dossier du dépôt.

{
  "extraKnownMarketplaces": {
    "my-team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

Pendant que vous développez votre propre plugin, ignorez complètement la marketplace. claude --plugin-dir ./my-plugin charge un répertoire pour la session en cours, /reload-plugins prend en compte vos modifications sans redémarrage, et claude plugin validate ./my-plugin vérifie le manifeste, les compétences, le frontmatter de l'agent et hooks/hooks.json avant toute mise à disposition.

Combien coûte un plugin Claude Code ?

Le mécanisme est gratuit. En août 2026, aucun frais n'est appliqué pour ajouter une marketplace, installer un plugin ou en maintenir un activé. Les marketplaces officielles et communautaires sont des dépôts git publics, et un plugin n'est qu'un répertoire de fichiers texte.

Le coût d'un plugin se mesure en tokens, et les tokens sont ce que votre abonnement ou votre facture d'API mesure réellement. Ce coût se manifeste de trois manières différentes, avec des comportements distincts.

Coût du contexte permanent. Ce qu'un plugin apporte est intégré à votre contexte et relu à chaque tour de session. Avant l'installation, la vue détaillée /plugin affiche une estimation Context cost en tokens ainsi qu'une section Will install listant les commandes, compétences, agents, hooks, et serveurs MCP et LSP que vous vous apprêtez à ajouter. Lisez ces deux éléments. Les plugins provenant de marketplaces locales ou personnalisées peuvent ne pas fournir ces données ; dans ce cas, vous devrez effectuer une estimation manuelle. Un plugin qui embarque un serveur MCP est généralement le plus lourd, car les définitions d'outils sont volumineuses, bien que sur les modèles supportant la recherche d'outils MCP, ces définitions soient différées jusqu'à ce qu'un outil soit nécessaire.

Coût d'invocation. L'exécution de la compétence d'un plugin ajoute ses instructions à la conversation ; vous ne payez donc pour le corps de la compétence que lorsqu'elle est utilisée. Un agent fonctionne différemment. Un sous-agent mène sa propre conversation avec son propre prompt système et son propre cache, en commençant sans aucun hit de cache. Par conséquent, un plugin dont le workflow génère des agents coûte considérablement plus cher que ce que suggère son estimation de contexte.

Coût du cache. Activer ou désactiver un plugin en cours de session peut forcer la requête suivante à retraiter l'intégralité de votre conversation. Les compétences, commandes, agents, hooks, serveurs LSP, moniteurs et thèmes ne provoquent jamais cela : ce qu'ils ajoutent est annexé à l'historique existant, de sorte que la requête suivante paie pour le nouveau contenu tout en lisant le reste depuis le cache. L'exception concerne les plugins fournissant un serveur MCP. Si leurs outils sont différés par la recherche d'outils, le cache est préservé. S'ils se chargent dans le préfixe du prompt, la requête suivante relit toute la conversation comme une entrée non mise en cache. C'est précisément pour cette raison que /reload-plugins affiche un avertissement et refuse l'opération tant que vous n'avez pas passé --force.

Vous pouvez surveiller cela plutôt que de le deviner. Chaque réponse d'API rapporte cache_read_input_tokens et cache_creation_input_tokens, et une ligne d'état personnalisée affichant l'utilisation des tokens en temps réel place ces deux valeurs sous vos yeux. Une session saine lit beaucoup plus qu'elle ne crée. Si la création reste élevée tour après tour, quelque chose dans votre préfixe change à chaque tour. Pour une vue d'ensemble sur ce qui remplit la fenêtre, consultez comment gérer la fenêtre de contexte de Claude Code et ce que ces nombres de tokens signifient réellement.

Une tâche de maintenance est particulièrement rentable. L'onglet Installed regroupe les plugins que vous n'avez pas utilisés depuis au moins deux semaines sous un en-tête Not used recently, avec une ligne Last used dans la vue détaillée. Ces plugins continuent de vous coûter du temps de démarrage et du contexte à chaque session. Désactivez-les ou désinstallez-les.

Un plugin s'exécute avec vos permissions

La documentation d'Anthropic est explicite à ce sujet : les plugins et les marketplaces sont des composants de confiance élevée capables d'exécuter du code arbitraire sur votre machine avec vos privilèges utilisateur. Ce n'est pas une hypothèse. Les hooks d'un plugin exécutent des commandes shell lors d'événements de session, notamment avant et après les appels d'outils. Son répertoire bin/ est ajouté au PATH de l'outil Bash tant que le plugin est activé. Ses serveurs MCP sont des processus qu'il démarre. Rien ici n'est isolé de votre compte utilisateur par un bac à sable.

Sur un ordinateur portable, ce risque est limité par ce à quoi votre utilisateur de bureau peut accéder. Sur un serveur, ce n'est généralement pas le cas. Le compte qui exécute l'agent détient souvent des clés SSH, des jetons de déploiement, une session CLI cloud et un accès au socket Docker ; ainsi, « code arbitraire en tant qu'utilisateur » signifie la machine entière. Si Claude Code tourne sur un VPS, lisez comment exécuter Claude Code en toute sécurité sur un VPS avant d'installer quoi que ce soit, et comment garder les identifiants hors de portée d'un agent avant d'installer un plugin qui communique avec un service externe.

Des garde-fous existent, et il est utile de savoir lesquels. Un plugin à portée de projet provient du dépôt plutôt que de vous ; il ne se charge donc qu'après que vous ayez approuvé l'espace de travail, ses serveurs MCP nécessitent toujours une approbation par serveur, ses serveurs LSP attendent cette approbation, et ses moniteurs en arrière-plan ne se chargent pas du tout. Les agents fournis par des plugins ne sont pas autorisés à déclarer des hooks, des serveurs MCP ou un mode de permission. Les plugins de la marketplace sont copiés dans le cache et les liens symboliques pointant vers l'extérieur de la marketplace sont ignorés ; un plugin ne peut donc pas importer des fichiers arbitraires de l'hôte.

Rien de tout cela ne remplace la vérification de ce que vous installez. Consultez la liste Will install, privilégiez les plugins dont vous pouvez ouvrir et lire le code source, conservez les plugins de votre équipe dans un dépôt de marketplace que vous contrôlez, et exécutez claude plugin validate sur tout ce que vous écrivez vous-même.

FAQ

Les plugins Claude Code sont-ils payants ?

Non. Il n'y a aucuns frais pour le système de plugins, pour l'ajout d'une marketplace ou pour l'installation d'un plugin. Le coût correspond à la consommation de tokens, facturée selon votre plan ou votre usage de l'API, comme pour tout autre contexte. Un plugin ajoute un contexte permanent à chaque tour, en ajoute davantage lorsqu'une de ses compétences ou agents est invoqué, et peut forcer un tour coûteux sans cache s'il fournit un serveur MCP dont les outils sont chargés dans le préfixe du prompt. La vue détaillée /plugin affiche une estimation Context cost avant l'installation.

Quelle est la différence entre un plugin et une compétence (skill) ?

Une compétence est une unité d'instruction unique. Un plugin est un package pouvant contenir des compétences, des agents, des hooks, des serveurs MCP, des serveurs LSP et des moniteurs, avec un nom, une version et une marketplace pour l'installer. Écrivez une compétence autonome dans .claude/ si elle est destinée à vous et à ce projet. Une compétence à usage unique comme Ponytail, qui pousse l'agent vers le plus petit changement fonctionnel en est l'exemple le plus clair : un fichier avec une règle, jusqu'au jour où votre équipe en a besoin aussi. Transformez-la en plugin lorsque d'autres personnes doivent l'utiliser et qu'elle nécessite des mises à jour régulières. Les compétences de plugin sont isolées par un namespace ; une compétence au sein d'un plugin est donc invoquée via /plugin-name:skill-name plutôt que /skill-name.

Mon plugin est installé mais ses compétences n'apparaissent pas. Quel est le problème ?

Consultez d'abord le résumé de l'installation. S'il indique Run /reload-plugins to activate., les composants ne sont pas encore chargés ; si le rechargement avertit qu'il va relire la conversation, relancez-le avec /reload-plugins --force. S'il est chargé mais n'affiche rien, ouvrez /plugin et lisez l'onglet Errors. L'erreur structurelle la plus courante consiste à placer skills/, agents/ ou hooks/ à l'intérieur de .claude-plugin/, là où Claude Code ne les cherche pas. N'oubliez pas que les compétences de plugin sont isolées par un namespace ; vous devez donc chercher /plugin-name:skill-name dans l'onglet Custom commands de /help. En dernier recours, faites rm -rf ~/.claude/plugins/cache, redémarrez et réinstallez.

Puis-je installer des plugins sans le panneau interactif ?

Oui. Utilisez la commande shell claude plugin install name@marketplace, qui installe au niveau de l'utilisateur sauf si vous passez --scope project ou --scope local. Cela fonctionne dans les scripts, les images et les environnements non interactifs où le panneau /plugin est indisponible. Comme cela s'exécute en dehors d'une session, une session déjà ouverte nécessite /reload-plugins pour que le plugin soit pris en compte.

Est-il sûr d'installer un plugin depuis une marketplace trouvée sur GitHub ?

Traitez cela comme si vous exécutiez le script d'installation de ce dépôt avec vos propres privilèges, car c'est pratiquement ce qui se passe. Un plugin peut exécuter des commandes shell via des hooks, ajouter des exécutables au PATH de l'outil Bash et démarrer des serveurs MCP, le tout avec les privilèges de votre utilisateur. Anthropic ne contrôle ni ne vérifie le contenu des plugins tiers. Installez uniquement depuis des sources que vous pouvez lire, examinez la liste Will install avant de confirmer, et soyez plus strict sur un serveur que sur un ordinateur portable, car le compte y détient généralement des clés et des tokens qui méritent d'être protégés.