Especificación de Agent Plugins

Versión de la especificación: 1.0.0

Estado: borrador de trabajo

Este documento define la especificación canónica Agent Plugins v1.0.0 para agrupar componentes reutilizables que amplían agentes de IA en plugins distribuibles.

Índice

1. Estado y versión
2. Lenguaje de conformidad
3. Terminología
4. Modelo de paquete de plugin
5. Manifiesto
6. Descubrimiento de componentes
7. Tipos de componentes
8. Extensiones de cliente
9. Variables de entorno y expansión de marcadores de posición
10. Versionado
11. Conformidad del cliente

Material no normativo

• Apéndice A: Lista de conformidad
• Decisiones de diseño

1. Estado y versión

Esta especificación define la versión 1.0.0 del formato Agent Plugins.

Los clientes y paquetes de plugins que declaren conformidad con Agent Plugins v1 MUST implementar o seguir los requisitos de este documento.

1.1 Modelo de gobernanza

La gobernanza del proyecto Agent Plugins se define por separado del formato de paquete portátil en la Carta técnica.

2. Lenguaje de conformidad

En las secciones normativas de este documento, las palabras clave MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY y OPTIONAL se interpretan según RFC 2119 y RFC 8174 únicamente cuando aparecen por completo en mayúsculas.

El Apéndice A y las Decisiones de diseño no son normativos. Todas las demás secciones son normativas.

3. Terminología

4. Modelo de paquete de plugin

4.1 Requisitos generales

1. Un plugin es un directorio con una única ubicación del sistema de archivos como raíz.
2. Un plugin MUST incluir un manifiesto en plugin.json, dentro de la raíz del plugin.
3. Cuando un cliente descubra, lea o ejecute un archivo o directorio aportado por el paquete, la ruta resuelta por el sistema de archivos MUST permanecer dentro de la raíz del plugin resuelta por el sistema de archivos. Los enlaces simbólicos, puntos de unión, puntos de reanálisis y mecanismos equivalentes MAY resolverse a destinos dentro de la raíz del plugin, pero los clientes MUST rechazar las rutas del paquete que se resuelvan fuera de ella.
4. Un campo de configuración que esta especificación defina como ruta relativa al plugin MUST empezar por ./, resolverse con respecto a la raíz del plugin y permanecer dentro de la raíz resuelta por el sistema de archivos después de su resolución.
5. Los valores de configuración que no estén definidos como rutas, incluidos los argumentos de comandos y los valores de variables de entorno, son cadenas opacas. Los clientes MUST NOT interpretarlos como rutas del paquete para aplicar esta sección.

Ejemplo: rutas relativas válidas y no válidas

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "server": {
      "type": "stdio",
      "command": "./bin/server",
      "cwd": "./data"
    }
  }
}

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "server": {
      "type": "stdio",
      "command": "../bin/server",
      "cwd": "data"
    }
  }
}

El primer ejemplo es válido: ambas rutas empiezan por ./ y permanecen dentro de la raíz del plugin. El segundo no es válido: ../bin/server escapa de la raíz y data no es una ruta relativa al plugin.

Estas reglas de contención regulan el acceso a los archivos proporcionados por el paquete. No aíslan en un sandbox un subproceso del plugin ni restringen las rutas proporcionadas en tiempo de ejecución. §7.2.1 define por separado la contención para un directorio de trabajo configurado cuya raíz es el directorio PLUGIN_DATA administrado por el cliente.

Cuando una ruta incumpla un requisito de contención, el cliente MUST aplicar el límite de fallo pertinente más específico:

1. Si plugin.json no se resuelve dentro de la raíz del plugin, el cliente MUST rechazar el plugin.
2. Si una ubicación fija de componente no se resuelve dentro de la raíz del plugin, el cliente MUST considerar que ese tipo de componente no es válido según §6.2.
3. Si un SKILL.md descubierto no se resuelve dentro de la raíz del plugin, el cliente MUST omitir esa Agent Skill según §7.1.
4. Si el command o cwd de un servidor MCP incumple la contención, el cliente MUST considerar que esa entrada de servidor no es válida según §7.2.2.
5. Para cualquier otra ruta del paquete que se resuelva fuera de la raíz, el cliente MUST denegar el acceso a la ruta.

4.2 Estructura estándar

Un plugin que contenga Agent Skills, servidores MCP y una extensión de cliente puede tener esta estructura:

my-plugin/
├── plugin.json
├── skills/
│   └── summarize/
│       ├── SKILL.md
│       ├── scripts/
│       │   └── analyze.sh
│       └── references/
│           └── checklist.md
├── mcp.json
├── com.example.client/
│   └── hooks/
├── LICENSE
└── CHANGELOG.md

Consulta también: §5 Manifiesto para las reglas del manifiesto, §6 Descubrimiento de componentes para las ubicaciones fijas y el comportamiento cuando faltan, y §8 Extensiones de cliente para las convenciones de extensiones.

5. Manifiesto

5.1 Ubicación y carga

Los clientes MUST buscar un manifiesto en plugin.json, dentro de la raíz del plugin.

La especificación principal de Agent Plugins define exactamente un manifiesto portátil por plugin. Ningún otro archivo puede sustituir, complementar ni reemplazar los campos principales del plugin.json raíz.

Un cliente carga y valida el plugin.json raíz antes de descubrir componentes o aplicar comportamiento específico del cliente.

Consulta también: §11 Conformidad del cliente para los requisitos de compatibilidad con plugin.json.

5.2 Objeto del manifiesto

El manifiesto MUST ser JSON y MUST contener un objeto de nivel superior. Su schema es cerrado: los únicos campos permitidos en el nivel superior son $schema, name, version, description, author, homepage, repository, license, keywords y extensions.

Si plugin.json contiene cualquier otro campo de nivel superior, no cumple el schema. Los clientes MUST informar de cada campo desconocido y omitirlo, y MUST continuar cargando el plugin si el resto del manifiesto satisface esta sección. Los clientes MUST NOT asignar semántica a los campos desconocidos. Los datos de manifiesto específicos del cliente deben incluirse bajo extensions, como se define en §8.

Un campo extensions que no sea un objeto se trata según §8.1. Cualquier otro campo permitido MUST cumplir el tipo y las restricciones que se definen a continuación. Toda infracción del schema que no sea un campo desconocido de nivel superior o un campo extensions que no sea un objeto es fatal: el cliente MUST rechazar el plugin y MUST NOT descubrir ni ejecutar ninguno de sus componentes.

El schema oficial legible por máquinas es schemas/1.0.0/plugin.schema.json. Si el texto de la especificación entra en conflicto con el schema legible por máquinas, prevalece el texto de la especificación.

El campo obligatorio $schema identifica la versión de la especificación Agent Plugins a la que se dirige el plugin y su schema de manifiesto correspondiente. Para Agent Plugins 1.0.0, su valor MUST ser el identificador canónico https://agent-plugins.org/schemas/1.0.0/plugin.schema.json.

Los clientes MUST usar un valor $schema reconocido para seleccionar reglas de validación e interpretación del manifiesto disponibles localmente. Un cliente MAY asignar varios identificadores canónicos a la misma implementación solo cuando reconozca de forma explícita que esas versiones de Agent Plugins son compatibles. Los clientes MUST NOT descargar un schema mientras cargan un plugin. Si un cliente no admite la versión declarada de Agent Plugins ni una versión que haya reconocido expresamente como compatible, MUST rechazar el plugin y SHOULD informar de la versión no admitida.

Ejemplo: manifiesto mínimo

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

Ejemplo: manifiesto completo

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/example/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "extensions": {
    "com.example.client": {
      "setting": true
    }
  }
}

5.3 Campos obligatorios

Si falta un campo obligatorio, tiene un tipo incorrecto, está vacío o incumple sus requisitos de cualquier otro modo, el manifiesto no es válido. Los clientes MUST rechazar el plugin y MUST NOT descubrir ni ejecutar ninguno de sus componentes. Los clientes SHOULD informar de cuál es el campo obligatorio no válido.

5.4 Campos de metadatos

El objeto author MAY contener únicamente los campos name, email y url, cada uno con un valor de cadena. Cualquier otro campo o tipo de valor hace que el manifiesto no sea válido.

Salvo que esta especificación indique una restricción explícita, los campos de metadatos solo se validan por sus tipos JSON. Los clientes MUST NOT rechazar un manifiesto únicamente porque version no use un versionado semántico válido; homepage, repository o author.url no sea una URL reconocida; author.email no sea una dirección de correo reconocida; o license no sea un identificador SPDX.

5.5 Restricciones del nombre del plugin

El valor name del manifiesto MUST satisfacer todas las condiciones siguientes:

Se permiten puntos en los nombres de plugins.

Nombres válidos: my-plugin, acme.tools, lint3r, a

Nombres no válidos: My-Plugin (mayúsculas), -start (guion inicial), has--double (guiones consecutivos), too.many..dots (puntos consecutivos), `` (vacío)

5.6 Campo extensions

El campo opcional extensions contiene datos de manifiesto específicos del cliente organizados por espacio de nombres de extensión. Consulta §8 para las reglas de procesamiento.

6. Descubrimiento de componentes

Consulta también: §4 Modelo de paquete de plugin para las convenciones de estructura de directorios.

6.1 Ubicaciones fijas

Los clientes MUST descubrir cada tipo de componente compatible en su ubicación fija. plugin.json no puede reemplazar estas ubicaciones ni contener configuración de componentes en línea.

Ubicaciones de componentes:

Ejemplo: un plugin reports-plugin con esta estructura:

reports-plugin/
├── plugin.json
├── skills/summarize/SKILL.md
└── mcp.json

El cliente descubre la Agent Skill summarize en skills/ y los servidores MCP en mcp.json.

6.2 Ubicaciones ausentes

Si falta una ubicación fija de componente, el cliente MUST NOT considerarlo un error.

Si una ubicación fija está presente pero no se resuelve al tipo esperado del sistema de archivos, por ejemplo, skills no se resuelve a un directorio o mcp.json no se resuelve a un archivo normal, el cliente MUST considerar que ese tipo de componente no es válido y continuar cargando otros tipos compatibles.

7. Tipos de componentes

Consulta también: §6 Descubrimiento de componentes para saber cómo se localizan los archivos de componentes.

Agent Plugins v1 define exactamente dos tipos de componentes: Agent Skills y servidores MCP. Los demás tipos quedan fuera del formato v1 y no afectan a la conformidad.

Los clientes MUST ignorar los tipos de componentes que no admitan.

7.1 Agent Skills

Las Agent Skills MUST cumplir la especificación de Agent Skills. Esa especificación es la fuente de referencia para el formato SKILL.md, los campos de frontmatter y la estructura de directorios (scripts/, references/, assets/).

Esta especificación define cómo se descubren las Agent Skills dentro de un plugin, no el formato de la Agent Skill ni cómo los clientes la exponen a usuarios o modelos.

La ubicación fija de descubrimiento es skills/. Cada directorio secundario directo que contenga una ruta llamada exactamente SKILL.md que se resuelva a un archivo normal se considera una Agent Skill. Los clientes MUST NOT buscar otras Agent Skills de forma recursiva en descendientes más profundos.

Si una Agent Skill descubierta no cumple la especificación de Agent Skills, el cliente MUST omitirla y continuar cargando otras Agent Skills y tipos de componentes. El cliente SHOULD informar de la Agent Skill no válida.

Ejemplo: directorio de Agent Skill llamado deploy dentro de skills/:

skills/
└── deploy/
    ├── SKILL.md          # name: deploy
    ├── scripts/
    │   └── rollback.sh
    └── references/
        └── runbook.md

7.2 Servidores MCP

La especificación de Model Context Protocol define el comportamiento de MCP en el protocolo y la semántica de su ciclo de vida. Agent Plugins define el formato de configuración mcp.json para localizar y conectar servidores MCP en un plugin. Los clientes asignan este formato portátil a su configuración nativa; sus nombres de campo y valores no tienen que coincidir con los del formato nativo del cliente.

7.2.1 Descubrimiento y configuración

La ruta de configuración MCP es mcp.json en la raíz del plugin. La configuración MCP MUST NOT declararse en línea en plugin.json ni cargarse desde ninguna otra ruta principal.

mcp.json MUST ser un objeto JSON que contenga los campos obligatorios $schema y mcpServers, sin ningún otro campo de nivel superior. mcpServers MUST ser un objeto cuyos nombres de miembro identifiquen servidores y cuyos valores de miembro sean objetos de configuración de servidores. Un objeto mcpServers vacío es válido.

El schema oficial legible por máquinas es schemas/1.0.0/mcp.schema.json. Si el texto de la especificación entra en conflicto con el schema legible por máquinas, prevalece el texto de la especificación. El schema expone #/$defs/server para que los clientes puedan validar cada servidor de forma independiente y conservar los límites de fallo de §7.2.2.

El campo obligatorio $schema identifica la versión de la especificación Agent Plugins a la que se dirige la configuración MCP y su schema MCP correspondiente. Para Agent Plugins 1.0.0, su valor MUST ser el identificador canónico https://agent-plugins.org/schemas/1.0.0/mcp.schema.json.

Los clientes MUST usar un valor $schema reconocido para seleccionar reglas de validación e interpretación de la configuración MCP disponibles localmente. Un cliente MAY asignar varios identificadores canónicos a la misma implementación solo cuando reconozca de forma explícita que esas versiones de Agent Plugins son compatibles. Los clientes MUST NOT descargar un schema mientras cargan un plugin.

Cada configuración de servidor MUST contener un campo type y coincidir exactamente con una de las variantes cerradas siguientes. Un campo desconocido, un valor type desconocido o un campo perteneciente a otra variante hace que esa entrada de servidor no sea válida.

stdio

El campo command MUST contener un solo token de ejecutable, no una cadena de comando de shell. MUST ser un nombre de ejecutable simple o una ruta relativa al plugin que empiece por ./. Los clientes MUST resolver los nombres simples con las reglas de búsqueda de ejecutables de la plataforma y MUST resolver las rutas relativas con respecto a la raíz del plugin. Los clientes MUST NOT expandir marcadores de posición en command.

El cliente define si un valor de entorno PATH configurado participa en la resolución de un command simple. Los plugins que declaren conformidad MUST NOT depender de ese comportamiento. Un plugin que incluya un ejecutable en el paquete MUST usar un command relativo al plugin.

Los clientes MAY usar un intérprete de comandos específico de la plataforma cuando sea necesario para iniciar el ejecutable resuelto, como un script .bat o .cmd en Windows, pero MUST conservar command como un token y pasar args por separado.

Cuando se omita cwd, los clientes MUST usar la raíz del plugin como directorio de trabajo del subproceso. Si está presente, cwd MUST tener una de estas formas:

1. Una ruta relativa al plugin que empiece por ./.
2. Exactamente ${PLUGIN_ROOT} o una ruta que empiece por ${PLUGIN_ROOT}/.
3. Exactamente ${PLUGIN_DATA} o una ruta que empiece por ${PLUGIN_DATA}/.

Los clientes MUST expandir los marcadores de posición antes de resolver cwd. Un valor relativo al plugin o con raíz en ${PLUGIN_ROOT} MUST permanecer dentro de la raíz del plugin resuelta por el sistema de archivos. Un valor con raíz en ${PLUGIN_DATA} MUST permanecer dentro del directorio de datos del plugin resuelto por el sistema de archivos. Cualquier otra forma o cualquier escape posterior a la resolución hace que esa entrada de servidor no sea válida según §7.2.2.

Los campos args, env y cwd de una configuración de servidor stdio MUST admitir la expansión de ${PLUGIN_ROOT} y ${PLUGIN_DATA}.

Streamable HTTP y el antiguo HTTP+SSE

streamable-http selecciona el transporte MCP Streamable HTTP actual. sse selecciona el transporte HTTP+SSE obsoleto definido por la especificación MCP 2024-11-05; no se refiere a respuestas ni flujos SSE usados dentro de Streamable HTTP.

El valor url MUST ser una URL HTTP o HTTPS absoluta y MUST NOT contener información de usuario ni un fragmento. Los extremos que no sean de bucle invertido MUST usar HTTPS. Se MAY usar HTTP cuando el host de la URL sea exactamente localhost o un literal IP de un intervalo de bucle invertido.

Los nombres y valores de encabezado MUST ser campos de encabezado HTTP válidos. Los nombres no distinguen entre mayúsculas y minúsculas; una entrada que contenga el mismo nombre más de una vez con distintas mayúsculas y minúsculas no es válida. Los clientes MUST NOT expandir marcadores de posición ni variables de entorno en url, los nombres de encabezado o sus valores.

Los valores de encabezado son datos visibles del paquete, no un mecanismo portátil de secretos. Los plugins MUST NOT incluir credenciales ni otros secretos en headers. Los encabezados generados por el cliente para implementar HTTP, MCP o autorización tienen prioridad sobre los encabezados configurados con el mismo nombre sin distinguir mayúsculas y minúsculas. Un cliente MUST NOT reenviar encabezados configurados a un origen distinto mediante una redirección o un evento de extremo SSE antiguo sin la autorización explícita del usuario.

Agent Plugins v1 no define configuración OAuth ni campos portátiles de referencia de credenciales. El descubrimiento de autorización, la interacción con el usuario y el almacenamiento de credenciales son responsabilidad del cliente. Un fallo de autorización es un fallo de conexión de ese servidor, no una configuración de plugin no válida.

Compatibilidad con transportes

Un cliente compatible con servidores MCP de Agent Plugins MUST admitir al menos uno de estos transportes: stdio o streamable-http. Además, SHOULD admitir ambos. La compatibilidad con sse es OPTIONAL. Un cliente MUST usar el transporte declarado por type para su primer intento de conexión. Agent Plugins no define un comportamiento alternativo si ese intento falla.

Ejemplo: mcp.json

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "local-validator": {
      "type": "stdio",
      "command": "./bin/validator",
      "args": ["--data", "${PLUGIN_DATA}/validator"],
      "env": {
        "CONFIG": "${PLUGIN_ROOT}/config.json"
      },
      "cwd": "${PLUGIN_ROOT}"
    },
    "deployment-api": {
      "type": "streamable-http",
      "url": "https://deploy.example.com/mcp",
      "headers": {
        "X-Tenant": "public-tenant"
      }
    },
    "legacy-events": {
      "type": "sse",
      "url": "https://legacy.example.com/sse"
    }
  }
}

7.2.2 Reglas de carga

1. Los clientes compatibles con servidores MCP MUST cargar la configuración únicamente desde mcp.json en la raíz del plugin.
2. Si mcp.json no es JSON válido, se dirige a una versión de Agent Plugins para la que el cliente no admite ninguna versión compatible ni reconoce una expresamente, se dirige a una versión de Agent Plugins distinta de la de plugin.json, o incumple los demás requisitos de nivel superior de §7.2.1, el cliente MUST desactivar MCP para ese plugin y continuar cargando otros tipos de componentes. El cliente SHOULD informar de la configuración no válida, no admitida o incompatible.
3. Si una entrada de servidor individual no satisface los requisitos de §7.2.1, el cliente MUST omitir ese servidor y continuar cargando otros servidores y tipos de componentes. El cliente SHOULD informar de la entrada no válida.
4. Si el cliente no admite el transporte declarado por una entrada de servidor que sea válida en los demás aspectos, MUST omitir ese servidor y continuar cargando otros servidores y tipos de componentes. El cliente SHOULD informar del transporte no admitido.
5. Si un servidor no puede iniciarse, conectarse, autenticarse o completar el protocolo de enlace MCP, el cliente MUST continuar cargando otros servidores y tipos de componentes. El cliente SHOULD informar del fallo de conexión.

8. Extensiones de cliente

Los datos de manifiesto específicos del cliente MUST representarse bajo un espacio de nombres de dominio inverso en extensions. Los archivos específicos del cliente MUST representarse bajo un directorio de nivel superior con el nombre de ese espacio. Un cliente MAY usar cualquiera de las dos representaciones o ambas.

Un cliente SHOULD basar su espacio de nombres en un dominio que controle y SHOULD mantenerlo estable. Por ejemplo, un cliente que controle example.com podría usar com.example.client.

Agent Plugins no asigna semántica portátil de descubrimiento, validación, carga ni fallos a los datos o archivos de extensiones de cliente. Cada cliente define el contenido y el comportamiento de su espacio de nombres, incluida la relación entre sus datos de manifiesto y el contenido del directorio.

8.1 Datos de extensión del manifiesto

El campo opcional extensions de plugin.json MUST ser un objeto cuyos nombres de miembro sean espacios de nombres de extensión de cliente y cuyos valores de miembro sean objetos.

Ejemplo:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "example-plugin",
  "extensions": {
    "com.example.client": {
      "setting": true
    }
  }
}

Si extensions no es un objeto, el cliente MUST informar del campo, omitirlo y continuar cargando componentes. Un cliente MUST ignorar las entradas de manifiesto para espacios de nombres que no implemente sin validar el contenido de sus valores. Ese cliente define la validación y el tratamiento de fallos dentro de un espacio de nombres implementado.

8.2 Directorios de extensión

El directorio de extensión de un espacio de nombres es el directorio de nivel superior que lleva su nombre. Por ejemplo, los archivos de com.example.client se guardan en com.example.client/.

Ejemplo: extensión de cliente formada solo por archivos

my-plugin/
├── plugin.json
├── skills/
│   └── summarize/
│       └── SKILL.md
└── com.example.client/
    └── hooks/
        └── hooks.json

Un cliente que implemente comportamiento basado en archivos para un espacio de nombres MUST buscarlo en el directorio de nivel superior correspondiente.

9. Variables de entorno y expansión de marcadores de posición

Consulta también: §7.2 Servidores MCP para los campos donde se aplica la expansión de variables del plugin, y §4.1 Requisitos generales para las reglas de seguridad de rutas.

9.1 Entorno de subprocesos

Los clientes que inicien subprocesos de plugins, es decir, servidores MCP stdio, MUST proporcionar PLUGIN_ROOT y PLUGIN_DATA en el entorno de cada subproceso. PLUGIN_ROOT es la ruta absoluta a la raíz del plugin resuelta por el sistema de archivos. PLUGIN_DATA es la ruta absoluta a un directorio de datos persistente, administrado por el cliente y dedicado a esa instancia instalada del plugin.

El cliente elige la ubicación de PLUGIN_DATA. MUST crear el directorio antes de iniciar un subproceso del plugin, MUST permitir que ese subproceso escriba en él y MUST conservar su contenido al actualizar el plugin. El cliente MAY eliminar el directorio cuando se desinstale el plugin.

Usa PLUGIN_DATA para dependencias instaladas (node_modules, entornos virtuales), código generado, cachés y otro estado del plugin que deba conservarse al actualizar. Usa PLUGIN_ROOT para hacer referencia a scripts, binarios y archivos de configuración incluidos con el plugin.

El cliente elige el entorno base del subproceso y MAY heredar, omitir o depurar las variables del entorno general. Después de expandir los marcadores de posición, las entradas del objeto env de un servidor stdio MUST superponerse al entorno base y sustituir las entradas con el mismo nombre según la semántica de nombres de entorno de la plataforma. A continuación, el cliente MUST establecer PLUGIN_ROOT y PLUGIN_DATA en los valores definidos antes y sustituir cualquier entrada con un nombre equivalente según esa semántica de la plataforma.

Salvo para la búsqueda de ejecutables de la plataforma usada para resolver un command simple, los plugins que declaren conformidad MUST NOT depender de una variable del entorno base, a menos que esta especificación exija esa variable o la configuración del servidor la proporcione expresamente.

Ejemplo: un cliente que carga el plugin devtools desde /home/alex/.agents/plugins/devtools establece:

PLUGIN_ROOT=/home/alex/.agents/plugins/devtools
PLUGIN_DATA=/home/alex/.agents/plugins/data/devtools

9.2 Expansión de marcadores de posición

Los clientes que inicien subprocesos de plugins MUST expandir ${PLUGIN_ROOT} y ${PLUGIN_DATA} en los campos de configuración compatibles. La expansión es una sustitución textual única y no recursiva de cada aparición exacta de ambos marcadores. El texto introducido por una sustitución MUST NOT volver a examinarse en busca de marcadores de posición.

La expansión se aplica a todos los elementos de cadena de args, todos los valores de cadena de env y la cadena cwd. No se aplica a las claves de env, command ni a las ubicaciones fijas de componentes.

El texto que parezca un marcador de posición no reconocido MUST conservarse como literal. Los clientes MUST NOT realizar ninguna otra expansión de marcadores de posición ni variables de entorno.

Los valores env configurados son datos visibles del paquete, no un mecanismo portátil de secretos. Los plugins MUST NOT incluir credenciales ni otros secretos en env.

El objeto env de un servidor MCP MUST NOT contener entradas llamadas PLUGIN_ROOT o PLUGIN_DATA. Una entrada de este tipo hace que la configuración de ese servidor no sea válida según §7.2.2. Los clientes MUST proporcionar ellos mismos las variables de entorno reservadas.

Ejemplo: expansión de variables del plugin en MCP

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["--config", "${PLUGIN_ROOT}/config/db.json"],
      "cwd": "${PLUGIN_ROOT}",
      "env": {
        "DATA_DIR": "${PLUGIN_DATA}/database"
      }
    }
  }
}

10. Versionado

10.1 Versiones de la especificación y los schemas

La versión de §1 identifica la publicación completa de la especificación Agent Plugins, incluidos su texto normativo, el schema del manifiesto y el schema de configuración MCP. Cada publicación de la especificación MUST publicar ambos schemas con la misma versión que la especificación, aunque las reglas de validación de un schema no hayan cambiado desde la publicación anterior.

El valor $schema obligatorio de plugin.json declara la versión de Agent Plugins a la que se dirige el paquete. Cuando existe mcp.json, la versión de su valor $schema MUST coincidir con la versión declarada por plugin.json. Si no coinciden, la configuración MCP no es válida según §7.2.2, pero los demás tipos de componentes conservan su validez.

Un cambio en cualquiera de los schemas exige una nueva publicación de la especificación. Los identificadores de schema canónicos publicados MUST NOT reasignarse a un contenido de schema distinto. Los plugins existentes MAY seguir dirigidos a una versión anterior de Agent Plugins; los clientes determinan la compatibilidad mediante los identificadores canónicos declarados y cualquier asignación de compatibilidad explícita.

10.2 Versiones de plugins

Los plugins SHOULD usar el versionado semántico para version.

Los clientes MAY usar version para determinar si hay actualizaciones disponibles y si las cachés han quedado obsoletas.

11. Conformidad del cliente

11.1 Requisitos mínimos del cliente

Un cliente conforme MUST satisfacer todos los requisitos aplicables de las secciones 1 a 10. Como mínimo:

1. Puede cargar un plugin desde una ruta de directorio.
2. Selecciona un schema de manifiesto disponible localmente a partir de $schema y después analiza y valida el schema cerrado de plugin.json con las excepciones no fatales de §5.2 y §8.1.
3. Ignora los miembros no implementados de extensions sin validar el contenido de sus valores.
4. Descubre los componentes en la ubicación fija de cada tipo compatible.
5. Si admite servidores MCP, selecciona un schema de configuración MCP disponible localmente a partir de $schema y admite al menos una de las variantes stdio o streamable-http de mcp.json.
6. Si el cliente inicia subprocesos de plugins, es decir, servidores MCP stdio, proporciona PLUGIN_ROOT y PLUGIN_DATA, y expande ambas variables en los valores de configuración de ejecución (args, env, cwd).
7. Para los servidores MCP stdio, resuelve command como un único token de ejecutable y usa la raíz del plugin como directorio de trabajo predeterminado del subproceso.
8. Admite al menos un tipo de componente (Agent Skills o servidores MCP).

11.2 Adopción gradual

No se exige que un cliente admita todos los tipos de componentes. Por ejemplo, un cliente que solo admita Agent Skills puede ser conforme sin admitir servidores MCP, siempre que satisfaga todos los requisitos aplicables.

11.3 Componentes no admitidos y fallos

1. Los clientes MUST ignorar los tipos de componentes no admitidos.
2. Un campo desconocido de nivel superior o un campo extensions que no sea un objeto no es fatal según §5.2 y §8.1. Cualquier otra infracción del schema de plugin.json es fatal para el plugin: el cliente MUST rechazarlo y MUST NOT descubrir ni ejecutar ninguno de sus componentes.
3. Un fallo aislado en un tipo, entrada o proceso de componente MUST NOT impedir que el cliente cargue componentes que sean válidos de forma independiente. Los clientes MUST aplicar el comportamiento ante fallos definido para ese componente en §6 y §7.
4. Los clientes SHOULD informar de configuraciones no válidas y fallos de componentes. Los clientes MAY informar de plugins parcialmente no admitidos, pero la falta de compatibilidad con un tipo de componente, transporte MCP o extensión de cliente no constituye por sí misma un error.

Apéndice A: Lista de conformidad

Esta lista se ofrece únicamente como ayuda. Si entra en conflicto con el texto anterior, prevalece la especificación.

Cargador de plugins

• Analizar y validar plugin.json (§5.1, §5.2)
• Validar los campos obligatorios $schema y name (§5.3)
• Validar el nombre del plugin según sus restricciones (§5.5)
• Informar de los campos desconocidos de plugin.json y omitirlos (§5.2)
• Ignorar los espacios de nombres no implementados de extensions sin validar el contenido de sus valores (§8.1)
• Rechazar las rutas del paquete que se resuelvan fuera de la raíz del plugin (§4.1)
• Descubrir extensiones implementadas basadas en archivos desde sus directorios de espacio de nombres de nivel superior (§8.2)

Descubrimiento de componentes

• Examinar la ubicación fija de cada tipo de componente compatible (§6.1)
• Ignorar las ubicaciones fijas ausentes sin producir errores (§6.2)

Configuración MCP

• Seleccionar un $schema compatible y validar después el schema cerrado de mcp.json y cada variante de servidor (§7.2.1)
• Si se admite MCP, implementar al menos uno de estos transportes: stdio o Streamable HTTP (§7.2.1)
• Usar el transporte declarado por cada entrada de servidor para el primer intento de conexión (§7.2.1)
• Aplicar los requisitos de URL remotas y encabezados literales (§7.2.1)

Entorno y expansión

• Si el cliente inicia subprocesos de plugins, proporcionar PLUGIN_ROOT y un directorio PLUGIN_DATA dedicado y escribible (§9.1)
• Resolver el command del servidor MCP como un único token de ejecutable simple o relativo al plugin (§7.2.1)
• Usar la raíz del plugin como directorio de trabajo predeterminado del servidor MCP (§7.2.1)
• Validar las formas explícitas de cwd y la contención posterior a su resolución (§7.2.1)
• Superponer las entradas env configuradas a un entorno base elegido por el cliente (§9.1)
• Establecer los valores PLUGIN_ROOT y PLUGIN_DATA proporcionados por el cliente después de aplicar env, y sustituir los nombres equivalentes según la semántica de nombres de entorno de la plataforma (§9.1)
• No exigir que el PATH configurado afecte a la resolución de comandos simples (§7.2.1)
• Expandir únicamente ${PLUGIN_ROOT} y ${PLUGIN_DATA} en los campos args, env y cwd del servidor MCP (§9.2)

Resiliencia

• Ignorar los tipos de componentes no admitidos (§11.3)
• Omitir las entradas de servidor cuyo transporte declarado no sea compatible sin afectar a otros servidores ni componentes (§7.2.2)
• Continuar la carga cuando falle un componente independiente (§11.3)
• Admitir al menos un tipo de componente (§11.1)

Decisiones de diseño

Esta sección explica las razones de las principales decisiones de diseño. Solo aporta contexto; las reglas vinculantes están en las secciones normativas anteriores.

¿Por qué se usa el descubrimiento basado en directorios?

Los plugins usan directorios del sistema de archivos como unidad de paquete en lugar de formatos de archivo (.zip, .tar.gz) o paquetes descargados de un registro. Así se pueden inspeccionar con herramientas estándar (ls, cat, git), editar en su propia ubicación durante el desarrollo y usar con sistemas de control de versiones sin herramientas especiales. Las ubicaciones fijas en la raíz, como skills/ y mcp.json, eliminan la búsqueda indirecta, la prioridad entre fuentes alternativas y la configuración de manifiesto que, de otro modo, todos los clientes tendrían que implementar.

¿Por qué v1 solo incluye Agent Skills y MCP?

Agent Plugins v1 se centra en Agent Skills y MCP porque ambos cuentan con especificaciones consolidadas fuera de este proyecto y con adopción real en varios clientes. Otros tipos propuestos, como comandos, hooks, agentes, reglas y servidores LSP, todavía dependen demasiado de cada cliente para constituir un contrato portátil estable. Quedan fuera de v1 hasta que sus formatos converjan.

¿Por qué plugin.json en la raíz es la base de conformidad?

Todo cliente conforme MUST buscar plugin.json en la raíz del plugin (§5.1). Esto da a los autores un único manifiesto que funciona en todos los clientes, sin exigirles conocer rutas específicas de cada uno.

¿Por qué se usa un manifiesto portátil cerrado?

Limitar el plugin.json raíz a campos conocidos permite aplicar una validación estricta, detectar errores tipográficos y completar claves a partir del schema. Los experimentos de un cliente no pueden declarar campos arbitrarios de nivel superior; deben incluirse bajo claves de dominio inverso en extensions. Los campos desconocidos de nivel superior siguen infringiendo el schema, pero los clientes informan de ellos y los omiten en vez de rechazar un plugin válido en los demás aspectos.

¿Por qué se usan extensiones de cliente con dominio inverso?

Los identificadores de dominio inverso ofrecen una convención descentralizada para evitar colisiones sin un registro central de nombres de clientes. El mismo identificador puede usarse para datos del manifiesto y para un directorio específico del cliente, y ambas representaciones pueden existir de forma independiente. Los directorios de extensión se mantienen en el nivel superior para conservar una estructura plana basada en convenciones.

¿Por qué se define un formato explícito de configuración MCP?

Los clientes existentes usan estructuras incompatibles para la configuración MCP y deducen los transportes de distintas formas. Por eso, Agent Plugins define una unión cerrada y explícita cuyo significado no depende del formato nativo de ningún cliente. Distinguir Streamable HTTP del antiguo HTTP+SSE asigna a cada entrada un transporte inicial inequívoco. El comportamiento alternativo después de una conexión fallida queda fuera del formato portátil.

¿Por qué los clientes pueden admitir un solo transporte MCP estándar?

Stdio y Streamable HTTP responden a modelos distintos de despliegue y seguridad. Exigir que todo cliente compatible con MCP admita tanto la ejecución de procesos locales como las conexiones HTTP remotas ampliaría su implementación y la superficie de confianza sin cambiar el formato de configuración portátil. Como cada entrada de servidor declara su transporte, un cliente puede omitir las entradas no compatibles y continuar cargando servidores y componentes independientes.

¿Por qué los schemas comparten la versión de la especificación?

Los schemas de plugin.json y mcp.json usan la versión de la especificación Agent Plugins en lugar de secuencias de versión independientes. Así, los autores y clientes solo necesitan comprender una versión del formato portátil, se evitan paquetes con versiones mezcladas y $schema selecciona el contrato completo de validación e interpretación, incluidos los requisitos que JSON Schema no puede expresar. Volver a publicar un schema sin cambios con una nueva versión de la especificación supone un pequeño coste de mantenimiento, pero evita exponer tres cronologías de compatibilidad independientes.

¿Por qué se usan variables del plugin en lugar de rutas relativas en la configuración?

Los argumentos de servidores MCP suelen necesitar rutas absolutas en tiempo de ejecución. ${PLUGIN_ROOT} proporciona un punto de referencia inequívoco y resuelto por el cliente para los archivos incluidos. ${PLUGIN_DATA} identifica el estado escribible administrado por el cliente que se conserva cuando una actualización reemplaza el contenido del paquete. El campo command no usa interpolación: una ruta ./ se resuelve directamente con respecto a la raíz del plugin y un nombre simple usa las reglas de búsqueda de ejecutables de la plataforma. Tratar command como un solo token evita que los clientes tengan que analizar y escapar cadenas de comandos de shell escritas por usuarios. Los clientes difieren en el entorno heredado y en el comportamiento de PATH; por eso, Agent Plugins normaliza los valores configurados que reemplazan el entorno, pero deja al cliente la búsqueda de comandos simples. Los comandos relativos al plugin permiten ejecutar de forma determinista los archivos incluidos.

¿Por qué los fallos de componentes no son fatales?

Cuando un servidor MCP no puede iniciarse ni conectarse, el cliente continúa cargando los demás componentes del plugin (§11.3). Un plugin con Agent Skills y un servidor MCP no debe quedar completamente inutilizable porque un servidor no esté disponible. La especificación combina los fallos no fatales de componentes con requisitos de diagnóstico para que sean visibles y no pasen inadvertidos.