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

Los complementos son paquetes que amplían la funcionalidad de Copilot CLI. Para obtener una visión general entre clientes, consulte Complementos para GitHub Copilot.

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.

Agent Plugins 1.0 es un formato portátil para habilidades y servidores MCP en clientes compatibles. Copilot CLI también admite un formato heredado Copilot .

  • Para usar Agent Plugins 1.0, declare el elemento canónico $schema en plugin.json.
  • El formato heredado admite componentes específicos de Copilot y rutas de acceso de componente configurables. En Copilot CLI, un manifiesto sin los Plugins de Agent $schema usa este formato.

Elija Agent Plugins 1.0 cuando quiera compartir aptitudes y servidores MCP en clientes compatibles. Compruebe la documentación del cliente para confirmar qué otros componentes admite. Elija el formato heredado cuando necesite rutas de acceso de componente configurables en Copilot CLI o esté manteniendo un complemento existente específico de Copilot.

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. Copilot CLI notifica e ignora los campos de nivel superior desconocidos. 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.

Prueba tu complemento con GitHub Copilot CLI

Los comandos siguientes prueban un complemento en Copilot CLI.

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

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

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

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

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

    Importante

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

    Shell
    copilot plugin install ./my-plugin

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

    Shell
    copilot plugin uninstall NAME

    Usa el valor del campo name en el manifiesto plugin.json del complemento para NAME, no la ruta de acceso al directorio del complemento.

Añade evaluaciones para tu complemento

Tratar el contexto del complemento como infraestructura agéntica. Agregue evaluaciones para los comportamientos que el complemento está diseñado para admitir y ejecútelos al cambiar sus instrucciones, herramientas u otros componentes.

Distribuye tu complemento

Para compartir el complemento con otros usuarios, agréguelo a un marketplace. Consulta Creación y uso compartido de un marketplace de complementos en GitHub.

Los valores predeterminados del repositorio pueden activar tu complemento en un proyecto. Los miembros pueden invalidar estos valores predeterminados localmente, pero la configuración administrada por la empresa puede requerir o bloquear el complemento y siempre tiene prioridad.

Lectura adicional