Agent Plugins 1.0.0: El formato de empaquetado compartido para habilidades y servidores MCP

Google, Microsoft, OpenAI, Cursor, Vercel y AWS han respaldado a Agent Plugins 1.0.0, una especificación que define cómo se empaquetan los complementos para agentes de inteligencia artificial. Esta versión corrige la estructura de los directorios, el formato de los archivos de configuración y las reglas de detección para dos tipos de componentes: habilidades y servidores MCP. El objetivo declarado es sencillo: escribir un complemento una sola vez y ejecutarlo en cualquier cliente compatible.

Hasta ahora existían dos formas habituales de dotar a un agente de programación de nuevas capacidades. Una habilidad es un conjunto de instrucciones en Markdown que el agente lee cuando las necesita. Un servidor MCP es un proceso separado que conecta al agente con herramientas externas, APIs o bases de datos. El contenido de ambos ya era portable entre herramientas, pero cada herramienta tenía sus propias convenciones en cuanto a la estructura de carpetas, los nombres de los archivos de configuración y dónde debían ubicarse los archivos.

La versión 1.0.0 solo se ocupa del contenedor exterior. Deja intacto el interior de una habilidad y el propio protocolo MCP.

Por qué es importante

Este valor es relevante para tres grupos:

• Los autores de plugins cuentan con una única estructura de directorios que funciona en todos los clientes compatibles. Ya no es necesario mantener copias separadas para Cursor, Copilot, Codex y el resto.
• Los proveedores de herramientas disponen de ubicaciones fijas para skills/ y mcp.json, por lo que no tienen que crear su propia lógica de detección ni de análisis de configuraciones. Un proveedor aún puede añadir elementos adicionales dentro de un directorio con nombres espaciales sin afectar a otras implementaciones.
• El ecosistema más amplio se beneficia de tres decisiones de diseño: el descubrimiento a través de directorios, la ausencia de configuración adicional aparte de colocar los archivos, y los fallos que permanecen contenidos. La distribución se vuelve más sencilla, y los autores pueden concentrarse en qué crear en lugar de en qué herramientas utilizar.

Los límites son igualmente claros. La especificación estandariza el contenedor del paquete pero no dice nada sobre la seguridad de su contenido. No incluye firmas, no tiene un modelo de permisos ni mecanismos para manejar datos confidenciales. Por el momento, la ventaja radica en la eficiencia de los desarrolladores, pero no ofrece garantías de seguridad ni de confianza.

Estructura del directorio

Un plugin que cumple con los requisitos es simplemente una carpeta. En el caso de un ejemplo llamado reports-plugin, el árbol completo se ve así:

reports-plugin/
├── plugin.json                  # Required: The only entry point for the plugin
├── skills/                      # Optional: Collection of skills
│   ├── summarize/               # One individual skill
│   │   ├── SKILL.md             #   Required: Skill definition file
│   │   ├── scripts/             #   Optional: Scripts used by the skill
│   │   │   └── analyze.sh
│   │   └── references/          #   Optional: Reference documentation for the skill
│   │       └── checklist.md
│   ├── deploy/                  # A second skill
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   │   └── rollback.sh
│   │   └── references/
│   │       └── runbook.md
│   └── code-review/             # A third skill
│       └── SKILL.md
├── mcp.json                     # Optional: MCP server configuration
├── com.cursor.tools/            # Optional: Cursor-specific extensions, other clients skip automatically
│   └── hooks/
│       └── hooks.json
├── LICENSE
└── CHANGELOG.md

Los clientes buscan en exactamente tres lugares. plugin.json marca la carpeta como un plugin válido. Cada subcarpeta de primer nivel de skills/ que contenga un SKILL.md se considera una habilidad. Además, mcp.json se lee como la configuración del servidor MCP. Las carpetas nombradas al estilo de dominio inverso, como com.cursor.tools/, solo son leídas por el cliente al que pertenecen, en este caso Cursor. Otros clientes, como ChatGPT y Codex, simplemente las ignoran.

El manifiesto plugin.json

plugin.json es el único archivo obligatorio, y uno mínimo es muy pequeño:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "hello-plugin"
}

El esquema es cerrado, con diez campos de nivel superior permitidos: $schema, name, version, description, author, homepage, repository, license, keywords y extensions. Un campo desconocido se reporta e ignora, y el complemento sigue cargándose. Un name incorrecto es otro asunto: si falta, tiene el tipo equivocado o contiene caracteres ilegales (letras mayúsculas, guiones dobles, cadena vacía), todo el complemento es rechazado.

Las reglas para name: de 1 a 64 caracteres, compuesto por letras minúsculas, dígitos, guiones y puntos. Debe comenzar y terminar con una letra o dígito, y está prohibido tener dos guiones o dos puntos seguidos.

Cómo se encuentran los componentes

El descubrimiento se basa exclusivamente en directorios. plugin.json no puede mover componentes a otro lugar ni incrustar su configuración directamente. Solo existen tres tipos de ubicaciones:

• skills/: cualquier subcarpeta de primer nivel que contenga un SKILL.md es una habilidad. Las carpetas más profundas no se escanean.
• mcp.json: la configuración del servidor MCP.
• Carpetas de extensiones del cliente: nombradas en formato de dominio invertido, como com.example.client/, e ignoradas por todos los demás clientes.

La falta de un componente no constituye un error. Si skills no es un directorio, o mcp.json no es un archivo regular, ese tipo de componente se marca como inválido, mientras que los demás se cargan como de costumbre.

Configuración MCP

mcp.json necesita dos campos de nivel superior: $schema y mcpServers. La versión de $schema debe ser igual a la declarada en plugin.json; de lo contrario, toda la configuración MCP es rechazada.

Se definen tres métodos de transporte:

• stdio ejecuta un proceso hijo local. command es un token ejecutable, ya sea un nombre simple resuelto a través de la ruta PATH del sistema o una ruta relativa al plugin que comienza con ./. Los campos opcionales son args, env y cwd, siendo cwd su valor por defecto la raíz del plugin.
• streamable-http es el estándar actual de MCP Streamable HTTP.
• sse es el método de transporte HTTP+SSE más antiguo, proveniente de la especificación MCP del 2024-11-05, y se mantiene para compatibilidad con versiones anteriores.

Los clientes deben implementar al menos stdio o streamable-http, y es mejor usar ambos. sse es opcional.

Variables de entorno y datos persistentes

Cada vez que un cliente inicia un proceso stdio, debe establecer dos variables. PLUGIN_ROOT contiene la ruta absoluta de la carpeta raíz del plugin. PLUGIN_DATA apunta a un directorio de datos persistentes proporcionado por el cliente, que permanece intacto tras las actualizaciones del plugin y se elimina al desinstalarlo.

Tanto ${PLUGIN_ROOT} como ${PLUGIN_DATA} pueden aparecer en args, en los valores de env y en cwd. La sustitución se realiza en una sola pasada de texto plano. No se admiten otros marcadores de posición ni expansión de variables al estilo shell.

Los fallos permanecen locales

La especificación aplica una regla de “el fallo parcial no debe propagarse” en varios niveles:

• Si un servidor MCP no puede iniciarse, eso no afecta a los demás servidores ni a las habilidades.
• Se omite una habilidad con formato incorrecto mientras el resto se carga normalmente.
• Se omite una entrada MCP que utiliza un transporte que el cliente no admite.
• Si mcp.json es completamente inválido, solo se desactivan los componentes MCP, pero las habilidades siguen cargándose.

Lo que no incluye la especificación

Faltan en la versión 1: cómo se instalan los complementos, el control de permisos en tiempo de ejecución, la autenticación de los autores y el almacenamiento seguro de secretos o claves API. El texto indica claramente que los valores de encabezados y los valores del entorno son datos del paquete visibles y no constituyen una forma portátil de mantener la confidencialidad de la información. Tampoco existe configuración OAuth ni campo de referencia de credenciales portátil, por lo que la autorización debe gestionarse por cada cliente de manera independiente.

Quiénes están incluidos y quiénes no

El soporte de lanzamiento abarca seis clientes: Kiro, VS Code, Cursor, GitHub Copilot, Codex y ChatGPT. Google se unió como mantenedor el mismo día, y su Agents CLI es uno de los primeros productos en adoptar este formato. AWS también es un colaborador en este proyecto.

Anthropic creó tanto el formato de habilidades como MCP, y Claude Code ha utilizado un empaquetado de complementos casi idéntico desde 2025. Aun así, Anthropic no formó parte del grupo de trabajo, y Claude Code no está en la lista inicial de soporte.

Un ejemplo de extremo a extremo con la CLI de Google’s Agents

Agents CLI es uno de los primeros en adoptarlo. Una vez instalado, proporciona a un agente de programación siete habilidades que abarcan patrones ADK, estructuración de proyectos, evaluación, despliegue y capacidad de observación.

Considere crear un asistente de conocimiento de tipo RAG. Un desarrollador describe el objetivo en lenguaje sencillo, y el agente procede por su cuenta:

1. Establece la estructura del proyecto a partir de la plantilla ADK agentic_rag, utilizando Vector Search como almacén de datos.
2. Se da cuenta de que la plantilla carece de soporte para citaciones, reescribe las instrucciones del agente para exigir citaciones incrustadas y cambia al recuperador para que devuelva IDs de fuentes.
3. Configura el almacén de datos, carga 12 documentos de referencia en Python como corpus y ejecuta una prueba de funcionamiento básica.

Se realiza una evaluación antes del despliegue: 20 casos de prueba en cuatro grupos, 6 para la precisión en la recuperación, 5 para rechazar solicitudes cuando falta contexto, 5 para el razonamiento multi-paso y 4 para la precisión en las citaciones.

La evaluación reveló un caso límite que causaba alucinaciones. Ante preguntas fuera del corpus, el agente a veces respondía con conocimientos generales en lugar de admitir que no lo sabía. La causa era una sola oración en el prompt del sistema que indicaba que las preguntas simples con respuesta conocida podían resolverse directamente sin herramientas. Eliminar esa oración solucionó el problema por completo.

La implementación en Google Cloud tarda de dos a tres minutos, con Cloud Trace activado por defecto. Después de registrarse en Gemini Enterprise, todos en la organización pueden encontrar y utilizar el agente.