Se você opera um marketplace de plugins para sua organização, pode fazer com que Claude Code sugira plugins específicos aos usuários com base no que estão trabalhando. Adicione um bloco relevance à entrada de um plugin em marketplace.json, depois coloque o marketplace na lista de permissões nas configurações gerenciadas. Quando a sessão de um usuário corresponder a um dos sinais declarados, Claude Code exibe uma sugestão de instalação para esse plugin.
As sugestões declaradas pelo marketplace são opcionais por marketplace através das configurações gerenciadas. Nenhuma declaração de relevance de um marketplace produz sugestões até que um administrador a adicione à lista de permissões, incluindo o marketplace oficial da Anthropic. Claude Code também inclui uma sugestão integrada que é independente dessa lista de permissões; essa dica e todas as dicas declaradas pelo marketplace são desabilitadas quando spinnerTipsEnabled é definido como false.
Este recurso requer Claude Code v2.1.152 ou posterior. Clientes mais antigos ignoram o campo relevance.
Esta página é para operadores de marketplace e administradores corporativos. Se você está procurando instalar plugins, consulte Descobrir e instalar plugins.
Como funciona
Cada entrada de plugin em marketplace.json pode conter um objeto relevance. O objeto nomeia um tópico e um ou mais sinais. Um sinal é um padrão que Claude Code testa contra a sessão atual, como o diretório de trabalho ou arquivos que Claude leu.
A correspondência de sinais acontece localmente na máquina do usuário. A correspondência não adiciona tráfego de rede e não relata quais sinais corresponderam, ou seus valores, à Anthropic ou ao operador do marketplace.
Quando um sinal corresponde e o plugin ainda não está instalado, Claude Code mostra o plugin em três lugares:
- Dica do spinner: uma mensagem “Trabalhando com tópico? Instale o plugin plugin” com o comando
/plugin install aparece abaixo do spinner enquanto Claude está respondendo.
- Sugestão de início de sessão: se o sinal
cwd corresponder ao diretório de trabalho, uma notificação de uma linha plugin suggestion: <name>@<marketplace> · /plugin aparece antes do primeiro turno. Esta superfície requer Claude Code v2.1.153 ou posterior.
- Aba Discover do
/plugin: o plugin é fixado no topo da lista Discover com uma anotação como “sugerido para este diretório” ou “sugerido para comandos stripe”. Esta superfície requer Claude Code v2.1.154 ou posterior.
A dica do spinner e a notificação de início de sessão fazem parte do sistema de dicas do spinner. Ambas são desabilitadas quando o usuário ou projeto define spinnerTipsEnabled como false, ou quando um spinnerTipsOverride personalizado é configurado com excludeDefault. O pino da aba Discover é independente das configurações de dicas.
Claude Code nunca instala um plugin automaticamente. O usuário sempre confirma.
Adicione relevância a uma entrada de plugin
Adicione um objeto relevance à entrada do plugin em seu marketplace.json. O exemplo a seguir declara que o plugin terraform-helpers é relevante quando Claude lê um arquivo .tf ou quando Claude executa terraform:
{
"name": "acme-corp-plugins",
"owner": { "name": "Acme Platform Team" },
"plugins": [
{
"name": "terraform-helpers",
"source": "./plugins/terraform-helpers",
"description": "Acme conventions and helpers for Terraform",
"relevance": {
"topic": "Terraform",
"signals": {
"cli": ["terraform"],
"filesRead": ["**/*.tf"]
}
}
}
]
}
relevance mas sem sinal correspondente se comporta como qualquer outra entrada do marketplace. Ele aparece na lista Discover em sua posição normal e nunca aparece como uma dica do spinner.
Referência de campos
relevance
| Campo | Tipo | Descrição |
|---|
topic | string | Opcional. A frase que preenche “Trabalhando com tópico?” na dica do spinner. Geralmente o nome do produto, por exemplo Stripe. Use um domínio como design quando o nome do plugin não se lê naturalmente como um tópico. Padrão é o nome do plugin com cada segmento de hífen capitalizado. A notificação de início de sessão não usa este valor. Máximo 64 caracteres. |
signals | object | Correspondentes que determinam quando o plugin é relevante. Pelo menos um sinal é necessário para que o plugin seja sugerível. Veja a tabela abaixo. |
relevance.signals
| Campo | Tipo | Descrição |
|---|
cwd | array of strings | Padrões Glob correspondidos contra o diretório de trabalho da sessão. Correspondido como um caminho absoluto e, quando dentro de um repositório git, como um caminho relativo à raiz do repositório. Normalizado com barra invertida e insensível a maiúsculas/minúsculas. Cada padrão corresponde ao diretório em si e a tudo sob ele, então infra, infra/, e infra/** se comportam de forma idêntica. Este é o único sinal que pode corresponder no início da sessão, antes do primeiro turno. Máximo 10 padrões de 256 caracteres cada. |
cli | array of strings | Nomes de comando de comandos shell que Claude executou nesta sessão, por exemplo ["stripe"]. Aplica-se em todas as plataformas: comandos executados no Windows através do PowerShell ou Git Bash são registrados da mesma forma. Claude Code registra um nome de comando por invocação de ferramenta shell: o primeiro token após qualquer atribuição de variável de ambiente inicial e sudo. Comandos compostos contribuem apenas com seu comando inicial, então cd infra && terraform plan registra cd, não terraform. Correspondência exata. Máximo 10 entradas de 64 caracteres cada. |
hosts | array of strings | Nomes de host vistos em URLs http:// ou https:// em comandos Bash nesta sessão, por exemplo ["api.stripe.com"]. Apenas nome de host em minúsculas: sem esquema, porta ou caminho. Correspondência exata insensível a maiúsculas/minúsculas. Máximo 20 entradas de 128 caracteres cada. |
filesRead | array of strings | Padrões Glob correspondidos contra os caminhos de arquivos que Claude leu nesta sessão, por exemplo ["**/*.tf"]. Normalizado com barra invertida e insensível a maiúsculas/minúsculas. Máximo 10 padrões de 256 caracteres cada. |
manifestDeps | array of objects | Dependências declaradas em manifestos de pacote que Claude leu nesta sessão. Cada entrada é { "file": "...", "pattern": "..." }, onde file é uma expressão regular correspondida contra o caminho do arquivo de manifesto conforme registrado no estado da sessão, normalmente um caminho absoluto, e pattern é uma expressão regular correspondida contra o conteúdo desse arquivo. Âncora file no final, por exemplo [/\\\\]package\\.json$ em forma com escape JSON, porque um padrão ancorado no início nunca corresponde a um caminho absoluto. Os caminhos não são normalizados por separador para este sinal, então os caminhos do Windows usam barras invertidas. Arquivos de manifesto maiores que 512 KB são ignorados. Ambos os valores são strings de origem RegExp do JavaScript de no máximo 256 caracteres. file corresponde insensível a maiúsculas/minúsculas. pattern é sensível a maiúsculas/minúsculas. Máximo 10 entradas. |
cli, hosts, filesRead e manifestDeps precisam de histórico de sessão, então eles só podem corresponder na dica do spinner e na aba Discover. Apenas cwd pode corresponder no início da sessão. Os sinais filesRead e manifestDeps testam o estado de arquivo registrado da sessão, que também inclui arquivos que Claude escreveu ou editou e arquivos de memória CLAUDE.md carregados automaticamente.
O exemplo a seguir usa manifestDeps para sugerir um plugin Stripe uma vez que Claude leu um package.json que depende de stripe. O padrão file usa [/\\\\] para que corresponda tanto a separadores de caminho com barra invertida quanto com barra invertida, e \\. para que o ponto seja literal. Em JSON, cada barra invertida na expressão regular é escrita duas vezes.
{
"name": "stripe-helpers",
"source": "./plugins/stripe-helpers",
"relevance": {
"topic": "Stripe",
"signals": {
"manifestDeps": [
{
"file": "[/\\\\]package\\.json$",
"pattern": "\"stripe\"\\s*:"
}
]
}
}
}
Campos desconhecidos sob relevance e relevance.signals são ignorados no tempo de carregamento para que clientes Claude Code mais antigos continuem carregando seu marketplace. Execute claude plugin validate para exibi-los como avisos.
Ative sugestões nas configurações gerenciadas
Declarar relevance em marketplace.json não é suficiente por si só. Um administrador deve colocar o marketplace na lista de permissões nas configurações gerenciadas antes que suas sugestões apareçam aos usuários.
Adicione o nome do marketplace a pluginSuggestionMarketplaces. Para qualquer marketplace que não seja o marketplace oficial da Anthropic, também declare a fonte do marketplace nas mesmas configurações gerenciadas, seja como entrada desse nome em extraKnownMarketplaces ou como entrada em strictKnownMarketplaces. O nome colocado na lista de permissões é ignorado se o marketplace registrado na máquina veio de uma fonte diferente. Isso impede que uma fonte não relacionada se registre sob um nome colocado na lista de permissões para ter seus plugins sugeridos em toda sua organização.
O managed-settings.json a seguir registra um marketplace de organização de um repositório GitHub e ativa suas sugestões:
{
"extraKnownMarketplaces": {
"acme-corp-plugins": {
"source": {
"source": "github",
"repo": "acme-corp/claude-plugins"
}
}
},
"pluginSuggestionMarketplaces": ["acme-corp-plugins"]
}
{
"pluginSuggestionMarketplaces": ["claude-plugins-official"]
}
pluginSuggestionMarketplaces e extraKnownMarketplaces para detalhes completos de configuração.
O que o usuário vê
Quando um sinal corresponde durante uma sessão, a dica do spinner lê:
Working with Terraform? Install the terraform-helpers plugin:
/plugin install terraform-helpers@acme-corp-plugins
cwd correspondente exibe a notificação de uma linha:
plugin suggestion: terraform-helpers@acme-corp-plugins · /plugin
/plugin, o plugin é fixado acima dos outros resultados com uma anotação que nomeia o sinal correspondente, como suggested for this directory ou suggested for terraform commands. A aba Discover fixa um determinado plugin uma vez; visitas posteriores o listam em ordem normal. O pino da aba Discover requer Claude Code v2.1.154 ou posterior. Na v2.1.152 apenas a dica do spinner aparece; a notificação de início de sessão é adicionada na v2.1.153.
Valide seu marketplace
Execute claude plugin validate contra seu diretório de marketplace para verificar o bloco relevance antes de publicar:
claude plugin validate ./my-marketplace
relevance e relevance.signals como avisos, sinaliza um valor relevance que não é um objeto, e rejeita uma entrada signals.hosts que inclui um esquema, porta ou caminho.
Veja também
