Personalización

La personalización permite adaptar Codex a la forma de trabajar de tu equipo.

En Codex, la personalización se compone de varias capas que funcionan en conjunto:

• Directrices del proyecto (AGENTS.md) para instrucciones persistentes
• Memorias para conservar contexto útil aprendido de trabajos anteriores
• Habilidades para flujos de trabajo reutilizables y conocimientos especializados
• MCP para acceder a herramientas externas y sistemas compartidos
• Subagentes para delegar trabajo en subagentes especializados

Estas capas se complementan, no compiten entre sí. AGENTS.md define el comportamiento, las memorias permiten reutilizar el contexto local, las habilidades encapsulan procesos repetibles y MCP conecta Codex con sistemas externos al espacio de trabajo local.

Directrices de AGENTS

AGENTS.md proporciona a Codex directrices duraderas del proyecto que se incluyen en el repositorio y se aplican antes de que el agente empiece a trabajar. Procura que sean breves.

Úsalo para las reglas que quieres que Codex siga siempre en un repositorio, como:

• Comandos de compilación y pruebas
• Criterios de revisión
• Convenciones específicas del repositorio
• Instrucciones específicas de cada directorio

Cuando el agente haga suposiciones incorrectas sobre tu código base, corrígelas en AGENTS.md y pídele que actualice AGENTS.md para que la corrección persista. Trátalo como un ciclo de retroalimentación.

Cuándo actualizar AGENTS.md

• Errores repetidos: Si el agente comete el mismo error repetidamente, añade una regla.
• Demasiada lectura: Si encuentra los archivos correctos, pero lee demasiados documentos, añade directrices de selección (qué directorios o archivos debe priorizar).
• Comentarios recurrentes en PR: Si haces el mismo comentario más de una vez, codifícalo.
• En GitHub: En un comentario de una solicitud de incorporación de cambios, etiqueta a @codex con una solicitud (por ejemplo, @codex add this to AGENTS.md) para delegar la actualización en un chat en la nube.
• Automatizar las comprobaciones de desviaciones: Usa tareas programadas para ejecutar comprobaciones recurrentes (por ejemplo, a diario) que detecten deficiencias en las directrices y sugieran qué añadir a AGENTS.md.

Combina AGENTS.md con infraestructura que aplique esas reglas: los hooks de pre-commit, los linters y los comprobadores de tipos detectan los problemas antes de que los veas, por lo que el sistema mejora progresivamente su capacidad para prevenir errores recurrentes.

Codex puede cargar directrices desde varias ubicaciones: un archivo global en tu directorio principal de Codex (para ti como desarrollador) y archivos específicos del repositorio que los equipos pueden incorporar al control de versiones. Los archivos más cercanos al directorio de trabajo tienen prioridad. Usa el archivo global para definir cómo se comunica Codex contigo (por ejemplo, el estilo de revisión, el nivel de detalle y los valores predeterminados) y mantén los archivos del repositorio centrados en las reglas del equipo y del código base.

<FileTree class="mt-4" tree={[ { name: "~/.codex/", open: true, children: [ { name: "AGENTS.md", comment: "Global (para ti como desarrollador)" }, ], }, { name: "repo-root/", open: true, children: [ { name: "AGENTS.md", comment: "Específico del repositorio (para tu equipo)" }, ], }, ]} />

Instrucciones personalizadas con AGENTS.md

Habilidades

Las habilidades proporcionan a Codex capacidades reutilizables para flujos de trabajo repetibles. Las habilidades suelen ser la opción más adecuada para los flujos de trabajo reutilizables porque admiten instrucciones, scripts y referencias más completas, a la vez que pueden reutilizarse en distintas tareas. Las habilidades se cargan y son visibles para el agente (al menos sus metadatos), por lo que Codex puede descubrirlas y seleccionarlas de forma implícita. De este modo, los flujos de trabajo completos permanecen disponibles sin sobrecargar el contexto desde el principio.

Usa carpetas de habilidades para crear e iterar flujos de trabajo localmente. Si ya existe un plugin para el flujo de trabajo, instálalo primero para reutilizar una configuración probada. Cuando quieras distribuir tu propio flujo de trabajo entre equipos o agruparlo con conectores, empaquétalo como un plugin. Las habilidades siguen siendo el formato de creación; los plugins son la unidad de distribución instalable.

Una habilidad suele constar de un archivo SKILL.md, además de scripts, referencias y recursos opcionales.

<FileTree class="mt-4" tree={[ { name: "my-skill/", open: true, children: [ { name: "SKILL.md", comment: "Obligatorio: instrucciones y metadatos" }, { name: "scripts/", comment: "Opcional: código ejecutable" }, { name: "references/", comment: "Opcional: documentación" }, { name: "assets/", comment: "Opcional: plantillas y recursos" }, ], }, ]} />

El directorio de la habilidad puede incluir una carpeta scripts/ con scripts de CLI que Codex invoca como parte del flujo de trabajo (por ejemplo, para cargar datos iniciales o ejecutar validaciones). Cuando el flujo de trabajo necesite sistemas externos (gestores de incidencias, herramientas de diseño o servidores de documentación), combina la habilidad con MCP.

Ejemplo de SKILL.md:

---
name: commit
description: Stage and commit changes in semantic groups. Use when the user wants to commit, organize commits, or clean up a branch before pushing.
---

1. Do not run `git add .`. Stage files in logical groups by purpose.
2. Group into separate commits: feat → test → docs → refactor → chore.
3. Write concise commit messages that match the change scope.
4. Keep each commit focused and reviewable.

Usa habilidades para:

• Flujos de trabajo repetibles (pasos de publicación, rutinas de revisión y actualizaciones de documentación)
• Conocimientos especializados del equipo
• Procedimientos que necesitan ejemplos, referencias o scripts auxiliares

Las habilidades pueden ser globales (en tu directorio de usuario, para ti como desarrollador) o específicas del repositorio (incorporadas a .agents/skills, para tu equipo). Coloca las habilidades del repositorio en .agents/skills cuando el flujo de trabajo se aplique a ese proyecto; usa tu directorio de usuario para las habilidades que quieras utilizar en todos los repositorios.

Codex usa la divulgación progresiva para las habilidades:

• Empieza con los metadatos (name, description) para descubrirlas
• Solo carga SKILL.md cuando se selecciona una habilidad
• Solo lee referencias o ejecuta scripts cuando es necesario

Las habilidades pueden invocarse de forma explícita y Codex también puede seleccionarlas de forma implícita cuando la tarea coincide con la descripción de la habilidad. Las descripciones claras de las habilidades mejoran la fiabilidad de su activación.

Crear habilidades

MCP

MCP (Model Context Protocol) es la forma estándar de conectar Codex con herramientas externas y proveedores de contexto. Resulta especialmente útil para sistemas alojados de forma remota, como Figma, Linear, GitHub o servicios internos de conocimiento de los que depende tu equipo.

Usa MCP cuando Codex necesite capacidades que se encuentren fuera del repositorio local, como gestores de incidencias, herramientas de diseño, navegadores o sistemas compartidos de documentación.

Una forma de entenderlo es la siguiente:

• Host: Codex
• Cliente: la conexión MCP dentro de Codex
• Servidor: la herramienta externa o el proveedor de contexto

Los servidores MCP pueden exponer:

• Herramientas (acciones)
• Recursos (datos legibles)
• Prompts (plantillas reutilizables de prompts)

Esta separación permite razonar mejor sobre los límites de confianza y capacidad. Algunos servidores proporcionan principalmente contexto, mientras que otros exponen acciones potentes.

En la práctica, MCP suele ser más útil cuando se combina con habilidades:

• Una habilidad define el flujo de trabajo e indica qué herramientas MCP se deben usar

Model Context Protocol

Subagentes

Puedes crear distintos agentes con diferentes roles e indicarles que usen las herramientas de formas distintas. Por ejemplo, un agente podría ejecutar comandos y configuraciones de prueba específicos, mientras que otro dispone de servidores MCP que obtienen registros de producción para la depuración. Cada subagente se mantiene centrado y usa las herramientas adecuadas para su trabajo.

Subagentes

Habilidades + MCP en conjunto

La combinación de habilidades y MCP es donde todo converge: las habilidades definen flujos de trabajo repetibles y MCP los conecta con herramientas y sistemas externos. Si una habilidad depende de MCP, declara esa dependencia en agents/openai.yaml para que Codex pueda instalarlo y configurarlo automáticamente (consulta Crear habilidades).

Siguiente paso

Configura estos elementos en el siguiente orden:

1. Instrucciones personalizadas con AGENTS.md para que Codex siga las convenciones de tu repositorio. Añade hooks de pre-commit y linters para aplicar esas reglas.
2. Instala un plugin cuando ya exista un flujo de trabajo reutilizable. De lo contrario, crea una habilidad y empaquétala como plugin cuando quieras compartirla.
3. Usa MCP cuando los flujos de trabajo necesiten sistemas externos (Linear, GitHub, servidores de documentación o herramientas de diseño).
4. Usa subagentes cuando tengas todo listo para delegar tareas ruidosas o especializadas en subagentes.