Référence Marketplace

Référence complète des champs marketplace.json, des entrées de plugin et des objets source de plugin et marketplace, avec les emplacements où chacun est valide.

marketplace.json est le fichier qui définit une marketplace de plugin. Il contient le nom de la marketplace, son propriétaire et une entrée par plugin. La source de plugin de chaque entrée indique où Claude Code récupère ce plugin.

Une source marketplace est un objet séparé qui indique où Claude Code récupère le fichier marketplace lui-même. Vous en écrivez un dans les paramètres, ou Claude Code en crée un lorsque vous exécutez claude plugin marketplace add.

Cette référence est destinée aux responsables de marketplace qui ont besoin d'un nom ou d'une valeur de champ exact, et aux administrateurs qui ont besoin de savoir quelles valeurs source sont valides dans extraKnownMarketplaces, strictKnownMarketplaces et blockedMarketplaces.

Trouvez la section pour ce que vous écrivez ou lisez :

• Le fichier marketplace : Champs de niveau supérieur et Entrées de plugin
• La source d'une entrée : Sources de plugin
• Un objet source dans les paramètres : Sources marketplace
• Sortie de claude plugin validate <path> : Messages de validation, qui mappe chaque message au champ qu'il nomme

Fichier marketplace

Enregistrez le fichier marketplace à .claude-plugin/marketplace.json dans le répertoire de votre marketplace. Si vous conservez le fichier ailleurs dans le référentiel, les utilisateurs doivent déclarer la marketplace dans extraKnownMarketplaces avec path défini sur sa source, car claude plugin marketplace add n'a pas d'option pour cela.

Le répertoire qui contient .claude-plugin/ s'appelle la racine marketplace, et chaque source de plugin relative se résout à partir de celui-ci, pas à partir de .claude-plugin/.

Chaque utilisateur enregistre une marketplace par name, donc un utilisateur ne peut pas avoir deux marketplaces avec le même nom enregistrées à la fois.

Claude Code ignore une clé de niveau supérieur inconnue ou une clé d'entrée de plugin plutôt que de la rejeter, donc une faute de frappe se charge silencieusement. claude plugin validate signale chaque clé inconnue comme un avertissement.

Noms réservés

Vous ne pouvez pas donner à votre marketplace l'un des noms suivants :

• Noms de marketplace officiels : claude-code-marketplace, claude-code-plugins, claude-plugins-official, anthropic-marketplace, anthropic-plugins, agent-skills, anthropic-agent-skills, life-sciences, knowledge-work-plugins, claude-for-legal, claude-for-financial-services, financial-services-plugins, first-party-plugins et claude-tag-plugins. Réservés sauf si la marketplace provient d'une source marketplace github ou git sous github.com/anthropics/.
• Noms de marketplace communautaire : claude-community, claude-plugins-community et healthcare. Réservés selon la même règle que les noms officiels.
• Noms de répertoire de plugin : anthropic-plugin-directory et claude-plugin-directory. Réservés selon la même règle que les noms officiels.
• Noms qui usurpent l'identité d'une marketplace officielle : des noms tels que official-claude-plugins ou claude-plugins-v2, et tout nom contenant un caractère non-ASCII. L'erreur est Marketplace name impersonates an official Anthropic/Claude marketplace. Un caractère de contrôle ou de formatage bidirectionnel dans un nom signale également Marketplace name cannot contain control or bidirectional-formatting characters.
• Une autre orthographe d'un nom réservé : un nom qui diffère d'un nom réservé uniquement par un point final, ou par un symbole autre qu'un trait d'union à la place d'un trait d'union, donc claude.code.plugins compte comme claude-code-plugins. claude plugin validate accepte un tel nom ; l'ajout de la marketplace échoue avec is another spelling of "<reserved>", a reserved marketplace name, et une marketplace déjà enregistrée sous l'une d'elles cesse de se charger. Cette vérification nécessite Claude Code v2.1.280 ou ultérieure.
• Noms que Claude Code utilise pour les plugins qui ne proviennent pas d'une marketplace : inline pour les plugins chargés avec --plugin-dir, builtin pour les plugins intégrés, skills-dir pour les plugins chargés automatiquement à partir de .claude/skills/ et synced pour les plugins synchronisés à partir de votre compte claude.ai. claude-plugin-test est également réservé. skills-dir apparaît également comme {"source": "skills-dir"} dans strictKnownMarketplaces et blockedMarketplaces, décrits sous Valeurs source valides uniquement dans les listes de politique.
• npm, pip, uv, cargo, github et gh : réservés dans n'importe quelle casse. Cette vérification nécessite Claude Code v2.1.275 ou ultérieure.
• Noms commençant par claudeai- : réservés pour les marketplaces hébergées sur claude.ai. claude plugin marketplace add refuse toute autre marketplace qui en utilise un avec Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai.

Champs de niveau supérieur

Le tableau liste chaque clé que Claude Code lit à partir de marketplace.json. name, owner et plugins sont obligatoires.

Entrées de plugin

Chaque objet du tableau plugins de niveau supérieur de marketplace.json nomme un plugin et indique où le récupérer. name et source sont obligatoires.

Une entrée accepte également tous les champs plugin.json, tels que description, version, author, commands et hooks. Pour savoir quand ces champs s'appliquent, consultez Comment une entrée se combine avec plugin.json.

Le tableau répertorie les champs propres à l'entrée et les champs du manifeste dont le sens change dans une entrée.

Comment une entrée se combine avec plugin.json

Les champs de l'entrée s'appliquent différemment à un plugin récupéré qui a son propre .claude-plugin/plugin.json et à un qui n'en a pas :

• Pas de plugin.json : l'entrée est le manifeste indépendamment de strict. Chaque champ de manifeste dans l'entrée s'applique, y compris mcpServers, lspServers, userConfig et channels.
• plugin.json présent : plugin.json est le manifeste. Le mode strict décide si les six champs de composant de l'entrée, commands, agents, skills, hooks, outputStyles et themes, sont combinés avec lui ou rejetés comme un conflit. L'entrée mcpServers, lspServers, userConfig et channels ne s'appliquent pas. Déclarez-les dans plugin.json.

Hooks dans une entrée

Écrivez les hooks d'entrée comme un objet en ligne qui mappe les noms d'événements de hook aux tableaux de correspondance. Si vous écrivez un chemin de fichier ou un tableau à la place, claude plugin validate le passe. Ces hooks ne s'exécutent jamais, et Claude Code signale une erreur not yet supported in a marketplace entry pour le plugin. Mettez les hooks basés sur des fichiers dans le propre hooks/hooks.json du plugin ou plugin.json.

Champs d'affichage

L'entrée et le propre plugin.json du plugin peuvent tous deux définir les champs d'affichage displayName, description, author, homepage, repository, license et keywords. Les utilisateurs voient ces valeurs dans les listes et détails des plugins, avant et après l'installation :

• Pour un champ que vous définissez sur l'entrée, les utilisateurs voient la valeur de l'entrée, même quand plugin.json en définit une différente.
• Pour un champ que l'entrée laisse non défini, les utilisateurs voient la valeur plugin.json.

Avant l'installation, Claude Code ne peut lire plugin.json que pour les entrées avec une source de chemin relatif, dont les fichiers de plugin se trouvent à l'intérieur du marketplace lui-même. Pour une entrée avec tout autre type de source, les utilisateurs ne voient que les champs propres de l'entrée jusqu'à ce qu'ils installent le plugin.

Mode strict

strict décide ce qui se passe quand le plugin récupéré a son propre plugin.json et que l'entrée déclare également l'un des champs de composant : commands, agents, skills, hooks, outputStyles ou themes. Avec strict: true, la valeur par défaut, Claude Code ajoute les champs de composant de l'entrée à plugin.json, sauf hooks, dont les correspondances remplacent celles du manifeste par événement. Avec strict: false, une entrée qui déclare un champ de composant est un conflit, et le plugin ne se charge pas. Le tableau montre chaque combinaison de strict, plugin.json et des champs de composant de l'entrée.

Sources de plugin

La source d'une entrée de plugin indique où Claude Code récupère ce plugin. C'est soit une chaîne de chemin relatif, soit un objet dont la propre clé source nomme le type, donc une entrée ressemble à "source": { "source": "github", "repo": "your-org/formatter" }.

Le tableau liste chaque type de source de plugin et ses champs.

Les noms url et github sont également des types de source marketplace, où url signifie un lien direct vers un fichier marketplace.json plutôt qu'un référentiel git. git n'existe que comme source marketplace, et npm existe comme les deux. git-subdir, archive et command n'existent que comme sources de plugin.

Utilisez un chemin relatif pour un plugin dans un sous-répertoire du référentiel marketplace lui-même. Utilisez git-subdir pour un sous-répertoire d'un autre référentiel.

Les sources github, url et git-subdir partagent les champs ref et sha :

• ref : une branche ou une balise. Par défaut, la branche par défaut du référentiel.
• sha : un SHA de commit complet de 40 caractères en minuscules. Lorsque vous définissez à la fois ref et sha, Claude Code extrait sha. 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 la balise nommée par ref a depuis été supprimée en amont, tant que le commit est toujours accessible à partir du référentiel. Certains serveurs, tels que AWS CodeCommit, ne supportent pas la récupération de commits par SHA. Sur ces serveurs, le ref doit toujours exister et le commit épinglé doit être accessible à partir de celui-ci.

Pour savoir comment chaque type est récupéré, mis en cache et versionné, voir Référence de chargement de plugin.

Source de plugin avec chemin relatif

Le chemin se résout à partir de la racine marketplace. ./plugins/formatter est <root>/plugins/formatter même si le fichier marketplace est dans <root>/.claude-plugin/.

Un chemin contenant .. échoue la validation. Sur macOS et Linux, Claude Code refuse un chemin d'entrée qui contient une barre oblique inverse n'importe où après le ./ initial, donc écrivez le chemin avec des barres obliques avant.

{ "name": "formatter", "source": "./plugins/formatter" }

Un chemin relatif se résout uniquement lorsque Claude Code a les fichiers de la marketplace, donc vérifiez le type de source marketplace :

• github, git, file et directory : Claude Code a les fichiers de la marketplace.
• url : Claude Code récupère uniquement marketplace.json, donc les chemins relatifs ne peuvent pas se résoudre. Donnez à chaque plugin une source d'objet à la place, telle que github ou git-subdir.
• settings : les chemins relatifs sont rejetés d'emblée.

Noms nus sous pluginRoot

Un nom nu est un seul nom de répertoire sans /, tel que "formatter". Pour écrire des noms nus au lieu de chemins ./, définissez metadata.pluginRoot sur le répertoire sous lequel ils se résolvent. Avec "pluginRoot": "./plugins", "source": "formatter" se résout à ./plugins/formatter. Nécessite Claude Code v2.1.239 ou ultérieure.

metadata.pluginRoot a ces limites :

• Il doit lui-même être un chemin relatif à l'intérieur de la marketplace.
• Il n'a aucun effet sur une source qui commence déjà par ./.
• Une source qui contient un /, telle que team-a/formatter, n'est pas un nom nu et a toujours besoin du préfixe ./, même lorsque metadata.pluginRoot est défini.

Source de plugin github

repo prend owner/repo. ref et sha sont optionnels.

{
  "name": "formatter",
  "source": {
    "source": "github",
    "repo": "your-org/formatter",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Source de plugin url

url est une URL git complète : https://, http://, file:// ou git@. Un suffixe .git n'est pas requis, donc les URL Azure DevOps et AWS CodeCommit fonctionnent telles qu'elles sont écrites. Ce type ne prend pas le raccourci owner/repo.

{
  "name": "formatter",
  "source": {
    "source": "url",
    "url": "https://gitlab.example.com/your-group/formatter.git",
    "ref": "main"
  }
}

Source de plugin git-subdir

url accepte une URL git complète ou le raccourci GitHub owner/repo. path est le sous-répertoire qui contient le plugin, et Claude Code télécharge uniquement ce sous-répertoire.

{
  "name": "formatter",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/your-org/monorepo.git",
    "path": "tools/formatter"
  }
}

Source de plugin npm

Une source npm prend ces champs :

• package : un nom de package, ou un nom scopé tel que @your-org/formatter
• version : une version ou une plage
• registry : une URL de registre pour un package qui n'est pas sur le registre par défaut

Claude Code récupère le package avec votre client npm. Les scripts d'installation du package, tels que preinstall ou postinstall, ne s'exécutent jamais, et ses dépendances ne sont pas installées lors de la récupération. Si le package a un fichier de verrouillage supporté à côté de son package.json, Claude Code installe ces dépendances de package Node.js dans une étape séparée, également avec les scripts désactivés.

{
  "name": "formatter",
  "source": {
    "source": "npm",
    "package": "@your-org/formatter",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

Source de plugin archive

url doit utiliser https:// et ne peut pas pointer vers un hôte loopback, link-local ou cloud-metadata.

La racine du plugin peut être au sommet du zip ou un répertoire plus bas.

sha256 est le digest de l'archive en tant que 64 caractères hexadécimaux, majuscules ou minuscules. Lorsque vous le définissez, Claude Code refuse un téléchargement qui ne correspond pas.

{
  "name": "formatter",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/formatter-2.0.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}

Source de plugin command

Utilisez une source command lorsqu'un outil installé sur la machine de l'utilisateur produit le répertoire du plugin, tel qu'un IDE qui rend son plugin pour la chaîne d'outils que l'utilisateur a sélectionnée. Claude Code exécute la commande lorsque l'utilisateur installe ou met à jour le plugin, et à nouveau une fois par session, donc les utilisateurs obtiennent la sortie modifiée de l'outil sans réinstaller.

Une source command prend ces champs :

• command : une commande shell qui imprime le chemin absolu du répertoire du plugin en une seule ligne et quitte 0. Claude Code affiche la chaîne entière aux utilisateurs pour examen avant de l'exécuter. Écrivez-la en ASCII imprimable, au maximum 500 caractères, sans suite de quatre espaces ou plus.
• timeout : un nombre entier de secondes de 1 à 600. Par défaut 60.
• mode : copy, la valeur par défaut, ou link. Voir Mode copie et mode lien.

{
  "name": "formatter",
  "source": {
    "source": "command",
    "command": "my-tool claude-plugin-path",
    "timeout": 120
  }
}

Pour savoir comment les utilisateurs acceptent la commande, voir Installer à partir de votre shell. Pour ce que les utilisateurs voient après l'avoir modifiée, voir Modifier la commande d'une source command. Les administrateurs désactivent les sources command avec disableCommandPluginSources.

Ce que la commande doit faire

Écrivez la commande pour répondre à ces exigences :

• Shell et répertoire de travail : Claude Code exécute la commande via sh, ou via cmd.exe sur Windows, à partir du répertoire personnel de l'utilisateur. Donnez un chemin absolu ou une commande sur PATH.
• Sortie : imprimez exactement une ligne sur stdout, le chemin absolu du répertoire du plugin, et quittez 0 dans les timeout secondes.
• Contenu du répertoire : le répertoire contient le plugin complet au moment où la commande quitte. Le chemin peut différer d'une exécution à l'autre.

Sortie qui échoue l'installation ou la mise à jour

L'installation ou la mise à jour échoue lorsque la commande quitte non-zéro, s'exécute plus longtemps que timeout, ou imprime autre chose qu'un chemin absolu. Elle échoue également lorsque le répertoire imprimé est l'un de ceux-ci :

• Pas de contenu de plugin : le répertoire imprimé n'a pas de contenu de plugin à son niveau supérieur, tel qu'un répertoire .claude-plugin/ ou un répertoire skills/, commands/, agents/ ou hooks/.
• Le répertoire de la session elle-même : le répertoire imprimé est celui dans lequel Claude Code a été démarré, ou l'un de ses parents.
• Un chemin réseau : sur Windows, le chemin imprimé est un chemin UNC.
• Trop volumineux à copier : en mode copie, le répertoire est plus grand que 256 MiB ou a plus de 20 000 entrées.

Mode copie et mode lien

mode décide si Claude Code copie le répertoire imprimé ou l'utilise sur place :

• copy : Claude Code copie le répertoire dans le cache du plugin et dérive la version du plugin d'un hash des fichiers copiés. Votre outil peut supprimer ou réécrire le répertoire après la sortie de la commande. Une réexécution qui produit des fichiers identiques compte comme à jour.
• link : Claude Code remplit l'entrée du cache du plugin avec un lien vers chaque entrée de niveau supérieur du répertoire imprimé et charge les fichiers sur place. Rien n'est copié, les contenus de fichiers ne sont pas hashés, et les limites de taille ne s'appliquent pas. Utilisez-le pour un répertoire trop volumineux à copier, tel qu'une exportation SDK rendue.

Un plugin en mode lien a ces exigences :

• Gardez le répertoire en place : Claude Code charge le plugin via les liens à chaque démarrage, donc le répertoire imprimé doit rester où il est tant que le plugin reste installé.
• Imprimez un chemin différent pour signaler un nouveau contenu : la version provient du chemin réel du répertoire imprimé et de ses entrées de niveau supérieur, pas des fichiers à l'intérieur.
• Gardez les symlinks de niveau supérieur à l'intérieur du répertoire : l'installation échoue si une entrée de niveau supérieur est un symlink qui pointe en dehors du répertoire imprimé.
• Incluez node_modules : Claude Code saute l'installation de dépendance de package Node.js pour un plugin en mode lien, donc imprimez un répertoire qui contient déjà les packages dont le plugin a besoin.
• Sessions démarrées à l'intérieur du répertoire : une session démarrée dans le répertoire imprimé ou n'importe où en dessous ne charge pas le plugin.
• Pas sur Windows : Claude Code refuse d'installer un plugin en mode lien sur Windows. Déclarez "mode": "copy" là.

Sources marketplace

Une source marketplace indique où Claude Code récupère un marketplace.json. La CLI en crée une pour vous lorsque vous ajoutez une marketplace, et vous en écrivez une vous-même dans les paramètres :

• claude plugin marketplace add : Claude Code crée la source à partir de la chaîne que vous passez.
• extraKnownMarketplaces : vous écrivez la source vous-même en tant qu'objet source.
• strictKnownMarketplaces et blockedMarketplaces : les administrateurs écrivent les sources dans ces deux listes de politique. strictKnownMarketplaces est la liste blanche et blockedMarketplaces est la liste noire.

Les noms de type url, git et github signifient quelque chose de différent dans une source marketplace que dans une source de plugin :

Le tableau liste chaque type de source marketplace avec ses champs, l'entrée claude plugin marketplace add qui le produit, et ce qu'il fait dans chacune des trois clés de paramètres.

Champs par type

Le tableau liste chaque champ de source marketplace qui a une valeur par défaut, une contrainte ou un sens spécifique à son type.

Valeurs source valides uniquement dans les listes de politique

hostPattern, pathPattern, skills-dir et la forme owner/* de repo sont valides uniquement dans les deux listes de politique, strictKnownMarketplaces et blockedMarketplaces :

• hostPattern et pathPattern : expressions régulières que Claude Code teste contre une source avant de la récupérer.
• skills-dir : pas une source. Si vous définissez strictKnownMarketplaces du tout, les plugins du répertoire de compétences cessent de charger jusqu'à ce que vous ajoutiez {"source": "skills-dir"} à cette liste.
• owner/* : en tant que valeur repo github, correspond à chaque référentiel sous exactement ce propriétaire GitHub. Nécessite Claude Code v2.1.223 ou ultérieure.

Pour l'ordre de correspondance, la sémantique exacte de ref et les recettes, voir Gérer les plugins pour votre organisation.

Objets source dans les paramètres

Une valeur extraKnownMarketplaces est un mappage du nom de marketplace à un objet avec source. Cette entrée enregistre une marketplace à partir d'un référentiel git à sa branche main :

{
  "extraKnownMarketplaces": {
    "your-marketplace": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/your-org/your-marketplace.git",
        "ref": "main"
      }
    }
  }
}

strictKnownMarketplaces et blockedMarketplaces sont des tableaux d'objets source. Cette liste blanche admet un propriétaire GitHub et un hôte interne :

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "your-org/*" },
    { "source": "hostPattern", "hostPattern": "^git\\.example\\.com$" }
  ]
}

Messages de validation

claude plugin validate <path> prend la racine marketplace ou le fichier marketplace lui-même. Il imprime les erreurs et les avertissements. Pour les codes de sortie et --strict, voir plugin validate.

Un message nomme une entrée de plugin par son index, écrit comme plugins.1.source ou plugins[1].source.

Un message préfixé par un index d'entrée et plugin.json →, tel que plugins[2] plugin.json →, concerne les propres fichiers de ce plugin. claude plugin validate signale les erreurs liste ces messages avec leurs corrections.

Les avertissements qui mentionnent les noms de drapeaux Claude Desktop signalent les noms que Claude Code accepte mais que Claude Desktop rejette, car les règles de nom de Claude Desktop sont plus strictes.

Le tableau mappe les messages au niveau marketplace au champ dont chacun parle.

Entrée invalide sur une source

Invalid input sur une source signifie que l'objet ne correspondait à aucun type de source. Vérifiez ces causes :

• Un chemin relatif qui ne commence pas par ./, autre que "." ou un nom nu sous metadata.pluginRoot
• Un package npm contenant ..
• Un type source qui n'est pas l'un des sources de plugin
• Un type connu avec un champ obligatoire manquant ou du mauvais type, tel que github sans repo

Défaillances que la validation ne détecte pas

claude plugin validate ne signale pas chaque défaillance. Un hooks d'entrée écrit comme un chemin de fichier ou un tableau passe la validation, et l'erreur n'apparaît que lorsque le plugin se charge, comme le décrit Hooks dans une entrée. Les erreurs de récupération d'une source apparaissent également uniquement après l'installation, pas dans la validation.

claude plugin list affiche un plugin qui n'a pas pu se charger avec son erreur, et Dépanner les plugins couvre les chaînes de temps de chargement.

Étapes suivantes

• Créer une marketplace : créez une marketplace à partir de ces champs et installez-la localement
• Héberger et maintenir une marketplace : où mettre le fichier et comment les utilisateurs reçoivent les modifications
• Référence du manifeste de plugin : les champs plugin.json qu'une entrée peut remplacer
• Gérer les plugins pour votre organisation : recettes de liste blanche et liste noire qui utilisent ces valeurs source