# referência de plugin da CLI GitHub Copilot
Encontre comandos e detalhes de configuração para plug-ins da CLI.
> \[!NOTE]
> Você pode encontrar ajuda para usar plug-ins entrando `copilot plugin [SUBCOMMAND] --help` no terminal.
Para obter uma visão geral do que são plug-ins e como eles funcionam entre Copilot clientes, consulte [Sobre plug-ins GitHub Copilot](/pt/copilot/concepts/agents/about-plugins).
## Comandos da CLI
Você pode usar os seguintes comandos no terminal para gerenciar plug-ins para Copilot CLI.
`copilot plugins` (plural) é um alias legado para `copilot plugin`—ambos apontam para o mesmo comando.
| Command | Descrição |
| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `copilot plugin install SPECIFICATION` (também conhecido como `add`) | Instale um plug-in. Consulte [Especificação do plugin para `install` o comando](#plugin-specification-for-install-command) abaixo. |
| `copilot plugin uninstall NAME` (aliases `remove`, `rm`) | Remover um plug-in |
| `copilot plugin list` | Listar plug-ins instalados |
| `copilot plugin update NAME` | Atualize um plug-in nomeado. Use `--all` para atualizar todos os plug-ins instalados ao mesmo tempo. |
| `copilot plugin enable NAME` | Habilite um plug-in desabilitado anteriormente. A alteração persiste na configuração e se aplica a sessões futuras. Isso funciona da mesma forma para instalações pelo Marketplace e instalações diretas (de `owner/repo`, uma URL ou um caminho local). |
| `copilot plugin disable NAME` | Desabilite um plug-in sem desinstalá-lo. Uma `--plugin-dir` montagem permanece somente leitura, pois não tem nenhuma ativação persistente a ser alterada. |
| `copilot plugin marketplace add SPECIFICATION` | Registre um mercado. O próprio nome do marketplace, a partir de seu `marketplace.json` manifesto, torna-se sua chave de registro— não há nenhuma opção para definir um nome local personalizado. |
| `copilot plugin marketplace list` | Listar marketplaces registrados |
| `copilot plugin marketplace browse NAME` | Navegue pelos plugins do marketplace |
| `copilot plugin marketplace update [NAME]` (também conhecido como `refresh`) | Buque novamente o catálogo de plug-ins do marketplace. Omita `NAME` para atualizar os catálogos de cada marketplace registrado. |
| `copilot plugin marketplace remove NAME` | Cancelar o registro de um marketplace. Será recusado se plugins do Marketplace ainda estiverem instalados; passe `--force` para também desinstalar esses plugins. |
Antes de `copilot plugin` ser dividido em comandos separados por recurso, `copilot plugins` também inspecionava e ativava e desativava servidores MCP, habilidades, instruções e servidores de linguagem usando as opções `--kind`, `--scope`, `--mcp` e `--skill`. Essas flags de compatibilidade entre tipos foram removidas. Use, em vez disso, os comandos dedicados [`copilot instruction`](/pt/copilot/reference/copilot-cli-reference/cli-command-reference#using-copilot-instruction), [`copilot skill`](/pt/copilot/reference/copilot-cli-reference/cli-command-reference#managing-skills-non-interactively), [`copilot mcp`](/pt/copilot/reference/copilot-cli-reference/cli-command-reference#copilot-mcp-subcommand) e [`copilot lsp`](/pt/copilot/reference/copilot-cli-reference/cli-command-reference#using-copilot-lsp).
`copilot plugin list --json` agora emite uma matriz simples de plug-ins em vez do objeto anterior `{ plugins, errors }` .
> \[!NOTE]
> Um plug-in ou marketplace definido por uma organização ou por uma política gerenciada por MDM (`enabledPlugins`, `extraKnownMarketplaces`) não pode ser reabilitado, desabilitado nem redirecionado localmente — o valor gerenciado prevalece para essa entrada. O `/plugin` painel marca essas linhas com um `Managed` indicador e não permite uma alternância conflitante. Consulte [Diretório de configuração do GitHub Copilot CLI](/pt/copilot/reference/copilot-cli-reference/cli-config-dir-reference#mdm-managed-settings).
>
> Um plug-in cuja ativação é decidida atualmente pela sobreposição do `enabledPlugins` repositório atual rejeita `copilot plugin enable`/`disable` em vez de persistir silenciosamente um valor global que não teria nenhum efeito nesse repositório. O erro nomeia o arquivo de configurações que realmente controla o plug-in. Consulte [Diretório de configuração do GitHub Copilot CLI](/pt/copilot/reference/copilot-cli-reference/cli-config-dir-reference#repository-settings-githubcopilotsettingsjson).
### Especificação do plug-in para `install` comando
| Formato | Exemplo | Descrição |
| ---------------------------- | ---------------------------- | ------------------------------------ |
| Marketplace | `plugin@marketplace` | Plug-in de um marketplace registrado |
| GitHub | `OWNER/REPO` | Raiz de um GitHub repositório |
| GitHub subdir | `OWNER/REPO:PATH/TO/PLUGIN` | Subdiretório em um repositório |
| Git URL | `http://gfffh3e2b966b640040f3sv95560oup5bk660n.ffgi.yc2.bjmu.edu.cn/o/r.git` | Qualquer URL do Git |
| Caminho local | | |
| `./my-plugin` ou `/abs/path` | Diretório local | |
### `copilot plugin list` opções
| Opção | Descrição | |
| ------------------------ | ---------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `--json` | Emita uma matriz JSON simples de plug-ins em vez de texto. | |
| `--config-dir=DIRECTORY` | Caminho para o diretório de configuração. Essa opção foi preterida. Use `COPILOT_HOME` em seu lugar. | |
Cada `--json` linha tem a forma `{ name, marketplace?, version?, enabled, source, installedFrom? }`.
### `copilot plugin enable`/`disable` opções
| Opção | Descrição | |
| ------------------------ | ---------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `--config-dir=DIRECTORY` | Caminho para o diretório de configuração. Essa opção foi preterida. Use `COPILOT_HOME` em seu lugar. | |
### `copilot plugin install` opções
Para instalar uma skill em vez de um plug-in, use [`copilot skill add`](/pt/copilot/reference/copilot-cli-reference/cli-command-reference#managing-skills-non-interactively) não se trata de uma instalação de plug-in e não passa por um marketplace.
| Opção | Descrição | |
| ------------------------ | ---------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `--config-dir=DIRECTORY` | Caminho para o diretório de configuração. Essa opção foi preterida. Use `COPILOT_HOME` em seu lugar. | |
Os servidores MCP são instalados a partir de um registro configurado por política, que requer autenticação e entrada de segredo interativa. Use a exibição **Online** do `/mcp` painel ou do [`copilot mcp add`](/pt/copilot/reference/copilot-cli-reference/cli-command-reference#copilot-mcp-subcommand) comando para adicionar servidores MCP em vez de `copilot plugin install`.
### `copilot plugin update` opções
| Opção | Descrição | |
| ------------------------ | ---------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `--all` | Atualizar cada plug-in instalado | |
| `--config-dir=DIRECTORY` | Caminho para o diretório de configuração. Essa opção foi preterida. Use `COPILOT_HOME` em seu lugar. | |
> \[!NOTE]
> Os plug-ins baseados em caminho em um marketplace local (baseado em diretório) são carregados diretamente do diretório real — ao editar um deles, a alteração passa a valer em `/restart` ou em uma nova sessão, sem precisar de `copilot plugin update`.
Os plugins nativos — aqueles instalados do marketplace interno `awesome-copilot` — são atualizados automaticamente no início de cada sessão em um diretório de trabalho confiável. Desabilite esse comportamento com a `autoUpdate` configuração (definida como `false`) ou a variável de `COPILOT_AUTO_UPDATE=false` ambiente. A atualização automática também é ignorada por padrão na CI. Consulte [Diretório de configuração do GitHub Copilot CLI](/pt/copilot/reference/copilot-cli-reference/cli-config-dir-reference#configuration-file-settings).
> \[!NOTE]
> `copilot-plugins` fornecido anteriormente como um segundo marketplace padrão interno junto com `awesome-copilot`. Agora é um marketplace comum, não padrão (`github/copilot-plugins`) no qual você mesmo se registra `copilot plugin marketplace add github/copilot-plugins`. Se você instalou plug-ins dele antes dessa alteração, uma migração única a adiciona à sua própria `extraKnownMarketplaces` com `autoUpdate: true` para que esses plug-ins continuem atualizando. Uma nova instalação que nunca usou `copilot-plugins` deve registrá-lo manualmente antes de instalar plug-ins a partir dele.
Um marketplace que você mesmo adicionou pode ativar a mesma atualização automática no início da sessão definindo `autoUpdate: true` no item `extraKnownMarketplaces` correspondente nas suas configurações de usuário. Essa adesão se aplica somente a sessões interativas e `-p` — as sessões de SDK e de servidor não são atualizadas automaticamente. Essa configuração é respeitada nas suas próprias configurações de usuário ou nas configurações gerenciadas (MDM/servidor), mas uma configuração `autoUpdate` no nível do repositório é aceita e ignorada — ela não pode ativar nem redirecionar a atualização automática para um marketplace. Em um conflito entre nomes idênticos, um marketplace interno primário prevalece. Em seguida, uma entrada gerenciada (que substitui toda a entrada do usuário com o mesmo nome, de modo que uma entrada gerenciada sem `"autoUpdate": true` remove a aceitação do usuário) e, por fim, a entrada do próprio usuário. Consulte [as configurações do Repositório](/pt/copilot/reference/copilot-cli-reference/cli-config-dir-reference#repository-settings-githubcopilotsettingsjson).
No modo interativo, `/plugin` indica um plug-in instalado ou o marketplace quando uma versão mais recente está disponível na origem e oferece, no painel, a ação **Atualizar** para baixá-la.
### `copilot plugin marketplace` (alias `marketplaces`) subcomandos
O marketplace padrão interno `awesome-copilot` é fornecido com o runtime e não pode ser removido.
| Subcommand | Descrição |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `list [--json]` | Listar todos os marketplaces registrados, incluindo o padrão interno |
| `add SOURCE` | Adicionar um marketplace (`owner/repo`, `owner/repo#ref`uma URL ou um caminho local) |
| `remove NAME [--force]` | Remover um marketplace; `--force` também desinstala plug-ins provenientes dele |
| `browse NAME [--json]` | Listar os plug-ins oferecidos pelo catálogo de um marketplace |
| `update [NAME]` (também conhecido como `refresh`) | Atualizar o catálogo de plugins para um marketplace ou para todos, se `NAME` for omitido |
Quando a autenticação HTTPS falha para um marketplace remoto ou busca de plug-in, a CLI tenta novamente uma vez com o GitHub token da sua sessão autenticada. Se a nova tentativa também falhar, execute `/login`.
No modo interativo, execute `/plugin marketplace update [NAME]` (alias `/plugin marketplace refresh`) ou pressione R na visualização **Marketplace** do painel `/plugin`, para atualizar o catálogo de cada marketplace registrado.
## `plugin.json`
Todos os plug-ins consistem em um diretório de plug-in que contém um arquivo de manifesto chamado `plugin.json`. Agent Plugins requer o arquivo de manifesto na raiz do plugin. Uma raiz voltada para Plug-ins de Agente tem precedência sobre e , de acordo com a especificação §5.1. Os plug-ins herdados dão suporte aos locais alternativos listados em [locais de arquivo](#file-locations). Consulte [Criando um plug-in para GitHub Copilot CLI](/pt/copilot/how-tos/copilot-cli/customize-copilot/plugins-creating).
Copilot CLI dá suporte ao manifesto do plug-in herdado e ao manifesto plug-ins do agente.
Copilot CLI reconhece como válidos os valores canônicos `$schema` para Plug-ins de Agente (Especificação Aberta de Plug-ins) v1.0.0 (`http://gfffh68e91ddef4fa4552sv95560oup5bk660n.ffgi.yc2.bjmu.edu.cn/schemas/1.0.0/plugin.schema.json`) e v1.1.0 (`http://gfffh68e91ddef4fa4552sv95560oup5bk660n.ffgi.yc2.bjmu.edu.cn/schemas/1.1.0/plugin.schema.json`), fazendo com que um plug-in adote a semântica de Plug-ins de Agente. Um manifesto sem um desses valores exatos usa o formato herdado e carrega como antes. Se um plug-in declarar uma versão do Agent Plugins que Copilot CLI não dá suporte, a CLI rejeitará o plug-in em vez de retornar silenciosamente ao modo herdado. Um plug-in rejeitado não contribui com ganchos, servidores LSP, servidores MCP, habilidades, comandos, agentes, regras ou diretórios de extensão.
### Campos do manifesto dos Plug-ins do Agente 1.0
Os Plugins de Agente 1.0 definem um esquema fechado de manifesto. Para obter os requisitos de formato completos, consulte a [especificação do Agent Plugins 1.0](http://gfffh3e2b966b640040f3sv95560oup5bk660n.ffgi.yc2.bjmu.edu.cn/agentplugins/agent-plugins-spec/blob/main/spec/1.0.0.md).
Os seguintes campos são permitidos:
| Campo | Tipo | Obrigatório | Descrição |
| ------------- | ----------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `$schema` | cadeia | Sim | Deve ser uma URL reconhecida de plug-ins do Agente `$schema` (v1.0.0 ou v1.1.0). Versões de plug-ins de agente sem suporte são rejeitadas. |
| `name` | cadeia | Sim | Nome do plug-in. Consulte [restrições de nome](#name-constraints). |
| `version` | cadeia | No | Cadeia de caracteres de versão. O versionamento semântico é recomendado. |
| `description` | cadeia | No | Breve descrição. |
| `author` | objeto | No | Campos de string opcionais `name`, `email` e `url`. |
| `homepage` | cadeia | No | Página inicial do plug-in ou documentação. |
| `repository` | cadeia | No | Repositório de origem. |
| `license` | cadeia | No | Identificador de licença. É recomendável um identificador SPDX. |
| `keywords` | cadeia de caracteres\[] | No | Palavras-chave de pesquisa e descoberta. |
| `extensions` | objeto | No | Dados específicos do cliente chaveados pelo namespace de domínio reverso. |
Campos de nível superior desconhecidos são informados e ignorados. Campos de caminho do componente, como `agents`, `skills`, `hooks`e `lspServers``mcpServers`não são campos de manifesto do Agent Plugins 1.0.
#### Restrições de nome
Um nome de Agent Plugins 1.0 deve:
* Contêm entre 1 e 64 caracteres.
* Contém apenas letras ASCII minúsculas, dígitos, hifens e períodos.
* Iniciar e terminar com um caractere alfanumérico.
* Não contém `--` ou `..`.
#### Componentes
O Agent Plugins 1.0 define dois tipos de componentes portáteis:
* Habilidades em subdiretórios imediatos `skills/` que contêm um `SKILL.md` arquivo.
* Servidores MCP em `mcp.json` na raiz do plug-in.
Esses locais são fixos e não podem ser configurados em `plugin.json`. As habilidades são carregadas apenas de `skills/` — não há fallback para a raiz `SKILL.md` (plugins legados recorrem à raiz `SKILL.md` quando não existe nenhum diretório `skills/`). A raiz `mcp.json` deve declarar uma versão reconhecida de Plug-ins do Agente `$schema` (correspondente à mesma versão de `plugin.json`) no campo `$schema`. O envelope de alto nível está fechado, e cada entrada de servidor é validada de acordo com seu esquema de transporte; entradas de servidor inválidas são ignoradas individualmente, enquanto as entradas válidas continuam sendo carregadas. A CLI aceita os nomes de transporte MCP `stdio`, `streamable-http` e `sse`.
Para servidores `stdio`, a CLI fornece `PLUGIN_ROOT` e `PLUGIN_DATA` no ambiente do subprocesso. Expande `${PLUGIN_ROOT}` e `${PLUGIN_DATA}` (além dos aliases `CLAUDE_PLUGIN_DATA` e `COPILOT_PLUGIN_DATA`) em `cwd`, valores de `args` e `env` do servidor.
`PLUGIN_DATA` aponta para um diretório persistente e gravável para o plug-in instalado. Valores de configuração de servidor remoto `sse`, `http` e `streamable-http` são transmitidos literalmente, sem expansão de marcadores nem de variáveis de ambiente.
Agent Plugins 1.0 não define agentes portáteis, gatilhos, comandos, regras nem servidores LSP. Elas permanecem específicas do cliente. Os dados de manifest específicos do cliente pertencem a `extensions`, identificados por um namespace de domínio reverso. Os arquivos específicos do cliente pertencem a um diretório de nível superior com o mesmo namespace. Os clientes ignoram namespaces que não dão suporte.
Copilot CLI lê seus componentes específicos do cliente do diretório `com.github.copilot`:
| Componente | Local |
| ---------------------- | ------------------------------------- |
| Agentes personalizados | `com.github.copilot/agents/` |
| Comandos de barra "/" | `com.github.copilot/commands/` |
| Regras | `com.github.copilot/rules/` |
| Ganchos | `com.github.copilot/hooks/hooks.json` |
| Servidores LSP | `com.github.copilot/lsp.json` |
Esses locais se aplicam somente aos plug-ins do Agent Plugins 1.0. Os plugins legados continuam usando seus próprios locais dos componentes e campos de caminho do manifesto.
### Exemplo de arquivo `plugin.json` do Agent Plugins 1.0
```json copy
{
"$schema": "http://gfffh68e91ddef4fa4552sv95560oup5bk660n.ffgi.yc2.bjmu.edu.cn/schemas/1.0.0/plugin.schema.json",
"name": "my-dev-tools",
"description": "React development utilities",
"version": "1.2.0",
"author": {
"name": "Jane Doe",
"email": "jane@example.com"
},
"license": "MIT",
"keywords": ["react", "frontend"]
}
```
### Campos de manifesto legados
#### Campo obrigatório
| Campo | Tipo | Descrição |
| ------ | ------ | ------------------------------------------------------------------------------------------ |
| `name` | cadeia | Nome do plug-in em kebab-case (somente letras, números e hífens). Máximo de 64 caracteres. |
#### Campos de metadados opcionais
| Campo | Tipo | Descrição |
| ----------------------------------------------------------- | ----------------------- | ---------------------------------------------- |
| `description` | cadeia | Breve descrição. Máximo de 1024 caracteres. |
| `version` | cadeia | Versão semântica (por exemplo, `1.0.0`). |
| `author` | objeto | |
| `name` (obrigatório), `email` (opcional), `url` (opcional). | | |
| `homepage` | cadeia | URL da página inicial do plugin. |
| `repository` | cadeia | URL do repositório de origem. |
| `license` | cadeia | Identificador de licença (por exemplo, `MIT`). |
| `keywords` | cadeia de caracteres\[] | Pesquisar palavras-chave. |
| `category` | cadeia | Categoria de plug-in. |
| `tags` | cadeia de caracteres\[] | Etiquetas adicionais. |
#### Campos de caminho do componente
Elas indicam à CLI onde encontrar os componentes do seu plug-in. Todos são opcionais. A CLI usa convenções padrão se omitidas.
| Campo | Tipo | Default | Descrição |
| ------------ | ----------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agents` | cadeia de caracteres \| cadeia de caracteres\[] | `agents/` | Caminhos para diretórios de agente (`.agent.md` arquivos). |
| `skills` | cadeia de caracteres \| cadeia de caracteres\[] | `skills/` | Caminhos para diretórios de habilidades (`SKILL.md` arquivos). |
| `commands` | cadeia de caracteres \| cadeia de caracteres\[] | — | Caminhos para diretórios de comando. |
| `hooks` | objeto string \| | — | Caminho para um arquivo de configuração de ganchos ou um objeto de ganchos embutido. |
| `extensions` | string \| string\[] \| object | — | Caminhos para diretórios de extensão. Use `{ paths: [...], exclusive: true }` para suprimir extensões internas. Nos [manifestos do Agent Plugins 1.0](#agent-plugins-10-manifest-fields), esse campo tem um significado diferente. |
| `mcpServers` | objeto string \| | — | Caminho para um arquivo de configuração MCP (por exemplo, `.mcp.json`) ou definições de servidor embutido. |
| `lspServers` | objeto string \| | — | Caminho para um arquivo de configuração do LSP, ou definições de servidor em linha. |
#### Servidores MCP de agentes fornecidos com plug-ins
Um agente incluído em um plug-in pode declarar seu próprio `mcp-servers` em seu frontmatter, restringindo um servidor MCP apenas a esse agente, em vez de expô-lo por meio da configuração `mcpServers` compartilhada do plug-in. Dentro daquele bloco `${PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_ROOT}` (ou seus nomes alternativos /`${COPILOT_PLUGIN_ROOT}``mcp-servers`) é expandido para o diretório raiz do plug-in, para que o `command` ou `args` do servidor possa apontar para um script incluído no plug-in:
```markdown
---
name: Plugin Linter
description: Runs the plugin's bundled linter via its own MCP server
mcp-servers:
plugin-linter:
command: node
args: ["${PLUGIN_ROOT}/tools/serve.js"]
tools: ["*"]
---
You are a linting specialist for this plugin's bundled rules.
```
Essa substituição só se aplica ao frontmatter `mcp-servers` do próprio agente fornecido com um plugin — ela não se estende a `${PLUGIN_DATA}` nem às variáveis de ambiente do servidor. Agentes de workspace e de usuário não possuem raiz de plug-in, portanto, seu frontmatter permanece inalterado.
### Configuração do servidor LSP
Para incluir servidores LSP (Language Server Protocol) em um plug-in, crie um `lsp-config/servers.json` arquivo no diretório do plug-in ou especifique um caminho ou objeto embutido usando o `lspServers` campo em `plugin.json`.
Exemplo `lsp-config/servers.json` (ou em linha via `lspServers` em `plugin.json`):
```json
{
"lspServers": {
"my-lsp": {
"command": "my-language-server",
"fileExtensions": { ".myext": "mylang" }
}
}
}
```
Para suporte multiplataforma, use `bash` e `powershell` , em vez de `command`:
```json
{
"lspServers": {
"my-lsp": {
"bash": "${PLUGIN_ROOT}/scripts/start-lsp.sh",
"powershell": "${PLUGIN_ROOT}/scripts/start-lsp.ps1",
"fileExtensions": { ".myext": "mylang" }
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ----------------------- | ----------------------- | ----------- | -------------------------------------------------------------------------------------------------------------- |
| `command` | cadeia | \* | Executável para iniciar o servidor de idiomas. |
| `bash` | cadeia | \* | Script bash para iniciar o servidor (Linux/macOS); executado por meio de `bash -c SCRIPT`. |
| `powershell` | cadeia | \* | Script do PowerShell para iniciar o servidor (Windows); executado por meio de `pwsh -c SCRIPT`. |
| `cwd` | cadeia | No | Diretório de trabalho. Absoluto ou relativo ao arquivo de configuração. Oferece suporte para `${PLUGIN_ROOT}`. |
| `args` | cadeia de caracteres\[] | No | Argumentos a serem passados para `command` (ignorados para `bash` e `powershell`). |
| `env` | objeto | No | Variáveis de ambiente a serem definidas ao gerar o servidor. |
| `fileExtensions` | objeto | Sim | Mapa de extensões de arquivo para IDs de idioma (por exemplo, `{ ".ts": "typescript" }`). |
| `rootUri` | cadeia | No | Raiz do projeto em relação à raiz do Git (padrão: `.`). |
| `initializationOptions` | any | No | Opções enviadas ao servidor na solicitação LSP `initialize` . |
(\*) Pelo menos um de `command`, `bash`ou `powershell` é necessário. Quando `bash` e `powershell` são especificados, o apropriado para a plataforma é selecionado automaticamente (PowerShell no Windows, Bash em outro lugar).
Use `${PLUGIN_ROOT}` para referenciar caminhos no diretório do plug-in.
## `marketplace.json`
Você pode criar um marketplace de plug-ins, que as pessoas podem usar para descobrir e instalar seus plug-ins, criando um `marketplace.json` arquivo e salvando-o no `.github/plugin/` diretório do repositório. Você também pode armazenar o `marketplace.json` arquivo em seu sistema de arquivos local. Por exemplo, salvar o arquivo como `/PATH/TO/my-marketplace/.github/plugin/marketplace.json` permite adicioná-lo à CLI usando o seguinte comando:
```shell
copilot plugin marketplace add /PATH/TO/my-marketplace
```
> \[!NOTE]
> O Copilot CLI também procura o arquivo `marketplace.json` no diretório `.claude-plugin/`.
Para obter mais informações, consulte [Criando um marketplace de plugin para GitHub Copilot CLI](/pt/copilot/how-tos/copilot-cli/customize-copilot/plugins-marketplace).
### Arquivo de exemplo `marketplace.json`
```json copy
{
"name": "my-marketplace",
"owner": {
"name": "Your Organization",
"email": "plugins@example.com"
},
"metadata": {
"description": "Curated plugins for our team",
"version": "1.0.0"
},
"plugins": [
{
"name": "frontend-design",
"description": "Create a professional-looking GUI ...",
"version": "2.1.0",
"source": "./plugins/frontend-design"
},
{
"name": "security-checks",
"description": "Check for potential security vulnerabilities ...",
"version": "1.3.0",
"source": "./plugins/security-checks"
}
]
}
```
> \[!NOTE]
> O valor do `source` campo para cada plug-in é o caminho para o diretório do plug-in, em relação à raiz do repositório. Não é necessário usar `./` no início do caminho. Por exemplo, `"./plugins/plugin-name"` e `"plugins/plugin-name"` resolvem para o mesmo diretório.
### Campos `marketplace.json`
#### Campos de nível superior
| Campo | Tipo | Obrigatório | Descrição |
| ---------------------------------------------------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | cadeia | Sim | Nome do mercado de kebabs. Máximo de 64 chars. Os pontos também são aceitos (por exemplo, `acme.tools`) para plugins do [Agent Plugins 1.0](#agent-plugins-10-manifest-fields). |
| `owner` | objeto | Sim | |
| `{ name, email? }` — informações do proprietário do marketplace. | | | |
| `plugins` | matriz | Sim | Lista de entradas de plug-in (consulte a tabela abaixo). |
| `metadata` | objeto | No | `{ description?, version?, pluginRoot? }` |
#### Campos de entrada de plug-in (objetos dentro da `plugins` matriz)
| Campo | Tipo | Obrigatório | Descrição |
| ------------- | ----------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name` | cadeia | Sim | Nome do plugin Kebab-case. Máximo de 64 chars. Pontos também são aceitos para plug-ins [Agent Plugins 1.0](#agent-plugins-10-manifest-fields). |
| `source` | objeto string \| | Sim | Onde buscar o plug-in (caminho relativo GitHub ou URL). |
| `description` | cadeia | No | Descrição do plug-in. Máximo de 1024 caracteres. |
| `version` | cadeia | No | Versão do plug-in. |
| `author` | objeto | No | `{ name, email?, url? }` |
| `homepage` | cadeia | No | URL da página inicial do plugin. |
| `repository` | cadeia | No | URL do repositório de origem. |
| `license` | cadeia | No | Identificador de licença. |
| `keywords` | cadeia de caracteres\[] | No | Pesquisar palavras-chave. |
| `category` | cadeia | No | Categoria de plug-in. |
| `tags` | cadeia de caracteres\[] | No | Etiquetas adicionais. |
| `commands` | cadeia de caracteres \| cadeia de caracteres\[] | No | Caminhos para diretórios de comando. |
| `agents` | cadeia de caracteres \| cadeia de caracteres\[] | No | Caminhos para diretórios de agente. |
| `skills` | cadeia de caracteres \| cadeia de caracteres\[] | No | Caminhos para diretórios de habilidades. |
| `hooks` | objeto string \| | No | Caminho para a configuração de hooks ou objeto de ganchos embutidos. |
| `mcpServers` | objeto string \| | No | Servidores MCP a serem ativados quando o plugin é instalado. Aceita um mapa de servidor embutido ou um caminho para um arquivo de configuração JSON. Usado quando a origem do plug-in não envia sua própria configuração de MCP. |
| `lspServers` | objeto string \| | No | Caminho para a configuração do LSP ou definições de servidor em linha. |
| `strict` | boolean | No | Quando `true` (o padrão), os plug-ins devem estar em conformidade com o esquema completo e as regras de validação. Quando `false` a validação relaxada é usada, permite mais flexibilidade, especialmente para instalações diretas ou plugins legados. |
#### Tipos de origem de plug-in
O campo `source` em uma entrada de plugin aceita uma string de caminho relativo ou um objeto que descreve um repositório GitHub ou uma origem de URL do Git:
```json
{
"source": {
"source": "github",
"repo": "owner/repo",
"ref": "v1.0.0",
"path": "plugins/my-plugin"
}
}
```
Os tipos de origem `github` e `url` aceitam um campo opcional `sha` para fixar as instalações em um commit exato, além de (ou em vez de) `ref`:
```json
{
"source": {
"source": "github",
"repo": "owner/repo",
"sha": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
"path": "plugins/my-plugin"
}
}
```
`sha` deve ser um SHA completo de commit com 40 caracteres. Fixe em um `sha` para instalações reproduzíveis que são imunes a pushes forçados ou movimentos de marcação/ramificação.
## Locais de arquivos
| Item | Caminho |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Plug-ins instalados | |
| `~/.copilot/installed-plugins/MARKETPLACE/PLUGIN-NAME` (instalado por meio de um marketplace) e `~/.copilot/installed-plugins/_direct/SOURCE-ID/` (instalado diretamente) | |
| Cache do Marketplace | Diretório de cache de plataforma: `~/.cache/copilot/marketplaces/` (Linux) `~/Library/Caches/copilot/marketplaces/` (macOS). Substituível por `COPILOT_CACHE_HOME`. |
| Manifesto do Plugin | Plug-ins do agente (v1.0.0 ou v1.1.0): `plugin.json` na raiz do plug-in. Um manifesto raiz direcionado a Plug-ins do Agente tem precedência sobre e , de acordo com a especificação §5.1. Plugins legados: `.plugin/plugin.json`, `plugin.json`, `.github/plugin/plugin.json` ou `.claude-plugin/plugin.json` (verificados nesta ordem). |
| Manifesto do Marketplace | |
| `marketplace.json`, `.plugin/marketplace.json`ou `.github/plugin/marketplace.json``.claude-plugin/marketplace.json` (verificado nesta ordem) | |
| Agentes | Plugins legados: `agents/` (por padrão, sobrescrevível no manifesto). |
| Habilidades | Plugins do agente: `skills/` (corrigido, sem fallback de raiz `SKILL.md`). Plugins legados: `skills/` (padrão, podendo ser sobrescritos no manifesto), recorrendo a um `SKILL.md` raiz quando não existe nenhum diretório `skills/`. |
| Configuração de ganchos | Plug-ins herdados: `hooks.json` ou `hooks/hooks.json`. |
| Configuração do MCP | Plugins do agente: `mcp.json`. Plugins legados: `.mcp.json`, `.github/mcp.json` ou o campo `mcpServers` do manifesto. |
| Configuração de LSP | Plug-ins herdados: `lsp.json` ou `.github/lsp.json`. |
| Dados de plug-in | Para servidores MCP do Agent Plugins 1.0, `${PLUGIN_DATA}` (também disponível como `${COPILOT_PLUGIN_DATA}` e `${CLAUDE_PLUGIN_DATA}`) aponta para um diretório persistente e gravável exclusivo para cada plug-in instalado. Use isso para dados de runtime específicos do plug-in em vez de caminhos dentro do diretório de cache de plug-ins instalados. |
## Ordem e precedência de carregamento
Se você instalar vários plug-ins, é possível que alguns agentes personalizados, habilidades, servidores MCP ou ferramentas fornecidas por meio de servidores MCP tenham nomes duplicados. Nessa situação, a CLI determina qual componente usar com base em uma ordem de precedência.
* **Agentes e habilidades** use a precedência do primeiro encontrado.
Se você tiver um agente personalizado no nível do projeto ou uma habilidade cujo nome ou ID sejam iguais a os de um plug-in que você instalar, o agente ou habilidade do plug-in será ignorado sem aviso. O plug-in não pode substituir configurações pessoais ou no nível do projeto. Os agentes personalizados são desduplicados usando seu ID, que é derivado de seu nome de arquivo (por exemplo, se o arquivo for nomeado `reviewer.agent.md`, a ID do agente será `reviewer`). As habilidades são desduplicadas pelo campo do nome dentro do arquivo `SKILL.md`.
* **Os servidores MCP** usam a precedência "último a vencer".
Se você instalar um plug-in que define um servidor MCP com o mesmo nome de servidor que um servidor MCP já instalado, a definição do plug-in terá precedência. Você pode usar a opção `--additional-mcp-config` de linha de comando para substituir uma configuração de servidor MCP com o mesmo nome, instalado usando um plug-in. Se dois ou mais plug-ins declararem um servidor MCP com o mesmo nome, a CLI usará a versão do plug-in que carregou por último e mostrará um aviso nomeando cada plug-in anterior que o definiu.
* **Ferramentas e agentes internos** estão sempre presentes e não podem ser substituídos por componentes definidos pelo usuário.
O diagrama a seguir ilustra as regras de ordem e precedência de carregamento.
```text
┌──────────────────────────────────────────────────────────────────┐
│ BUILT-IN - HARDCODED, ALWAYS PRESENT │
│ • tools: bash, view, apply_patch, glob, rg, task, ... │
│ • agents: explore, task, code-review, general-purpose, research │
└────────────────────────┬─────────────────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────────────────────┐
│ CUSTOM AGENTS - FIRST LOADED IS USED (dedup by ID) │
│ 1. ~/.copilot/agents/ (user, .github convention) │
│ 2. /.github/agents/ (project) │
│ 3. /.github/agents/ (inherited, monorepo) │
│ 4. /.claude/agents/ (project) │
│ 5. /.claude/agents/ (inherited, monorepo) │
│ 6. /.github/agents/ (added root, --add-dir) │
│ 7. PLUGIN: agents/ dirs (plugin, by install order) │
│ 8. Remote org/enterprise agents (remote, via API) │
└──────────────────────┬──────────────────────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────────────────────┐
│ AGENT SKILLS - FIRST LOADED IS USED (dedup by name) │
│ 1. /.github/skills/ (project) │
│ 2. /.agents/skills/ (project) │
│ 3. /.claude/skills/ (project) │
│ 4. /.github/skills/ etc. (inherited) │
│ 5. ~/.copilot/skills/ (personal-copilot) │
│ 6. ~/.agents/skills/ (personal-agents) │
│ 7. PLUGIN: skills/ dirs (plugin) │
│ 8. COPILOT_SKILLS_DIRS env + config (custom) │
│ --- then commands (.claude/commands/), skills override commands ---│
└──────────────────────┬──────────────────────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────────────────────┐
│ MCP SERVERS - LAST LOADED IS USED (dedup by server name) │
│ 1. ~/.copilot/mcp-config.json (lowest priority) │
│ 2. PLUGIN: MCP configs (plugins) │
│ 3. --additional-mcp-config flag (highest priority) │
└─────────────────────────────────────────────────────────────────────┘
```
## Leitura adicional
* [Sobre os padrões de plug-in gerenciados pela empresa](/pt/copilot/concepts/enterprise/plugin-standards)
* [GitHub Copilot CLI](/pt/copilot/how-tos/copilot-cli)
* [referência de comando da CLI GitHub Copilot](/pt/copilot/reference/copilot-cli-reference/cli-command-reference)
* [referência programática do GitHub Copilot CLI](/pt/copilot/reference/copilot-cli-reference/cli-programmatic-reference)