Referência do plugin CLI do GitHub Copilot

Comandos da CLI

Você pode usar os seguintes comandos no terminal para gerenciar plug-ins para CLI do Copilot.

Especificação do plug-in para install comando

          `./my-plugin` ou `/abs/path`    | Diretório local |

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

Campo obrigatório

Campos de metadados opcionais

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

Arquivo de exemplo plugin.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"],
  "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": "jane@example.com"
  },
  "license": "MIT",
  "keywords": ["react", "frontend"],
  "agents": "agents/",
  "skills": ["skills/", "extra-skills/"],
  "hooks": "hooks.json",
  "mcpServers": ".mcp.json"
}

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 saber mais, confira Criando um marketplace de plugins para CLI do GitHub Copilot.

Arquivo de exemplo marketplace.json

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

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

Campos marketplace.json

Campos de nível superior

          `{ name, email? }` — informações do proprietário do marketplace. |

| plugins | matriz | Yes | Lista de entradas de plug-in (consulte a tabela abaixo). | | metadata | objeto | Não | { description?, version?, pluginRoot? } |

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

Locais de arquivos

          `~/.copilot/installed-plugins/` e `~/.copilot/installed-plugins/_direct` |

| Cache do Marketplace | ~/.copilot/state/marketplace-cache/ | | Manifesto do Plugin | plugin.json, .github/plugin/plugin.json ou .claude-plugin/plugin.json | | Manifesto do Marketplace | .github/plugin/marketplace.json ou .claude-plugin/marketplace.json | | Agents | agents/ (padrão, substituível no manifesto) | | Skills | skills/ (padrão, substituível no manifesto) | | Configuração de ganchos | hooks.json ou hooks/hooks.json | | Configuração do MCP | .mcp.json ou .github/mcp.json | | Configuração LSP | lsp.json ou .github/lsp.json |

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.

•         **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  │
└────────────────────────┬────────────────────────────────┘
                         │
  ┌──────────────────────▼──────────────────────────────────────────────┐
  │  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. ~/.claude/agents/            (user, .claude convention)         │
  │  5. <project>/.claude/agents/    (project)                          │
  │  6. <parents>/.claude/agents/    (inherited, monorepo)              │
  │  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. ~/.claude/skills/                (personal-claude)              │
  │  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. .vscode/mcp.json                 (workspace)                    │
  │  3. PLUGIN: MCP configs              (plugins)                      │
  │  4. --additional-mcp-config flag     (highest priority)             │
  └─────────────────────────────────────────────────────────────────────┘