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 CLI do Copilot. copilot plugin e copilot plugins são equivalentes — use o que soar melhor para o subcomando.

De forma não interativa, copilot plugins enable NAME --plugin, copilot plugins disable NAME --plugin e copilot plugins remove NAME --plugin fornecem as mesmas operações de habilitar, desabilitar e desinstalar. --plugin é o tipo padrão e pode ser omitido para esses três comandos. Consulte referência de comando da CLI GitHub Copilot para os tipos --mcp não interativos --skill, que estendem esses comandos para servidores MCP e habilidades.

Especificação do plug-in para install comando

copilot plugins install opções

Além de instalar um plug-in a partir de uma especificação, o copilot plugins install pode instalar uma skill individual a partir de um arquivo, de uma URL ou de um diretório com --skill. A instalação de uma skill não é uma instalação de plug-in e não passa por uma loja — consulte referência de comando da CLI GitHub Copilot para ver detalhes sobre as skills em si.

Instalar um diretório registra-o como uma fonte de habilidade personalizada em vez de copiá-lo; A instalação de um arquivo ou URL copia o conteúdo da habilidade no diretório de habilidades pessoais ou de projeto.

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 o /plugins dashboard (modo Online) ou o /mcp comando de barra para adicionar servidores MCP em vez de copilot plugins install.

copilot plugins update opções

Os plug-ins de primeira parte — aqueles instalados a partir dos marketplaces e copilot-plugins internos 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 optar pela mesma atualização automática de início de sessão definindo autoUpdate: true sua extraKnownMarketplaces entrada em suas configurações de usuário. Essa aceitação só é respeitada em suas próprias configurações de usuário– uma configuração de repositório ou gerenciada (MDM) não pode habilitar ou redirecionar a atualização automática para um marketplace. Consulte as configurações do Repositório.

copilot plugins marketplace Subcomandos

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

plugin.json

Todos os plug-ins consistem em um diretório de plug-in contendo, no mínimo, um arquivo de manifesto chamado plugin.json localizado na raiz do diretório do plug-in. Consulte Criando um plug-in para CLI do GitHub Copilot.

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.

Arquivo de exemplo plugin.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"],
  "agents": "agents/",
  "skills": ["skills/", "extra-skills/"],
  "hooks": "hooks.json",
  "mcpServers": ".mcp.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"],
  "agents": "agents/",
  "skills": ["skills/", "extra-skills/"],
  "hooks": "hooks.json",
  "mcpServers": ".mcp.json"
}

Suporte à Especificação Aberta de Plugins

Declarar o $schema canônico em plugin.json faz com que um plug-in adote o formato Agent Plugins (Open Plugin Spec) v1.0.0, de forma adicional ao carregamento padrão de plug-ins:

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 CLI do GitHub Copilot.

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/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. PLUGIN: agents/ dirs         (plugin, by install order)         │
  │  7. 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
• CLI do GitHub Copilot
• referência de comando da CLI GitHub Copilot
• referência programática do GitHub Copilot CLI