Plugin Claude Code : partager ses skills en équipe

Nos guides précédents ajoutent chacun une pièce à un poste de travail d'agence : un skill de reporting, des sous-agents d'audit et un hook de lecture seule. À notre avis, recopier ces fichiers dans le dossier .claude/ de chaque collaborateur crée des versions qui divergent. Claude Code propose pour cela les plugins : un dossier qui regroupe skills, sous-agents, hooks et serveurs MCP, installé et chargé comme une seule unité. Ce guide montre comment assembler un plugin d'agence, le tester, le publier dans une marketplace privée et relire un plugin avant de l'installer.

Les faits viennent des pages plugins de la documentation de Claude Code (vue d'ensemble, création, composants, création et hébergement d'une marketplace, installation, sécurité, référence de la marketplace), consultées le 14 octobre 2026. Le plugin d'exemple est notre assemblage : aucune de ces pages n'en publie de semblable.

Ce qu'est un plugin, et quand en faire un

D'après la vue d'ensemble, un plugin est un dossier de composants, avec en général un manifeste, un fichier JSON situé à .claude-plugin/plugin.json qui donne son nom au plugin. Une marketplace est un catalogue : un dépôt ou un dossier contenant .claude-plugin/marketplace.json, qui liste des plugins et indique où récupérer chacun. La documentation le décrit comme un catalogue.

La documentation conseille de garder le montage autonome (fichiers dans .claude/) tant qu'il sert un seul projet ou une seule personne, et de créer un plugin pour le partager avec des collègues, l'installer dans plusieurs projets ou publier des versions. Les composants vont dans des dossiers fixes à la racine du plugin :

Des composants rangés dans .claude-plugin/ ne se chargent pas, et un .mcp.json placé dans ~/.claude/ non plus : la racine du plugin est son propre dossier.

Un plugin d'agence en trois composants

Notre exemple regroupe les trois pièces des guides précédents :

agence-ads/
  .claude-plugin/
    plugin.json
  skills/
    rapport-hebdo/
      SKILL.md                  le skill de reporting
  agents/
    tracking-auditor.md         l'auditeur de tracking en lecture seule
  hooks/
    hooks.json                  le garde-fou de lecture seule
  scripts/
    lecture-seule.sh
    outils-lecture.txt

Le manifeste ne demande que name, qui devient le préfixe de chaque skill et de chaque sous-agent du plugin ; description, version et author sont facultatifs :

{
  "name": "agence-ads",
  "description": "Reporting hebdomadaire, auditeur de tracking et garde-fou de lecture seule",
  "author": { "name": "<nom de l'agence>" }
}

Avec ce nom, le skill se lance par /agence-ads:rapport-hebdo et le sous-agent s'appelle agence-ads:tracking-auditor, que l'on peut désigner avec @agent-agence-ads:tracking-auditor. Le préfixe évite les collisions : deux plugins peuvent fournir chacun un skill rapport-hebdo.

Le hook se déclare dans hooks/hooks.json, avec le chemin du script relatif à la racine du plugin :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__meta-ads__.*",
        "hooks": [
          {
            "type": "command",
            "command": "bash",
            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/lecture-seule.sh"],
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

La variable CLAUDE_PLUGIN_ROOT est fournie à chaque hook du plugin, et avec le champ args chaque élément est passé comme un seul argument, sans guillemets à prévoir ; le champ onFailure demande Claude Code v2.1.295 ou plus. Le script et le fichier de liste sont ceux de notre guide des hooks, déplacés dans scripts/. Le matcher vise un serveur nommé meta-ads que chaque collaborateur ajoute lui-même. Si le serveur était déclaré dans le plugin, ses outils s'appelleraient mcp__plugin_agence-ads_meta-ads__<outil> et le matcher devrait suivre.

Deux contraintes de la documentation expliquent ce découpage. D'abord, les champs permissionMode, hooks et mcpServers sont ignorés dans l'en-tête d'un sous-agent de plugin : un sous-agent de plugin ne peut pas porter son propre hook, c'est pourquoi le garde-fou vit dans hooks/hooks.json. Les champs que notre auditeur utilise (name, description, tools, model, maxTurns) sont pris en charge. Ensuite, Claude Code ne charge pas de CLAUDE.md à la racine d'un plugin ; pour y mettre des instructions, il faut les écrire comme un skill. Le contexte propre à chaque client reste, à notre avis, dans le fichier de son dépôt, comme décrit dans notre guide du CLAUDE.md pour un client.

Tester sans marketplace

Une marketplace n'est pas nécessaire pour développer un plugin. La documentation donne cette séquence :

claude plugin validate ./agence-ads
claude --plugin-dir ./agence-ads

La première commande vérifie le manifeste et l'en-tête de chaque skill, sous-agent et commande ; elle affiche Validation passed en cas de succès, et --strict fait échouer aussi sur les avertissements. La seconde charge le plugin pour une seule session, sans l'installer. Après une modification, /reload-plugins applique les changements dans la session ; l'onglet Errors de /plugin liste ce qui n'a pas chargé, et claude plugin list affiche l'état de chargement des plugins. Pour vérifier un hook, déclenchez l'événement qu'il vise puis lisez le journal de débogage, qui indique les hooks retenus, leurs codes de sortie et leurs sorties. La commande claude plugin eval exécute des cas de test avec et sans le plugin et note l'écart, ce qui sert à vérifier qu'un plugin qui se charge sans erreur oriente Claude comme prévu.

Si vous avez déjà ces fichiers sous .claude/, la documentation décrit une conversion sans réécriture : copier skills/ et agents/ à la racine du plugin et déplacer l'objet hooks d'un fichier de réglages vers hooks/hooks.json. Un point à surveiller : les hooks n'ont pas de préfixe, donc un hook présent à la fois dans vos réglages et dans le plugin s'exécute deux fois. Supprimez les originaux une fois le plugin validé.

Publier dans une marketplace d'équipe

Une marketplace est un dossier avec un fichier .claude-plugin/marketplace.json qui exige trois champs : name, owner et plugins. Chaque entrée de plugins demande un name et une source.

{
  "name": "marketplace-agence",
  "description": "Plugins internes de l'agence",
  "owner": { "name": "<nom de l'agence>" },
  "plugins": [
    {
      "name": "agence-ads",
      "source": "./plugins/agence-ads",
      "description": "Reporting hebdomadaire, auditeur de tracking et garde-fou de lecture seule"
    }
  ]
}

La source d'un plugin rangé dans la marketplace s'écrit comme un chemin relatif à la racine de la marketplace, sans .. ; dans notre exemple, le plugin est copié sous plugins/ dans le dossier de la marketplace. Le nom de l'entrée doit rester identique au nom du manifeste du plugin : s'ils diffèrent, une installation par le nom du manifeste échoue. Le test local tient en trois commandes, qui valident la marketplace, l'enregistrent et installent le plugin sous l'identifiant nom@marketplace :

claude plugin validate ./agence-plugins
claude plugin marketplace add ./agence-plugins
claude plugin install agence-ads@marketplace-agence

Pour l'équipe, la documentation indique qu'on pousse le dossier sur un hébergeur git, que le dépôt peut être privé et que chaque collègue l'enregistre avec une commande. Pour un dépôt privé, Claude Code clone avec les identifiants git déjà présents sur la machine et ne pose aucune question : en HTTPS, ceux de gh auth login, du trousseau macOS ou de git-credential-store conviennent ; en SSH, l'hôte doit figurer dans known_hosts et la clé fonctionner sans demande de phrase secrète. La forme courte propriétaire/dépôt désigne github.com ; pour un autre hébergeur, il faut l'URL complète.

claude plugin marketplace add votre-org/agence-plugins

Trois portées d'installation existent : utilisateur (vous, dans tous les projets de la machine), projet (tous ceux qui travaillent dans le dépôt, par le fichier .claude/settings.json versionné) et local (vous, dans ce dépôt). En portée projet, la documentation précise que versionner l'entrée active le plugin pour les collaborateurs sans le télécharger : chacun lance une fois claude plugin install <nom>@<marketplace> --scope project. Pour enregistrer la marketplace elle-même auprès de tous les collaborateurs d'un dépôt, on ajoute --scope project à la commande marketplace add et on versionne le fichier de réglages produit ; la marketplace est alors enregistrée pour chaque collègue qui fait confiance au dossier.

Reste le versionnage. Les utilisateurs reçoivent une nouvelle copie d'un plugin seulement quand sa version calculée change. Deux options : renseigner version et l'augmenter à chaque publication, ou l'omettre pour que les utilisateurs suivent vos commits. Renseigner version sans la changer laisse les utilisateurs sur leur copie en cache, et la renseigner à la fois dans plugin.json et dans l'entrée de la marketplace fait retenir sans avertissement la valeur de plugin.json, l'écart n'étant signalé que par claude plugin validate. Une exception : un plugin chargé en place depuis une marketplace ajoutée par un chemin local, comme dans notre test, lit vos fichiers courants à chaque démarrage de session et n'est pas contrôlé par version. La mise à jour automatique est désactivée par défaut pour votre marketplace : chaque utilisateur l'active dans l'onglet Marketplaces de /plugin, ou un administrateur l'impose par les réglages gérés.

Ce qu'un plugin ajoute à chaque session

• Du contexte : pour chaque skill et sous-agent que Claude peut invoquer de lui-même, le nom et la description sont dans le contexte à chaque tour, même dans une session où rien du plugin ne s'exécute. Le texte complet ne se charge qu'à l'usage.
• Des processus : les serveurs MCP du plugin tournent dans chaque session où il est activé, et ses hooks se déclenchent sur leurs événements, sans attendre qu'un skill du plugin serve. Notre garde-fou s'applique donc à toute session où le plugin est actif.
• Des permissions : ce que le plugin exécute, il l'exécute sous votre identité.

Pour couper un plugin sans le désinstaller, claude plugin disable ou l'onglet Installed de /plugin suffisent.

Relire un plugin avant de l'installer

D'après la page sécurité, un plugin installé peut exécuter du code arbitraire sur votre machine avec vos privilèges. Ses hooks et ses moniteurs sont des commandes shell exécutées avec toutes vos permissions, ses serveurs MCP de type stdio démarrent comme des processus sur votre machine, son dossier bin/ est ajouté au PATH de l'outil Bash, et ses skills et sous-agents entrent dans le contexte de Claude comme des instructions. Une marketplace publiée par un collègue ou par votre organisation est classée parmi les marketplaces tierces : le nom d'une marketplace indique qui publie le catalogue ; il ne renseigne pas sur ce que fait chaque plugin.

La documentation décrit quatre vérifications. Afficher la source de chaque marketplace avec claude plugin marketplace list. Ouvrir le plugin dans /plugin, dont le panneau « Will install » liste commandes, sous-agents, skills, hooks et serveurs, sans montrer ce qu'un hook exécute. Lire dans le dépôt les fichiers hooks/hooks.json, .mcp.json et le dossier bin/. Et lancer claude --plugin-dir <dossier> plugin details <nom>, qui affiche l'inventaire des composants sans démarrer de session.

Par où commencer

1. Rassembler dans un dossier le skill, le sous-agent et le hook que votre équipe utilise déjà, avec un manifeste minimal (seul name est requis).
2. Lancer claude plugin validate puis claude --plugin-dir, et vérifier chaque composant sous son nouveau nom.
3. Retirer les originaux de .claude/ et du fichier de réglages pour éviter les doublons de hooks.
4. Créer la marketplace dans un dépôt privé, la valider et l'installer sur une machine de test.
5. Choisir entre un champ version augmenté à chaque publication et son omission, puis l'indiquer à l'équipe.

Questions fréquentes sur les plugins Claude Code

Sources consultées le 14 octobre 2026

• Anthropic : vue d'ensemble des plugins, création d'un plugin, composants, création d'une marketplace, hébergement d'une marketplace, installation, sécurité, référence de la marketplace, référence des hooks