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.
• 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 hífen no lugar de um hífen, então claude.code.plugins conta como claude-code-plugins. claude plugin validate aceita tal nome; 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 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.

​

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

​

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, ou um nome com escopo como @your-org/formatter
• version: uma versão ou intervalo
• registry: uma URL de registro para um pacote que não está no registro padrão

{
  "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 de qualquer forma, plugins de diretório de skills param de carregar até que você adicione {"source": "skills-dir"} a essa lista.
• 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 caminho relativo que não começa com ./, diferente de "." ou um nome simples sob metadata.pluginRoot
• 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