Plugins Claude Code : fonctionnement et coût réel

Ce qu’est un plugin Claude Code

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

Un plugin n’accorde à l’agent aucune capacité qu’il ne possède déjà. Chaque composant d’un plugin peut être créé manuellement dans un répertoire .claude/. Le plugin est la couche de packaging : il permet de versionner ces composants, de les distribuer à quinze personnes et de les mettre à jour sans demander à chacun de copier des fichiers. C’est tout le principe. La plupart des confusions sur les plugins viennent du fait qu’on les considère à tort comme un nouveau type de capacité.

Le manifest facultatif situé dans .claude-plugin/plugin.json définit le nom du plugin, qui devient un namespace. Une skill d’un plugin appelé commit-commands est appelée avec /commit-commands:commit. Deux plugins peuvent donc chacun fournir une skill appelée commit sans que l’une masque l’autre. Les agents des plugins sont soumis au même principe dans la liste des mentions avec @, comme plugin-name:agent-name.

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

Ces quatre termes sont souvent présentés comme s’ils se faisaient concurrence. Ce n’est pas le cas. Il est utile de préciser une fois leurs rôles respectifs.

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

La question à laquelle répond un plugin n’est donc pas « que peut faire l’agent ? ». C’est plutôt : « comment distribuer cet ensemble à mon équipe et le mettre à jour le mois prochain ? ». Si vous devez choisir entre les trois premiers éléments, la comparaison des skills, des serveurs MCP et des fichiers de règles détaille cette décision. Si la partie MCP vous intéresse, exécuter vos propres serveurs MCP sur un VPS traite de l’hébergement.

Emplacement des plugins et contenu d’un plugin

Un plugin installé depuis une marketplace est copié dans un cache local à ~/.claude/plugins/cache, au lieu d’être exécuté depuis l’emplacement où il a été cloné. 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, puis supprimé environ deux semaines plus tard. Une session qui a déjà chargé l’ancienne version continue ainsi de fonctionner au lieu d’é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 d’un plugin utilisent ${CLAUDE_PLUGIN_ROOT}, qui se résout vers le répertoire d’installation courant. Les données d’état qui doivent être conservées lors d’une mise à jour vont dans ${CLAUDE_PLUGIN_DATA}, qui se résout vers un répertoire stable sous ~/.claude/plugins/data/.

Seul le répertoire propre au plugin est copié dans le cache. Cette règle entraîne un problème que l’on rencontre souvent tardivement. Un chemin qui pointe en dehors de la racine du plugin, comme ../shared-utils, fonctionne pendant le développement avec un chemin local, puis échoue après l’installation, car ces fichiers n’ont jamais été copiés.

L’arborescence se présente ainsi.

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 se trouve à la racine du plugin. Placer skills/ ou hooks/ dans .claude-plugin/ est la raison la plus fréquente pour laquelle un plugin s’installe correctement, puis ne fait absolument rien : Claude Code recherche ces répertoires à la racine, n’en trouve aucun et charge un plugin sans composants.

Le manifest lui-même est court.

{
  "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 fait 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 individuellement depuis cette marketplace. La marketplace officielle d’Anthropic, claude-plugins-official, est enregistrée pour vous lors du premier démarrage 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 repository est anthropics/claude-code, tandis que la marketplace s’appelle claude-code-plugins. Le nom provient du fichier de catalogue situé dans le repository, et non du chemin du repository. 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 dans 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 indique que la conversation serait relue, relancez-la avec /reload-plugins --force. Vérifiez ensuite que le plugin est bien présent : /plugin l’affiche dans l’onglet Installed, /help répertorie ses skills dans Custom commands, et tout élément qui n’a pas pu être chargé apparaît dans l’onglet Errors avec la raison de l’échec.

L’installation demande de choisir un scope, qui détermine les utilisateurs du plugin. Le scope user vous concerne dans tous les projets. Le scope project écrit le plugin dans .claude/settings.json du repository, sous enabledPlugins. Toute personne qui clone le repository se voit alors proposer ce plugin. Le scope local vous concerne uniquement dans ce repository.

Pour un script, un Dockerfile ou toute session sans panneau interactif, utilisez la syntaxe shell. L’installation utilise le scope user, 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. Une session déjà ouverte ne verra donc pas le nouveau plugin avant l’exécution de /reload-plugins ou le démarrage d’une nouvelle session.

La gestion des plugins installés suit le même principe dans les deux interfaces. /plugin list affiche les plugins 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 formes slash-command ouvrent le panneau des plugins pour appliquer la modification. C’est pourquoi il faut utiliser les équivalents shell claude plugin ... dans les scripts.

Pour proposer une marketplace à toute une équipe, ajoutez-la au .claude/settings.json du projet. Les membres sont invités à l’installer une fois qu’ils ont approuvé le dossier du repository.

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

Pendant le développement de votre propre plugin, n’utilisez pas de 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 manifest, les frontmatter des skills et des agents, ainsi que hooks/hooks.json avant que d’autres utilisateurs ne le voient.

Combien coûte un plugin Claude Code ?

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

Ce qu’un plugin coûte, ce sont des tokens. Ce sont eux que mesurent réellement l’utilisation de votre abonnement ou votre facture API. Lequel de ces deux postes est concerné dépend de votre mode de paiement initial pour l’outil. Le coût de Claude Code selon chaque forfait présente les niveaux d’abonnement à côté de la tarification API par token. Ce coût intervient de trois façons différentes, qui ne se comportent pas de la même manière.

Coût du contexte permanent. Ce qu’un plugin ajoute reste dans votre contexte et est relu à chaque tour de la session. Avant l’installation, la vue détaillée /plugin affiche une estimation Context cost en tokens, ainsi qu’une section Will install qui répertorie les commands, skills, agents, hooks, serveurs MCP et serveurs LSP que vous êtes sur le point d’ajouter. Consultez les deux. Les plugins provenant de marketplaces locales ou personnalisées peuvent ne pas fournir ces données. Vous devez alors faire l’estimation vous-même. Un plugin qui intègre un serveur MCP est généralement le plus lourd, car les définitions des outils sont volumineuses. Toutefois, sur les modèles qui prennent en charge la recherche d’outils MCP, ces définitions sont différées jusqu’à ce qu’un outil soit nécessaire.

Coût d’invocation. L’exécution d’une skill de plugin ajoute ses instructions à la conversation. Vous ne payez donc le contenu de la skill que lorsqu’elle est utilisée. Ce contenu est toutefois la partie la moins coûteuse. Ce que la skill demande à l’agent peut coûter davantage : la méthode Depth Tree de la skill unlazy consomme presque tous ses tokens lors des passes supplémentaires qu’elle impose avant d’autoriser l’agent à déclarer une tâche terminée, et non dans le fichier installé. Un agent fonctionne autrement. Un subagent exécute sa propre conversation avec son propre system prompt et son propre cache, en commençant sans aucun cache hit. Un plugin dont le workflow lance des agents coûte donc nettement plus que ne le laisse penser son estimation de contexte.

Coût du cache. Activer ou désactiver un plugin au cours d’une session peut obliger la requête suivante à retraiter toute votre conversation. Les skills, commands, agents, hooks, serveurs LSP, monitors et themes ne provoquent jamais cela : leur contenu est ajouté après l’historique existant. La requête suivante paie donc le nouveau contenu, tout en relisant depuis le cache tout ce qui le précède. L’exception concerne un plugin qui fournit un serveur MCP. Si ses outils sont différés par la recherche d’outils, le cache est conservé. S’ils sont chargés 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 pourquoi /reload-plugins affiche un avertissement et refuse cette opération tant que vous n’avez pas transmis --force.

Vous pouvez observer ce phénomène au lieu de l’estimer. Chaque réponse API indique cache_read_input_tokens et cache_creation_input_tokens, et une statusline personnalisée qui affiche l’utilisation actuelle des tokens vous permet de les consulter directement. Une session saine lit beaucoup plus qu’elle ne crée. Si la création reste élevée à chaque tour, quelque chose dans votre préfixe change à chaque tour. Pour comprendre ce qui remplit la fenêtre de contexte, consultez la gestion de la fenêtre de contexte de Claude Code et la signification réelle de ces décomptes de tokens.

Une tâche de maintenance est rapidement rentabilisée. L’onglet Installed regroupe sous l’en-tête Not used recently les plugins que vous n’avez pas utilisés depuis au moins deux semaines. La vue détaillée contient également une ligne Last used. Ces plugins vous font toujours perdre du temps au 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 claire à ce sujet : les plugins et les marketplaces sont des composants hautement fiables qui peuvent exécuter du code arbitraire sur votre machine avec les privilèges de votre utilisateur. Ce n’est pas un cas théorique. Les hooks d’un plugin exécutent des commandes shell lors des événements de session, notamment avant et après les appels d’outils. Son répertoire bin/ est ajouté à PATH du Bash tool tant que le plugin est activé. Ses serveurs MCP sont des processus qu’il démarre. Rien de tout cela n’est isolé de votre compte utilisateur par une sandbox.

Sur un laptop, le risque est limité par ce que votre utilisateur de bureau peut atteindre. 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 deploy tokens, une session de cloud CLI et un accès au Docker socket. « Code arbitraire avec vos droits » signifie donc un accès à la machine. Si Claude Code s’exécute sur un VPS, consultez comment exécuter Claude Code en toute sécurité sur un VPS avant d’installer quoi que ce soit, puis comment garder les identifiants hors de portée d’un agent avant d’installer un plugin qui communique avec un service externe. Les autres harnesses se heurtent au même problème sur le même serveur loué. C’est pourquoi les plugins DeepSeek Harness qui valent la peine d’être installés servent surtout à plafonner les dépenses, à appliquer des règles d’autorisation des outils et à détecter les injections, plutôt qu’à fournir de nouvelles capacités.

Certaines protections existent, et il est utile de savoir lesquelles. Un plugin limité au projet provient du repository plutôt que de vous. Il ne se charge donc qu’après validation du workspace. Ses serveurs MCP nécessitent toujours une approbation individuelle, ses serveurs LSP attendent cette validation et ses monitors d’arrière-plan ne se chargent pas du tout. Les agents fournis par les plugins ne peuvent pas déclarer de hooks, de serveurs MCP ni de permission mode. Les plugins de la marketplace sont copiés dans le cache, mais les symlinks pointant en dehors de la marketplace sont ignorés. Un plugin ne peut donc pas charger arbitrairement des fichiers de l’hôte.

Aucune de ces mesures ne vous dispense de vérifier ce que vous installez. Contrôlez 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 repository 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 coûtent-ils plus cher ?

Non. Le système de plugins, l’ajout d’une marketplace et l’installation d’un plugin sont gratuits. Le coût correspond à l’utilisation de tokens, facturée sur votre forfait ou votre consommation API, comme pour tout autre contexte. Un plugin ajoute un contexte permanent à chaque tour, en ajoute davantage lorsqu’une de ses skills ou un de ses agents est appelé, et peut imposer un tour non mis en cache coûteux 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 skill ?

Une skill est une unité d’instructions unique. Un plugin est un package qui peut contenir des skills, des agents, des hooks, des serveurs MCP, des serveurs LSP et des monitors, avec un nom, une version et une marketplace depuis laquelle l’installer. Écrivez une skill autonome dans .claude/ lorsqu’elle est destinée à vous et à ce projet. Une skill à usage unique telle que Ponytail, qui oriente l’agent vers la plus petite modification fonctionnelle en est l’exemple le plus clair : un fichier contenant une seule règle, jusqu’au jour où votre équipe en a également besoin. Transformez-la en plugin lorsque d’autres personnes doivent l’utiliser et qu’elle doit être mise à jour au fil du temps. Les skills des plugins sont namespacées : une skill située dans un plugin est appelée avec /plugin-name:skill-name plutôt qu’avec /skill-name.

Mon plugin est installé, mais ses skills n’apparaissent pas. Quel est le problème ?

Consultez d’abord le résumé de l’installation. S’il indiquait 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. Si les composants sont chargés, mais que rien ne s’affiche, ouvrez /plugin et consultez l’onglet Errors. L’erreur de structure la plus fréquente consiste à placer skills/, agents/ ou hooks/ dans .claude-plugin/, où Claude Code ne les recherche pas. N’oubliez pas que les skills des plugins sont namespacées : recherchez /plugin-name:skill-name dans l’onglet Custom commands de /help. En dernier recours, exécutez rm -rf ~/.claude/plugins/cache, redémarrez, puis réinstallez.

Puis-je installer des plugins sans le panneau interactif ?

Oui. Utilisez la commande shell claude plugin install name@marketplace. Elle installe le plugin dans le scope utilisateur, sauf si vous transmettez --scope project ou --scope local. Elle fonctionne dans les scripts, les images et les environnements non interactifs où le panneau /plugin n’est pas disponible. Comme elle s’exécute en dehors d’une session, une session déjà ouverte doit recevoir /reload-plugins avant que le plugin soit pris en compte.

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

Considérez cette opération comme l’exécution, avec votre compte utilisateur, du script d’installation de ce dépôt : c’est pratiquement ce qu’elle fait. Un plugin peut exécuter des commandes shell au moyen de hooks, ajouter des exécutables au PATH de l’outil Bash et démarrer des serveurs MCP, avec tous les privilèges de votre utilisateur. Anthropic ne contrôle ni ne vérifie le contenu des plugins tiers. Installez les plugins depuis des sources dont vous pouvez lire le code, examinez la liste Will install avant de confirmer et appliquez des règles plus strictes sur un serveur que sur un ordinateur portable, car le compte qui y est utilisé détient généralement des clés et des tokens qu’un attaquant pourrait voler.