Codex Skills: creación, ejecución y verificación en una tarea de code review

El mecanismo de Skills en Codex

El mecanismo de habilidades (skills), descrito en la documentación oficial, incorpora al agente instrucciones y plantillas para tareas especializadas sin sobrecargar el contexto del sistema.

Un skill consiste en un directorio con un archivo obligatorio SKILL.md. En su frontmatter YAML son obligatorios los campos name y description, mientras que el cuerpo contiene las reglas para el modelo:

.agents/skills/boundary-review/
└── SKILL.md

Codex utiliza divulgación progresiva (progressive disclosure): al inicio se genera un índice compacto de los skills disponibles. El texto completo de SKILL.md es leído por el agente únicamente en el momento en que decide aplicar un skill específico.

El descubrimiento de skills opera en cuatro niveles:

1. Repositorio (REPO): .agents/skills en el directorio actual y hacia arriba hasta la raíz de Git.
2. Usuario (USER): $HOME/.agents/skills.
3. Administrador (ADMIN): /etc/codex/skills.
4. Sistema (SYSTEM): directorios del sistema del entorno (empaquetados o bundled).

La invocación se realiza de forma explícita (mediante el prefijo $name) o implícita (según la coincidencia semántica entre la petición y el campo description). La disponibilidad y los conflictos se gestionan en el archivo config.toml.

Requisitos previos y aislamiento

Para reproducir este escenario, se requiere:

• Python 3;
• Una interfaz de línea de comandos Codex CLI instalada y autorizada.

Los datos de prueba se registraron el 2026-09-16 utilizando la versión 0.153.3 de Codex CLI.

Todos los comandos se ejecutan en un directorio local preparado fuera de un repositorio Git. Dado que las instrucciones textuales en SKILL.md orientan el comportamiento del modelo pero no garantizan el aislamiento del sistema operativo, las ejecuciones se realizan con los siguientes modificadores:

• --ephemeral: evita que se guarde el estado de la sesión;
• --skip-git-repo-check: permite la ejecución en una carpeta aislada sin Git;
• --sandbox read-only: restringe el acceso de escritura del proceso al nivel del entorno de ejecución.

La CLI puede heredar configuraciones globales y emitir advertencias de servicio sobre hooks de terceros, por lo que la verificación real se basa estrictamente en los eventos de lectura del skill objetivo.

Creación del skill boundary-review

Cree el directorio del skill en la carpeta actual:

mkdir -p .agents/skills/boundary-review

Guarde el siguiente contenido en .agents/skills/boundary-review/SKILL.md:

---
name: boundary-review
description: Review Python pagination code for boundary errors and show one minimal failing input. Use when asked to review pagination boundaries.
---
Read the provided Python file. Do not edit it. Begin your answer with BOUNDARY_REVIEW. Report a specific failing input, expected and actual result, and a minimal correction. Do not inspect files outside this project.

La instrucción textual prohíbe al modelo modificar archivos y le exige comenzar su respuesta con el marcador de señal BOUNDARY_REVIEW, indicando obligatoriamente un valor de entrada con fallo.

Archivo de prueba con defecto

Cree un archivo pages.py con el típico error de desfase por uno al calcular la cantidad de páginas:

def page_count(total, size):
    return total // size + 1

Bajo las condiciones size > 0 y total >= 0, la función falla en los valores límite: con total = 1 y size = 1, devuelve 2 en lugar de 1. Además, para una lista vacía con total = 0, la función devolverá 1.

Ejecución y verificación de invocaciones

Las consultas se pasan entre comillas simples para evitar que el intérprete de comandos interprete el símbolo $ como una variable de entorno.

1. Invocación explícita por nombre

Ejecute una comprobación explícita especificando directamente el skill:

codex exec --ephemeral --skip-git-repo-check --sandbox read-only 'Review pages.py using $boundary-review'

El modelo devuelve el resultado:

BOUNDARY_REVIEW

Failing input:
page_count(1, 1)

Expected result: 1
Actual result: 2

Minimal correction:
def page_count(total, size):
    return (total + size - 1) // size

La sola presencia del marcador BOUNDARY_REVIEW no demuestra que SKILL.md se haya cargado, ya que el texto del marcador podría haberse generado a partir del contexto de la petición. En la ejecución real del 2026-09-16, el registro del sistema registró un evento de comando que leía el archivo .agents/skills/boundary-review/SKILL.md. La combinación del evento de lectura de archivo en el registro, el prefijo BOUNDARY_REVIEW y el contraejemplo page_count(1, 1) confirma la ejecución de la instrucción objetivo.

2. Invocación implícita por descripción

Formule la tarea en lenguaje natural sin mencionar el identificador $boundary-review:

codex exec --ephemeral --skip-git-repo-check --sandbox read-only 'Review the pagination boundaries in pages.py'

El registro de esta ejecución también grabó la lectura de .agents/skills/boundary-review/SKILL.md, activada por la coincidencia semántica entre la frase de la consulta y el campo description. El agente generó una respuesta estructurada similar con el marcador BOUNDARY_REVIEW y un análisis del fallo en la entrada (1, 1).

Verificación de la lógica y pasos para el lector

Comprobemos el comportamiento original de la función mediante el intérprete local de Python:

python3 -c "from pages import page_count; print(page_count(1, 1))"

El comando imprime 2, confirmando la presencia del defecto.

Durante la ejecución de referencia del 2026-09-16, el archivo original pages.py se mantuvo sin modificaciones; no se realizó una nueva ejecución de la CLI sobre el archivo modificado. La corrección matemática de la fórmula propuesta (total + size - 1) // size para total >= 0 y size > 0 se verificó en los conjuntos de valores límite:

• (0, 10) -> 0;
• (1, 1) -> 1;
• (10, 10) -> 1;
• (11, 10) -> 2.

Para corregirlo manualmente, el lector puede modificar pages.py para que quede así:

def page_count(total, size):
    if total == 0:
        return 0
    return (total + size - 1) // size

Tras guardar los cambios, el lector puede ejecutar una verificación con aserciones:

python3 -c "from pages import page_count; assert page_count(0, 10) == 0; assert page_count(1, 1) == 1; assert page_count(10, 10) == 1; assert page_count(11, 10) == 2; print('OK')"

La salida esperada del comando tras editar manualmente el archivo es OK.

Diagnóstico de problemas

Si un skill no se detecta o no se invoca automáticamente:

1. Ruta del archivo: asegúrese de que la ruta relativa al directorio de trabajo sea exactamente .agents/skills/<skill-name>/SKILL.md.
2. Actualización del registro: si los archivos se agregaron durante una sesión activa, reinicie el proceso de la CLI para volver a escanear los directorios.
3. Bloqueo en la configuración: revise ~/.codex/config.toml. Si el skill fue deshabilitado, una entrada como:

   [[skills.config]]
   path = "/полный/путь/к/.agents/skills/boundary-review/SKILL.md"
   enabled = false

   bloqueará su carga. Elimine el bloque o establezca enabled = true.
4. Conflictos de nombres: si existen valores idénticos de name tanto a nivel de repositorio como de usuario, las reglas de prioridad pueden generar ambigüedad.
5. Precisión de description: para la invocación implícita, los desencadenadores clave (“pagination boundaries”, “boundary errors”) deben ubicarse cerca del inicio de la descripción.
6. Skills de terceros: si se requiere cargar paquetes externos, el punto de entrada es la utilidad $skill-installer. Cualquier skill de terceros exige una auditoría manual obligatoria de sus archivos SKILL.md y del directorio scripts/ antes de su ejecución. En el escenario descrito no se instalaron componentes de terceros.