MCP HubMCP Hub
POST·BUILDY

Cómo crear tu primer plugin para agentes: Guía paso a paso

AIMCP Teamon 19 days ago · 2 min read

Cómo crear tu primer plugin para agentes: Guía paso a paso

Los Agent Plugins (v1.0.0) son el estándar de empaquetado portátil para componentes de agentes — habilidades y servidores MCP — que funciona en clientes compatibles. En esta guía, crearás un plugin real y conforme a la especificación desde cero: un plugin que incluye una habilidad y un servidor MCP, y luego lo validarás con el esquema oficial.

Paso 1: Crear la estructura del paquete

Un plugin es simplemente un directorio. Créalo con las dos partes obligatorias desde el principio:

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

Paso 2: Escribir el manifiesto

plugin.json es el único archivo obligatorio. El esquema del manifiesto es cerrado — los campos portátiles de nivel superior se limitan a un conjunto fijo:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "summarize.tools",
  "version": "1.0.0",
  "description": "Habilidades y servidores para resumir documentos.",
  "author": {
    "name": "Tu Nombre",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/summarize-tools",
  "repository": "https://github.com/you/summarize-tools",
  "license": "MIT",
  "keywords": ["summarization", "documents", "llm"]
}

Solo $schema y name son obligatorios. Todo lo demás es opcional pero recomendado: version (SemVer), description, author, homepage, repository, license (SPDX) y keywords para facilitar su descubrimiento.

Nota: el esquema es cerrado por diseño. Las configuraciones específicas de un cliente pertenecen a espacios de nombres de extensión, no a campos de nivel superior.

Paso 3: Añadir una habilidad

Las habilidades residen en skills/, siguiendo la especificación de Agent Skills. Cada subdirectorio inmediato que contenga un archivo SKILL.md es una habilidad:

skills/
└── summarize/
    ├── SKILL.md
    ├── scripts/
    │   └── summarize.py
    └── references/
        └── guidelines.md

Un SKILL.md mínimo:

---
name: summarize
description: Resume un documento en puntos clave. Úsalo cuando el usuario pida condensar un texto largo.
---

# Summarize

1. Lee el documento de la entrada del usuario.
2. Extrae el argumento principal, los puntos de apoyo y los elementos de acción.
3. Escribe el resumen en markdown, máximo 10 puntos.

## Scripts

- `scripts/summarize.py` — CLI que toma una ruta de archivo e imprime un resumen.

Los clientes descubren las habilidades escaneando skills/*/SKILL.md; no profundizan más allá, así que mantén una habilidad por subdirectorio inmediato.

Paso 4: Añadir un servidor MCP

Si tu plugin incluye un servidor MCP, descríbelo en mcp.json. El formato admite transporte stdio, Streamable HTTP y el legado HTTP+SSE:

{
  "servers": {
    "summarize": {
      "command": "python",
      "args": ["scripts/mcp_server.py"],
      "env": {}
    }
  }
}

Los clientes mapean este formato portátil a su configuración nativa — los nombres de los campos no tienen que coincidir con el formato interno de ningún cliente.

Paso 5: (Opcional) Añadir extensiones de cliente

¿Quieres añadir comportamiento para un cliente específico sin bifurcar el núcleo? Usa un directorio de espacio de nombres de dominio inverso nombrado según tu cliente, por ejemplo, com.example.client/hooks/hooks.json. Los clientes buscan su directorio de espacio de nombres en la raíz del plugin; los espacios de nombres desconocidos se ignoran.

Paso 6: Validar

Antes de distribuir, valida tu manifiesto:

  1. $schema debe hacer referencia a la URL oficial del esquema: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json.
  2. name debe estar presente y no estar vacío — un campo obligatorio faltante hace que todo el plugin sea inválido y los clientes deben rechazarlo.
  3. Verifica que el frontmatter de tu SKILL.md tenga al menos name y description.
  4. Valida mcp.json con el esquema JSON de la especificación (publicado en agent-plugins.org/schemas).

También puedes usar el plugin de ejemplo del repositorio de la especificación (agentplugins/agent-plugins-example) como referencia canónica, o ejecutar tu plugin a través del envío de directorio de AIMCP — valida con el esquema oficial e informa los recuentos de componentes.

Paso 7: Distribuir

Un Agent Plugin es un directorio, por lo que la distribución es flexible: súbelo a un repositorio de GitHub, publícalo en un marketplace o compártelo directamente. Los clientes compatibles descubren y cargan plugins de manera consistente, independientemente del transporte.

Próximos pasos