Criando um plug-in para GitHub Copilot CLI

Crie um plug-in para compartilhar personalizações em um pacote fácil de instalar.

Neste artigo

Plug-ins são pacotes que estendem a funcionalidade de Copilot CLI. Para obter uma visão geral de vários clientes, consulte Plug-ins para GitHub Copilot.

Observação

Você pode encontrar ajuda para usar plug-ins entrando copilot plugin [SUBCOMMAND] --help no terminal.

Estrutura de plug-in

Um plug-in consiste em um diretório com uma estrutura específica e um plugin.json arquivo de manifesto. O Agent Plugins 1.0 requer o arquivo de manifesto na raiz do plug-in. Plugins legados oferecem suporte a locais adicionais para manifesto. Um plug-in também pode conter qualquer combinação de agentes, habilidades, ganchos e configurações de servidor MCP.

Agent Plugins 1.0 é um formato portátil para habilidades e servidores MCP em clientes compatíveis. Copilot CLI também dá suporte a um formato herdado Copilot .

  • Para usar Agent Plugins 1.0, declare o canonical $schema em plugin.json.
  • O formato herdado dá suporte a componentes Copilotespecíficos e caminhos de componente configuráveis. Em Copilot CLI, um manifest sem os Plug-ins $schema do Agente usa esse formato.

Escolha Plug-ins do Agente 1.0 quando quiser compartilhar habilidades e servidores MCP entre clientes compatíveis. Verifique a documentação do cliente para confirmar quais outros componentes ele suporta. Escolha o formato herdado quando precisar de caminhos de componente configuráveis em Copilot CLI ou se estiver mantendo um plug-in específico de Copilot existente.

Criando um plug-in

  1. Crie um diretório para o plug-in.

  2. Escolha um formato de plug-in e adicione um plugin.json arquivo de manifesto à raiz do diretório.

    Para criar um plug-in do Agent Plugins 1.0, inclua a tag canônica $schema:

Exemplo de arquivo plug-ins do agente 1.0 plugin.json

JSON
{
  "$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": "jane@example.com"
  },
  "license": "MIT",
  "keywords": ["react", "frontend"]
}

O esquema permite apenas $schema, , name, version, description, author, homepage, , repository, license, keywordse extensions como campos de nível superior. Copilot CLI informa e ignora campos desconhecidos de nível superior. O extensions campo é um mapa de dados específicos do cliente chaveados pelo namespace de domínio reverso.

Para criar um plug-in legado, omita os Plug-ins de agente $schema. Você pode usar campos de caminho do componente no manifesto:

Exemplo de arquivo legado plugin.json

JSON
{
  "name": "my-dev-tools",
  "description": "React development utilities",
  "agents": "agents/",
  "skills": ["skills/", "extra-skills/"],
  "hooks": "hooks.json",
  "mcpServers": ".mcp.json"
}

Para obter detalhes do conjunto completo de campos que você pode incluir neste arquivo, consulte referência de plugin da CLI GitHub Copilot.

  1. Adicione componentes ao plug-in.

    Em um plug-in do Agent Plugins 1.0, as habilidades devem ser subdiretórios imediatos de skills/, e cada habilidade deve conter um arquivo SKILL.md. A configuração do MCP deve estar em mcp.json na raiz do plug-in. Você não pode substituir esses locais em plugin.json. componentes específicos de Copilot ficam no diretório com.github.copilot, como com.github.copilot/agents/ para agentes personalizados e com.github.copilot/hooks/hooks.json para hooks.

    Em um plug-in legado, use os locais padrão dos componentes ou os caminhos dos componentes configurados em plugin.json.

    Por exemplo:

    1. Adicione um agente criando um NAME.agent.md arquivo em um agents subdiretório. Em um plug-in do Agent Plug-ins 1.0, crie o arquivo em com.github.copilot/agents/. Em um plug-in legado, crie-o em agents/.

      Markdown
      ---
name: my-agent
description: Helps with specific tasks
tools: ["bash", "edit", "view"]
---

You are a specialized assistant that...

    2. Adicione uma habilidade criando um skills/NAME subdiretório do diretório do plug-in, onde NAME está o nome da sua habilidade. Em seguida, dentro desse subdiretório, crie um SKILL.md arquivo que defina a habilidade.

      Por exemplo, para desenvolver uma skill chamada "deploy", crie o seguinte skills/deploy/SKILL.md:

      Markdown
      ---
name: deploy
description: Deploy the current project to...
---

Instructions for the skill...

    3. Para um plugin do Agent Plugins 1.0, adicione servidores MCP em um arquivo mcp.json raiz. A configuração do MCP usa seu próprio esquema de Plug-ins do Agente:

      JSON
      {
 "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
 "mcpServers": {
   "deployment-api": {
     "type": "streamable-http",
     "url": "https://deploy.example.com/mcp"
   },
   "local-validator": {
     "type": "stdio",
     "command": "node",
     "args": ["${PLUGIN_ROOT}/server/index.js"],
     "cwd": "${PLUGIN_ROOT}",
     "env": {
       "DATA_DIR": "${PLUGIN_DATA}/validator"
     }
   }
 }
}

      O nome de transporte streamable-http é aceito por servidores HTTP de streaming. Para servidores stdio, Copilot CLI fornece as variáveis de ambiente PLUGIN_ROOT e PLUGIN_DATA e expande ${PLUGIN_DATA} e ${PLUGIN_ROOT} em args, valores de env e cwd.

Testar o plug-in com GitHub Copilot CLI

Os comandos a seguir testam um plug-in em Copilot CLI.

  1. Instale o plug-in localmente, para que você possa testá-lo à medida que o desenvolve.

    Por exemplo, onde ./my-plugin está o caminho para o diretório do plug-in, insira:

    Shell
    copilot plugin install ./my-plugin

  2. Verifique se o plug-in foi carregado com êxito exibindo sua lista de plug-ins instalados:

    Shell
    copilot plugin list

    Ou você pode iniciar uma nova sessão interativa e inserir:

    Copilot prompt
    /plugin list

  3. Verifique se os agentes, as habilidades, os ganchos e as configurações do servidor MCP definidos são carregados corretamente.

    Por exemplo, em uma sessão interativa, para verificar se os agentes personalizados definidos no plug-in foram carregados, insira:

    Copilot prompt
    /agent

    Para verificar se as habilidades definidas no plug-in foram carregadas, insira:

    Copilot prompt
    /skills list

  4. Use a funcionalidade fornecida pelos componentes do plug-in para verificar se cada componente funciona conforme o esperado.

  5. Faça iterações no desenvolvimento do plug-in, conforme necessário.

    Importante

    Quando você instala um plug-in, seus componentes são armazenados em cache e Copilot CLI lê do cache em sessões subsequentes. Para aplicar as alterações feitas em um plug-in local, instale-o novamente:

    Shell
    copilot plugin install ./my-plugin

  6. Depois de concluir o teste, você poderá desinstalar a versão local do plug-in inserindo:

    Shell
    copilot plugin uninstall NAME

    Use o valor do campo name no manifesto plugin.json do plug-in para NAME, não o caminho para o diretório do plug-in.

Adicionar avaliações para o plug-in

Trate o contexto do plug-in como infraestrutura agêntica. Adicione avaliações para os comportamentos que seu plug-in tem o objetivo de dar suporte e execute-os quando você alterar suas instruções, ferramentas ou outros componentes.

Distribua seu plug-in

Para compartilhar seu plug-in com outras pessoas, adicione-o a um marketplace. Confira Criando e compartilhando um marketplace de plug-in no GitHub.

As configurações padrão do repositório podem habilitar o plug-in para um projeto. Os membros podem substituir esses padrões localmente, mas as configurações gerenciadas pela empresa podem exigir ou bloquear o plug-in e sempre prevalecem.

Leitura adicional