# 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. ## 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ística | Skill independiente | Plugin modular | | :--- | :--- | :--- | | **Propósito principal** | Define pautas y flujos para una tarea específica | Paquete completo que amplía el entorno de ejecución del agente | | **Contenido del paquete** | Archivo Markdown `SKILL.md` + archivos de referencia | Conjunto de Skills, servidores MCP, hooks de ciclo de vida y configuración | | **Integraciones externas** | Sin acceso nativo a APIs de servicios de terceros | Conecta servicios externos mediante Model Context Protocol (MCP) | | **Distribución** | Copia manual de directorios en el espacio de trabajo | Instalación con un solo comando o clic desde Marketplaces | | **Actualizaciones** | Sustitución manual de archivos por el desarrollador | Actualizaciones automatizadas vía CLI o catálogo | > [!NOTE] > 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"] } } } ``` > [!IMPORTANT] > 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. > [!WARNING] > **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 :::tabs @tab Listar instalados ```bash # Mostrar todos los plugins instalados en el entorno actual codex plugin list ``` @tab Listar disponibles ```bash # Consultar los plugins disponibles en todos los marketplaces conectados codex plugin list --available # Obtener la salida detallada en formato JSON codex plugin list --available --json ``` @tab Instalar plugin ```bash # Instalar un plugin por su nombre único codex plugin add github-toolkit # Instalar un plugin desde un marketplace específico codex plugin add dev-suite@company-internal ``` @tab Desinstalar plugin ```bash # Eliminar por completo un plugin instalado del entorno local codex plugin remove github-toolkit # Desinstalar un plugin asociado a un marketplace concreto codex plugin remove dev-suite@company-internal ``` ::: 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: :::tabs @tab GitHub Shorthand ```bash # Sintaxis abreviada para repositorios públicos o accesibles de GitHub (owner/repo) codex plugin marketplace add orlov-ai/community-plugins ``` @tab HTTPS Git URL ```bash # Conexión estándar mediante HTTPS (válida para GitLab y Bitbucket) codex plugin marketplace add https://github.com/company/internal-codex-plugins.git ``` @tab SSH Git URL ```bash # Conexión mediante claves SSH privadas para repositorios corporativos codex plugin marketplace add git@github.com:enterprise/secure-plugins.git ``` @tab Directorio local ```bash # Conectar una carpeta local para crear y depurar marketplaces propios codex plugin marketplace add ./my-local-marketplace ``` ::: ### 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 ``` > [!TIP] > 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). > [!WARNING] > **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. --- ## 8. Ciclo de vida: deshabilitar, desinstalar un plugin o desconectar un catálogo Es común confundir los tres niveles de desactivación de extensiones: | Acción | Comando o interfaz | Impacto en disco | Consecuencia en las sesiones | | :--- | :--- | :--- | :--- | | **Deshabilitar plugin (Disable)** | Interruptor en `/plugins` | Los archivos se conservan en disco | Las skills y herramientas MCP se desactivan en nuevas sesiones | | **Desinstalar plugin (Uninstall)** | `codex plugin remove ` | Elimina los archivos del plugin del entorno local | Limpieza completa; requerirá reinstalación para volver a usarlo | | **Desconectar marketplace** | `codex plugin marketplace remove ` | Solo desconecta el catálogo; los plugins instalados se mantienen | No 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 # Instalar un plugin codex plugin add # Instalar desde un marketplace específico codex plugin remove # Desinstalar un plugin # ─── Operaciones con Marketplaces ───────────────────────────────── codex plugin marketplace list # Listar catálogos conectados codex plugin marketplace add # Añadir marketplace (GitHub / URL / Local) codex plugin marketplace upgrade # Actualizar un catálogo concreto codex plugin marketplace upgrade # Actualizar todos los catálogos codex plugin marketplace remove # 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.