SpyBara
Go Premium

plugins/relevance.md 2026-10-01 23:59 UTC to 2026-10-02 11:59 UTC

This page contains 247 additions and 0 deletions.

2026
Fri 2 11:59

Recomendar plugins para sua organização

Adicione um bloco de relevância às entradas de plugins do marketplace para que o Claude Code os sugira quando o trabalho de um usuário corresponder, e adicione o marketplace à allowlist nas configurações gerenciadas.

O Claude Code pode sugerir a instalação de um plugin do marketplace da sua organização quando a sessão de um usuário corresponde aos sinais que você define para esse plugin. Os sinais incluem o diretório de trabalho, os arquivos que o Claude leu e os comandos que o Claude executou. Você os define adicionando um bloco relevance à entrada do plugin em marketplace.json.

Um operador de marketplace escreve as entradas relevance. Em seguida, um administrador adiciona o marketplace à allowlist nas configurações gerenciadas. Os usuários não veem sugestões de um marketplace até que ele seja adicionado à allowlist.

Comece pelas seções correspondentes à sua função:

Entender como funciona a relevância de plugins

Cada entrada de plugin em marketplace.json pode incluir um objeto relevance. O objeto nomeia um tópico e um ou mais sinais. Um sinal é um padrão que o Claude Code testa em relação à sessão atual, como o diretório de trabalho ou os arquivos que o Claude leu.

A correspondência de sinais acontece localmente na máquina do usuário e não adiciona tráfego de rede. O Claude Code não informa à Anthropic nem ao operador do marketplace quais sinais corresponderam nem seus valores.

Quando um sinal corresponde e o plugin ainda não está instalado, o Claude Code sugere o plugin nestes locais:

  • Dica do spinner: uma mensagem com o comando /plugin install aparece abaixo do spinner enquanto o Claude está respondendo.
  • Notificação de início de sessão: se um sinal cwd corresponder ao diretório de trabalho, uma notificação de uma linha aparece antes que o usuário envie a primeira mensagem.
  • Aba Discover do /plugin: o plugin é fixado no topo da lista Discover.

Visualizar o que o usuário vê mostra o texto exato de cada um e com que frequência se repetem.

O Claude Code nunca instala o plugin automaticamente. O usuário sempre confirma.

A dica do spinner e a notificação de início de sessão deixam de aparecer quando o usuário ou o projeto define spinnerTipsEnabled como false, ou quando um spinnerTipsOverride com excludeDefault substitui as dicas integradas. A fixação na aba Discover não é afetada por nenhuma dessas configurações.

Adicionar relevância a uma entrada de plugin

Adicione um objeto relevance à entrada do plugin no seu marketplace.json. O exemplo a seguir declara que o plugin terraform-helpers é relevante quando o Claude lê um arquivo .tf ou executa terraform:

{
  "name": "your-marketplace",
  "owner": { "name": "Your Org" },
  "plugins": [
    {
      "name": "terraform-helpers",
      "source": "./plugins/terraform-helpers",
      "description": "Your organization's Terraform conventions and helpers",
      "relevance": {
        "topic": "Terraform",
        "signals": {
          "cli": ["terraform"],
          "filesRead": ["**/*.tf"]
        }
      }
    }
  ]
}

Enquanto nenhum de seus sinais corresponder, o plugin mantém sua posição normal na lista Discover e não aparece como dica do spinner.

Para verificar o bloco antes de publicar, valide seu marketplace.

Referência de campos

O objeto relevance e seu objeto aninhado signals aceitam os campos nas tabelas a seguir.

Clientes mais antigos ainda carregam um marketplace que usa campos de relevance que eles não reconhecem, porque campos desconhecidos em relevance e relevance.signals são ignorados no momento do carregamento. Um campo reconhecido cujo valor excede seu limite na referência de campos invalida toda a entrada do plugin, e os usuários não conseguem instalar esse plugin do marketplace até que você o corrija; claude plugin validate informa os mesmos limites.

`relevance`

Campo Tipo Descrição
topic string Opcional. A frase que preenche "Working with topic?" na dica do spinner. O padrão é o nome do plugin com cada segmento separado por hífen em maiúscula. Máximo de 64 caracteres.
signals object Matchers que determinam quando o plugin é relevante. O Claude Code sugere o plugin somente se pelo menos um sinal estiver definido. Consulte relevance.signals.

O topic costuma ser o nome do produto, por exemplo Terraform. Use um domínio como design quando o nome do plugin não soar natural como tópico.

`relevance.signals`

O objeto signals aceita os campos a seguir.

Campo Tipo Descrição Limite
cwd array de strings Padrões glob comparados com o diretório de trabalho da sessão. Consulte correspondência do diretório de trabalho. 10 padrões de 256 caracteres cada
cli array de strings Nomes de comandos de comandos do shell que o Claude executou nesta sessão, por exemplo ["terraform"]. Correspondência exata. Consulte correspondência de nomes de comandos. 10 entradas de 64 caracteres cada
hosts array de strings Nomes de host vistos em URLs http:// ou https:// em comandos Bash nesta sessão, por exemplo ["registry.terraform.io"]. Apenas o nome de host simples em minúsculas: sem esquema, porta ou caminho. Correspondência exata sem distinção entre maiúsculas e minúsculas. 20 entradas de 128 caracteres cada
filesRead array de strings Padrões glob comparados com os caminhos dos arquivos que o Claude leu nesta sessão, por exemplo ["**/*.tf"]. Normalizados com barras normais e sem distinção entre maiúsculas e minúsculas. 10 padrões de 256 caracteres cada
manifestDeps array de objetos Dependências declaradas em manifestos de pacotes que o Claude leu nesta sessão. Cada entrada é { "file": "...", "pattern": "..." }, em que ambos os valores são expressões regulares. Consulte correspondência de dependências de manifesto. 10 entradas, cada valor com no máximo 256 caracteres. Arquivos de manifesto maiores que 512 KB são ignorados

Os sinais filesRead e manifestDeps também correspondem a arquivos que o Claude escreveu ou editou nesta sessão e aos arquivos de memória CLAUDE.md do projeto carregados automaticamente.

Correspondência do diretório de trabalho

cwd é o único sinal que pode corresponder no início da sessão, antes que o usuário envie a primeira mensagem.

O Claude Code compara cada padrão cwd da seguinte forma:

  • O padrão é comparado com o diretório de trabalho como caminho absoluto. Quando a sessão está dentro de um repositório git, ele também é comparado com o caminho do diretório de trabalho relativo à raiz do repositório.
  • A correspondência é normalizada com barras normais e não diferencia maiúsculas de minúsculas.
  • Todo padrão corresponde ao próprio diretório e a tudo abaixo dele, então infra, infra/ e infra/** se comportam de forma idêntica.

Correspondência de nomes de comandos

O Claude Code registra um nome de comando para cada comando do shell que o Claude executa: o primeiro token após quaisquer atribuições iniciais de variáveis de ambiente e sudo. Comandos compostos contribuem apenas com seu comando inicial, então cd infra && terraform plan registra cd, não terraform.

Correspondência de dependências de manifesto

Cada entrada manifestDeps combina duas strings de origem RegExp do JavaScript:

  • file: comparada sem distinção entre maiúsculas e minúsculas com o caminho do arquivo de manifesto. O caminho normalmente é absoluto, então ancore o padrão no final em vez de no início. Os caminhos não são normalizados quanto ao separador para este sinal, então caminhos do Windows usam barras invertidas.
  • pattern: comparada com distinção entre maiúsculas e minúsculas com o conteúdo desse arquivo.

O exemplo a seguir usa manifestDeps para sugerir seu plugin quando o Claude tiver lido um package.json que depende do pacote npm do seu SDK, chamado your-sdk aqui.

{
  "name": "your-plugin",
  "source": "./plugins/your-plugin",
  "relevance": {
    "signals": {
      "manifestDeps": [
        {
          "file": "[/\\\\]package\\.json$",
          "pattern": "\"your-sdk\"\\s*:"
        }
      ]
    }
  }
}

Neste exemplo, o padrão file usa [/\\\\] para corresponder tanto a separadores de caminho com barra normal quanto com barra invertida, e \\. para que o ponto seja literal. Em JSON, cada barra invertida na expressão regular é escrita duas vezes.

Validar seu marketplace

No seu shell, execute claude plugin validate no diretório do seu marketplace para verificar o bloco relevance antes de publicar:

claude plugin validate ./my-marketplace

O validador informa erros e avisos sobre o bloco relevance, incluindo estes:

  • Informa chaves desconhecidas em relevance e relevance.signals como avisos
  • Sinaliza um valor de relevance que não é um objeto
  • Rejeita uma entrada signals.hosts que inclui esquema, porta ou caminho

Cada resultado é exibido com o caminho do campo a que se refere, e a saída termina com Validation passed, Validation passed with warnings ou Validation failed.

Habilitar sugestões nas configurações gerenciadas

Os usuários não veem sugestões de um marketplace até que um administrador o adicione à allowlist nas configurações gerenciadas, mesmo quando seu marketplace.json declara relevance.

Para adicionar um marketplace à allowlist, edite suas configurações gerenciadas da seguinte forma:

  • Adicione o nome do marketplace a pluginSuggestionMarketplaces.
  • Para qualquer marketplace diferente do marketplace oficial da Anthropic, declare também a origem do marketplace, seja como a entrada desse nome em extraKnownMarketplaces ou como uma entrada em strictKnownMarketplaces.

Em uma máquina onde o marketplace não está registrado, ou está registrado com o nome da allowlist a partir de uma origem diferente, nenhuma sugestão dele aparece. A verificação de origem impede que uma origem não relacionada se registre com um nome da allowlist para ter seus plugins sugeridos em toda a sua organização.

O managed-settings.json a seguir registra um marketplace da organização a partir de um repositório do GitHub e habilita suas sugestões:

{
  "extraKnownMarketplaces": {
    "your-marketplace": {
      "source": {
        "source": "github",
        "repo": "your-org/your-marketplace"
      }
    }
  },
  "pluginSuggestionMarketplaces": ["your-marketplace"]
}

O nome do marketplace oficial só pode ser registrado a partir da origem oficial da Anthropic, então ele não precisa de declaração de origem. Para o marketplace oficial, adicione apenas o nome à allowlist:

{
  "pluginSuggestionMarketplaces": ["claude-plugins-official"]
}

Visualizar o que o usuário vê

Quando um sinal relevance de um plugin corresponde durante uma sessão, a dica abaixo do spinner diz:

Working with Terraform? Install the terraform-helpers plugin:
/plugin install terraform-helpers@your-marketplace

Quando um sinal cwd corresponde no início da sessão, a notificação de uma linha diz:

plugin suggestion: terraform-helpers@your-marketplace · /plugin

Na aba Discover do /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.

O Claude Code limita a frequência com que sugere um determinado plugin:

  • A sugestão aparece no máximo uma vez a cada três sessões, considerando a dica do spinner e a notificação de início de sessão em conjunto.
  • A notificação de início de sessão deixa de aparecer quando a dica do spinner e a notificação tiverem mostrado o plugin um total combinado de duas vezes.
  • Nem a dica do spinner nem a notificação de início de sessão se repetem depois que o plugin é instalado.
  • A aba Discover fixa o plugin na primeira vez que o usuário abre a aba enquanto os sinais do plugin correspondem. O Claude Code registra isso em ~/.claude.json, então, em todas as vezes posteriores em que o usuário abrir /plugin nessa máquina, o plugin aparece na ordem normal.

Veja também