> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

> [!NOTE]
>
> Estes casos são abordados em outras páginas:
>
> * **Você quer instalar plugins**: consulte [Instalar e gerenciar plugins](https://code.claude.com/docs/pt/plugins/install.md)
> * **Você quer desativar as sugestões**: consulte [Entender como funciona a relevância de plugins](#understand-how-plugin-relevance-works)

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

* **Operadores de marketplace**: leia [como as sugestões funcionam](#understand-how-plugin-relevance-works), depois [adicione relevância a uma entrada de plugin](#add-relevance-to-a-plugin-entry) e [valide seu marketplace](#validate-your-marketplace)
* **Administradores**: [habilite as sugestões nas configurações gerenciadas](#enable-suggestions-in-managed-settings)

## 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ê](#preview-what-the-user-sees) 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`](https://code.claude.com/docs/pt/settings-reference#spinnertipsenabled) como `false`, ou quando um [`spinnerTipsOverride`](https://code.claude.com/docs/pt/settings-reference#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`:

```json theme={null}
{
  "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](#validate-your-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](#field-reference) 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`](#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](#working-directory-matching). | 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](#command-name-matching). | 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](#manifest-dependency-matching). | 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.

```json theme={null}
{
  "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:

```bash theme={null}
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](https://code.claude.com/docs/pt/plugins/org.md), 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`](https://code.claude.com/docs/pt/plugins/org#require-a-marketplace-and-its-plugins) ou como uma entrada em [`strictKnownMarketplaces`](https://code.claude.com/docs/pt/plugins/org#allowlist-with-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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```text theme={null}
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:

```text theme={null}
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

* [Hospedar um marketplace](https://code.claude.com/docs/pt/plugins/host-marketplace.md): execute o marketplace que hospeda seus plugins
* [Referência do marketplace](https://code.claude.com/docs/pt/plugins/marketplace-reference.md#plugin-entries): todos os campos que uma entrada de plugin aceita
* [Recomendar seu plugin a partir da sua CLI](https://code.claude.com/docs/pt/plugins/cli-hints.md): solicite aos usuários a partir da sua própria CLI em vez de a partir dos sinais de sessão do Claude Code
* [Gerenciar plugins para sua organização](https://code.claude.com/docs/pt/plugins/org.md): `extraKnownMarketplaces`, `strictKnownMarketplaces` e as demais chaves de política de plugins