Guía práctica de Codex Skills y Plugins: convierte los workflows del equipo en capacidades reutilizables

La misma checklist de revisión de código se copia en cinco repositorios. En cada PR todavía hay que recordar a mano: “ejecuta primero los tests que fallan”, “revisa el límite de permisos”, “no olvides el changelog”. El problema no es que el prompt sea corto. El proceso aún no está convertido en algo reutilizable.

Codex Skills y Plugins sirven para resolver esa repetición: sacan los workflows repetidos del equipo de prompts sueltos y de un AGENTS.md cada vez más largo, y los convierten en capacidades reutilizables. Un Skill es el formato de autor para un workflow reutilizable. Un Plugin es una unidad instalable de distribución. No reemplazan las reglas del proyecto: las reglas permanentes se quedan en AGENTS.md; los procedimientos de varios pasos, ejemplos, scripts y referencias largas pasan a Skills; la distribución al equipo se empaqueta como Plugin.

Una tabla de decisión basta para escoger entre Skill, Plugin, MCP, AGENTS.md y Subagent. Después puedes empezar con un árbol mínimo de Skill y avanzar hacia el diseño de un role-specific plugin, el modelo de distribución del equipo y la checklist de límites de permisos.

1. Workflows de equipo copiados y pegados: el problema no es el prompt

La revisión de código, los checks antes de release, los flujos de test y las actualizaciones de documentación suelen tener una forma estable dentro del equipo. Quizá ya pegas en Codex, en cada revisión de PR, algo como: “comprueba si falta changelog, si bajó la cobertura y si hay que actualizar la documentación de la API”. Los problemas aparecen enseguida:

• El mantenimiento queda disperso: cuando cambia la checklist, toca actualizar cinco .github/PULL_REQUEST_TEMPLATE.md o varios archivos de prompts.
• La calidad de ejecución varía: Codex reconstruye el proceso desde cero cada vez y puede saltarse pasos importantes como “ejecutar primero los tests que fallan”.
• Las responsabilidades se mezclan: frontend, QA, seguridad y documentación terminan apilados en un solo prompt, y Codex tiene más dificultad para elegir el estándar correcto.

Algunos equipos escriben todo esto en AGENTS.md. Eso trae otro problema: el archivo de reglas del proyecto crece demasiado. Comandos permanentes de build, convenciones de carpetas e instrucciones temporales de proceso quedan mezcladas. El archivo acaba haciendo más de lo que debería como fuente de restricciones duraderas.

Codex ofrece una separación más clara: AGENTS.md para reglas permanentes, Skills para workflows reutilizables y Plugins para distribución. Lo importante es saber qué va en cada capa.

2. Una tabla para distinguir Skill, Plugin, MCP y AGENTS.md

Un Skill es un formato de autor para workflows reutilizables, normalmente un archivo SKILL.md con scripts, referencias y assets opcionales. Un Plugin es una unidad instalable de Codex que puede empaquetar Skills, integraciones de apps, MCP servers y assets. MCP es el protocolo para conectar herramientas externas y contexto, como documentación de terceros, navegador, Figma o GitHub. AGENTS.md guarda restricciones permanentes del proyecto: comandos de build, convenciones de directorios y expectativas de revisión. Un Subagent delega un rol para tareas ruidosas o especializadas.

Cuándo elegir cada opción

Tipo de contenido	Opción adecuada	Caso típico	No lo uses para
Comandos de build, rutas de scripts de test, convenciones de directorios	AGENTS.md	”Todos los componentes nuevos van en src/components/”, “los tests se ejecutan con npm run test:unit”	Procesos de varios pasos, ejemplos, llamadas a herramientas externas
Workflows de varios pasos con ejemplos, scripts o referencias	Skill	Revisión de código en 10 pasos, checklist de release de 7 puntos, generación de docs API	Una sola orden o una regla de una línea
Distribución de equipo y empaquetado de configuración app/MCP	Plugin	Plugin de rol frontend con 4 Skills de revisión y un Figma connector	Un workflow que solo se itera en un repositorio y no se comparte
Llamadas a herramientas externas y contexto de terceros	MCP	Conectar Figma para leer specs, usar la API de GitHub para issues	Definición pura de workflow sin datos externos
Delegación de tareas ruidosas o especializadas	Subagent	Encargar diagnóstico de tests o análisis de logs a un agent dedicado	Procesos simples que caben en la conversación principal

Cuándo extraer algo de AGENTS.md a un Skill

Estas señales indican que el proceso ya superó el alcance de un archivo de reglas de proyecto:

• La misma checklist aparece en varios PR y se copia manualmente cada vez.
• El flujo tiene varios pasos y necesita ejemplos, scripts o referencias externas.
• El flujo tiene un disparador claro, como “antes de release” o “durante la revisión de PR”, en vez de ser una restricción permanente.
• Distintos roles tienen criterios distintos y no conviene meterlos todos en un solo archivo.
• El proceso necesita versionado y notas de cambio, no una edición directa de las reglas del proyecto cada vez.

Cuándo subir un Skill a Plugin

Un Skill basta mientras se itera dentro de un repositorio o workflow personal. Conviene empaquetarlo como Plugin cuando necesitas:

• Compartirlo entre equipos, no solo en una carpeta personal o un único repositorio.
• Empaquetar integraciones de apps, como Figma, GitHub o herramientas CI/CD, o configuración de MCP server.
• Versionado, changelog y mecanismo de actualización, en vez de copiar carpetas de Skill.
• Distribuirlo desde la Plugin Directory de Codex App a workspace members.
• Publicar un paquete estable, no un flujo experimental que cambia a diario.

Un orden práctico: fija las convenciones del repositorio en AGENTS.md; instala un Plugin existente si encaja; si no, crea un Skill; conviértelo en Plugin cuando la distribución sea real; agrega MCP solo cuando necesites un sistema externo; usa Subagent cuando la tarea sea lo bastante ruidosa o especializada.

3. Skill mínimo útil: empezar por revisión de código

Árbol mínimo de Skill

Un Skill necesita al menos esto:

.agents/skills/code-review/
├── SKILL.md
├── references/
│   └── security-checklist.md
└── scripts/
    └── run-failed-tests.sh

El nombre del directorio y el name en el frontmatter de SKILL.md deben coincidir. El formato es lowercase alphanumeric + hyphen.

Ejemplo de SKILL.md: Skill de revisión de código

---
name: code-review
description: Use for pull request reviews in frontend projects. Checks changelog, test coverage, security boundary, and API docs. Do not use for backend-only changes or infrastructure PRs.
---

# Code Review Checklist

## Before Starting
1. Run failed tests first: `npm run test:failed`
2. Check if PR has clear description and scope

## Review Steps
1. Changelog: Does `CHANGELOG.md` need update?
2. Test Coverage: Did coverage decrease? Check report in `coverage/`
3. Security: Review changes in `src/auth/`, `src/api/`, and `src/middleware/`
4. API Docs: If API changed, update `docs/api.md`

## Security Boundary Checks
See `references/security-checklist.md` for detailed items.

## Failed Test Runner
Use `scripts/run-failed-tests.sh` to rerun previously failed tests.

Diseñar el disparador en description: before/after

Codex usa la description para decidir cuándo invocar un Skill de forma implícita. Si es demasiado vaga, puede dispararse de más o no dispararse:

Before, fácil de activar mal	After, más fiable
”Code review skill for frontend projects"	"Use for pull request reviews in frontend projects. Checks changelog, test coverage, security boundary, and API docs."
"Help review code"	"Use when reviewing PRs with frontend changes. Do not use for backend-only changes or infrastructure PRs."
"Review checklist"	"Trigger on: PR reviews, code audit requests. Exclude: backend changes, config-only updates.”

La clave es escribir “Use when…” y “Do not use when…” con límites claros. Pon palabras como pull request, review y frontend al principio, porque las descripciones largas pueden truncarse. Si quieres invocación solo explícita, configura allow_implicit_invocation: false.

Ubicación y alcance de un Skill

Ubicación	Alcance	Uso recomendado	Notas
.agents/skills/ en la raíz del repositorio	Repositorio actual	Procesos de revisión, test y release del equipo	Se versiona en Git y se comparte con el equipo
$HOME/.agents/skills/	Personal, multi-proyecto	Estilo personal y comandos frecuentes	No se sincroniza automáticamente con el repositorio
/etc/codex/skills/	Organización	Revisiones uniformes de seguridad o cumplimiento	Requiere permisos de admin
System bundled	Integrado	Skills como $skill-creator y $skill-installer	No se puede modificar

Los Skills con el mismo nombre no se combinan. La prioridad suele ser repo > user > admin > system, pero si el comportamiento cambia, la documentación oficial manda.

Diseño con progressive disclosure

No metas todo en el SKILL.md principal. Codex usa progressive disclosure en tres capas:

1. Metadata: al inicio ve solo name, description y file path.
2. Instructions: el SKILL.md completo se carga solo cuando el Skill se selecciona.
3. Resources: references/, scripts/ y assets/ se leen solo cuando hacen falta.

Como regla práctica, mantén el SKILL.md principal por debajo de 500 líneas. Las referencias largas van en archivos separados. scripts/ debe contener validaciones deterministas, como un runner de tests o una comprobación de cobertura. references/ es para checklists detalladas, contexto y casos históricos. assets/ es para plantillas y capturas de ejemplo.

Invocación explícita e implícita

La invocación explícita usa $code-review o el selector /skills. La implícita deja que Codex decida, por la description, si el Skill encaja con la tarea. Para desactivarla, define allow_implicit_invocation: false en agents/openai.yaml.

La invocación implícita encaja con flujos frecuentes y bien delimitados, como revisar cada PR. La explícita es más segura para tareas poco frecuentes que requieren criterio humano, como una auditoría de seguridad trimestral. Si un Skill incluye scripts externos u operaciones sensibles, prioriza la invocación explícita.

4. Empaquetado de Plugin y distribución de equipo: de Skill local a suite de equipo

Estructura mínima de un Plugin

Un Plugin no es solo renombrar un directorio de Skill. Es un paquete instalable y necesita al menos un manifest .codex-plugin/plugin.json:

.agents/plugins/frontend-review/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── code-review/
│   │   └── SKILL.md
│   ├── accessibility-check/
│   │   └── SKILL.md
│   └── performance-lint/
│       └── SKILL.md
├── assets/
│   └── templates/
└── README.md

Campos obligatorios de plugin.json

{
  "name": "frontend-review",
  "version": "1.0.0",
  "description": "Frontend team code review and accessibility check skills",
  "skills": "./skills/",
  "assets": "./assets/",
  "author": "frontend-team",
  "repository": "https://github.com/org/frontend-review-plugin"
}

Los campos opcionales incluyen apps para integraciones como .app.json for Figma, mcpServers para configuración de MCP server como .mcp.json, y policy para permisos y políticas de datos, siempre sujeto a la workspace admin policy.

Estructura de marketplace: directorio de Plugins del equipo

Un Plugin marketplace es una lista JSON que apunta a ubicaciones de Plugins:

.agents/plugins/marketplace.json

{
  "plugins": [
    {
      "source": "local",
      "path": "./frontend-review"
    },
    {
      "source": "github",
      "owner": "openai",
      "repo": "role-specific-plugins",
      "ref": "main",
      "path": "plugins/data-analytics"
    }
  ]
}

local sirve para Plugins internos aún no publicados. github apunta a repositorios públicos o paquetes compartidos entre equipos.

Checklist de comandos para distribuir Plugins

Los comandos CLI pueden cambiar, así que usa la documentación oficial como referencia:

# Crear el scaffold de un Plugin nuevo
codex plugin create frontend-review

# Agregar un Plugin al marketplace
codex plugin marketplace add owner/repo --ref main --sparse

# Listar Plugins instalados
codex plugin marketplace list

# Actualizar un Plugin
codex plugin marketplace upgrade frontend-review

# Eliminar un Plugin
codex plugin marketplace remove frontend-review

En Codex App, la Plugin Directory puede mostrar Curated by OpenAI, Shared with you y Created by you. Un local plugin puede compartirse con workspace members o groups. Los workspace admins pueden desactivar plugin sharing o definir managed requirements.

Compartirlo en el workspace no equivale a publicarlo. Las conexiones a apps externas y MCP servers siguen necesitando autorización, y los approval settings siguen aplicando.

Organización del marketplace del equipo

Pon el marketplace del repositorio en $REPO_ROOT/.agents/plugins/marketplace.json para Plugins específicos del proyecto. Para Plugins de organización, usa $HOME/.agents/plugins/marketplace.json o un repositorio de GitHub organization. Declara la versión en el manifest, mantén un changelog en README y valida las actualizaciones en un entorno de prueba. Los Plugins sensibles, como seguridad o cumplimiento, conviene mantenerlos a nivel de organización para evitar instalaciones improvisadas.

Primero itera con un local skill. Cuando esté estable, empaquétalo como Plugin. Empezar por el Plugin suele hacer más difícil ajustar el workflow.

5. Diseño de role-specific Plugin: fijar frontend, QA y documentación

El repositorio role-specific-plugins de OpenAI trae plantillas para Sales, Data Analytics, Product Design y Financial Markets. Un equipo de desarrollo no necesita copiar flujos de ventas o finanzas, pero sí puede aprovechar el patrón de descomposición: partir de un rol, dividirlo en 3 a 5 Skills pequeños y empaquetarlos como Plugin.

Marco de descomposición: rol → entregables repetidos → fuentes de datos/herramientas → Skills pequeños → forma de compartir

Rol	Entregable repetido	Fuente de datos/herramientas	Skills a separar	Apps/MCP posibles	Criterio de aceptación
Ingeniero frontend	Revisión de componentes, performance, accesibilidad	Specs Figma, biblioteca Storybook existente	component-audit, accessibility-check, performance-lint, design-system-sync	Figma connector, Storybook MCP	Cada componente nuevo pasa los 4 checks
Ingeniero QA	Reporte de cobertura, diagnóstico E2E, checklist de regresión	Resultados CI/CD, historial de fallos	test-coverage-check, e2e-suite-runner, flaky-test-diagnosis, regression-suite-builder	Herramientas CI/CD como GitHub Actions/Jenkins	Tests fallidos primero, sin caída de cobertura
Redactor técnico	Actualización API docs, changelog, guías de migración	API schema, Git commit history	api-doc-generator, changelog-builder, readme-audit, migration-guide-writer	GitHub API, herramientas de schema	La documentación se actualiza cuando cambia la API
Ingeniero de seguridad	Revisión de permisos, secrets scan, seguridad de dependencias	Manifests de dependencias, configuración de secrets	auth-boundary-check, secrets-scan, dependency-security	Snyk, Dependabot MCP	Checklist de seguridad antes de cada release

Ejemplo de descomposición para un Plugin de rol frontend

frontend-engineer-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── component-audit/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── component-template.md
│   ├── accessibility-check/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── axe-audit.sh
│   ├── performance-lint/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── lighthouse-check.sh
│   └── design-system-sync/
│       ├── SKILL.md
│       └── references/
│           └── design-tokens.md
├── assets/
│   └── templates/
│       └── component-template.tsx
└── README.md

component-audit revisa si un componente nuevo cumple las normas del equipo: nombre, carpeta, tipos de props. accessibility-check ejecuta un script con axe-core. performance-lint revisa métricas clave con Lighthouse. design-system-sync compara la implementación con las especificaciones de Figma.

Ejemplo de descomposición para un Plugin de rol QA

qa-engineer-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── test-coverage-check/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── coverage-threshold-check.sh
│   ├── e2e-suite-runner/
│   │   └── SKILL.md
│   ├── flaky-test-diagnosis/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── flaky-test-log-analysis.md
│   └── regression-suite-builder/
│       └── SKILL.md
├── .mcp.json
└── README.md

test-coverage-check detecta si baja la cobertura y marca archivos sin cubrir. e2e-suite-runner ejecuta tests E2E por prioridad. flaky-test-diagnosis analiza logs históricos para encontrar tests inestables. regression-suite-builder crea una checklist de regresión a partir del alcance del cambio.

Checklist para reemplazar connector placeholders

Las plantillas oficiales pueden traer connector IDs placeholder en .app.json. Hay que reemplazarlos antes de instalar:

{
  "app_id": "figma-placeholder"
}

Revisa todos los placeholder IDs en .app.json y reemplázalos por IDs reales disponibles en tu workspace. No copies connector IDs de otro workspace: pueden ser inválidos o no tener permisos. Los tokens OAuth/Bearer de MCP server configuration deben configurarse para tu entorno, no usar ejemplos de plantilla. Después, valida el connector en un entorno de prueba.

El README oficial de role-specific-plugins explica que esas plantillas deben personalizarse antes de usarse. Los connector-backed plugins pueden incluir app IDs o connector IDs que hay que reemplazar.

6. Seguridad y mantenimiento: un Plugin no es un pase de permisos

Límites de permisos de Connector / MCP

Instalar un Plugin no evita los approval settings de Codex. Las apps externas y MCP servers siguen requiriendo autorización, y el intercambio de datos sigue sujeto a sus políticas. Los placeholder IDs en .app.json deben reemplazarse, pero no copies connector IDs de otro workspace. Apps externas como Figma o GitHub requieren autorización separada. El Plugin empaqueta configuración; no concede autorización. MCP servers siguen gobernados por enabled y tool policy en config.toml. Approval mode también aplica: si está en “suggest-only”, los scripts del Plugin no se ejecutan automáticamente.

No trates un Plugin como un pase de permisos. Empaqueta workflow, configuración y assets, pero el límite de permisos sigue existiendo.

Revisión del origen de scripts

La carpeta scripts/ de un Skill o Plugin puede contener ejecutables. Los Plugins de terceros o marketplaces comunitarios requieren revisión: inspecciona todos los ejecutables bajo scripts, confirma el origen, evita ejecutar scripts de repositorios no verificados, prueba primero en un entorno de prueba y fija versiones con tag o commit hash en vez de tomar siempre lo último de main.

El mismo principio que aplica a Skills de terceros con riesgo aplica a cualquier script ejecutable y Plugin externo: revisar origen, minimizar permisos y validar en un entorno de prueba.

Versiones y changelog

La colaboración en equipo necesita versionado. Declara version en plugin.json y súbela en cada cambio. Mantén un changelog en README para explicar Skills añadidos, modificados o retirados. Antes de actualizar, prueba en un entorno de prueba, ejecuta todos los Skills, verifica scripts y confirma que los connectors siguen disponibles. En marketplace entries, fija ref a un tag o commit, no al main más reciente.

Impacto de la cantidad de Skills y Plugins

La lista inicial de Skills tiene presupuesto de contexto. La documentación oficial indica que la initial skills list ocupa aproximadamente 2% del contexto, o 8.000 characters cuando el tamaño del contexto es desconocido.

En la práctica, una description demasiado larga puede truncarse, así que los términos clave deben ir al principio. Cargar demasiados Skills también puede dificultar que Codex elija el correcto. Los Skills frecuentes y bien delimitados encajan en el directorio repo o user. Los Skills poco frecuentes pueden ir en un Plugin que instalas solo cuando hace falta, en vez de mantener todo siempre activo.

Si Codex activa el Skill equivocado o no activa el correcto, revisa primero la description. No intentes resolverlo agregando más Skills.

7. Comparación con tecnologías relacionadas

Comparación con Claude Code Skills

BetterLink ya cubrió antes el mecanismo de Claude Code Skills. El modelo mental es parecido, pero los productos son distintos: ambos usan el formato abierto Agent Skills y un archivo SKILL.md; ambos usan name, description y opcionalmente scripts/, references/, assets/; ambos soportan progressive disclosure: metadata → instructions → resources.

Las diferencias importan. Codex usa .agents/skills/; Claude Code usa .claude/skills/. Codex se invoca con $skill-name o /skills; Claude Code usa el comando /skill. En distribución, Codex Plugin tiene marketplace, comandos CLI y workspace sharing; Claude Code no tiene hoy un Plugin marketplace oficial. Las herramientas integradas también cambian: Codex tiene $skill-creator, $skill-installer y @plugin-creator; Claude Code tiene sus propios comandos.

Si ya escribiste Claude Code Skills, puedes reutilizar el modelo mental. No copies rutas ni sintaxis de invocación; sigue la documentación oficial de cada producto.

Relación con MCP

MCP, Model Context Protocol, conecta herramientas externas y contexto. No reemplaza a Skills ni Plugins. Un Skill define el workflow. MCP conecta la herramienta externa, como Figma, GitHub o un sistema CI/CD. Un Plugin puede empaquetar configuración de MCP server, pero el MCP server sigue controlado por config.toml.

Ejemplo: un Skill de revisión frontend define el proceso “comprobar si el componente respeta el sistema de diseño”; un Figma MCP server da acceso al archivo de diseño; un Plugin frontend empaqueta el Skill de revisión y la configuración de Figma MCP, pero Figma OAuth necesita autorización separada.

Aquí solo aclaramos la frontera. Una guía práctica sobre Codex MCP tools puede profundizar en la implementación.

Conclusión

Codex Skills y Plugins sirven para sacar workflows repetidos del equipo de prompts copiados y de un AGENTS.md sobrecargado. La regla es simple: AGENTS.md para reglas permanentes, Skill para workflows de varios pasos, Plugin para empaquetado y distribución, MCP para sistemas externos. Escribe condiciones claras en la description, valida primero un local skill y conviértelo en Plugin solo cuando la distribución sea real. Los scripts, connector IDs y configuraciones MCP de Plugins de terceros siguen necesitando revisión.

Empieza con un Skill mínimo. Convierte el proceso de revisión de código o tests de tu equipo en SKILL.md, ejecútalo varias veces y comprueba si el disparador es fiable. Si tu equipo tiene roles frontend, QA, seguridad o documentación, toma el patrón de OpenAI role-specific-plugins: 3 a 5 Skills pequeños por rol y después un Plugin de rol.

Lecturas relacionadas en BetterLink:

• Guía completa para empezar con Codex
• Reglas de proyecto AGENTS.md
• Límites de seguridad y permisos en Codex
• Codex MCP tools en la práctica
• Comparación con Claude Code Skill
• Bases del protocolo MCP