referência de plugin da CLI GitHub Copilot

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.

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.

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, copilot skill, copilot mcp e copilot lsp. copilot plugin list --json agora emite uma matriz simples de plug-ins em vez do objeto anterior { plugins, errors } .

Especificação do plug-in para install comando

copilot plugin list opções

Cada --json linha tem a forma { name, marketplace?, version?, enabled, source, installedFrom? }.

copilot plugin enable/disable opções

copilot plugin install opções

Para instalar uma skill em vez de um plug-in, use copilot skill add não se trata de uma instalação de plug-in e não passa por um marketplace.

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 comando para adicionar servidores MCP em vez de copilot plugin install.

copilot plugin update opções

Os plugins nativos (aqueles instalados a partir de marketplaces integrados) copilot-plugins e 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.

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.

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

Os marketplaces padrão integrados acompanham o runtime e não podem ser removidos.

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. Consulte Criando um plug-in para GitHub Copilot CLI.

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 (https://agent-plugins.org/schemas/1.0.0/plugin.schema.json) e v1.1.0 (https://agent-plugins.org/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.

Os seguintes campos são permitidos:

Campos de nível superior desconhecidos são informados e ignorados. Campos de caminho do componente, como agents, skills, hookse lspServers``mcpServersnã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:

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

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-dev-tools",
  "description": "React development utilities",
  "version": "1.2.0",
  "author": {
    "name": "Jane Doe",
    "email": "[email protected]"
  },
  "license": "MIT",
  "keywords": ["react", "frontend"]
}

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-dev-tools",
  "description": "React development utilities",
  "version": "1.2.0",
  "author": {
    "name": "Jane Doe",
    "email": "[email protected]"
  },
  "license": "MIT",
  "keywords": ["react", "frontend"]
}

Campos de manifesto legados

Campo obrigatório

Campos de metadados opcionais

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.

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:

---
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):

{
    "lspServers": {
        "my-lsp": {
            "command": "my-language-server",
            "fileExtensions": { ".myext": "mylang" }
        }
    }
}

Para suporte multiplataforma, use bash e powershell , em vez de command:

{
    "lspServers": {
        "my-lsp": {
            "bash": "${PLUGIN_ROOT}/scripts/start-lsp.sh",
            "powershell": "${PLUGIN_ROOT}/scripts/start-lsp.ps1",
            "fileExtensions": { ".myext": "mylang" }
        }
    }
}

(*) Pelo menos um de command, bashou 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:

copilot plugin marketplace add /PATH/TO/my-marketplace

Para obter mais informações, consulte Criando um marketplace de plugin para GitHub Copilot CLI.

Arquivo de exemplo marketplace.json

{
  "name": "my-marketplace",
  "owner": {
    "name": "Your Organization",
    "email": "[email protected]"
  },
  "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"
    }
  ]
}

{
  "name": "my-marketplace",
  "owner": {
    "name": "Your Organization",
    "email": "[email protected]"
  },
  "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"
    }
  ]
}

Campos marketplace.json

Campos de nível superior

Campos de entrada de plug-in (objetos dentro da plugins matriz)

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:

{
    "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:

{
    "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

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.

┌──────────────────────────────────────────────────────────────────┐
│  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. <project>/.github/agents/    (project)                          │
  │  3. <parents>/.github/agents/    (inherited, monorepo)              │
  │  4. <project>/.claude/agents/    (project)                          │
  │  5. <parents>/.claude/agents/    (inherited, monorepo)              │
  │  6. <add-dir>/.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. <project>/.github/skills/        (project)                      │
  │  2. <project>/.agents/skills/        (project)                      │
  │  3. <project>/.claude/skills/        (project)                      │
  │  4. <parents>/.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
• GitHub Copilot CLI
• referência de comando da CLI GitHub Copilot
• referência programática do GitHub Copilot CLI