Referencia del plugin CLI de GitHub Copilot

Para obtener información general sobre qué son los complementos y cómo funcionan en los Copilot clientes, consulte Información sobre GitHub Copilot complementos.

Comandos de la CLI

Puede usar los siguientes comandos en el terminal para administrar complementos para Copilot CLI. copilot plugins (plural) es un alias heredado para copilot plugin: ambos se resuelven en el mismo comando.

Antes de que copilot plugin se dividiera en comandos independientes por recurso, copilot plugins también inspeccionaba y activaba o desactivaba servidores MCP, habilidades, instrucciones y servidores de idiomas mediante las opciones --kind, --scope, --mcp y --skill. Se han eliminado esos indicadores entre tipos. En su lugar, use los comandos dedicados copilot mcp, copilot skill, copilot instructiony copilot lsp . copilot plugin list --json ahora emite una matriz plana de complementos en lugar del objeto anterior { plugins, errors } .

Especificación para el comando del complemento install

copilot plugin list Opciones

Cada --json fila tiene la forma { name, marketplace?, version?, enabled, source, installedFrom? }.

copilot plugin enable/disable opciones

copilot plugin install Opciones

Para instalar una skill en lugar de un complemento, utiliza copilot skill add; no se trata de la instalación de un complemento ni se realiza a través de un marketplace.

Los servidores MCP se instalan desde un registro configurado por directivas, lo que requiere autenticación e entrada secreta interactiva. Use la vista En línea del /mcp panel o el copilot mcp add comando para agregar servidores MCP en lugar de copilot plugin install.

copilot plugin update Opciones

Los plugins de origen —los instalados desde las tiendas integradas copilot-plugins y awesome-copilot— se actualizan automáticamente al inicio de cada sesión en un directorio de trabajo de confianza. Deshabilite este comportamiento con la opción autoUpdate (establecida en false) o la variable de entorno COPILOT_AUTO_UPDATE=false. La actualización automática también se omite de forma predeterminada en CI. Consulte directorio de configuración de la CLI de GitHub Copilot.

Un mercado que hayas añadido tú mismo puede activarse para la misma actualización automática al inicio de la sesión configurando autoUpdate: true en su entrada extraKnownMarketplaces en tu configuración de usuario. Esta opción de activación solo se aplica a las sesiones interactivas y -p; las sesiones de SDK y de servidor no se actualizan automáticamente. Se respeta la configuración del usuario o la configuración administrada (MDM/servidor), pero se acepta e ignora una configuración autoUpdate en el nivel de repositorio; esta no puede habilitar ni redirigir la actualización automática de un marketplace. En caso de conflicto de nombres, tiene prioridad el marketplace propio integrado, seguido de una entrada administrada (que sustituye por completo a la entrada de usuario con el mismo nombre, por lo que una entrada administrada sin "autoUpdate": true elimina la opción de participación del usuario) y, por último, la propia entrada del usuario. Consulte Configuración del repositorio.

En modo interactivo, /plugin señala un complemento o un mercado instalado cuando hay una versión más reciente disponible en el origen, y ofrece una acción Actualizar desde el panel de control para descargarla.

copilot plugin marketplace (alias marketplaces) subcomandos

Los marketplaces predeterminados integrados se incluyen con el entorno de ejecución y no se pueden quitar.

En modo interactivo, ejecute /plugin marketplace update [NAME] (alias /plugin marketplace refresh) o presione R en la vista marketplace del /plugin panel para actualizar cada catálogo de Marketplace registrado.

plugin.json

Todos los complementos constan de un directorio de complementos que contiene un archivo de manifiesto denominado plugin.json. Agent Plugins 1.0 requiere el manifiesto en la raíz del complemento. Los complementos heredados admiten las ubicaciones alternativas enumeradas en Ubicaciones de archivos. Consulte Creación de un complemento para GitHub Copilot CLI.

Copilot CLI admite tanto el manifiesto del complemento antiguo como el manifiesto de Agent Plugins 1.0. El valor exacto $schema https://agent-plugins.org/schemas/1.0.0/plugin.schema.json hace que un complemento se ajuste a la semántica de Agent Plugins 1.0. Un manifiesto sin este valor usa el formato heredado y se carga como antes.

Campos del manifiesto de Agent Plugins 1.0

Los complementos del agente 1.0 definen un esquema de manifiesto cerrado. Para conocer los requisitos de formato completos, consulte la especificación Agent Plugins 1.0.

Se permiten los siguientes campos:

Los campos de nivel superior desconocidos se notifican y se ignoran. Los campos de ruta del componente, como agents, skills, hooks, mcpServers y lspServers, no son campos del manifiesto de Agent Plugins 1.0.

Restricciones de nombre

El nombre de un complemento de Agent Plugins 1.0 debe:

• Contienen entre 1 y 64 caracteres.
• Solo contienen letras ASCII minúsculas, dígitos, guiones y puntos.
• Comience y termine con un carácter alfanumérico.
• No contiene -- ni ...

Componentes

Agent Plugins 1.0 define dos tipos de componentes portátiles:

• Habilidades en los subdirectorios inmediatos de skills/ que contienen un archivo SKILL.md.
• Servidores MCP en la raíz del complemento mcp.json.

Estas ubicaciones son fijas y no se pueden configurar en plugin.json. La raíz mcp.json debe declarar https://agent-plugins.org/schemas/1.0.0/mcp.schema.json en el campo $schema. La CLI acepta los nombres de transporte MCP stdio, streamable-http y sse.

Para los servidores stdio, la CLI proporciona PLUGIN_ROOT y PLUGIN_DATA en el entorno del subproceso. Expande ${PLUGIN_ROOT} y ${PLUGIN_DATA} en los valores args, env y cwd del servidor. PLUGIN_DATA apunta a un directorio persistente y grabable para el complemento instalado.

Los complementos de agente 1.0 no definen agentes portátiles, enlaces, comandos, reglas o servidores LSP. Estos siguen siendo específicos del cliente. Los datos del manifiesto específicos del cliente deben ir en extensions, indexados mediante un espacio de nombres de dominio inverso. Los archivos específicos del cliente pertenecen a un directorio de nivel superior con el mismo espacio de nombres. Los clientes omiten los espacios de nombres que no admiten.

Copilot CLI lee sus componentes específicos del cliente del directorio com.github.copilot:

Estas ubicaciones solo se aplican a los plugins de Agent Plugins 1.0. Los plugins heredados siguen utilizando las ubicaciones de sus componentes y los campos de ruta del manifiesto.

Ejemplo de archivo plugin.json de Agent Plugins 1.0

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

Campos de manifiesto heredados

Campo obligatorio

Campos de metadatos opcionales

Campos de ruta de acceso de componente

Estos indican a la CLI dónde encontrar los componentes del complemento. Todos son opcionales. La CLI utiliza convenciones predeterminadas si se omiten ciertos parámetros.

Configuración del servidor LSP

Para incluir servidores LSP (protocolo de servidor de idiomas) en un complemento, cree un archivo lsp-config/servers.json en el directorio del complemento, o especifique una ruta de acceso o un objeto en línea mediante el campo lspServers de plugin.json.

Ejemplo lsp-config/servers.json (o en línea mediante lspServers en plugin.json):

{
    "lspServers": {
        "my-lsp": {
            "command": "my-language-server",
            "fileExtensions": { ".myext": "mylang" }
        }
    }
}

Para la compatibilidad multiplataforma, use bash y powershell en lugar de command:

{
    "lspServers": {
        "my-lsp": {
            "bash": "${PLUGIN_ROOT}/scripts/start-lsp.sh",
            "powershell": "${PLUGIN_ROOT}/scripts/start-lsp.ps1",
            "fileExtensions": { ".myext": "mylang" }
        }
    }
}

(*) Se requiere al menos uno de command, basho powershell . Cuando se especifican bash y powershell, se selecciona automáticamente la adecuada para la plataforma (PowerShell en Windows, Bash en otro lugar).

Use ${PLUGIN_ROOT} para hacer referencia a rutas de acceso dentro del directorio del complemento.

marketplace.json

Puede crear un marketplace de complementos ,que los usuarios pueden usar para detectar e instalar los complementos, creando un marketplace.json archivo y guardándolo en el .github/plugin/ directorio del repositorio. También puede almacenar el marketplace.json archivo en el sistema de archivos local. Por ejemplo, guardar el archivo como /PATH/TO/my-marketplace/.github/plugin/marketplace.json le permite agregarlo a la CLI mediante el siguiente comando:

copilot plugin marketplace add /PATH/TO/my-marketplace

Para obtener más información, vea Creación de un marketplace de complementos para GitHub Copilot CLI.

Archivo marketplace.json de ejemplo

{
  "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 nivel superior

Campos de entrada del complemento (objetos dentro de la plugins matriz)

Tipos de origen del complemento

El campo source de una entrada de un complemento acepta una cadena con una ruta relativa o un objeto que describe un repositorio GitHub o un origen con una URL de Git:

{
    "source": {
        "source": "github",
        "repo": "owner/repo",
        "ref": "v1.0.0",
        "path": "plugins/my-plugin"
    }
}

Tanto el tipo de origen github como el url aceptan un campo opcional sha para fijar las instalaciones a un commit exacto, además de (o en lugar de) ref:

{
    "source": {
        "source": "github",
        "repo": "owner/repo",
        "sha": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
        "path": "plugins/my-plugin"
    }
}

sha debe ser un SHA de commit completo de 40 caracteres. Fíjalo a un sha para instalaciones reproducibles que sean inmunes a los force-pushes o a los movimientos de etiquetas/ramas.

Ubicaciones de archivos

Orden de carga y prioridad

Si instala varios complementos, es posible que algunos agentes personalizados, aptitudes, servidores MCP o herramientas proporcionados a través de servidores MCP tengan nombres duplicados. En esta situación, la CLI determina qué componente usar en función de un orden de precedencia.

• Los agentes y las aptitudes utilizan la prioridad de "primero en encontrar, primero en ganar."

  Si tiene un agente personalizado de nivel de proyecto o una aptitud con el mismo nombre o identificador que uno en un complemento que instale, el agente o la aptitud del complemento se omiten silenciosamente. El complemento no puede invalidar configuraciones personales o de nivel de proyecto. Los agentes personalizados se desduplican mediante su identificador, que se deriva de su nombre de archivo (por ejemplo, si el archivo se denomina reviewer.agent.md, el identificador del agente es reviewer). Las aptitudes se desduplican por su campo de nombre dentro del archivo SKILL.md.

• Los servidores MCP usan precedencia de última instancia.

  Si instala un complemento que define un servidor MCP con el mismo nombre de servidor que un servidor MCP que ya ha instalado, la definición del complemento tiene prioridad. Puede usar la --additional-mcp-config opción de línea de comandos para invalidar una configuración del servidor MCP con el mismo nombre, instalada mediante un complemento. Si dos o más complementos declaran un servidor MCP con el mismo nombre, la CLI usa la versión del complemento que cargó por última vez y muestra una advertencia que asigna un nombre a cada complemento anterior que lo definió.

• Las herramientas y agentes integrados siempre están presentes y no se pueden invalidar mediante componentes definidos por el usuario.

En el diagrama siguiente se muestran las reglas de orden de carga y precedencia.

┌──────────────────────────────────────────────────────────────────┐
│  BUILT-IN - HARDCODED, ALWAYS PRESENT                            │
│  • tools: bash, view, apply_patch, glob, rg, task, ...           │
│  • agents: explore, task, code-review, general-purpose, research │
└────────────────────────┬─────────────────────────────────────────┘
                         │
  ┌──────────────────────▼──────────────────────────────────────────────┐
  │  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. <project>/.claude/agents/    (project)                          │
  │  5. <parents>/.claude/agents/    (inherited, monorepo)              │
  │  6. PLUGIN: agents/ dirs         (plugin, by install order)         │
  │  7. 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. ~/.agents/skills/                (personal-agents)              │
  │  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. PLUGIN: MCP configs              (plugins)                      │
  │  3. --additional-mcp-config flag     (highest priority)             │
  └─────────────────────────────────────────────────────────────────────┘

Lectura adicional

• Acerca de los estándares de complementos administrados por la empresa
• GitHub Copilot CLI
• Referencia de comandos de la CLI de GitHub Copilot
• Referencia programática de la CLI de GitHub Copilot