Qu'est-ce qu'un plugin#

Un plugin, c'est un dossier qui regroupe tes skills, agents, hooks et serveurs MCP, et que Claude Code charge comme une seule unite installable.

Temps de lecture : 10 min | Niveau : Intermediaire

Ce que tu sauras faire apres#

• Nommer les cinq types de composants qu'un plugin peut contenir.
• Decider si ton besoin merite un plugin ou si une skill seule suffit.
• Expliquer le cycle de vie complet : declare, telecharge, charge.
• Activer et desactiver un plugin sans le desinstaller.
• Estimer ce qu'un plugin coute en contexte a chaque message.

1. La definition exacte#

Un plugin Claude Code est un repertoire de composants, en general accompagne d'un manifeste.

Le manifeste est un fichier JSON situe a .claude-plugin/plugin.json. Il donne au plugin son nom, et peut ajouter une version, une description et d'autres metadonnees.

Voici le plus petit plugin possible :

mon-plugin/
└── .claude-plugin/
    └── plugin.json

{
  "name": "mon-plugin",
  "description": "Ce que fait le plugin",
  "version": "1.0.0",
  "author": {
    "name": "Ton Nom"
  }
}

Le champ name est le seul obligatoire. Il sert d'identifiant et de prefixe a tous les composants du plugin.

Regle importante : seul plugin.json va dans .claude-plugin/. Les composants que tu ajoutes ensuite se posent a cote de ce dossier, jamais dedans. Un skills/ place dans .claude-plugin/ ne se charge pas.

2. Ce qu'un plugin peut contenir#

La doc officielle liste les composants dans un tableau d'emplacements par defaut. Voici ceux que tu vas reellement utiliser en data.

Trois mots de vocabulaire a fixer tout de suite, puisqu'ils reviennent partout :

• skill : un fichier SKILL.md avec des instructions que Claude charge quand sa description correspond a ta tache. Tu peux aussi le lancer toi-meme comme une commande.
• hook : une commande que Claude Code declenche automatiquement a un moment de son cycle de vie, par exemple apres chaque edition de fichier.
• MCP server (serveur MCP) : un serveur externe qui donne des outils a Claude, par exemple un acces a ta base de donnees.

Comment chaque composant est nomme#

C'est le point qui pose le plus de confusion. Le nom du plugin sert de prefixe.

Ce dernier nom d'outil est celui a ecrire dans tes regles de permission et dans les matchers de hooks. Un matcher pose sur le seul nom du serveur ne se declenche jamais.

3. Plugin ou pas plugin ? 🤔#

Les skills, subagents, hooks et serveurs MCP fonctionnent tous sans plugin. Une skill posee dans ~/.claude/skills/ est disponible dans tous tes projets, point.

La doc donne le critere de decision. Je le reformule pour ton cas :

En une phrase : le plugin sert au regroupement et a la distribution. S'il n'y a ni l'un ni l'autre, tu n'en as pas besoin.

Ce qui change quand tu migres vers un plugin#

Si tu deplaces une configuration .claude/ existante dans un plugin, deux choses bougent :

• L'emplacement : les fichiers passent sous la racine du plugin, en skills/, agents/, hooks/hooks.json et .mcp.json.
• Le nom : les skills et agents recoivent le prefixe du plugin. Une skill deploy devient /mon-plugin:deploy.

C'est un effet de bord utile : deux plugins peuvent chacun fournir une skill deploy sans collision.

4. Le cycle de vie 🔄#

Un plugin passe par trois etapes avant de te servir. Quand quelque chose ne marche pas, c'est toujours l'une des trois qui a echoue.

1. DECLARE (reglages)        2. TELECHARGE (disque)       3. CHARGE (session)
   enabledPlugins               ~/.claude/plugins/           au demarrage
   extraKnownMarketplaces       cache/ + les .json           ou /reload-plugins

Etape 1 — Declare, dans tes reglages. La cle enabledPlugins dit quels plugins doivent etre actifs. La cle extraKnownMarketplaces dit quelles marketplaces doivent exister.

Etape 2 — Telecharge, sur le disque. Tout vit sous ~/.claude/plugins/. Les fichiers utiles a connaitre :

Etape 3 — Charge, dans la session. Les plugins se chargent au demarrage de la session. Un changement de reglages ou de disque n'atteint pas la session en cours tant que tu n'as pas lance /reload-plugins ou ouvert une nouvelle session.

C'est pour cette raison que claude plugin update se termine par Restart to apply changes.

Trois variables de chemin#

Tes scripts et configurations peuvent referencer trois variables, ecrites sous la forme ${NOM} :

Point critique : ${CLAUDE_PLUGIN_ROOT} change a chaque mise a jour du plugin, puisqu'il designe un dossier de version. N'y ecris jamais d'etat. Utilise ${CLAUDE_PLUGIN_DATA} pour ca.

5. Activer, desactiver, desinstaller#

Trois actions differentes, souvent confondues.

Un auteur peut livrer un plugin qui demarre eteint, via le champ defaultEnabled du manifeste. Le plugin est alors installe mais reste inactif tant que tu ne l'allumes pas. Une fois que ton reglage est ecrit, il ne bouge plus : un changement de defaultEnabled dans une version suivante ne te concerne plus.

Dans une session, la meme chose se fait via /plugin, onglet Installed : touche Espace pour activer ou desactiver l'element selectionne.

6. Le cout reel d'un plugin actif 💰#

Ce point est trop souvent ignore, et il compte pour toi qui vas empiler des outils data.

Un plugin actif fait partie de chaque session, pas seulement de celles ou tu t'en sers. Concretement :

• Contexte : pour chaque skill, agent et commande que Claude peut invoquer lui-meme, le nom et la description sont dans le contexte de Claude a chaque tour. Ces tokens comptent dans ton usage et prennent de la place dans la fenetre de contexte, meme si rien du plugin ne se declenche. Le texte complet d'une skill ne se charge que si elle est utilisee.
• Processus : les serveurs MCP du plugin tournent a cote de chaque session ou il est actif, et ses hooks se declenchent a leurs evenements.
• Permissions : ce que le plugin execute, il l'execute avec tes droits d'utilisateur.

Pour mesurer, lance dans ton shell :

claude plugin details <nom-du-plugin>

La ligne Always-on donne le nombre de tokens que le plugin ajoute a chaque session, et les lignes par composant montrent quelle skill ou quel agent pese le plus.

Dans une session, l'onglet Installed de /plugin regroupe sous un en-tete Not used recently les plugins que tu pourrais eteindre.

7. Template a copier-coller 📋#

Quand tu hesites sur la forme a donner a ton besoin, copie ce prompt dans une session Claude Code.

Contexte : je travaille en [DEV / DATA ENGINEERING / DATA ANALYTICS] sur [TECHNO : dbt, Airflow, pandas, SQL Server...].

J'ai actuellement ces elements de configuration Claude Code :
- skills : [LISTE_DES_SKILLS]
- agents : [LISTE_DES_AGENTS]
- hooks : [LISTE_DES_HOOKS]
- serveurs MCP : [LISTE_DES_SERVEURS_MCP]

Je veux que ces elements soient disponibles : [POUR MOI SEUL / SUR PLUSIEURS PROJETS / POUR MON EQUIPE DE N PERSONNES].

Questions :
1. Est-ce que j'ai besoin d'un plugin, ou est-ce qu'une configuration standalone suffit ?
2. Si oui, propose-moi le nom du plugin en kebab-case et l'arborescence de dossiers exacte.
3. Estime le cout en contexte : combien de skills seront invocables par le modele et donc presentes a chaque tour ?

Reponds en francais, avec un tableau pour l'arborescence.

A retenir#

• Un plugin est un dossier de composants avec un manifeste .claude-plugin/plugin.json ; le champ name est obligatoire et sert de prefixe a tout le reste.
• Seul plugin.json va dans .claude-plugin/ : les composants se posent a cote, sinon ils ne se chargent pas.
• Le plugin sert au regroupement et a la distribution. Pour une seule skill personnelle, ~/.claude/skills/ suffit.
• Le cycle de vie a trois etapes : declare dans les reglages, telecharge sous ~/.claude/plugins/, charge dans la session. Une session en cours ne voit rien tant que tu n'as pas fait /reload-plugins.
• Un plugin actif coute du contexte a chaque tour, meme inutilise. claude plugin details <nom> te donne le chiffre.
• Ecris ton etat dans ${CLAUDE_PLUGIN_DATA}, jamais dans ${CLAUDE_PLUGIN_ROOT} qui change a chaque version.

Sources#

• Plugins overview — Claude Code
• Add components to a plugin — Claude Code
• Plugin manifest reference — Claude Code
• Plugin loading reference — Claude Code
• Create a plugin — Claude Code
• Install and manage plugins — Claude Code
• anthropics/claude-code - code d'exemple sur ce que contient un plugin : les 13 plugins de plugins/, chacun avec son .claude-plugin/plugin.json et ses dossiers commands/, agents/, skills/, hooks/
• obra/superpowers - code d'exemple sur un plugin reel : .claude-plugin/plugin.json a la racine, skills dans skills/, hooks dans hooks/