Creación de un complemento para GitHub Copilot CLI

Cree un complemento para compartir personalizaciones en un paquete fácil de instalar.

En este artículo

Introducción

Los complementos son paquetes que amplían la funcionalidad de Copilot CLI. Consulta Información sobre GitHub Copilot complementos.

Nota:

Puede encontrar ayuda sobre el uso de complementos escribiendo copilot plugin [SUBCOMMAND] --help en el terminal.

Estructura del complemento

Un complemento consta de un directorio con una estructura específica y un plugin.json archivo de manifiesto. Agent Plugins 1.0 requiere el manifiesto en la raíz del complemento. Los complementos heredados admiten ubicaciones de manifiesto adicionales. Un complemento también puede contener cualquier combinación de agentes, aptitudes, enlaces y configuraciones de servidor MCP.

Copilot CLI admite dos formatos de complemento:

  • Plugins de agente 1.0, un formato portátil para habilidades y servidores MCP. Declarar la etiqueta canónica $schema en plugin.json hace que el complemento use este formato.
  • El formato heredado Copilot, que admite componentes específicos de Copilot y rutas de componentes configurables. Un manifiesto sin los complementos $schema del agente sigue usando este formato.

Se admiten ambos formatos. Elija Agent Plugins 1.0 cuando quiera hacer portables las aptitudes y los servidores MCP en distintos clientes compatibles. Elija el formato heredado cuando necesite rutas personalizadas para componentes o esté manteniendo un plugin específico de Copilot ya existente. En Plugins de agente 1.0, las habilidades y los servidores MCP son portátiles, y los componentes específicos de Copilot, como agentes, comandos, reglas, hooks y servidores LSP, proceden del directorio com.github.copilot del plugin.

Creación de un complemento

  1. Cree un directorio para el complemento.

  2. Elija un formato de complemento y agregue un plugin.json archivo de manifiesto a la raíz del directorio.

    Para crear un complemento de Agent Plugins 1.0, incluya la etiqueta canónica $schema:

Archivo de complementos de agente de ejemplo 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"]
}

El esquema solo permite $schema, version, name, description, author, homepage, repository, license, keywords y extensions como campos de nivel superior. Los campos de nivel superior desconocidos se notifican y se ignoran. El campo extensions es un mapa de datos específicos del cliente indexados por un espacio de nombres de dominio inverso.

Para crear un complemento heredado, omita Agent Plugins $schema. Puede usar campos de ruta del componente en el manifiesto:

Archivo heredado plugin.json de ejemplo

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

Para obtener más información sobre el conjunto completo de campos que puede incluir en este archivo, consulte Referencia del plugin CLI de GitHub Copilot.

  1. Agregue componentes al complemento.

    En un complemento Agent Plugins 1.0, las aptitudes deben ser subdirectorios inmediatos de skills/y cada aptitud debe contener un SKILL.md archivo. La configuración de MCP debe estar en mcp.json, en la raíz del complemento. No puede invalidar estas ubicaciones en plugin.json. Los componentes específicos de Copilot se encuentran en el directorio com.github.copilot, como com.github.copilot/agents/ para agentes personalizados y com.github.copilot/hooks/hooks.json para hooks.

    En un complemento heredado, use las ubicaciones predeterminadas de los componentes o las rutas de acceso de los componentes configuradas en plugin.json.

    Por ejemplo:

    1. Agregue un agente mediante la creación de un NAME.agent.md archivo en un agents subdirectorio. En un complemento Agent Plugins 1.0, cree el archivo en com.github.copilot/agents/. En un complemento heredado, créelo en agents/.

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

You are a specialized assistant that...

    2. Agregue una aptitud mediante la creación de un skills/NAME subdirectorio del directorio del complemento, donde NAME es el nombre de la aptitud. A continuación, dentro de este subdirectorio, cree un SKILL.md archivo que defina la aptitud.

      Por ejemplo, para crear una aptitud de "implementación", cree skills/deploy/SKILL.md:

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

Instructions for the skill...

    3. Para un complemento Agent Plugins 1.0, agregue servidores MCP en un archivo raíz mcp.json . La configuración de MCP usa su propio esquema de complementos de 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"
     }
   }
 }
}

      Se acepta el nombre de transporte streamable-http para los servidores HTTP Streamable. Para los servidores stdio, Copilot CLI proporciona las variables de entorno PLUGIN_ROOT y PLUGIN_DATA y expande ${PLUGIN_ROOT} y ${PLUGIN_DATA} en args, los valores env y cwd.

  2. Instale el complemento localmente para que pueda probarlo a medida que lo desarrolle.

    Por ejemplo, donde ./my-plugin es la ruta de acceso al directorio del complemento, escriba:

    Shell
    copilot plugin install ./my-plugin

  3. Compruebe que el complemento se cargó correctamente viendo la lista de complementos instalados:

    Shell
    copilot plugin list

    O bien, puede iniciar una nueva sesión interactiva y escribir:

    Copilot prompt
    /plugin list

  4. Compruebe que los agentes, aptitudes, enlaces y configuraciones del servidor MCP que ha definido se cargan correctamente.

    Por ejemplo, en una sesión interactiva, para comprobar que los agentes personalizados definidos en el complemento se cargaron, escriba:

    Copilot prompt
    /agent

    Para comprobar que las aptitudes definidas en el complemento se cargaron, escriba:

    Copilot prompt
    /skills list

  5. Use la funcionalidad proporcionada por los componentes del complemento para comprobar que cada componente funciona según lo previsto.

  6. Itere en el desarrollo del complemento, según sea necesario.

    Importante

    Al instalar un complemento, sus componentes se almacenan en caché y la CLI lee de la memoria caché para sesiones posteriores. Para recoger los cambios realizados en un complemento local, instálelo de nuevo:

    Shell
    copilot plugin install ./my-plugin

  7. Una vez finalizadas las pruebas, puede desinstalar la versión local del complemento escribiendo lo siguiente:

    Shell
    copilot plugin uninstall NAME

    Nota:

    Para desinstalar un complemento, use el nombre del complemento como se especifica en el name campo del archivo de manifiesto del plugin.json complemento, no la ruta de acceso al directorio del complemento.

Distribución del complemento

Para distribuir el complemento, puede agregarlo a un marketplace. Consulta Creación de un marketplace de complementos para GitHub Copilot CLI.

Lectura adicional