Codex Skill Configuration

Qué se configura en una skill

Una skill empaqueta un procedimiento, instrucciones y recursos para tareas recurrentes. Esta guía aplica ese concepto a Codex con documentación consultada el 2026-11-09. agent-skills conserva la definición general; codex-agent-configuration describe el perfil de un participante que puede utilizar skills.

La guía oficial de creación de skills requiere un directorio con SKILL.md, incluyendo name y description. Codex descubre skills de repositorio bajo .agents/skills y puede seleccionarlas por su descripción o mediante invocación explícita. La ubicación de descubrimiento y el procedimiento son decisiones diferentes de los permisos de ejecución.

Ejemplo mínimo de repositorio

Una skill ilustrativa podría organizarse así:

.agents/skills/review-atlas-document/
└── SKILL.md

Contenido propuesto para ese archivo:

---
name: review-atlas-document
description: Revisa documentos de conocimiento asignados para detectar contradicciones y afirmaciones sin evidencia.
---
 
Recibe los documentos y la pregunta de revisión.
Lee sus fuentes relevantes y distingue hallazgos de dudas pendientes.
Devuelve ubicaciones, razones y límites de la revisión.
Conserva el alcance del encargo; no publiques cambios.

El nombre de directorio y skill coincide para facilitar descubrimiento y mantenimiento. La descripción debe permitir decidir cuándo usar el procedimiento; el cuerpo aporta lo que no conviene repetir en cada encargo. No hacen falta scripts, plantillas ni referencias vacías para completar una estructura.

Si una tarea requiere una guía extensa o recursos concretos, agregarlos solo cuando aporten valor y enlazarlos desde SKILL.md. El objetivo es que puedan recuperarse al necesitarlos, sin cargar siempre todo su contenido.

Activación, disponibilidad y scope

Una invocación explícita ilustrativa es:

$review-atlas-document Revisá estos dos documentos contra su criterio de aceptación.

La existencia del archivo no demuestra que esa sesión lo haya descubierto o seleccionado. Comprobar qué skill está disponible y qué instrucciones se cargaron. Si falta, revisar directorio, metadata y compatibilidad del cliente antes de atribuir el problema al modelo.

La documentación también admite metadata opcional en agents/openai.yaml, por ejemplo para presentación y dependencias. Esa metadata no sustituye el archivo principal ni define por sí sola permisos de lectura, escritura o acceso a un servicio.

Habilitar o deshabilitar una skill

Como ejemplo para la configuración de usuario ~/.codex/config.toml, la guía oficial documenta selectores de skills.config. Este fragmento utiliza un nombre ficticio:

[[skills.config]]
name = "review-atlas-document"
enabled = false

El selector por nombre afecta a las skills con ese nombre; un selector por ruta permite identificar un archivo concreto. No mezclar ambos en la misma entrada. Cambiar disponibilidad sirve para controlar qué procedimiento se ofrece, no para convertirlo en una identidad con privilegios propios.

Antes de deshabilitar una skill compartida, identificar quién la utiliza y qué procedimiento dejará de estar disponible. Rehabilitarla requiere volver a revisar su contenido y recursos si cambiaron; no supone que cualquier nueva acción esté autorizada.

Lectura, escritura y herramientas

Escribir «solo lectura» dentro de SKILL.md comunica una restricción de conducta. La aplicación técnica de filesystem, comandos, red y aprobaciones corresponde a los controles descritos en codex-permissions-and-approvals-configuration. Una skill de edición necesita una sesión que permita la modificación autorizada; no puede concederse acceso ampliado a sí misma mediante texto.

Un script incluido hereda las condiciones de ejecución que realmente le provea el entorno. Una dependencia MCP necesita configuración y autorización propias. Identificar qué datos salen, qué efectos ocurren y quién puede autorizarlos sigue siendo necesario aunque el procedimiento sea reutilizable.

Verificación propuesta

En un entorno de prueba, comprobar descubrimiento e invocación sobre un documento sintético. Observar si el procedimiento solicita fuentes pertinentes y devuelve evidencia útil. Para una skill de edición, revisar el diff y sus checks; para una de lectura, probar además el control técnico que impide escrituras cuando esa propiedad sea necesaria.

La validación sintáctica del frontmatter no demuestra que la skill tome buenas decisiones. Usar casos donde deba detectar una contradicción y otros donde deba reconocer insuficiencia de evidencia. No se ejecutó ni instaló esta skill de ejemplo. coding-agent-prompting-and-context-recipes y ai-technology-catalog ofrecen los recorridos relacionados.