Skip to main content
Todas las guías
Contenido de la guía

Contenido de la guía

Tiempo de estudio: 15 min
#ai_agents#codex#plugins#skills#mcp#marketplace
Intermedio15 min

Plugins de Codex para principiantes: qué reemplazó a las Skills tradicionales

Guía exhaustiva sobre el ecosistema de plugins en Codex: diferencias entre Skills y Plugins, conexión de Marketplaces, gestión mediante GUI y CLI, autorización de servidores MCP y desarrollo de plugins propios.

Publicado:

1. Evolución del ecosistema: de Skills individuales a Plugins modulares

En las etapas iniciales del desarrollo con agentes de inteligencia artificial autónomos, la herramienta principal para configurar el comportamiento del modelo eran las Skills (habilidades): carpetas aisladas con archivos de instrucciones en formato Markdown (SKILL.md) que enseñaban al modelo cómo realizar tareas específicas, como revisiones de código según los estándares del equipo, optimización de bases de datos o redacción de documentación técnica.

Aunque las Skills continúan siendo la unidad básica de conocimiento, la necesidad de copiarlas manualmente entre proyectos, la falta de control de versiones y la imposibilidad de empaquetar herramientas ejecutables junto a las instrucciones dieron paso a un ecosistema modular completo: los Codex Plugins y los catálogos Marketplaces.

mermaid
flowchart TD subgraph Distribution ["Capa de distribución"] M["Marketplace (Repositorio Git o carpeta local)"] end subgraph Packaging ["Capa de empaquetado: Plugin"] P["Codex Plugin"] P --> S["Skills (Instrucciones y experiencia)"] P --> T["MCP Tools (APIs externas: GitHub, Slack, Figma)"] P --> H["Hooks (Disparadores automáticos)"] P --> C["Config (Manifiesto plugin.json)"] end subgraph Execution ["Capa de ejecución"] Session["Nueva sesión activa de Codex"] end M -->|codex plugin add| P P -->|Inicializar extensiones| Session

Comparativa arquitectónica: Skill frente a Plugin

CaracterísticaSkill independientePlugin modular
Propósito principalDefine pautas y flujos para una tarea específicaPaquete completo que amplía el entorno de ejecución del agente
Contenido del paqueteArchivo Markdown SKILL.md + archivos de referenciaConjunto de Skills, servidores MCP, hooks de ciclo de vida y configuración
Integraciones externasSin acceso nativo a APIs de servicios de tercerosConecta servicios externos mediante Model Context Protocol (MCP)
DistribuciónCopia manual de directorios en el espacio de trabajoInstalación con un solo comando o clic desde Marketplaces
ActualizacionesSustitución manual de archivos por el desarrolladorActualizaciones automatizadas vía CLI o catálogo
Nota

La analogía más precisa es la del desarrollo de software: las Skills son funciones de biblioteca individuales, mientras que los Plugins son paquetes completos (módulos npm). Si solo necesita una pauta de trabajo aislada, una Skill es suficiente. Si desea dotar al agente de herramientas ejecutables para interactuar con GitHub, Slack o Figma junto a instrucciones de uso, elija un Plugin.

2. Anatomía de un plugin: Skills, servidores MCP, configuraciones y hooks

Un plugin en Codex no es simplemente un prompt de sistema extenso. Es un directorio estructurado o archivo empaquetado que incluye un manifiesto declarativo y componentes ejecutables.

text
my-awesome-plugin/ ├── .codex-plugin/ │ └── plugin.json # Manifiesto obligatorio del plugin ├── skills/ │ ├── code-review/ │ │ └── SKILL.md # Primera skill integrada │ └── perf-audit/ │ └── SKILL.md # Segunda skill integrada ├── mcp/ │ └── server-config.json # Configuración del servidor MCP └── README.md # Documentación para desarrolladores

Componentes fundamentales de un plugin

  1. Manifiesto (.codex-plugin/plugin.json): Archivo de configuración central que establece el identificador único del plugin, su versión semántica, autoría, dependencias y puntos de entrada.
  2. Paquetes de habilidades (skills/): Uno o varios directorios con archivos SKILL.md que instruyen a Codex en metodologías especializadas.
  3. Servidores MCP (Model Context Protocol): Servidores ejecutables o adaptadores que proporcionan al agente herramientas directas (por ejemplo, consultar pull requests en GitHub, crear tickets en Linear o inspeccionar tokens de diseño en Figma).
  4. Hooks de ciclo de vida (Lifecycle Hooks): Scripts o comandos ejecutados automáticamente ante eventos concretos de la sesión (por ejemplo, ejecutar un linter antes de confirmar cambios en git).
json
{ "name": "developer-toolkit", "version": "1.2.0", "description": "Herramientas integrales para auditoría de código y automatización en GitHub", "author": "Engineering Team", "skills": [ "./skills/code-review", "./skills/perf-audit" ], "mcpServers": { "github-connector": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] } } }
Importante

A diferencia de los prompts de texto convencionales, los plugins expanden directamente las capacidades operativas del agente. Sin un plugin con servidor MCP, el agente solo razona sobre cómo trabajar con GitHub; con el plugin instalado, adquiere herramientas para llamar directamente a la API de GitHub.

3. Qué son los Marketplaces: catálogos de extensiones y fuentes de distribución

Para centralizar la búsqueda, validación y distribución de plugins, Codex utiliza el concepto de Marketplaces (catálogos de extensiones).

Un Marketplace es un registro o repositorio que contiene una lista de plugins disponibles, sus metadatos y las direcciones de origen para su descarga. En lugar de buscar archivos en fuentes no confiables, el desarrollador conecta un marketplace verificado e instala extensiones mediante un identificador directo.

mermaid
flowchart LR subgraph Sources ["Fuentes de catálogos"] Official["Registro oficial de OpenAI"] Community["Repositorios públicos de GitHub"] Private["Registros corporativos internos"] Local["Carpetas locales de desarrollo"] end subgraph Client ["Entorno cliente de Codex"] Reg["Administrador de Marketplaces"] Reg --> P1["Plugin: GitHub Sync"] Reg --> P2["Plugin: PostgreSQL Inspector"] Reg --> P3["Plugin: Team Styleguide"] end Official --> Reg Community --> Reg Private --> Reg Local --> Reg

Tipos de marketplaces admitidos

  • Catálogo público oficial: Registro predeterminado disponible para todos los usuarios de Codex con extensiones verificadas de servicios populares (Figma, Notion, Google Workspace, GitHub).
  • Repositorios Git de la comunidad: Cualquier repositorio público o privado en GitHub o GitLab configurado según la especificación de marketplaces.
  • Registros corporativos internos: Catálogos privados de empresas que alojan plugins para interactuar con microservicios internos, redes VPN y sistemas de seguridad.
  • Directorios locales de desarrollo: Carpetas en el disco local empleadas para diseñar, probar y depurar plugins antes de su publicación.

4. Gestión mediante interfaz gráfica: el comando /plugins

Para los flujos de trabajo habituales, no es necesario memorizar comandos de terminal extensos: Codex incluye un navegador gráfico de plugins integrado en la sesión.

Acceso a la interfaz interactiva

Para abrir el panel visual de extensiones, introduzca el siguiente comando en la línea de chat de su sesión de Codex:

bash
/plugins

Este explorador le permite:

  • Revisar plugins instalados: Comprobar qué extensiones están activas y su estado operativo actual.
  • Buscar nuevas extensiones: Filtrar plugins por nombre, etiquetas o categorías temáticas (Development, DevOps, Analytics, Design).
  • Alternar entre catálogos: Filtrar extensiones según el marketplace conectado correspondiente.
  • Controlar el estado: Habilitar (Enable) o deshabilitar temporalmente (Disable) plugins con un solo clic sin desinstalarlos del sistema.
Atención

Regla de la nueva sesión: Al instalar un plugin o habilitar una extensión desactivada, sus skills y herramientas MCP solo entran en vigor en las nuevas sesiones de trabajo. Las sesiones en ejecución conservan su estado original; abra siempre un nuevo diálogo tras modificar la configuración de plugins.

5. Gestión de plugins mediante CLI: listar, instalar y desinstalar

Para desarrolladores que operan preferentemente en la consola o en entornos de integración continua (CI/CD), Codex ofrece un conjunto completo de comandos bajo codex plugin.

Comandos básicos de plugins

El comando codex plugin list proporciona el nombre de cada plugin, su versión, fuente de origen y estado de activación.

6. Gestión de Marketplaces: añadir repositorios, actualizar y eliminar

Para ampliar el catálogo de extensiones disponibles, conecte repositorios externos utilizando los subcomandos de codex plugin marketplace.

Consultar catálogos conectados:

bash
codex plugin marketplace list

Muestra el identificador de cada catálogo, el protocolo de origen (git o local) y su dirección URI.

Conectar nuevas fuentes de marketplaces

Codex soporta diversos formatos de conexión adaptados a cada infraestructura:

Actualizar y eliminar catálogos

bash
# Actualizar el índice de un marketplace concreto codex plugin marketplace upgrade community-plugins # Actualizar todos los marketplaces de tipo Git simultáneamente codex plugin marketplace upgrade # Desconectar un marketplace de la lista de fuentes codex plugin marketplace remove community-plugins
Consejo

Si un plugin recién publicado por su equipo no aparece en las búsquedas, ejecute codex plugin marketplace upgrade para sincronizar el índice local.

7. Plugins con servidores MCP: autorización, permisos y seguridad

Cuando un plugin incorpora un servidor MCP, obtiene la capacidad de interactuar con plataformas externas (bases de datos, repositorios en la nube, APIs). Esto convierte a Codex en un agente capaz de ejecutar acciones reales en su infraestructura.

mermaid
sequenceDiagram autonumber actor Dev as Desarrollador participant Codex as Sesión Codex participant Plugin as Plugin (Adaptador MCP) participant Cloud as Servicio externo (API de GitHub) Dev->>Codex: "Crea una issue con los hallazgos de la auditoría" Codex->>Plugin: Invoca la herramienta create_issue() alt Requiere autorización Plugin-->>Dev: Solicita aprobación OAuth o token Dev->>Plugin: Confirma credenciales end Plugin->>Cloud: POST /repos/:owner/:repo/issues Cloud-->>Plugin: HTTP 201 Created (Issue #42) Plugin-->>Codex: Resultado con enlace a la issue Codex-->>Dev: "¡Issue #42 creada con éxito!"

Modelos de autorización en servicios externos

  1. Flujo de autenticación OAuth: Los servicios en la nube (Google Drive, Slack, GitHub) abren una ventana en el navegador durante el primer uso para solicitar autorización sobre la cuenta.
  2. Variables de entorno para credenciales: Los adaptadores de bases de datos y APIs privadas (PostgreSQL, Supabase) leen las claves de archivos .env o de la configuración global de Codex.
  3. Control granular de permisos: Codex solicita confirmación explícita al usuario antes de ejecutar operaciones potencialmente destructivas (eliminar datos, enviar correos, cerrar pull requests).
Atención

Seguridad de servidores MCP: Nunca instale plugins con servidores MCP procedentes de catálogos no verificados. Un servidor MCP malicioso podría leer archivos locales o enviar credenciales privadas a servidores externos. Examine siempre el código fuente antes de la instalación.

Es común confundir los tres niveles de desactivación de extensiones:

AcciónComando o interfazImpacto en discoConsecuencia en las sesiones
Deshabilitar plugin (Disable)Interruptor en /pluginsLos archivos se conservan en discoLas skills y herramientas MCP se desactivan en nuevas sesiones
Desinstalar plugin (Uninstall)codex plugin remove <name>Elimina los archivos del plugin del entorno localLimpieza completa; requerirá reinstalación para volver a usarlo
Desconectar marketplacecodex plugin marketplace remove <name>Solo desconecta el catálogo; los plugins instalados se mantienenNo se podrán descargar actualizaciones ni plugins nuevos de esa fuente

Criterio de elección

  • Si un plugin genera conflictos temporales o desea pausar herramientas pesadas: deshabilítelo (Disable) desde /plugins.
  • Si finalizó el proyecto y no volverá a usar el conjunto de herramientas: desinstálelo (Remove) mediante CLI.
  • Si un catálogo externo quedó obsoleto o fuera de servicio: desconéctelo (Marketplace Remove).

9. Desarrollo de un Plugin propio: manifiesto, empaquetado de Skills y pruebas locales

Crear un plugin propio es la forma más eficaz de unificar los estándares de arquitectura y asegurar la calidad del código generado en todo el equipo.

Guía paso a paso para crear un plugin

Paso 1. Preparar la estructura de carpetas

Cree un espacio de trabajo limpio para el plugin:

bash
mkdir -p my-team-plugin/.codex-plugin mkdir -p my-team-plugin/skills/architecture-review

Paso 2. Crear el archivo de manifiesto plugin.json

Cree el archivo .codex-plugin/plugin.json:

json
{ "name": "team-architecture-plugin", "version": "1.0.0", "description": "Reglas corporativas de diseño de servicios y auditoría de arquitectura limpia", "author": "Architecture Guild", "skills": [ "./skills/architecture-review" ] }

Paso 3. Redactar las instrucciones en SKILL.md

Cree el archivo my-team-plugin/skills/architecture-review/SKILL.md:

markdown
--- name: architecture-review description: Validación de módulos según los principios de Domain-Driven Design (DDD) --- Al analizar nuevos módulos de arquitectura, comprueba estas reglas: 1. La lógica de negocio nunca debe importar directamente el ORM o el controlador de base de datos. 2. Las integraciones externas se definen como puertos (interfaces) en la capa de dominio. 3. Cada mutación de estado debe generar un evento de dominio registrado.

Paso 4. Conectar un marketplace local y realizar pruebas

Para probar el plugin en local sin publicarlo en GitHub, registre el directorio como catálogo local:

bash
# Conectar la carpeta local como fuente de marketplace codex plugin marketplace add ./local-market # Instalar el plugin recién creado codex plugin add team-architecture-plugin # Verificar el estado de instalación codex plugin list

Abra una nueva sesión en Codex y compruebe el funcionamiento del plugin con una tarea real de revisión de código.

10. Cuaderno de referencia de comandos y lista de verificación de seguridad

Guarde esta guía rápida para consultar los comandos de consola y mantener la seguridad de su equipo.

Referencia rápida de comandos CLI

bash
# ─── Operaciones con plugins ─────────────────────────────────────── codex plugin list # Listar plugins instalados codex plugin list --available # Listar plugins disponibles en catálogos codex plugin add <plugin-name> # Instalar un plugin codex plugin add <plugin@marketplace> # Instalar desde un marketplace específico codex plugin remove <plugin-name> # Desinstalar un plugin # ─── Operaciones con Marketplaces ───────────────────────────────── codex plugin marketplace list # Listar catálogos conectados codex plugin marketplace add <source> # Añadir marketplace (GitHub / URL / Local) codex plugin marketplace upgrade <name> # Actualizar un catálogo concreto codex plugin marketplace upgrade # Actualizar todos los catálogos codex plugin marketplace remove <name> # Desconectar un catálogo # ─── Interfaz gráfica ───────────────────────────────────────────── /plugins # Abrir el navegador interactivo de plugins

Lista de verificación de seguridad previa a la instalación

  • Origen verificado: El repositorio del marketplace pertenece a un proveedor oficial o a una comunidad reconocida.
  • Auditoría del manifiesto: En plugin.json no existen comandos ejecutables sospechosos ni binarios desconocidos.
  • Comprobación de endpoints de red en MCP: Los servidores MCP se comunican únicamente con direcciones oficiales de la plataforma destino.
  • Ausencia de colisiones: Las skills del plugin no interfieren con directivas esenciales del proyecto.
  • Pruebas en entorno aislado: El plugin ha sido evaluado en un proyecto de prueba antes de incorporarlo a repositorios de producción.
Esta guía es completamente gratuita. Si te ahorró una noche, puedes apoyar el crecimiento del proyecto.
Apoyar al autor