Créer et distribuer une place de marché de plugins

Créez et hébergez des places de marché de plugins pour distribuer les extensions Claude Code dans vos équipes et communautés.

Une place de marché de plugins est un catalogue qui vous permet de distribuer des plugins à d'autres. Les places de marché offrent une découverte centralisée, un suivi des versions, des mises à jour automatiques et la prise en charge de plusieurs types de sources, notamment les dépôts git et les chemins locaux. Ce guide vous montre comment créer votre propre place de marché pour partager des plugins avec votre équipe ou votre communauté.

Vous cherchez à installer des plugins à partir d'une place de marché existante ? Consultez Découvrir et installer des plugins préconfigurés.

Aperçu

La création et la distribution d'une place de marché impliquent :

1. Créer des plugins : créez un ou plusieurs plugins avec des compétences, des agents, des hooks, des serveurs MCP ou des serveurs LSP. Ce guide suppose que vous avez déjà des plugins à distribuer ; consultez Créer des plugins pour plus de détails sur la création de plugins.
2. Créer le fichier de place de marché : définissez un marketplace.json qui répertorie vos plugins et où les trouver. Voir Créer le fichier de place de marché.
3. Héberger la place de marché : poussez vers GitHub, GitLab ou un autre hôte git. Voir Héberger et distribuer les places de marché.
4. Partager avec les utilisateurs : les utilisateurs ajoutent votre place de marché avec /plugin marketplace add et installent des plugins individuels. Voir Découvrir et installer des plugins.

Une fois votre place de marché en ligne, vous pouvez la mettre à jour en poussant les modifications vers votre dépôt. Les utilisateurs actualisent leur copie locale avec /plugin marketplace update.

Procédure pas à pas : créer une place de marché locale

Cet exemple crée une place de marché avec un plugin : une compétence quality-review pour les révisions de code. Vous allez créer la structure de répertoires, ajouter une compétence, créer le manifeste du plugin et le catalogue de la place de marché, puis l'installer et la tester.

mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review

---
description: Review code for bugs, security, and performance
---

Review the code I've selected or the recent changes for:
- Potential bugs or edge cases
- Security concerns
- Performance issues
- Readability improvements

Be concise and actionable.

{
"name": "quality-review-plugin",
"description": "Adds a quality-review skill for quick code reviews",
"version": "1.0.0"
}

{
"name": "my-plugins",
"owner": {
"name": "Your Name"
},
"plugins": [
{
"name": "quality-review-plugin",
"source": "./plugins/quality-review-plugin",
"description": "Adds a quality-review skill for quick code reviews"
}
]
}

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

/quality-review-plugin:quality-review

Pour en savoir plus sur ce que les plugins peuvent faire, notamment les hooks, les agents, les serveurs MCP et les serveurs LSP, consultez Plugins.

Créer le fichier de place de marché

Créez .claude-plugin/marketplace.json à la racine de votre dépôt. Ce fichier définit le nom de votre place de marché, les informations du propriétaire et une liste de plugins avec leurs sources.

Chaque entrée de plugin a besoin au minimum d'un name et d'une source qui indique à Claude Code où la récupérer. Consultez le schéma complet ci-dessous pour tous les champs disponibles.

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

Schéma de la place de marché

Champs obligatoires

Champs du propriétaire

Champs optionnels

description et version sont également acceptés sous metadata pour la compatibilité rétroactive.

Entrées de plugin

Chaque entrée de plugin dans le tableau plugins décrit un plugin et où le trouver. Vous pouvez inclure n'importe quel champ du schéma du manifeste du plugin, tel que description, version, author, commands et hooks, plus ces champs spécifiques à la place de marché : source, category, tags, strict et relevance.

Champs obligatoires

Champs de plugin optionnels

Champs de métadonnées standard :

Champs de configuration des composants :

Sources de plugin

Les sources de plugin indiquent à Claude Code où récupérer chaque plugin individuel répertorié dans votre place de marché. Elles sont définies dans le champ source de chaque entrée de plugin dans marketplace.json.

Une fois qu'un plugin est cloné ou téléchargé sur la machine locale, il est copié dans le cache de plugin local versionné à ~/.claude/plugins/cache.

Les types de source basés sur git ci-dessous sont github, url et git-subdir. Lorsque ref et sha sont tous deux définis sur l'un d'eux, le sha est l'épingle effective. Claude Code récupère et vérifie le commit épinglé directement.

Sur la plupart des hôtes git, y compris GitHub, GitLab et Bitbucket, cela signifie que l'installation réussit même si la branche ou le tag nommé par ref a depuis été supprimé en amont, tant que le commit est toujours accessible à partir du dépôt. Certains serveurs, tels qu'AWS CodeCommit, ne prennent pas en charge la récupération des commits par SHA. Sur ces serveurs, le ref doit toujours exister et le commit épinglé doit être accessible à partir de celui-ci.

Chemins relatifs

Pour les plugins dans le même dépôt, utilisez un chemin commençant par ./ :

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

Les chemins se résolvent par rapport à la racine de la place de marché, qui est le répertoire contenant .claude-plugin/. Dans l'exemple ci-dessus, ./plugins/my-plugin pointe vers <repo>/plugins/my-plugin, même si marketplace.json se trouve à <repo>/.claude-plugin/marketplace.json. N'utilisez pas ../ pour référencer des chemins en dehors de la racine de la place de marché.

Dépôts GitHub

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}

Vous pouvez épingler à une branche, un tag ou un commit spécifique :

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Dépôts Git

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

Vous pouvez épingler à une branche, un tag ou un commit spécifique :

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Sous-répertoires Git

Utilisez git-subdir pour pointer vers un plugin qui se trouve dans un sous-répertoire d'un dépôt git. Claude Code utilise un clone partiel et clairsemé pour récupérer uniquement le sous-répertoire, minimisant la bande passante pour les grands monodépôts.

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin"
  }
}

Vous pouvez épingler à une branche, un tag ou un commit spécifique :

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Le champ url accepte également un raccourci GitHub (owner/repo) ou des URL SSH (git@github.com:owner/repo.git).

Paquets npm

Les plugins distribués en tant que paquets npm sont installés à l'aide de npm install. Cela fonctionne avec n'importe quel paquet du registre npm public ou d'un registre privé que votre équipe héberge.

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}

Pour épingler à une version spécifique, ajoutez le champ version :

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0"
  }
}

Pour installer à partir d'un registre privé ou interne, ajoutez le champ registry :

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

Entrées de plugin avancées

Cet exemple montre une entrée de plugin utilisant de nombreux champs optionnels, notamment des chemins personnalisés pour les commandes, les agents, les hooks et les serveurs MCP :

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "enterprise@example.com"
  },
  "homepage": "https://docs.example.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

Points clés à noter :

• commands et agents : vous pouvez spécifier plusieurs répertoires ou fichiers individuels. Les chemins sont relatifs à la racine du plugin.
• ${CLAUDE_PLUGIN_ROOT} : Utilisez cette variable dans les hooks et les configurations du serveur MCP pour référencer les fichiers dans le répertoire d'installation du plugin. C'est nécessaire car les plugins sont copiés vers un emplacement de cache lors de l'installation. Pour les dépendances ou l'état qui doivent survivre aux mises à jour des plugins, utilisez ${CLAUDE_PLUGIN_DATA} à la place.
• strict: false : puisque ceci est défini sur false, le plugin n'a pas besoin de son propre plugin.json. L'entrée de la place de marché définit tout. Voir Mode strict ci-dessous.

Par défaut, les compétences d'un plugin se chargent à partir du répertoire skills/ sous sa source. Les chemins répertoriés dans le champ skills s'ajoutent à cette analyse :

"skills": ["./skills/", "./extra-skills/"]

Lorsque plusieurs entrées de plugin partagent un dossier skills/ à la racine de la place de marché (source: "./"), énumérez plutôt des sous-répertoires spécifiques afin que chaque entrée ne charge que ses propres compétences :

"source": "./",
"skills": ["./skills/code-review", "./skills/docs"]

Avec une source à la racine de la place de marché, les chemins énumérés constituent l'ensemble complet pour cette entrée, et les autres répertoires dans le dossier skills/ partagé ne se chargent pas. L'énumération du répertoire skills/ lui-même, ou de la racine du plugin, maintient l'analyse complète. Si aucun des chemins énumérés n'existe, l'analyse par défaut s'exécute à la place.

Mode strict

Le champ strict contrôle si plugin.json est l'autorité pour les définitions de composants (compétences, agents, hooks, serveurs MCP, styles de sortie).

Quand utiliser chaque mode :

• strict: true : le plugin a son propre plugin.json et gère ses propres composants. L'entrée de la place de marché peut ajouter des compétences ou des hooks supplémentaires par-dessus. C'est la valeur par défaut et fonctionne pour la plupart des plugins.
• strict: false : l'opérateur de la place de marché veut le contrôle total. Le dépôt du plugin fournit des fichiers bruts, et l'entrée de la place de marché définit lesquels de ces fichiers sont exposés en tant que compétences, agents, hooks, etc. Utile lorsque la place de marché restructure ou sélectionne les composants d'un plugin différemment de ce que l'auteur du plugin avait prévu.

Héberger et distribuer les places de marché

Héberger sur GitHub (recommandé)

GitHub est la méthode recommandée pour héberger et distribuer une place de marché :

1. Créer un dépôt : Configurez un nouveau dépôt pour votre place de marché
2. Ajouter le fichier de place de marché : Créez .claude-plugin/marketplace.json avec vos définitions de plugins
3. Partager avec les équipes : Les utilisateurs ajoutent votre place de marché avec /plugin marketplace add owner/repo

Avantages : Contrôle de version intégré, suivi des problèmes et fonctionnalités de collaboration d'équipe.

Héberger sur d'autres services git

N'importe quel service d'hébergement git fonctionne, comme GitLab, Bitbucket et les serveurs auto-hébergés. Les utilisateurs ajoutent avec l'URL complète du dépôt :

/plugin marketplace add https://gitlab.com/company/plugins.git

Dépôts privés

Claude Code prend en charge l'installation de plugins à partir de dépôts privés. Pour l'installation manuelle et les mises à jour, Claude Code utilise vos assistants de credentials git existants, donc l'accès HTTPS via gh auth login, Keychain macOS ou git-credential-store fonctionne de la même manière que dans votre terminal. L'accès SSH fonctionne tant que l'hôte est déjà dans votre fichier known_hosts et que la clé est chargée dans ssh-agent, puisque Claude Code supprime les invites SSH interactives pour l'empreinte digitale de l'hôte et la phrase de passe de la clé.

Les mises à jour automatiques en arrière-plan s'exécutent au démarrage sans assistants de credentials, car les invites interactives bloqueraient le démarrage de Claude Code. Pour activer les mises à jour automatiques pour les places de marché privées, définissez le jeton d'authentification approprié dans votre environnement :

Définissez le jeton dans votre configuration de shell (par exemple, .bashrc, .zshrc) ou passez-le lors de l'exécution de Claude Code :

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Tester localement avant la distribution

Testez votre place de marché localement avant de la partager :

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

Pour la gamme complète de commandes add (GitHub, URL Git, chemins locaux, URL distantes), consultez Ajouter des places de marché.

Exiger des places de marché pour votre équipe

Vous pouvez configurer votre dépôt pour que les membres de l'équipe soient automatiquement invités à installer votre place de marché lorsqu'ils font confiance au dossier du projet. Ajoutez votre place de marché à .claude/settings.json :

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

Vous pouvez également spécifier quels plugins doivent être activés par défaut :

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

Pour les options de configuration complètes, consultez Paramètres des plugins.

Pré-remplir les plugins pour les conteneurs

Pour les images de conteneur et les environnements CI, vous pouvez pré-remplir un répertoire de plugins au moment de la construction afin que Claude Code démarre avec des places de marché et des plugins déjà disponibles, sans rien cloner au moment de l'exécution. Définissez la variable d'environnement CLAUDE_CODE_PLUGIN_SEED_DIR pour pointer vers ce répertoire.

Pour superposer plusieurs répertoires de seed, séparez les chemins avec : sur Unix ou ; sur Windows. Claude Code recherche chaque répertoire dans l'ordre et utilise le premier seed qui contient une place de marché ou un cache de plugin donné.

Le répertoire de seed reflète la structure de ~/.claude/plugins :

$CLAUDE_CODE_PLUGIN_SEED_DIR/
  known_marketplaces.json
  marketplaces/<name>/...
  cache/<marketplace>/<plugin>/<version>/...

Pour construire un répertoire de seed, exécutez Claude Code une fois lors de la construction de l'image, installez les plugins dont vous avez besoin, puis copiez le répertoire ~/.claude/plugins résultant dans votre image et pointez CLAUDE_CODE_PLUGIN_SEED_DIR vers lui.

Pour ignorer l'étape de copie, définissez CLAUDE_CODE_PLUGIN_CACHE_DIR sur votre chemin de seed cible lors de la construction afin que les plugins s'installent directement là :

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins

Ensuite, définissez CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed dans l'environnement d'exécution de votre conteneur afin que Claude Code lise à partir du seed au démarrage.

Au démarrage, Claude Code enregistre les places de marché trouvées dans le known_marketplaces.json du seed dans la configuration principale, et utilise les caches de plugins trouvés sous cache/ en place sans re-cloner. Cela fonctionne à la fois en mode interactif et en mode non-interactif avec le drapeau -p.

Détails du comportement :

• Lecture seule : le répertoire de seed n'est jamais écrit. Les mises à jour automatiques sont désactivées pour les places de marché de seed puisque git pull échouerait sur un système de fichiers en lecture seule.
• Les entrées de seed ont la priorité : les places de marché déclarées dans le seed remplacent toutes les entrées correspondantes dans la configuration de l'utilisateur à chaque démarrage. Pour refuser un plugin de seed, utilisez /plugin disable plutôt que de supprimer la place de marché.
• Résolution des chemins : Claude Code localise le contenu de la place de marché en sondant $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/ au moment de l'exécution, pas en faisant confiance aux chemins stockés dans le JSON du seed. Cela signifie que le seed fonctionne correctement même lorsqu'il est monté à un chemin différent de celui où il a été construit.
• La mutation est bloquée : l'exécution de /plugin marketplace remove ou /plugin marketplace update contre une place de marché gérée par seed échoue avec des conseils pour demander à votre administrateur de mettre à jour l'image de seed.
• Compose avec les paramètres : si extraKnownMarketplaces ou enabledPlugins déclarent une place de marché qui existe déjà dans le seed, Claude Code utilise la copie du seed au lieu de cloner.

Restrictions des places de marché gérées

Pour les organisations nécessitant un contrôle strict sur les sources de plugins, les administrateurs peuvent restreindre les places de marché de plugins que les utilisateurs sont autorisés à ajouter en utilisant le paramètre strictKnownMarketplaces dans les paramètres gérés. Pour également rejeter les drapeaux CLI qui chargent les plugins, les agents et les serveurs MCP pour une seule exécution, associez-le à disableSideloadFlags.

Lorsque strictKnownMarketplaces est configuré dans les paramètres gérés, le comportement de restriction dépend de la valeur :

Configurations courantes

Désactiver tous les ajouts de place de marché :

{
  "strictKnownMarketplaces": []
}

Autoriser uniquement les places de marché spécifiques :

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    }
  ]
}

Autoriser toutes les places de marché d'un serveur git interne en utilisant la correspondance de motif regex sur l'hôte. C'est l'approche recommandée pour GitHub Enterprise Server ou les instances GitLab auto-hébergées :

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

Autoriser les places de marché basées sur le système de fichiers à partir d'un répertoire spécifique en utilisant la correspondance de motif regex sur le chemin :

{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}

Utilisez ".*" comme pathPattern pour autoriser n'importe quel chemin du système de fichiers tout en contrôlant les sources réseau avec hostPattern.

Comment fonctionnent les restrictions

Les restrictions sont vérifiées avant toute opération réseau ou système de fichiers. La vérification s'exécute lors de l'ajout de place de marché et lors de l'installation, la mise à jour, l'actualisation et la mise à jour automatique du plugin. Si une place de marché a été ajoutée avant la configuration de la politique et que sa source ne correspond plus à la liste d'autorisation, Claude Code refuse d'installer ou de mettre à jour les plugins à partir de celle-ci. L'application de la même restriction s'applique à blockedMarketplaces.

La liste d'autorisation utilise la correspondance exacte pour la plupart des types de sources. Pour qu'une place de marché soit autorisée, tous les champs spécifiés doivent correspondre exactement :

• Pour les sources GitHub : repo est obligatoire, et ref ou path doivent également correspondre s'ils sont spécifiés dans la liste d'autorisation
• Pour les sources URL : l'URL complète doit correspondre exactement
• Pour les sources hostPattern : l'hôte de la place de marché est comparé au motif regex
• Pour les sources pathPattern : le chemin du système de fichiers de la place de marché est comparé au motif regex

La correspondance exacte ne normalise pas les URL : une barre oblique finale, un suffixe .git ou une forme ssh:// par rapport à https:// sont traités comme des valeurs différentes. Si la place de marché de votre organisation peut être clonée par plus d'une forme d'URL, préférez une entrée hostPattern à une URL littérale afin que toutes les formes correspondent.

Parce que strictKnownMarketplaces est défini dans les paramètres gérés, les configurations individuelles des utilisateurs et des projets ne peuvent pas contourner ces restrictions.

Pour les détails de configuration complets, y compris tous les types de sources pris en charge et la comparaison avec extraKnownMarketplaces, consultez la référence strictKnownMarketplaces.

Résolution des versions et canaux de publication

Les versions des plugins déterminent les chemins du cache et la détection des mises à jour : si la version résolue correspond à ce qu'un utilisateur possède déjà, /plugin update et la mise à jour automatique ignorent le plugin.

Claude Code résout la version d'un plugin à partir du premier de ces éléments qui est défini :

1. version dans le plugin.json du plugin
2. version dans l'entrée de la place de marché du plugin
3. Le SHA du commit git de la source du plugin

Pour les types de sources basés sur git github, url, git-subdir et les chemins relatifs à l'intérieur d'une place de marché hébergée sur git, vous pouvez omettre entièrement version et chaque nouveau commit est traité comme une nouvelle version. C'est la configuration la plus simple pour les plugins internes ou en développement actif.

Configurer les canaux de publication

Pour prendre en charge les canaux de publication « stable » et « latest » pour vos plugins, vous pouvez configurer deux places de marché qui pointent vers différentes refs ou SHAs du même dépôt. Vous pouvez ensuite assigner les deux places de marché à différents groupes d'utilisateurs via les paramètres gérés.

Exemple

{
  "name": "stable-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "stable"
      }
    }
  ]
}

{
  "name": "latest-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "latest"
      }
    }
  ]
}

Assigner les canaux aux groupes d'utilisateurs

Assignez chaque place de marché au groupe d'utilisateurs approprié via les paramètres gérés. Par exemple, le groupe stable reçoit :

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}

Le groupe early-access reçoit latest-tools à la place :

{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/latest-tools"
      }
    }
  }
}

Épingler les versions des dépendances

Un plugin peut contraindre ses dépendances à une plage semver afin que les mises à jour d'une dépendance ne cassent pas le plugin dépendant. Consultez Contraindre les versions des dépendances de plugins pour la convention de balise git {plugin-name}--v{version}, la syntaxe de plage et la façon dont plusieurs contraintes sur la même dépendance sont combinées.

Renommer ou supprimer un plugin

Le name d'un plugin est son identifiant stable. Les utilisateurs le référencent dans enabledPlugins, pluginConfigs et les commandes /plugin install, donc le changer casse chaque installation existante. Pour changer l'étiquette affichée dans l'interface utilisateur sans casser les installations, définissez displayName et gardez name inchangé.

Si vous devez changer le name d'un plugin, ou si vous supprimez un plugin du tableau plugins, ajoutez une entrée renames au niveau supérieur afin que les utilisateurs existants migrent au lieu de voir une erreur plugin-not-found. La migration automatique nécessite Claude Code v2.1.193 ou ultérieur. Mappez chaque ancien nom à son nouveau nom, ou à null si le plugin n'existe plus. L'exemple suivant renomme formatter en code-formatter et enregistre que legacy-linter a été supprimé :

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

Lorsqu'un utilisateur démarre Claude Code avec l'ancien nom toujours dans ses paramètres, Claude Code suit la carte renames :

• Si l'entrée pointe vers un nouveau nom, Claude Code charge le plugin sous son nouveau nom et affiche un avis d'une ligne tel que Renamed to "code-formatter" in the "acme-tools" marketplace. Il réécrit ensuite l'ancienne clé vers la nouvelle clé dans les portées de paramètres utilisateur, projet et local pour enabledPlugins et pluginConfigs, afin que l'avis n'apparaisse qu'une fois.
• Pour une entrée null, Claude Code supprime l'ancienne clé et l'avis signale que le plugin a été supprimé de la place de marché.
• Si le plugin renommé utilise une source distante telle que github ou npm, Claude Code signale plugin-cache-miss après le renommage et l'utilisateur doit exécuter /plugin install une fois pour le récupérer sous le nouveau nom.

Traitez renames comme un historique d'ajout uniquement : gardez les anciennes entrées en place même après vous attendre à ce que chaque utilisateur ait migré. Claude Code suit les chaînes, donc si vous renommez ultérieurement code-formatter en formatter-pro, ajoutez une deuxième entrée plutôt que de modifier la première. Un utilisateur qui a toujours le formatter original activé se résout ensuite à travers les deux entrées vers formatter-pro.

Exécutez claude plugin validate . après avoir modifié la carte ; il rejette toute entrée dont la chaîne forme un cycle ou ne se termine pas à null ou à un nom listé dans plugins.

Les versions antérieures de Claude Code ignorent le champ renames et signalent plugin-not-found pour l'ancien nom.

Validation et test

Testez votre place de marché avant de la partager.

Validez la syntaxe JSON de votre place de marché :

claude plugin validate .

Ou depuis Claude Code :

/plugin validate .

Ajoutez la place de marché pour le test :

/plugin marketplace add ./path/to/marketplace

Installez un plugin de test pour vérifier que tout fonctionne :

/plugin install test-plugin@marketplace-name

Pour les flux de travail complets de test de plugins, consultez Tester vos plugins localement. Pour le dépannage technique, consultez Référence des plugins.

Gérer les places de marché à partir de la CLI

Claude Code fournit des sous-commandes claude plugin marketplace non-interactives pour les scripts et l'automatisation. Elles sont équivalentes aux commandes /plugin marketplace disponibles dans une session interactive.

Plugin marketplace add

Ajoutez une place de marché à partir d'un dépôt GitHub, d'une URL git, d'une URL distante ou d'un chemin local.

claude plugin marketplace add <source> [options]

Arguments :

• <source> : Raccourci GitHub owner/repo, URL git, URL distante vers un fichier marketplace.json ou chemin de répertoire local. Pour épingler à une branche ou un tag, ajoutez @ref au raccourci GitHub ou #ref à une URL git

Une URL doit inclure son schéma. À partir de Claude Code v2.1.196, un hôte saisi sans schéma, tel que gitlab.example.com/team/plugins, est rejeté comme un raccourci owner/repo invalide et l'erreur vous indique d'ajouter https:// ou d'utiliser ./ pour un chemin local. Les versions antérieures l'interprétaient mal comme un chemin de dépôt GitHub et échouent au moment du clonage avec une erreur GitHub non trouvé.

Options :

Ajoutez une place de marché à partir de GitHub en utilisant le raccourci owner/repo :

claude plugin marketplace add acme-corp/claude-plugins

Épinglez à une branche ou un tag spécifique avec @ref :

claude plugin marketplace add acme-corp/claude-plugins@v2.0

Ajoutez à partir d'une URL git sur un hôte non-GitHub :

claude plugin marketplace add https://gitlab.example.com/team/plugins.git

Ajoutez à partir d'une URL distante qui sert le fichier marketplace.json directement :

claude plugin marketplace add https://example.com/marketplace.json

Ajoutez à partir d'un répertoire local pour le test :

claude plugin marketplace add ./my-marketplace

Déclarez la place de marché à la portée du projet afin qu'elle soit partagée avec votre équipe via .claude/settings.json :

claude plugin marketplace add acme-corp/claude-plugins --scope project

Pour un monodépôt, limitez le checkout aux répertoires qui contiennent le contenu du plugin :

claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

Plugin marketplace list

Listez toutes les places de marché configurées.

claude plugin marketplace list [options]

Options :

Avec --json, chaque entrée inclut name, source et des champs spécifiques à la source : repo pour les sources GitHub, url pour les sources git et URL, et path pour les sources locales. Les sources GitHub et git incluent également un champ ref lorsque la place de marché a été ajoutée avec une branche ou un tag épinglé.

Plugin marketplace remove

Supprimez une place de marché configurée. L'alias rm est également accepté.

claude plugin marketplace remove <name> [options]

Arguments :

• <name> : nom de la place de marché à supprimer, comme indiqué par claude plugin marketplace list. C'est le name de marketplace.json, pas la source que vous avez passée à add

Options :

Plugin marketplace update

Actualisez les places de marché à partir de leurs sources pour récupérer les nouveaux plugins et les changements de version.

claude plugin marketplace update [name]

Arguments :

• [name] : nom de la place de marché à mettre à jour, comme indiqué par claude plugin marketplace list. Met à jour toutes les places de marché si omis

À la fois remove et update échouent lorsqu'ils sont exécutés contre une place de marché gérée par seed, qui est en lecture seule. Lors de la mise à jour de toutes les places de marché, les entrées gérées par seed sont ignorées et les autres places de marché se mettent toujours à jour. Pour modifier les plugins fournis par seed, demandez à votre administrateur de mettre à jour l'image de seed. Voir Pré-remplir les plugins pour les conteneurs.

Dépannage

La place de marché ne se charge pas

Symptômes : Impossible d'ajouter la place de marché ou de voir les plugins qu'elle contient

Solutions :

• Vérifiez que l'URL de la place de marché est accessible
• Vérifiez que .claude-plugin/marketplace.json existe au chemin spécifié
• Assurez-vous que la syntaxe JSON est valide en utilisant claude plugin validate ou /plugin validate. Pour vérifier le frontmatter des compétences, agents et commandes, exécutez la commande sur chaque répertoire de plugin
• Pour les dépôts privés, confirmez que vous avez les permissions d'accès

Erreurs de validation de la place de marché

Exécutez claude plugin validate . ou /plugin validate . à partir de votre répertoire de place de marché pour vérifier les problèmes. Lorsqu'il est pointé sur un répertoire de place de marché, le validateur vérifie marketplace.json pour les erreurs de schéma, les noms de plugins en doublon et la traversée de chemin source. Pour chaque entrée dont la source est un chemin local, il valide également le plugin.json de ce plugin et avertit lorsque la version de l'entrée ne correspond pas à celle dans plugin.json. Les problèmes trouvés dans le plugin.json d'un plugin sont préfixés par l'index d'entrée, sous la forme plugins[2] plugin.json →.

À partir de Claude Code v2.1.196, la passe par entrée inclut également :

• les plugins dont la source est .
• s'exécute lorsque marketplace.json est en dehors d'un répertoire .claude-plugin, en résolvant les sources par rapport au répertoire du fichier lui-même
• signale les problèmes de chaque entrée même lorsqu'une autre partie du fichier a des erreurs de schéma

Les versions antérieures ignorent les plugins à la racine de la place de marché et ne descendent que depuis un .claude-plugin/marketplace.json.

Pour valider le plugin.json d'un plugin individuel et ses fichiers de compétence, agent, commande et hook, exécutez la commande sur le répertoire du plugin lui-même, par exemple claude plugin validate ./plugins/my-plugin. Erreurs courantes :

Avertissements (non bloquants) :

• Marketplace has no plugins defined : ajoutez au moins un plugin au tableau plugins
• No marketplace description provided : ajoutez une description au niveau supérieur pour aider les utilisateurs à comprendre votre place de marché
• Plugin name "x" is not kebab-case : le nom du plugin contient des lettres majuscules, des espaces ou des caractères spéciaux. Renommez en minuscules, chiffres et tirets uniquement (par exemple, my-plugin). Claude Code accepte d'autres formes, mais la synchronisation de la place de marché Claude.ai les rejette.

Échecs d'installation de plugins

Symptômes : La place de marché apparaît mais l'installation du plugin échoue

Solutions :

• Vérifiez que les URL sources des plugins sont accessibles
• Vérifiez que les répertoires des plugins contiennent les fichiers requis
• Pour les sources GitHub, assurez-vous que les dépôts sont publics ou que vous avez accès
• Testez manuellement les sources de plugins en les clonant/téléchargeant
• Si la source épingle à la fois ref et sha, une branche ou un tag en amont supprimé ne bloque pas l'installation sur la plupart des hôtes git, y compris GitHub, GitLab et Bitbucket. Sur les serveurs qui ne supportent pas la récupération des commits par SHA, comme AWS CodeCommit, le ref doit toujours exister et le commit épinglé doit être accessible à partir de celui-ci. Si l'installation échoue toujours, confirmez que le commit épinglé existe toujours dans le dépôt

L'authentification du dépôt privé échoue

Symptômes : Erreurs d'authentification lors de l'installation de plugins à partir de dépôts privés

Solutions :

Pour l'installation manuelle et les mises à jour :

• Vérifiez que vous êtes authentifié auprès de votre fournisseur git (par exemple, exécutez gh auth status pour GitHub)
• Vérifiez que votre assistant de credentials est configuré correctement : git config --global credential.helper
• Essayez de cloner le dépôt manuellement pour vérifier que vos credentials fonctionnent

Pour les mises à jour automatiques en arrière-plan :

• Définissez le jeton approprié dans votre environnement : echo $GITHUB_TOKEN
• Vérifiez que le jeton a les permissions requises (accès en lecture au dépôt)
• Pour GitHub, assurez-vous que le jeton a la portée repo pour les dépôts privés
• Pour GitLab, assurez-vous que le jeton a au moins la portée read_repository
• Vérifiez que le jeton n'a pas expiré

Les mises à jour de la place de marché échouent dans les environnements hors ligne

Symptômes : Le git pull de la place de marché échoue et Claude Code efface le cache existant, rendant les plugins indisponibles.

Cause : Par défaut, lorsqu'un git pull échoue, Claude Code supprime le clone obsolète et tente de re-cloner. Dans les environnements hors ligne ou isolés, le re-clonage échoue de la même manière, laissant le répertoire de la place de marché vide.

Solution : Définissez CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 pour conserver le cache existant lorsque le pull échoue au lieu de l'effacer :

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

Avec cette variable définie, Claude Code conserve le clone obsolète de la place de marché en cas d'échec de git pull et continue d'utiliser le dernier état connu bon. Pour les déploiements entièrement hors ligne où le dépôt ne sera jamais accessible, utilisez CLAUDE_CODE_PLUGIN_SEED_DIR pour pré-remplir le répertoire des plugins au moment de la construction à la place.

Les opérations Git expirent

Symptômes : L'installation du plugin ou les mises à jour de la place de marché échouent avec une erreur de délai d'expiration comme « Git clone timed out after 120s » ou « Git pull timed out after 120s ».

Cause : Claude Code utilise un délai d'expiration de 120 secondes pour toutes les opérations git, y compris le clonage des dépôts de plugins et l'extraction des mises à jour de la place de marché. Les grands dépôts ou les connexions réseau lentes peuvent dépasser cette limite.

Solution : Augmentez le délai d'expiration en utilisant la variable d'environnement CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS. La valeur est en millisecondes :

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 minutes

Les plugins avec chemins relatifs échouent dans les places de marché basées sur les URL

Symptômes : Vous avez ajouté une place de marché via URL (comme https://example.com/marketplace.json), mais les plugins avec des sources de chemin relatif comme "./plugins/my-plugin" échouent à installer avec des erreurs « path not found ».

Cause : Les places de marché basées sur les URL téléchargent uniquement le fichier marketplace.json lui-même. Elles ne téléchargent pas les fichiers de plugins du serveur. Les chemins relatifs dans l'entrée de la place de marché référencent des fichiers sur le serveur distant qui n'ont pas été téléchargés.

Solutions :

• Utiliser des sources externes : Changez les entrées de plugins pour utiliser les sources GitHub, npm ou URL git au lieu des chemins relatifs :

  { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
  

• Utiliser une place de marché basée sur Git : Hébergez votre place de marché dans un dépôt Git et ajoutez-la avec l'URL git. Les places de marché basées sur Git clonent le dépôt entier, ce qui rend les chemins relatifs fonctionnels.

Fichiers non trouvés après l'installation

Symptômes : Le plugin s'installe mais les références aux fichiers échouent, en particulier les fichiers en dehors du répertoire du plugin

Cause : Les plugins sont copiés vers un répertoire de cache plutôt que d'être utilisés sur place. Les chemins qui référencent des fichiers en dehors du répertoire du plugin (comme ../shared-utils) ne fonctionneront pas car ces fichiers ne sont pas copiés.

Solutions : Consultez Plugin caching and file resolution pour les solutions de contournement, y compris les symlinks et la restructuration des répertoires.

Pour des outils de débogage supplémentaires et des problèmes courants, consultez Debugging and development tools.

Voir aussi

• Découvrir et installer des plugins préconfigurés - Installation de plugins à partir de places de marché existantes
• Plugins - Création de vos propres plugins
• Référence des plugins - Spécifications techniques complètes et schémas
• Paramètres des plugins - Options de configuration des plugins
• Référence strictKnownMarketplaces - Restrictions des places de marché gérées