Agent Plugins Spec de 0 a Hero

Tienes cinco skills que funcionan, un servidor MCP configurado a mano y un equipo de ocho personas que necesita exactamente lo mismo en sus máquinas. Hasta ahora eso se resolvía copiando carpetas, pegando fragmentos de configuración en el archivo de cada cliente y esperando que nadie se equivocara de ruta. Y cuando alguien cambiaba de herramienta, había que rehacerlo entero: cada agente esperaba su propio formato.

Agent Plugins es el formato que empaqueta todo eso en una unidad que viaja.

La definición literal con la que abre el repositorio oficial:

Agent Plugins is an open, vendor-neutral standard for packaging reusable components that extend AI agents into distributable plugins. It defines a portable package format for Agent Skills and MCP servers.

Un estándar abierto y vendor-neutral para empaquetar componentes reutilizables que extienden agentes de IA en plugins distribuibles. Define un formato portable de paquete para Agent Skills y servidores MCP.

Versión cubierta: Agent Plugins Specification 1.0.0, con estado Published. Es la única versión publicada del estándar. Todo el contenido normativo del curso sale de spec/1.0.0.md —640 líneas de Markdown— y de los dos JSON Schema oficiales, plugin.schema.json y mcp.schema.json.

En la práctica, el plugin más pequeño que sirve para algo es esto:

hello-plugin/
├── plugin.json
└── skills/
    └── greet/
        └── SKILL.md

Y el manifiesto completo son dos líneas:

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

Un cliente que soporte skills carga ese plugin leyendo plugin.json y descubriendo skills/greet/SKILL.md. Cómo el cliente expone después ese skill al usuario o al modelo queda fuera del alcance de la especificación, y esa frontera —dónde termina el estándar y dónde empieza el producto— es una de las cosas que más veces vas a leer en este curso.

A quién sirve este curso

Perfil	Qué se lleva
Quien ya escribe skills	Convierte una carpeta suelta en un paquete versionado, validable y distribuible con un comando
Quien lidera un equipo técnico	Reparte skills y servidores MCP con git, versionado semántico y validación en CI, en vez de instrucciones por chat
Quien publica herramientas	Empaqueta la experiencia de su producto en un plugin que funciona en cualquier cliente conforme, sin escribir una integración por agente
Quien construye un agente	Implementa descubrimiento, validación del manifiesto, resolución de rutas y carga de componentes según el contrato normativo
Quien evalúa el estándar	Sabe exactamente qué garantiza la 1.0.0, qué dejó fuera a propósito y quién decide lo que viene

No hace falta ser experto en JSON Schema ni en MCP. El manifiesto tiene diez campos y solo uno es obligatorio; el esquema de MCP es una unión cerrada de tres variantes. Todo cabe en la cabeza.

Antes de empezar

Necesitas:

• Conocer el formato SKILL.md. Este es el requisito que más rinde. Agent Plugins no redefine qué es un skill: su §7.1 delega en la especificación de Agent Skills y solo fija dónde viven los skills dentro del paquete. Si el frontmatter de un SKILL.md todavía no te resulta obvio, lee antes el curso hermano Agent Skills de 0 a Hero —o al menos sus cuatro primeros capítulos— y vuelve aquí.
• JSON a nivel de lectura. Objetos, arrays, strings, booleanos. Nada más.
• Una terminal y git. Los capítulos de validación y distribución asumen que sabes clonar un repositorio, hacer commits y ejecutar un binario de Node o Python.
• Un editor de texto. No hay build, ni bundler, ni compilación, ni registro central al que dar de alta nada.

Ayuda tener, pero no es requisito:

• Nociones de MCP. El capítulo 5 explica lo necesario sobre transportes stdio, http y sse, pero si ya has levantado un servidor MCP rinde mucho más.
• Experiencia con JSON Schema. El capítulo 8 usa ajv-cli y check-jsonschema, e interpreta sus mensajes de error uno por uno.
• Haber montado un pipeline de CI. El mismo capítulo 8 trae un workflow de GitHub Actions completo, listo para copiar.

No necesitas: una API key, un servidor propio, un framework de agentes, ni permiso de nadie para publicar un plugin.

Cómo se lee el lenguaje normativo

La especificación usa RFC 2119. Este curso traduce siempre igual y marca el término original la primera vez que aparece en cada capítulo:

Original	Traducción	Significado
MUST	DEBE	Requisito absoluto. Incumplirlo hace que el paquete o el cliente no sea conforme.
MUST NOT	NO DEBE	Prohibición absoluta.
SHOULD	DEBERÍA	Recomendación fuerte. Se puede ignorar con razones, asumiendo el coste.
SHOULD NOT	NO DEBERÍA	Desaconsejado, no prohibido.
MAY	PUEDE	Opcional. Ni recomendado ni desaconsejado.

Y hay una segunda distinción que el curso mantiene en todos los capítulos, porque confundirla produce afirmaciones falsas sobre el estándar:

Fuente	Qué es	Ejemplos
Normativo	Obliga a paquetes y clientes conformes	spec/1.0.0.md, plugin.schema.json, mcp.schema.json
Informativo	Explica o proyecta, no obliga	README.md, FUTURE_CONSIDERATIONS.md, CONTRIBUTING.md
Comportamiento de cliente	Decisión de un producto concreto	Comandos de instalación, catálogos, UI, permisos

Cuando el curso dice “la spec exige”, es normativo. Cuando dice “este cliente hace”, es la tercera columna. La propia especificación declara explícitamente fuera de su alcance cómo un cliente expone un skill al usuario o al modelo.

Ruta de aprendizaje

flowchart TD
    A["Fundamentos<br/>Cap. 1-2"] --> B["El formato<br/>Cap. 3-5"]
    B --> C["Contrato con el cliente<br/>Cap. 6-7"]
    C --> D["Publicar<br/>Cap. 8-9"]
    D --> E["Comunidad<br/>Cap. 10"]
    A -.->|"solo instalar plugins<br/>de terceros"| D
    B -.->|"implementar un cliente<br/>conforme"| C

El bloque de fundamentos te deja con un plugin cargando. El bloque del formato recorre los tres archivos que definen el paquete. El bloque del contrato explica qué hace el cliente con ese paquete y qué significa ser conforme. El de publicar lo saca de tu máquina. El último te cuenta quién manda sobre el estándar y cómo se cambia.

Capítulos

Bloque 1 · Fundamentos

Qué problema resuelve el estándar, dónde están sus fronteras y cómo se construye el primer plugin de punta a punta.

#	Capítulo	Qué cubre
1	Qué es Agent Plugins y qué problema resuelve	La definición literal, el problema de fragmentación entre agentes, las tres piezas del ecosistema —Skills, Plugins, MCP— y su relación exacta, la terminología oficial, cómo se lee el lenguaje RFC 2119, qué define la spec y qué deja explícitamente fuera
2	Tu primer plugin paso a paso	El plugin mínimo útil del README oficial explicado línea por línea, qué hace un cliente al cargarlo, crecimiento a un segundo skill con metadatos y un servidor MCP, cómo probarlo localmente y los errores típicos de la primera vez

Si solo vas a leer dos capítulos, que sean estos: al terminar el 2 tienes un plugin propio que un cliente carga.

Bloque 2 · El formato

Los tres archivos que componen el paquete: el manifiesto, el directorio de skills y la configuración MCP. Es el bloque de referencia del curso.

#	Capítulo	Qué cubre
3	plugin.json: el manifiesto al detalle	Dónde vive y cuándo se carga, por qué el esquema es cerrado y tiene diez campos exactos, el papel real de $schema, las reglas de nomenclatura de name, los campos de metadatos, el campo extensions, la matriz de qué es fatal y qué solo se reporta, y manifiestos válidos e inválidos con la razón exacta
4	Empaquetar Agent Skills dentro de un plugin	Cómo se componen dos especificaciones distintas, la ubicación fija skills/, las tres reglas de descubrimiento, qué pasa si el directorio no existe, contención dentro del plugin root, skills no conformes que se saltan sin abortar, rutas relativas, recursos empaquetados y colisiones de nombres
5	Servidores MCP dentro de un plugin	El documento mcp.json y su ubicación fija, la unión cerrada de tres variantes de transporte, command, args, env y cwd, la expansión de PLUGIN_ROOT y PLUGIN_DATA, las fronteras de fallo, qué valida el esquema frente a qué valida el cliente y la seguridad de distribuir configuración ejecutable

El 3 es el capítulo que vas a releer más veces. El 4 y el 5 son independientes entre sí: si tu plugin no lleva servidores MCP, puedes saltarte el 5 y volver cuando lo necesites.

Bloque 3 · El contrato con el cliente

El paquete ya está bien formado. Ahora, qué hace exactamente un cliente con él y qué significa que ambos lados sean conformes.

#	Capítulo	Qué cubre
6	Descubrimiento, resolución y carga por parte del cliente	El recorrido normativo completo: localizar el manifiesto, seleccionar reglas con $schema, validar y decidir la fatalidad, descubrir componentes en ubicaciones fijas, resolución de rutas con contención en el plugin root, la escalera de fallos por límite más estrecho, el ciclo de carga entero, qué se ignora, qué se rechaza y qué queda fuera del alcance
7	Versionado, compatibilidad y conformidad	Cómo se versiona la especificación frente a cómo versionas tu plugin, qué significa exactamente 1.0.0, la lista completa de requisitos de conformidad del paquete y del cliente, y cómo usar extensiones propietarias sin romper la portabilidad

Estos dos capítulos son obligatorios si vas a implementar soporte de Agent Plugins en un agente propio: entre ambos está el contrato entero, con sus listas de conformidad.

Bloque 4 · Publicar

Sacar el plugin de tu carpeta: comprobarlo automáticamente y ponerlo en manos de otros.

#	Capítulo	Qué cubre
8	Validar un plugin: JSON Schema y automatización	Validar plugin.json y mcp.json contra los dos esquemas oficiales con ajv-cli y con check-jsonschema, qué cosas el esquema no puede validar, hook de pre-commit, workflow de GitHub Actions completo, interpretación de los errores más comunes y lista de verificación antes de publicar
9	Distribuir e instalar plugins	Que la especificación no dice nada sobre distribución y por qué eso importa, el repositorio git como unidad de distribución, qué son y qué no son los catálogos de plugins, disección del marketplace.json real de google/skills, los comandos de instalación tal como los documenta ese README y la frontera estándar-producto en una tabla

El capítulo 9 es el más “de producto” del curso: casi todo lo que cuenta es comportamiento de cliente, no norma, y lo marca en cada sección.

Bloque 5 · Comunidad

Quién gobierna el estándar, con qué reglas y cómo se propone un cambio.

#	Capítulo	Qué cubre
10	Gobernanza, hoja de ruta y cómo contribuir	Qué documento manda sobre qué, el Technical Charter y los roles y votaciones del TSC, los mantenedores actuales, el licenciamiento dual CC-BY-4.0 y Apache 2.0, las siete áreas de FUTURE_CONSIDERATIONS.md que quedaron fuera de la 1.0.0 a propósito, el proceso real de contribución y el criterio de AGENTS.md con el que se evalúa una propuesta

La trilogía de cursos

Agent Plugins define el contenedor. Por debajo hay un formato de contenido y por encima hay catálogos reales que lo publican, y cada capa tiene su propio curso. Juntos cubren el ciclo completo: escribir, empaquetar y ver cómo se hace a escala.

flowchart LR
    A["Agent Skills<br/>El formato<br/>SKILL.md"] --> B["Agent Plugins<br/>El empaquetado<br/>plugin.json y mcp.json"]
    B --> C["Google Skills<br/>El catalogo real<br/>skills y plugins publicados"]
    C -.->|"el uso real informa<br/>al estandar"| B
    A -.->|"la spec delega<br/>en el formato"| B

Agent Skills

El formato. Qué es un SKILL.md, qué campos tiene su frontmatter, cómo se escribe una description que dispare en el momento correcto, cómo se mide si el skill aporta algo y cómo se parte el contenido pesado en references/ y assets/.

Agent Plugins no redefine nada de eso: su §7.1 delega en esa especificación externa y se limita a fijar que los skills viven en skills/ y que cada subdirectorio inmediato con un SKILL.md es un skill.

Léelo antes que este curso. Un plugin sin skills útiles es un envoltorio vacío, y todo el bloque 2 de aquí da el formato por conocido.

Este curso · Agent Plugins Spec

El empaquetado. El manifiesto, las ubicaciones fijas, la configuración MCP, las variables de plugin, las reglas de carga, la conformidad de cliente y la validación automática. Todo lo que hace que un conjunto de skills viaje a otra máquina, a otro cliente o a otro equipo sin instrucciones adjuntas.

Empieza a pagar cuando dejas de ser el único que usa tus skills.

Google Skills

El catálogo real. El repositorio oficial de Google con más de cien skills en producción, su marketplace.json, sus plugins agrupados por área —Cloud, AI/ML, infraestructura, datos, publicidad— y las convenciones que aparecen cuando una organización mantiene un catálogo a escala.

Es el mejor material que existe para contrastar la teoría de estos dos cursos contra la práctica: cómo se nombra un plugin real, cómo se agrupa, qué granularidad se elige y qué aspecto tiene un catálogo mantenido de verdad. El capítulo 9 de este curso disecciona justamente ese marketplace.json.

Orden recomendado

Orden	Curso	Por qué ahí
1º	Agent Skills	Define el formato que este curso empaqueta y da por conocido
2º	Agent Plugins Spec (este)	El contenedor portable: manifiesto, MCP, carga y conformidad
3º	Google Skills	Un catálogo real que valida las decisiones de estructura y nomenclatura

Dos desvíos razonables:

• Si ya sabes escribir skills, entra directo aquí y usa el curso de Agent Skills como referencia puntual cuando el capítulo 4 mencione algo del SKILL.md.
• Si vas a publicar ya, adelanta Google Skills al segundo puesto: ver un catálogo mantenido ahorra decisiones de estructura de repositorio antes de escribir el primer plugin.json.

Qué vas a saber hacer al terminar

Al cerrar el capítulo 10 deberías poder, sin volver a abrir la especificación:

Construir

• Crear un plugin desde cero con la estructura correcta y verlo cargar en un cliente.
• Escribir un plugin.json conforme sabiendo de memoria cuáles son los diez campos, cuál es obligatorio, qué tipo tiene cada uno y por qué el esquema es cerrado.
• Colocar skills en skills/ respetando las tres reglas de descubrimiento y la contención dentro del plugin root.
• Escribir un mcp.json con las tres variantes de transporte, usando PLUGIN_ROOT y PLUGIN_DATA en vez de rutas absolutas de tu máquina.
• Añadir datos propietarios en extensions y directorios de extensión de cliente sin romper la portabilidad del paquete.

Razonar sobre el contrato

• Predecir qué hará un cliente conforme con tu plugin: qué carga, qué ignora, qué reporta y qué rechaza de plano.
• Distinguir un fallo fatal de uno que solo degrada un componente, aplicando el límite más estrecho.
• Separar en cualquier afirmación sobre el estándar lo normativo, lo informativo y el comportamiento de un producto concreto.
• Enumerar los requisitos de conformidad del paquete y del cliente, y auditar una implementación contra ellos.
• Decidir qué versión de la spec targetea tu plugin y cómo versionas el plugin mismo.

Publicar

• Validar plugin.json y mcp.json contra los esquemas oficiales desde la terminal, en un hook de pre-commit y en CI.
• Interpretar un error de validación y saber si el culpable es el manifiesto, el esquema elegido o algo que el esquema ni siquiera puede ver.
• Preparar un repositorio git como unidad de distribución, con licencia, changelog y etiquetas de versión.
• Leer un catálogo de plugins ajeno y entender qué garantiza y qué no antes de instalar nada.
• Auditar la configuración ejecutable de un plugin de terceros antes de dejarlo arrancar un proceso en tu máquina.

Participar

• Saber quién decide los cambios del estándar, con qué mayorías y bajo qué licencias.
• Identificar cuál de las siete áreas abiertas de FUTURE_CONSIDERATIONS.md te afecta y cómo mitigarla hoy, fuera del estándar.
• Abrir una Discussion o un Issue que cumpla el criterio del proyecto, en lugar de un PR que nadie va a poder aceptar.

Cómo usar este curso

1. Lee los capítulos 1 y 2 en orden y ejecuta el 2. Un plugin tarda cinco minutos en crearse; leerlo sin hacerlo convierte el resto del curso en abstracción.
2. Trata el bloque 2 como referencia, no como lectura lineal. El 3, el 4 y el 5 son los capítulos que vas a volver a abrir cada vez que escribas un plugin nuevo.
3. No te saltes el 6 si implementas clientes. Es el único capítulo que recorre el ciclo de carga completo, con la escalera de fallos y las reglas de contención de rutas.
4. Monta la validación del capítulo 8 antes de publicar nada. Los dos esquemas oficiales cuestan diez minutos de integrar y evitan la clase de error que solo aparece en la máquina de otra persona.
5. Recuerda la frontera en cada capítulo. Cuando el curso dice “el cliente PUEDE”, esa opcionalidad es real y significa que tu plugin no debería depender de ese comportamiento.
6. Ante la duda, abre el archivo. La especificación son 640 líneas y los dos JSON Schema, 65 y 120. Está escrita para leerse entera de una sentada.

Glosario mínimo

Término	Qué significa aquí
Plugin	Un directorio con un plugin.json en su raíz que agrupa componentes reutilizables
Plugin root	El directorio raíz del plugin; nada del paquete debe resolverse fuera de él
Manifiesto	El archivo plugin.json: metadatos del paquete, no configuración de componentes
Ubicación fija	La ruta donde el cliente DEBE buscar cada tipo de componente: skills/ y mcp.json
Componente	Una unidad que el plugin aporta: un skill o un servidor MCP
Skill	Un directorio con SKILL.md, conforme a la especificación de Agent Skills
MCP	Model Context Protocol; los servidores se configuran en mcp.json
Cliente	Cualquier producto que descubre, valida y carga plugins conforme al estándar
Conforme	Que cumple todos los requisitos DEBE de la especificación, como paquete o como cliente
Extensión	Datos o directorios propietarios de un cliente que no rompen la portabilidad
Fuera de alcance	Lo que la spec declara que no regula, empezando por la UX del cliente

Fuentes

El curso está escrito contra el repositorio oficial del estándar: spec/1.0.0.md como único texto normativo, schemas/1.0.0/plugin.schema.json y schemas/1.0.0/mcp.schema.json como esquemas de validación, y README.md, GOVERNANCE.md, FUTURE_CONSIDERATIONS.md, CONTRIBUTING.md, MAINTAINERS.md y AGENTS.md como documentos informativos, siempre señalados como tales.

Cuando un capítulo cita texto normativo lo hace en su idioma original seguido de la traducción, para que puedas contrastar contra la fuente sin ambigüedad.

Resumen

• Agent Plugins es un estándar abierto y vendor-neutral que define un formato portable de paquete para Agent Skills y servidores MCP. La versión vigente es la 1.0.0, con estado Published, y es la única publicada.
• Un plugin es un directorio con plugin.json en su raíz; los skills viven en skills/ y los servidores MCP se configuran en mcp.json, ambas ubicaciones fijas.
• El curso son 10 capítulos en cinco bloques: fundamentos (1-2), el formato (3-5), el contrato con el cliente (6-7), publicar (8-9) y comunidad (10).
• El requisito previo que más rinde es conocer el formato SKILL.md: la spec delega en Agent Skills y solo fija dónde viven los skills.
• Forma una trilogía con Agent Skills —el formato— y Google Skills —el catálogo real con más de cien skills y sus plugins publicados.
• Todo el contenido normativo sale de spec/1.0.0.md y de los dos JSON Schema, y el curso distingue siempre entre lo que DEBE cumplirse, lo que DEBERÍA cumplirse, lo que un cliente PUEDE decidir y lo que la especificación declara fuera de su alcance.

Empieza por Qué es Agent Plugins →