Qué es Agent Plugins y qué problema resuelve

Agent Plugins es 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.

Esa frase no es una paráfrasis: es la definición literal que abre el README.md del repositorio oficial. Y conviene retenerla entera, porque cada una de sus partes acota lo que este curso va a cubrir y —tan importante como eso— lo que la especificación deja explícitamente fuera.

La versión vigente es Agent Plugins Specification 1.0.0, con estado Published. El documento normativo se titula Agent Plugins Specification y su primera línea de propósito dice: “This document defines the canonical Agent Plugins Specification v1.0.0 for packaging reusable components that extend AI agents into distributable plugins.”

El problema: cada agente inventaba su propio formato

Antes de que existiera un formato portable, extender un agente de IA significaba aprender el formato de ese agente concreto. Un cliente esperaba la configuración MCP en un archivo con cierto nombre y cierta forma; otro cliente la esperaba en otro archivo con otra forma; un tercero la incrustaba en su propio archivo de configuración global. El paquete que funcionaba en uno no cargaba en el otro.

La propia especificación lo reconoce en su sección de Design Decisions, que es material no normativo pero que explica el porqué de cada decisión:

“Existing clients use incompatible MCP configuration shapes and infer transports differently.”

Es decir: no es que faltara tecnología, es que faltaba un acuerdo. Existían ya dos piezas con especificación propia y adopción real entre clientes distintos —Agent Skills y el Model Context Protocol— pero nadie había estandarizado el sobre que las transporta juntas.

Ese sobre es el plugin.

flowchart LR
    subgraph ANTES["Antes: sin formato portable"]
        A1["Autor de la extension"] --> B1["Formato del cliente A"]
        A1 --> B2["Formato del cliente B"]
        A1 --> B3["Formato del cliente C"]
    end
    subgraph DESPUES["Con Agent Plugins 1.0.0"]
        A2["Autor del plugin"] --> P["Un solo paquete portable"]
        P --> C1["Cliente A"]
        P --> C2["Cliente B"]
        P --> C3["Cliente C"]
    end

El Technical Charter del proyecto declara el objetivo en una sola línea: “The Project exists to enable portability, competition, and long-term stability for plugin packages across vendors and platforms.”

Las tres piezas del ecosistema y su relación exacta

Aquí es donde más gente se confunde, así que vale la pena fijar la relación con precisión quirúrgica. Hay tres especificaciones distintas, mantenidas por proyectos distintos, y Agent Plugins solo es una de ellas.

Pieza	Qué aporta	Quién la define
Agent Skills	La unidad de conocimiento: un SKILL.md con instrucciones para el modelo	Agent Skills specification
MCP	Herramientas y datos: servidores que el agente puede invocar o consultar	Model Context Protocol specification
Agent Plugins	El sobre que empaqueta a los dos anteriores para distribuirlos	Agent Plugins Specification 1.0.0

Un skill es la unidad de conocimiento. Es un directorio con un archivo SKILL.md que le dice al agente cómo hacer algo. Ese formato —el frontmatter, los directorios scripts/, references/, assets/— lo define la Agent Skills specification, no Agent Plugins. Lo dice el texto normativo sin ambigüedad:

“Agent Skills MUST conform to the Agent Skills specification. That specification is the source of truth for the SKILL.md format, frontmatter fields, and directory layout (scripts/, references/, assets/).”

Si vienes del formato SKILL.md y quieres dominarlo antes de empaquetarlo, ese terreno está cubierto en el curso hermano de Agent Skills.

MCP aporta herramientas y datos. Un servidor MCP es un proceso local o un endpoint remoto que expone capacidades al agente. El comportamiento de cable y el ciclo de vida los define la especificación del Model Context Protocol. Lo que Agent Plugins añade es únicamente el formato de configuración mcp.json que permite localizar y conectar esos servidores dentro de un plugin, de forma independiente del formato nativo de cada cliente:

“Clients map this portable format to their native configuration; its field names and values need not match a client-native format.”

Y un plugin es el sobre. Un directorio autocontenido con un manifiesto plugin.json y componentes opcionales. No aporta capacidades nuevas: aporta empaquetado, identidad y portabilidad.

flowchart TD
    P["Plugin: directorio con plugin.json"] --> S["skills/ — unidades de conocimiento"]
    P --> M["mcp.json — servidores MCP"]
    S --> SS["Formato definido por Agent Skills spec"]
    M --> MM["Comportamiento definido por MCP spec"]
    P --> PP["Formato de paquete definido por Agent Plugins 1.0.0"]

La consecuencia práctica: un plugin no es un skill mejorado ni un servidor MCP con metadatos. Es una capa de empaquetado por encima de dos formatos que ya existían y que siguen siendo autoridad en su propio terreno.

El plugin más pequeño que sirve para algo

El README.md oficial lo llama “the smallest useful plugin” y lo presenta así:

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

Con este plugin.json:

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

Y este skills/greet/SKILL.md:

---
name: greet
description: Greet the user and offer help.
---

Greet the user and offer help.

Dos campos en el manifiesto. Nada más. Un cliente que soporte skills carga el plugin leyendo plugin.json y descubriendo skills/greet/SKILL.md.

Fíjate en la frase con la que el README cierra ese ejemplo, porque es la primera frontera de alcance del curso:

“How the client exposes the skill to users or models is outside the Agent Plugins specification.”

Cómo el cliente muestra ese skill, cuándo lo activa, si lo lista en un menú o lo inyecta en el contexto: nada de eso está en la especificación. Esa frase es del README.md, que es material informativo, pero el texto normativo dice lo mismo en §7.1 con otras palabras: “not the skill format itself or how clients expose skills to users or models”.

Terminología oficial

La especificación fija siete términos en §3. Vale la pena leerlos ahora porque los vas a encontrar en cada capítulo del curso.

Término	Significado	Definición
Plugin	Unidad de paquete	Un directorio autocontenido con un manifiesto y componentes opcionales
Plugin root	Raíz de sistema de archivos	El directorio de nivel superior de un paquete de plugin
Manifest	Documento de metadatos	Un archivo plugin.json en la raíz del plugin
Component	Unidad provista por el plugin	Un skill o una entrada de servidor MCP suministrada mediante un tipo de componente estandarizado por esta especificación
Client	Runtime del plugin	Una herramienta que descubre, instala, carga y ejecuta componentes de plugin
Extension namespace	Identificador propiedad del cliente	Un identificador de dominio inverso usado para datos de manifiesto específicos de cliente, un directorio de nivel superior específico de cliente, o ambos
Extension directory	Raíz de archivos propiedad del cliente	Un directorio de nivel superior cuyo nombre es exactamente un extension namespace y cuyo contenido define el cliente dueño de ese namespace

Dos observaciones sobre esa tabla. Primera: Component cubre exactamente dos cosas, un skill o una entrada de servidor MCP. Segunda: Client es el término que usaremos siempre para referirnos al agente que carga el plugin, sea cual sea el producto.

El lenguaje normativo: cómo leer la especificación

Agent Plugins 1.0.0 usa el vocabulario de RFC 2119 y RFC 8174. La regla de §2 es literal y estricta:

“In the normative sections of this document, the key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals.”

La coletilla “when, and only when, they appear in all capitals” importa: la palabra must en minúsculas dentro de una frase explicativa no es una obligación normativa.

Traducciones que este curso usará de forma consistente:

Original	Traducción	Significado
MUST / REQUIRED	DEBE (MUST)	Requisito absoluto
MUST NOT	NO DEBE (MUST NOT)	Prohibición absoluta
SHOULD / RECOMMENDED	DEBERÍA (SHOULD)	Recomendación fuerte; se puede ignorar con razones sopesadas
SHOULD NOT	NO DEBERÍA (SHOULD NOT)	Desaconsejado con la misma fuerza
MAY / OPTIONAL	PUEDE (MAY)	Verdaderamente opcional

Un dato curioso y verificable: en las 640 líneas de spec/1.0.0.md no aparece ninguna afirmación con SHOULD NOT ni con REQUIRED. §2 lista ambas entre las palabras clave interpretables, pero fuera de esa misma frase de §2 el documento no las usa nunca. Las que sí aparecen en afirmaciones normativas son MUST, MUST NOT, SHOULD, MAY, RECOMMENDED y OPTIONAL —esta última una sola vez, en §7.2.1, para decir que el soporte de sse es OPCIONAL (OPTIONAL)—.

La segunda frase de §2 es igual de importante para leer bien el documento:

“Appendix A and Design Decisions are non-normative. All other sections are normative.”

Es decir: las secciones 1 a 11 son normativas. El Apéndice A (una checklist de conformidad) y las Design Decisions (el racional de diseño) son informativos. El propio Apéndice A lo dice de sí mismo: “when it conflicts with the spec text above, the spec governs”.

Y hay una tercera jerarquía que conviene memorizar desde ya, porque aparece dos veces en el texto normativo (§5.2 y §7.2.1) con las mismas palabras:

“The specification text is authoritative if it conflicts with the schema.”

El texto manda sobre el JSON Schema. Los esquemas son una red de seguridad parcial, no la definición completa de la conformidad. Volveremos sobre esto en el capítulo de validación.

Qué define la especificación

Este es el mapa completo del terreno normativo. Cada punto se desarrolla en un capítulo posterior del curso.

• Unidad de paquete: un plugin es un directorio anclado en una sola ubicación del sistema de archivos. No un .zip, no un .tar.gz, no un bundle descargado de un registry. Las Design Decisions lo justifican: así el plugin queda inspeccionable con ls, cat y git, editable en sitio durante el desarrollo y compatible con control de versiones sin herramientas especiales.
• Manifiesto obligatorio: un plugin DEBE (MUST) incluir un manifiesto en plugin.json en la raíz del plugin. Y hay exactamente uno: “The Agent Plugins core specification defines exactly one portable manifest per plugin. No other file can replace, supplement, or override the core fields in root plugin.json.”
• Manifiesto cerrado: solo diez campos de nivel superior permitidos. $schema y name son obligatorios; los otros ocho son opcionales y se reparten en siete campos de metadatos (§5.4) más extensions, que no es metadato sino el hueco reservado a los datos específicos de cliente (§5.6).
• Ubicaciones fijas de componentes: los skills se descubren en skills/, los servidores MCP en mcp.json. plugin.json no puede sobreescribir esas ubicaciones ni contener configuración de componentes en línea.
• Exactamente dos tipos de componente en v1: skills y servidores MCP.
• Formato mcp.json: un objeto con $schema y mcpServers, y una unión cerrada de tres variantes de transporte.
• Contención de rutas: toda ruta del paquete que el cliente descubra, lea o ejecute DEBE (MUST) permanecer dentro de la raíz del plugin ya resuelta.
• Extensiones de cliente: los datos y archivos específicos de un cliente van bajo un namespace de dominio inverso, nunca sueltos en el manifiesto.
• Variables de plugin: PLUGIN_ROOT y PLUGIN_DATA, con expansión de ${PLUGIN_ROOT} y ${PLUGIN_DATA} acotada a campos concretos.
• Versionado: la versión de la especificación cubre el texto y ambos esquemas como un solo release.
• Conformidad de cliente: ocho capacidades mínimas, con adopción incremental permitida.

flowchart TD
    SPEC["Agent Plugins 1.0.0"] --> N["Secciones 1-11: normativas"]
    SPEC --> I["Apendice A y Design Decisions: informativos"]
    N --> N1["Modelo de paquete"]
    N --> N2["Manifiesto plugin.json"]
    N --> N3["Descubrimiento de componentes"]
    N --> N4["Skills y servidores MCP"]
    N --> N5["Extensiones de cliente"]
    N --> N6["Variables y expansion"]
    N --> N7["Versionado y conformidad"]

Qué deja explícitamente fuera

Esta sección es la que más errores previene. Todo lo que sigue está declarado fuera de alcance con texto explícito en las fuentes oficiales, y confundirlo con la especificación es el fallo más común al hablar de Agent Plugins.

Fuera de alcance según el texto normativo

Tema	Cita literal
El formato del skill en sí	”That specification is the source of truth for the SKILL.md format, frontmatter fields, and directory layout” (§7.1)
Cómo el cliente expone los skills	”not the skill format itself or how clients expose skills to users or models” (§7.1)
Comportamiento de cable y ciclo de vida de MCP	”The Model Context Protocol specification defines MCP wire behavior and lifecycle semantics” (§7.2)
Sandboxing del subproceso	”They do not sandbox a plugin subprocess or restrict paths supplied at runtime” (§4.1)
OAuth y referencias portables a credenciales	”Agent Plugins v1 defines no OAuth configuration or portable credential-reference fields” (§7.2.1)
Fallback de transporte tras fallo de conexión	”Agent Plugins does not define fallback behavior if that attempt fails” (§7.2.1)
Semántica de las extensiones de cliente	”Agent Plugins assigns no portable discovery, validation, loading, or failure semantics to client extension data or files” (§8)
Otros tipos de componente	”Other component types are outside the v1 format and do not affect conformance” (§7)
Gobernanza respecto del formato portable	”Governance for the Agent Plugins project is defined separately from the portable package format” (§1.1)

Sobre los tipos de componente que quedan fuera, las Design Decisions son concretas: “Other proposed component types — such as commands, hooks, agents, rules, and LSP servers — remain too client-specific for a stable portable contract and are outside the v1 format until their formats converge.”

Si tu cliente favorito soporta comandos slash, hooks o subagentes, eso es funcionalidad de ese producto. No forma parte de Agent Plugins 1.0.0.

Fuera de alcance según Future Considerations

FUTURE_CONSIDERATIONS.md es un documento no normativo que además advierte de sí mismo, literalmente: “none of these items is required for conformance or committed for inclusion in a future release”. No es una hoja de ruta comprometida. Es una lista de huecos reconocidos.

• Modelo de permisos y confianza: “v1.0.0 does not define a trust model, permission system, or sandboxing requirements for plugins.”
• Verificación de procedencia: “v1.0.0 does not specify how clients or users can verify the origin or integrity of a plugin.” Nada de firmas criptográficas ni cadenas de atestación en 1.0.0.
• Manejo de secretos: “v1.0.0 does not specify how sensitive values should be provided, stored, or scoped.” De ahí la prohibición tajante de meter credenciales en env o en headers, que veremos en el capítulo de MCP.
• Controles empresariales: allowlists, registries de organización, overrides centralizados y reporting de compliance no están cubiertos.
• Auditoría estandarizada: 1.0.0 define requisitos de reporte de fallos, pero no estandariza esquemas de eventos de diagnóstico o de ciclo de vida.
• Dependencias entre plugins: “Plugins currently cannot declare dependencies on other plugins.”
• Testing y validación: “No test harness or validation tool is specified.” No existe un linter ni un validador oficial. Lo que sí existe son dos JSON Schema publicados que puedes usar con validadores genéricos.

La frontera con los productos

Hay un tercer nivel que no es ni normativo ni “consideración futura”: es simplemente comportamiento de un producto concreto. Los marketplaces, los catálogos y los comandos de instalación de cada CLI entran aquí.

Dato duro y verificable: la palabra marketplace aparece cero veces en spec/1.0.0.md, cero veces en el README.md del repositorio y cero veces en GOVERNANCE.md y FUTURE_CONSIDERATIONS.md. El concepto de marketplace no existe en Agent Plugins 1.0.0. La palabra registry aparece dos veces, y ambas en sentido negativo: “rather than … registry-fetched bundles” y “without requiring a central client-name registry”.

flowchart TD
    A["Lo que estas leyendo"] --> B{"De donde sale?"}
    B -->|spec/1.0.0.md secciones 1-11| C["Normativo: obliga a clientes y paquetes"]
    B -->|Apendice A, Design Decisions, README| D["Informativo: contexto y racional"]
    B -->|FUTURE_CONSIDERATIONS.md| E["Hueco reconocido: no comprometido"]
    B -->|CLI o catalogo de un producto| F["Convencion de producto: no es la spec"]

Cuando el capítulo 9 entre en distribución e instalación, todo lo que veas allí es de la cuarta categoría. Un catálogo real, con sus dos manifiestos distintos y sus comandos de instalación por harness, está diseccionado en el curso hermano de Google Skills.

Gobernanza en una línea

El proyecto se rige por un Technical Charter con un Technical Steering Committee formado por Core Maintainers y un Lead Core Maintainer, donde todos los roles los ocupan personas y no organizaciones, y donde ningún vendor puede controlar la mayoría de los asientos.

Eso es todo lo que necesitas saber por ahora. El capítulo 10 entra en el detalle: promoción y remoción de roles, reglas de votación, licencias —doble licencia, CC-BY-4.0 para el texto y Apache-2.0 para los esquemas— y cómo se propone un cambio a la especificación.

Un apunte de rigor: §1.1 aclara que la gobernanza está definida aparte del formato portable. Nada de lo que dice el Charter afecta a si tu plugin es conforme o no.

Postura de diseño: el piso mínimo, no el techo

El repositorio incluye un AGENTS.md con la postura editorial del proyecto. Su primera línea de diseño resume mejor que ninguna otra por qué la especificación es tan corta:

“Define the smallest genuinely portable interoperability floor, not a universal plugin system or the union of existing client behavior.”

Agent Plugins no intenta ser el sistema de plugins definitivo. Intenta ser el mínimo común denominador que todos los clientes pueden implementar de forma consistente. Cada vez que te preguntes “¿por qué la spec no cubre X?”, la respuesta suele estar en esa frase: porque X todavía no se puede implementar de forma consistente entre clientes, o porque no responde a una necesidad de portabilidad demostrada.

Otras dos líneas de la misma postura, útiles como brújula durante el curso:

“Optimize for simple, robust client implementations. Avoid unnecessary optionality, precedence rules, configurable indirection, compatibility paths, and speculative abstractions.”

“Prefer fixed conventions, flat layouts, and deterministic semantics. Configuration should carry information, not merely activate content a client can already discover.”

Esa última explica de un plumazo por qué skills/ y mcp.json son ubicaciones fijas y no configurables: si el cliente ya puede encontrar el contenido, la configuración no debería servir para activarlo.

Hacia dónde va este curso

El recorrido está pensado para llevarte de la definición al plugin publicado, capítulo a capítulo, sin saltos.

#	Capítulo	Qué resuelve
1	Qué es Agent Plugins y qué problema resuelve	El mapa conceptual y la frontera de alcance
2	Tu primer plugin paso a paso	Del directorio vacío a un plugin que carga
3	plugin.json: el manifiesto al detalle	Los diez campos, sus reglas y qué es fatal
4	Empaquetar Agent Skills dentro de un plugin	Descubrimiento en skills/ y sus límites
5	Servidores MCP dentro de un plugin	mcp.json, los tres transportes y la expansión de variables
6	Descubrimiento, resolución y carga por parte del cliente	El recorrido completo desde la raíz del plugin
7	Versionado, compatibilidad y conformidad	Versiones de spec, de esquema y de plugin
8	Validar un plugin: JSON Schema y automatización	Herramientas reales y lo que el esquema no ve
9	Distribuir e instalar plugins	Lo que hacen los productos, no la spec
10	Gobernanza, hoja de ruta y cómo contribuir	El Charter, las licencias y el proceso de propuesta

Dos hábitos que te pido adoptar desde ahora y mantener hasta el final:

1. Distingue siempre las tres fuentes. Lo que dice el texto normativo, lo que dice un documento informativo del mismo repositorio, y lo que hace un cliente concreto. Son tres cosas distintas y mezclarlas produce afirmaciones falsas.
2. Ante la duda, abre el archivo. La especificación son 640 líneas de Markdown y dos JSON Schema de 65 y 120 líneas. Es corta a propósito. Leerla entera cuesta menos que discutir sobre lo que crees que dice.

Resumen

• Agent Plugins es 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.
• La versión vigente es 1.0.0, con estado Published, y es la única publicada.
• El problema que resuelve es la fragmentación: cada cliente esperaba su propio formato de extensión y nada era portable entre ellos.
• Las tres piezas del ecosistema tienen roles distintos: un skill es la unidad de conocimiento en formato SKILL.md, MCP aporta herramientas y datos, y un plugin es el sobre que empaqueta ambos para distribuirlos.
• Un plugin es un directorio con un plugin.json obligatorio en su raíz; el manifiesto mínimo tiene dos campos, $schema y name.
• v1 define exactamente dos tipos de componente: skills y servidores MCP. Commands, hooks, agents, rules y LSP servers quedan fuera del formato v1.
• Las secciones 1 a 11 son normativas; el Apéndice A y las Design Decisions son informativos; el texto de la especificación manda sobre los JSON Schema.
• Quedan explícitamente fuera: el formato del SKILL.md, cómo el cliente expone los skills al usuario o al modelo, el comportamiento de cable de MCP, permisos, sandboxing, firmas, secretos, dependencias entre plugins y cualquier validador oficial. Marketplace y registry no son conceptos de la spec.
• La gobernanza vive en un Technical Charter aparte, con un TSC de personas —no de empresas— y sin mayoría para ningún vendor.

Siguiente: Tu primer plugin paso a paso