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

​

Aperçu

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.

​

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

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

​

Créer le fichier de place de marché

{
  "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

​

Entrées de plugin

​

Champs obligatoires

​

Champs de plugin optionnels

​

Sources de plugin

​

Chemins relatifs

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

​

Dépôts GitHub

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

{
  "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"
  }
}

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

​

Sous-répertoires Git

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

{
  "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"
  }
}

​

Paquets npm

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

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

{
  "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

{
  "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
}

• 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 commandes de hook 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.
  • Consultez le tableau de substitution pour savoir quels champs de configuration le substituent par type de serveur
  • 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.

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

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

​

Mode strict

• 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é)

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

​

Héberger sur d’autres services git

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

​

Dépôts privés

• Définissez CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 pour conserver le clone existant lorsque le pull en arrière-plan échoue, au lieu de supprimer et re-cloner. Vos plugins continuent de fonctionner à partir du dernier état synchronisé, et les mises à jour manuelles avec /plugin marketplace update tirent toujours avec vos credentials.
• Configurez un assistant de credentials git, par exemple avec gh auth setup-git pour GitHub, afin que le fallback re-clone puisse s’authentifier sans inviter.

git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"

​

Tester localement avant la distribution

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

​

Exiger des places de marché pour votre équipe

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

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

​

Pré-remplir les plugins pour les conteneurs

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

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

• 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

​

Configurations courantes

{
  "strictKnownMarketplaces": []
}

{
  "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"
    }
  ]
}

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

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

​

Comment fonctionnent les restrictions

• 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

​

Résolution des versions et canaux de publication

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

​

Configurer les canaux de publication

{
  "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"
      }
    }
  ]
}

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

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

​

Épingler les versions des dépendances

​

Renommer ou supprimer un plugin

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

• 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.

​

Validation et test

claude plugin validate .

/plugin validate .

/plugin marketplace add ./path/to/marketplace

/plugin install test-plugin@marketplace-name

​

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

​

Plugin marketplace add

claude plugin marketplace add <source> [options]

• <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

claude plugin marketplace add acme-corp/claude-plugins

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

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

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

claude plugin marketplace add ./my-marketplace

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

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

​

Plugin marketplace list

claude plugin marketplace list [options]

​

Plugin marketplace remove

claude plugin marketplace remove <name> [options]

• <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

​

Plugin marketplace update

claude plugin marketplace update [name]

• [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

​

Dépannage

​

La place de marché ne se charge pas

• 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é

• 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

• 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

• 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

• 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

• Par défaut, les actualisations en arrière-plan désactivent les assistants de credentials git pour la récupération, de sorte que la récupération ne peut pas s’authentifier via HTTPS. Les dépôts SSH avec une clé chargée dans ssh-agent s’authentifient toujours. Un échec de récupération déclenche un re-clonage à partir de zéro, qui utilise vos credentials stockés mais peut expirer sur les grands dépôts
• Définissez CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 pour conserver le clone existant lorsque la récupération en arrière-plan échoue
• Configurez un assistant de credentials git, par exemple gh auth setup-git, de sorte que le re-clonage de secours puisse s’authentifier
• Si le re-clonage expire sur un grand dépôt, augmentez la limite avec CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS
• Configurez une réécriture d’URL git limitée au dépôt de la place de marché de sorte que la récupération en arrière-plan s’authentifie directement
• Ou mettez à jour les places de marché privées manuellement avec /plugin marketplace update <name>, qui utilise vos credentials

​

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

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

​

Les opérations Git expirent

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

• 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

​

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