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

Introdução

Plug-ins são pacotes que estendem a funcionalidade de Copilot CLI. Confira Sobre plug-ins 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.

Copilot CLI dá suporte a dois formatos de plug-in:

  • Plugins de agentes 1.0, um formato portátil para habilidades e servidores MCP. Declarar o canônico $schema em plugin.json faz com que o plug-in adote esse formato.
  • O formato herdado Copilot , que dá suporte a componentes Copilotespecíficos e caminhos de componente configuráveis. Um manifesto sem os Plug-ins $schema do Agente continua a usar esse formato.

Há suporte para ambos os formatos. Escolha Plug-ins do Agente 1.0 quando quiser tornar as habilidades e os servidores MCP portáteis entre clientes compatíveis. Escolha o formato herdado quando precisar de caminhos de componente personalizados ou se estiver mantendo um plug-in específico existente Copilot. No Agent Plugins 1.0, as habilidades e os servidores MCP são portáteis, e componentes específicos de Copilot, como agentes, comandos, regras, hooks e servidores LSP, vêm do diretório com.github.copilot no plugin.

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. Campos de nível superior desconhecidos são relatados e ignorados. 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.

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

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

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

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

  6. 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 a CLI lê do cache para sessões subsequentes. Para pegar as alterações feitas em um plug-in local, instale-o novamente:

    Shell
    copilot plugin install ./my-plugin

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

    Shell
    copilot plugin uninstall NAME

    Observação

    Para desinstalar um plug-in, use o nome do plug-in conforme especificado no name campo do arquivo de manifesto do plug-in plugin.json , não o caminho para o diretório do plug-in.

Distribuindo seu plug-in

Para distribuir o plug-in, você pode adicioná-lo a um marketplace. Confira Criando um marketplace de plugin para GitHub Copilot CLI.

Leitura adicional