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 un 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
disable-model-invocation: true
---

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

​

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

​

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

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

​

Tester localement avant la distribution

/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace

​

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

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

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

​

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>

• <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 et que le frontmatter est bien formé en utilisant claude plugin validate ou /plugin validate
• Pour les dépôts privés, confirmez que vous avez les permissions d’accès

​

Erreurs de validation de la place de marché

• Marketplace has no plugins defined : ajoutez au moins un plugin au tableau plugins
• No marketplace description provided : ajoutez metadata.description 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

​

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

• 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

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