Empaquetar el complemento
En esta página
Lección reescrita el 3 de noviembre de 2026 basándose en la página Package your plugin de la documentación de Complementos de OpenAI. La lección anterior describía la creación de un «paquete» para una «Tienda de ChatGPT» inexistente utilizando un manifiesto faltante. Un complemento se empaqueta con un manifiesto
plugin.jsonque sigue el esquema de Agent Plugins. Fuente: Package your plugin.
Por qué empaquetar
Una vez que has escrito tus habilidades y, si es necesario, construido el servidor MCP, el paso final consiste en ensamblarlas en una unidad instalable. El empaquetado otorga a tu complemento una identidad estable e indica a ChatGPT y Codex qué habilidades, conexiones de servidores MCP y recursos pertenecen al mismo conjunto. La interfaz de usuario y la lógica de autenticación permanecen dentro del servidor MCP; el manifiesto simplemente vincula esa integración con el resto del paquete.
Estructura de un paquete portable
Un complemento portable tiene un manifiesto plugin.json en su raíz, donde se declara el esquema de Agent Plugins. La carpeta también puede contener un directorio skills/, un archivo mcp.json para los servidores MCP distribuidos con el complemento y recursos visuales en assets/.
mon-plugin/
├── plugin.json
├── mcp.json
├── skills/
│ └── compte-rendu/
│ └── SKILL.md
└── assets/
├── icon.png
└── logo.png
El manifiesto mínimo cabe en apenas unas líneas. El nombre, estable y en kebab-case, sirve tanto como identificador como espacio de nombres para los componentes; las habilidades se descubren automáticamente en skills/ sin necesidad de declararlas explícitamente.
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "notes-equipe",
"version": "0.1.0",
"description": "Team notes and meeting minutes"
}
Cada habilidad reside en skills/<nombre>/SKILL.md, con una cabecera que proporciona su nombre y descripción, seguida de las instrucciones:
---
name: compte-rendu
description: Drafts meeting minutes from team notes.
---
Retrieve meeting notes using list_notes, group them by topic,
then draft a summary: decisions, action items with owners, and open points.
Declaración del servidor MCP
Los servidores MCP distribuidos con el complemento se declaran en mcp.json en la raíz, utilizando el esquema correspondiente y especificando un tipo de transporte para cada servidor:
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"notes": {
"type": "streamable-http",
"url": "https://notes.example.com/mcp"
}
}
}
La autenticación del servidor se declara en este mismo archivo, bajo extensions["com.openai"].auth para cada servidor; pertenece al servidor, no al manifiesto. Para el envío público, debes enviar el punto final HTTPS remoto; los servidores locales siguen una ruta separada reservada para complementos de escritorio.
Metadatos específicos de OpenAI
La presentación del directorio, las asignaciones a servidores MCP ya registrados y los ganchos se declaran en el objeto extensions.com.openai del plugin.json raíz, mientras que la identidad portable (name, version, description) permanece en la raíz:
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "notes-equipe",
"version": "0.1.0",
"description": "Team notes and meeting minutes",
"extensions": {
"com.openai": {
"interface": {
"displayName": "Team Notes",
"shortDescription": "Notes and meeting minutes",
"developerName": "Your Team",
"category": "Productivity",
"capabilities": ["Read", "Write"],
"websiteURL": "https://example.com",
"privacyPolicyURL": "https://example.com/privacy",
"termsOfServiceURL": "https://example.com/terms",
"defaultPrompt": ["Use Team Notes to draft Monday's meeting minutes."],
"composerIcon": "./assets/icon.png",
"logo": "./assets/logo.png"
}
}
}
}
Las rutas en este objeto son relativas a la raíz del complemento y comienzan con ./. Los recursos visuales (composerIcon, logo, screenshots) deben preferiblemente ubicarse en ./assets/. El campo apps se utiliza únicamente para apuntar a un archivo .app.json que contiene asignaciones a servidores MCP ya registrados en ChatGPT.
También puedes declarar una habilidad de incorporación mediante extensions.com.openai.onboardingSkill (por ejemplo, ./skills/setup/SKILL.md): esta guía al usuario tras la instalación para elegir un espacio de trabajo o configurar preferencias. Pruébala en una conversación nueva y durante una instalación en curso.
Un formato anterior, con un manifiesto en .codex-plugin/plugin.json, sigue siendo aceptado por compatibilidad: solo se utiliza si el objeto extensions.com.openai está ausente, ya que ambos no se fusionan. Los nuevos paquetes deben usar el plugin.json raíz.
La vía rápida: @plugin-creator
ChatGPT y Codex incluyen una habilidad, @plugin-creator, que genera la estructura por ti; actualmente en el formato de compatibilidad .codex-plugin/. Para adjuntar un servidor MCP a él, conecta primero ese servidor en ChatGPT (Add custom MCP server, luego Create as a plugin), anota el ID de conexión técnica de la URL del navegador —comienza con plugin_asdk_app— y proporciónalo a @plugin-creator en modo Work (o a $plugin-creator en Codex). La habilidad también puede crear una entrada de mercado personal, lo que te permite instalar y probar el complemento desde tu directorio local de origen.
Mercados locales
Un mercado es un catálogo JSON de complementos. Sirve para escribir, probar y distribuir en equipo junto con el directorio público: en modo Work o en Codex, cada mercado aparece como una fuente seleccionable en el directorio de complementos. Así es como probarás el complemento completo antes de enviarlo (Lección 9).
Ganchos: solo escritorio
Los ganchos del ciclo de vida solo son compatibles con complementos instalados manualmente en la aplicación de escritorio de Codex, y un complemento que los contenga no es elegible para el directorio público. Si tu complemento tiene como objetivo la publicación, omítelos.
Puntos clave
- Un paquete portable:
plugin.json(esquema de Agent Plugins),skills/,mcp.json,assets/ - El servidor MCP se declara en
mcp.jsoncon su tipo de transporte; la autenticación también va allí - La presentación, las asignaciones y la habilidad de incorporación van en
extensions.com.openai @plugin-creatorgenera la estructura; un mercado local es para pruebas- Un complemento con ganchos no es elegible para el directorio público