Referência do marketplace

• O arquivo marketplace: Top-level fields e Plugin entries
• A source de uma entrada: Plugin sources
• Um objeto source nas configurações: Marketplace sources
• Saída de claude plugin validate <path>: Validation messages, que mapeia cada mensagem para o campo que ela nomeia

​

Arquivo marketplace

​

Nomes reservados

• Nomes de marketplace oficial: 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 e claude-tag-plugins. Reservado a menos que o marketplace venha de uma origem de marketplace github ou git sob github.com/anthropics/.
• Nomes de marketplace comunitário: claude-community, claude-plugins-community e healthcare. Reservado sob a mesma regra que os nomes oficiais.
• Nomes de diretório de plugins: anthropic-plugin-directory e claude-plugin-directory. Reservado sob a mesma regra que os nomes oficiais.
• Nomes que se passam por um marketplace oficial: nomes como official-claude-plugins ou claude-plugins-v2, e qualquer nome contendo um caractere não-ASCII. O erro é Marketplace name impersonates an official Anthropic/Claude marketplace. Um caractere de controle ou formatação bidirecional em um nome também relata Marketplace name cannot contain control or bidirectional-formatting characters. Um marketplace já registrado sob tal nome para de carregar, junto com seus plugins.
• Outra grafia de um nome reservado: um nome que difere de um nome reservado apenas por um ponto final, ou por um símbolo diferente de um sublinhado no lugar de um hífen, então claude.code.plugins conta como claude-code-plugins. Adicionar o marketplace falha com is another spelling of "<reserved>", a reserved marketplace name, e um marketplace já registrado sob um para de carregar. Esta verificação requer Claude Code v2.1.280 ou posterior.
• Nomes que Claude Code usa para plugins que não vêm de um marketplace: inline para plugins carregados com --plugin-dir, builtin para plugins integrados, skills-dir para plugins carregados automaticamente de .claude/skills/ e synced para plugins sincronizados de sua conta claude.ai. claude-plugin-test também é reservado. skills-dir também aparece como {"source": "skills-dir"} em strictKnownMarketplaces e blockedMarketplaces, descrito em Source values valid only in policy lists.
• npm, pip, uv, cargo, github e gh: reservado em qualquer capitalização. Esta verificação requer Claude Code v2.1.275 ou posterior.
• Nomes de membros que todo objeto JavaScript possui: constructor, hasOwnProperty, isPrototypeOf, propertyIsEnumerable, toLocaleString, toString e valueOf. claude plugin marketplace add recusa um marketplace que use um deles com Claude Code reserves this name and cannot register a marketplace under it. Esta verificação requer Claude Code v2.1.296 ou posterior.
• Nomes começando com claudeai-: reservado para marketplaces hospedados em claude.ai. claude plugin marketplace add recusa qualquer outro marketplace que use um com Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai.
• A pasta de download de um marketplace GitHub registrado, <owner>-<repo>: Claude Code baixa um marketplace adicionado de uma origem github como acme/x-tools por meio de uma pasta chamada acme-x-tools, qualquer que seja o name próprio desse marketplace. Enquanto esse marketplace estiver registrado sob um nome diferente de acme-x-tools, claude plugin marketplace add recusa um marketplace diferente chamado acme-x-tools após baixá-lo e relata Can't use the marketplace name "acme-x-tools". Esta verificação requer Claude Code v2.1.290 ou posterior.

​

Top-level fields

​

Plugin entries

​

How an entry combines with plugin.json

• Sem plugin.json: a entrada é o manifesto independentemente de strict. Cada campo de manifesto que a entrada aceita se aplica, incluindo mcpServers, lspServers, userConfig e channels.
• plugin.json presente: plugin.json é o manifesto. Strict mode decide se os seis campos de componente da entrada, commands, agents, skills, hooks, outputStyles e themes, são combinados com ele ou rejeitados como um conflito. Entrada mcpServers, lspServers, userConfig e channels não se aplicam. Declare-os em plugin.json.

​

Hooks in an entry

​

Display fields

• Para um campo que você define na entrada, os usuários veem o valor da entrada, mesmo quando plugin.json define um diferente.
• Para um campo que a entrada deixa indefinido, os usuários veem o valor de plugin.json.

​

Strict mode

​

Plugin sources

• ref: uma branch ou tag. Padrão para a branch padrão do repositório.
• sha: um SHA de commit completo de 40 caracteres em minúsculas. Quando você define tanto ref quanto sha, Claude Code faz checkout de sha. Na maioria dos hosts git, incluindo GitHub, GitLab e Bitbucket, isso significa que a instalação é bem-sucedida mesmo se a branch ou tag nomeada por ref foi deletada upstream, desde que o commit ainda seja alcançável do repositório. Alguns servidores, como AWS CodeCommit, não suportam buscar commits por SHA. Nesses servidores, o ref ainda deve existir e o commit fixado deve ser alcançável a partir dele.

​

Relative path plugin source

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

• github, git, file e directory: Claude Code tem os arquivos do marketplace.
• url: Claude Code busca apenas marketplace.json, então caminhos relativos não podem se resolver. Dê a cada plugin uma origem de objeto em vez disso, como github ou git-subdir.
• settings: caminhos relativos são rejeitados imediatamente.

​

Git submodules in the marketplace repository

• O plugin está dentro do submódulo: o submódulo é o diretório do plugin ou um diretório acima dele
• O submódulo está dentro do plugin: o submódulo está em qualquer lugar sob o diretório do plugin
• Um link simbólico aponta para dentro do submódulo: um link com commit no repositório tem seu destino no submódulo

• Um diretório de componente: um diretório na raiz que contém componentes do plugin, como skills/, hooks/ ou bin/
• Um caminho na configuração do plugin: um caminho na entrada de marketplace do plugin, em seu plugin.json ou em um arquivo de configuração como .mcp.json ou hooks/hooks.json
• Um link simbólico: um link com commit no repositório
• Texto nos arquivos do plugin: o caminho de um submódulo, como vendor/tool, escrito em um arquivo de configuração ou em um arquivo sob um diretório de componente

• Um SKILL.md na raiz: o repositório inteiro é então o diretório de uma skill
• Um arquivo que Claude Code não consegue ler: o arquivo do marketplace, um dos arquivos de configuração do plugin ou .gitmodules

​

Bare names under pluginRoot

• Ele próprio deve ser um caminho relativo dentro do marketplace.
• Não tem efeito em uma origem que já começa com ./.
• Uma origem que contém um /, como team-a/formatter, não é um nome simples e ainda precisa do prefixo ./, mesmo quando metadata.pluginRoot está definido.

​

github plugin source

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

​

url plugin source

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

​

git-subdir plugin source

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

​

npm plugin source

• package: um nome de pacote do registro, como @your-org/formatter, um nome com uma versão anexada, como @your-org/formatter@2.0.0, ou um link https para o arquivo tarball do pacote
• version: uma versão, um intervalo semver ou uma dist-tag, usado quando package é um nome de pacote sem versão anexada. Omita-o para buscar latest
• registry: uma URL de registro para um pacote que não está no registro padrão

• Um endereço git, uma pasta ou caminho file:, ou um alias npm:: use uma origem github, url ou git-subdir para um repositório git, um caminho relativo para uma pasta no marketplace e o próprio nome do pacote para um alias
• Um link de tarball em github.com, gist.github.com, gitlab.com, bitbucket.org ou git.sr.ht: recusado mesmo quando o link é um download de release do GitHub, a menos que seja um link do registro npm do GitLab sob gitlab.com/api/v4/
• Um link de tarball sobre http: recusado a menos que aponte para o próprio registro npm padrão do usuário que está instalando

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

​

archive plugin source

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

​

command plugin source

• command: um comando shell que imprime o caminho absoluto do diretório do plugin como uma linha e sai com 0. Claude Code mostra aos usuários a string inteira para revisão antes de executá-la. Escreva-a como ASCII imprimível, no máximo 500 caracteres, sem uma sequência de quatro ou mais espaços.
• timeout: um número inteiro de segundos de 1 a 600. Padrão para 60.
• mode: copy, o padrão, ou link. Veja Copy mode and link mode.

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

​

What the command must do

• Shell e diretório de trabalho: Claude Code executa o comando através de sh, ou através de cmd.exe no Windows, a partir do diretório home do usuário. Dê um caminho absoluto ou um comando em PATH.
• Saída: imprima exatamente uma linha em stdout, o caminho absoluto do diretório do plugin, e saia com 0 dentro de timeout segundos.
• Conteúdo do diretório: o diretório contém o plugin completo no momento em que o comando sai. O caminho pode diferir de uma execução para a próxima.

​

Output that fails the install or update

• Sem conteúdo de plugin: o diretório impresso não tem conteúdo de plugin em seu nível superior, como um diretório .claude-plugin/ ou um diretório skills/, commands/, agents/ ou hooks/.
• O diretório da própria sessão: o diretório impresso é aquele em que Claude Code foi iniciado, ou um de seus pais.
• Um caminho de rede: no Windows, o caminho impresso é um caminho UNC.
• Muito grande para copiar: em modo copy, o diretório é maior que 256 MiB ou tem mais de 20.000 entradas.

​

Copy mode and link mode

• copy: Claude Code copia o diretório para o cache de plugins e deriva a versão do plugin de um hash dos arquivos copiados. Sua ferramenta pode deletar ou reescrever o diretório após o comando sair. Uma re-execução que produz arquivos idênticos conta como atualizado.
• link: Claude Code preenche a entrada de cache do plugin com um link para cada entrada de nível superior do diretório impresso e carrega os arquivos no lugar. Nada é copiado, conteúdos de arquivo não são hash, e os limites de tamanho não se aplicam. Use-o para um diretório muito grande para copiar, como uma exportação de SDK renderizada.

• Mantenha o diretório no lugar: Claude Code carrega o plugin através dos links a cada inicialização, então o diretório impresso deve ficar onde está enquanto o plugin permanecer instalado.
• Imprima um caminho diferente para sinalizar novo conteúdo: a versão vem do caminho real do diretório impresso e suas entradas de nível superior, não dos arquivos dentro deles.
• Mantenha symlinks de nível superior dentro do diretório: a instalação falha se uma entrada de nível superior é um symlink que aponta para fora do diretório impresso.
• Inclua node_modules: Claude Code pula a instalação de dependência de pacote Node.js para um plugin em modo link, então imprima um diretório que já contém os pacotes que o plugin precisa.
• Sessões iniciadas dentro do diretório: uma sessão iniciada no diretório impresso ou em qualquer lugar abaixo dele não carrega o plugin.
• Não no Windows: Claude Code recusa instalar um plugin em modo link no Windows. Declare "mode": "copy" lá.

​

Fontes do marketplace

• claude plugin marketplace add: Claude Code constrói a fonte a partir da string que você passa.
• extraKnownMarketplaces: você escreve a fonte você mesmo como o objeto source.
• strictKnownMarketplaces e blockedMarketplaces: administradores escrevem fontes nessas duas listas de política. strictKnownMarketplaces é a lista de permissão e blockedMarketplaces é a lista de bloqueio.

​

Campos por tipo

​

Valores de fonte válidos apenas em listas de política

• hostPattern e pathPattern: expressões regulares que Claude Code testa contra uma fonte antes de buscar dela.
• skills-dir: não é uma fonte. Se você definir strictKnownMarketplaces sem uma entrada {"source": "skills-dir"}, plugins de diretório de skills param de carregar. Se você bloquear qualquer tipo de personalização com strictPluginOnlyCustomization, eles param de carregar independentemente de a entrada estar presente ou não.
• owner/*: como um valor repo de github, corresponde a cada repositório sob exatamente esse proprietário do GitHub. Requer Claude Code v2.1.223 ou posterior.

​

Objetos de fonte nas configurações

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

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

​

Validation messages

​

Invalid input on a source

• Um package npm contendo ..
• Um tipo de source que não é um das origens de plugin
• Um tipo conhecido com um campo obrigatório faltando ou do tipo errado, como github sem repo

​

Failures that validation doesn’t catch

​

Next steps

• Create a marketplace: construa um marketplace a partir desses campos e instale dele localmente
• Host and maintain a marketplace: onde colocar o arquivo e como os usuários recebem mudanças
• Plugin manifest reference: os campos plugin.json que uma entrada pode sobrescrever
• Manage plugins for your organization: receitas de lista de permissões e bloqueio que usam esses valores de origem