ask-codex

Skill para invocar al agente de codificación Codex de OpenAI mediante codex exec (modo no interactivo) para consultar sobre diseño e implementación, realizar investigaciones profundas y solicitar revisiones de código.

Codex tiende a investigar de manera persistente para mejorar la precisión, por lo que es adecuado para segundas opiniones o análisis profundos donde la exactitud es crítica.

Codex se inicia en frío cada vez y no conoce la conversación actual, el plan ni los resultados de investigaciones anteriores. Las premisas, intenciones, restricciones y archivos relevantes deben indicarse explícitamente en el prompt cada vez (consulte la sección "Cómo escribir el mensaje de tarea" y los ejemplos a continuación).

Prerrequisitos

La CLI codex debe estar instalada y autenticada (verificar con codex --version).
Si la autenticación ha expirado, se requiere configurar Codex desde el lado del usuario; indíquelo al usuario.

Antes de ejecutar

Informe al usuario con una oración sobre qué consulta va a realizar antes de invocar Codex. No es necesario esperar la aprobación; después de informar, puede ejecutar directamente.

Patrón de invocación básico

Codex actúa como un revisor superior de solo lectura, por lo que se usa -s read-only por defecto. El prompt se pasa a través de stdin (codex exec -) para evitar escapes del shell.

Hay dos prácticas centrales:

Completar la extracción de la respuesta (cat) dentro del mismo comando que invoca Codex. $OUT de OUT=$(mktemp …) desaparece en la siguiente invocación del shell (otro shell), por lo que intentar leerlo con un Read posterior pierde la ruta. Haciendo cat dentro del mismo comando se asegura de obtener la respuesta sin asumir comportamientos.
No enviar stdout/stderr de Codex al contexto. Codex envía los registros de progreso, encabezados, advertencias, hooks, ecos finales y tokens used a stderr, mientras que solo el mensaje final va a stdout y al archivo -o (todo lo que "hizo/pensó" está en stderr). Como solo se necesita la conclusión, se descarta stdout y se redirige stderr a un archivo temporal para mostrarlo solo en caso de error. De esta manera, el resultado de la herramienta contiene solo el mensaje final de cat "$OUT", y las causas de error (como autenticación caducada o banderas inválidas) son visibles solo cuando falla.

Se dividen en dos recetas canónicas según el uso.

A. Consulta corta / revisión pequeña (primer plano)

La respuesta (solo el mensaje final) se devuelve como resultado de la herramienta de ejecución del shell. No se necesita un Read adicional.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' "$PROMPT" | codex exec - -s read-only -C <DIR> -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
cat "$OUT"

B. Invocación larga (segundo plano)

codex exec puede tardar varios minutos, y la ejecución en primer plano podría ser interrumpida según el entorno. Para tareas largas como investigaciones profundas o revisiones de código con codex exec review, se debe enviar al mecanismo de ejecución en segundo plano de su harness (el método de envío depende del harness). El comando en sí usa codex exec - (consulta/investigación) o codex exec review (revisión de diff, ver más abajo).

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' "$PROMPT" | codex exec - -s read-only -C <DIR> -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="
cat "$OUT"

Cuando se completa, el harness emite una notificación de finalización y la salida en segundo plano contiene la respuesta después de === ANSWER ===. Se lee esa salida (si es larga, se puede extraer con Grep a partir de === ANSWER ===). No cree un bucle de sondeo con sleep/pgrep (el harness notifica la finalización).

Significado de las banderas

codex exec -: Lee el prompt desde stdin. Permite pasar de forma segura texto largo, bloques de código y caracteres especiales.
-s read-only: Permite solo lectura. En este skill se añade por defecto (actúa como asesor/revisor, por lo que no necesita escritura). No es el valor predeterminado de la CLI/config. Es exclusivo de codex exec, no existe en codex exec review (si se añade, da error).
-C <DIR>: Raíz de trabajo de codex exec. Apunta al repositorio objetivo de la investigación/revisión. Si se omite, usa el directorio actual. codex exec review no tiene -C, por lo que para revisiones se debe hacer cd <DIR> dentro del mismo comando antes de llamarlo (ver más abajo).
-o <FILE>: Escribe solo el mensaje final de Codex en este archivo. Se escribe solo al completar (está vacío durante la ejecución), así que no se debe leer antes de que termine. En las recetas canónicas, esta es la fuente de la respuesta.
stdout: Codex también emite el mensaje final a stdout, pero en las recetas canónicas se toma de -o, por lo que se descarta con >/dev/null (evita duplicados y ahorra contexto).
stderr: Contiene registros de progreso, encabezados, advertencias, hooks, ecos finales, tokens used y errores (autenticación caducada, banderas inválidas, fallos de verificación de repo, etc.). Si se descarta simplemente con 2>/dev/null, cuando cat "$OUT" esté vacío no se podrá ver la causa, por lo que se redirige a un archivo temporal ($ERR) y se muestra solo en caso de error. En caso de éxito, no entra en el contexto; solo se ve la causa en caso de error.
mktemp /tmp/codex_answer.XXXXXX.txt: El XXXXXX final se reemplaza aleatoriamente, generando una ruta única sin colisiones. Incluso si se envían varias invocaciones en paralelo, cada una tendrá su propio mktemp.

Opciones normalmente innecesarias

--skip-git-repo-check: Solo necesario si se ejecuta fuera de un repositorio git. No se añade si se está dentro de un repositorio.
-s workspace-write: Solo si se quiere que Codex edite archivos. Esto se sale del propósito de este skill (revisor de solo lectura), por lo que no se usa en principio.

Especificación del modelo

Para usar un modelo específico, añada -m <MODEL> (ejemplo: -m gpt-5.5). Si no se especifica, sigue el valor predeterminado de la configuración de Codex. No lo especifique sin motivo; solo añádalo si el usuario lo solicita.

Búsqueda web

Si ~/.codex/config.toml tiene configurado web_search = "live", Codex puede usar la búsqueda web. La búsqueda web es una herramienta nativa de Responses, por lo que no se detiene con -s read-only (que solo restringe la ejecución de shell). Para verificar especificaciones concretas de bibliotecas, API o CLI, indique explícitamente en el prompt: "consulta la documentación oficial con la búsqueda web". codex exec no tiene una bandera --search; se controla mediante web_search en la configuración.

Mostrar ayuda

codex exec -h muestra la ayuda.

Cómo escribir el mensaje de tarea

Los LLM son buenos siguiendo ejemplos, por lo que los prompts de los ejemplos siguientes se pueden usar directamente como modelos para escribir buenos mensajes de tarea. Limite cada consulta a una sola decisión/revisión/plan/investigación, e incluya lo siguiente en un solo prompt:

Intención, contexto y restricciones: Como Codex se inicia en frío, siempre escriba qué quiere hacer, por qué y las premisas.
Archivos relevantes: Indíquelos en línea con @path/to/file. Si quiere que revise cambios no confirmados, indique explícitamente "revisa el diff con git diff".
Puntos de enfoque / alternativas a comparar / riesgos a buscar: Escríbalos de manera específica.
Formato de salida: Especifique la forma deseada (riesgos clasificados, tabla de compensaciones, cambios de plan recomendados, etc.).
Qué ignorar: Escriba lo que no debe considerar (nombres, formato, etc.) para evitar que el alcance se extienda.
Si necesita verificar especificaciones externas, indique: "consulta la documentación oficial con la búsqueda web".
Para revisiones, pida que se evalúe primero intención → implementación (primero verifique si es adecuado según la intención, luego la implementación).

El texto del prompt se debe encerrar con comillas simples (printf '%s' '...') para que los $ y las comillas invertidas dentro del texto no sean interpretados por el shell (si el texto contiene ' ASCII, use otro método de encerrado).

Ejemplos de uso por propósito

1. Segunda opinión / Comparación de múltiples opciones (Receta A)

Para obtener una segunda opinión sobre una decisión de diseño/implementación. Cuanto más específicos sean las opciones, restricciones y formato de salida, mejor será la calidad.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' 'Intención: Quiero decidir el método de refresco de tokens de autenticación. Actualmente, en cada llamada a la API se verifica la expiración y se refresca de forma síncrona (@src/auth/client.ts), lo que provoca dobles refrescos en solicitudes concurrentes de alta frecuencia.

Opciones a comparar:
(1) Compartir la Promise durante el refresco para unificarlo
(2) Actualizar proactivamente en segundo plano antes de la expiración
(3) Refrescar una sola vez después de recibir un 401 y reintentar

Restricciones: Debe funcionar tanto en SSR como en CSR. No quiero añadir nuevas bibliotecas.
Salida: Tabla de compensaciones con columnas correctness / complejidad / modos de fallo, opción recomendada por defecto y opción de respaldo, y bajo qué condiciones cambiar a otra opción. Ignora nombres y formato.' \
  | codex exec - -s read-only -C /path/to/repo -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
cat "$OUT"

2. Revisión de código

Restricción importante: Las banderas de alcance de codex exec review (--uncommitted / --base / --commit) no se pueden usar junto con un prompt de instrucciones personalizadas (ni stdin - ni argumento posicional) (verificado en codex 0.142.4. Si se usan juntos, falla inmediatamente con error: the argument '--uncommitted' cannot be used with '[PROMPT]'). Por lo tanto, se dividen en dos casos según el uso.

2a. Revisión con perspectiva e intención (uso principal y recomendado de este skill): Como no se pueden usar juntos las banderas de alcance y las instrucciones de perspectiva, se usa codex exec - (Receta A/B) en lugar de codex exec review, y se especifica el alcance dentro del prompt pidiendo que revise git diff, etc. Se pueden usar -s read-only, -C y stdin sin problemas, y se evitan los escapes.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' 'Intención: Este cambio solo debería alterar el comportamiento al suprimir el sonido de notificación inactivo, y no debería afectar la reproducción del sonido de solicitud de entrada del usuario. Revisa los cambios no confirmados con git diff (y git diff --cached o untracked si es necesario). Primero evalúa si es adecuado según la intención, luego la implementación.
Puntos de enfoque: Inversión de condiciones, cambios en valores predeterminados, desviaciones semánticas entre cliente/servidor.
Salida: Recomendación → hallazgos con evidencia → supuestos no verificados, en ese orden. Ignora nombres y formato.' \
  | codex exec - -s read-only -C /path/to/repo -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="
cat "$OUT"

2b. Revisión de diff sin especificar perspectiva: Si no se necesita un prompt personalizado, se pueden usar las banderas de alcance de codex exec review directamente (como no se añade PROMPT, no se cae en la restricción mencionada). A diferencia de codex exec, codex exec review no tiene -C ni -s, por lo que se debe cambiar al directorio del repositorio antes de llamarlo.

OUT=$(mktemp /tmp/codex_review.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
cd /path/to/repo || exit 1
codex exec review --uncommitted -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="
cat "$OUT"

Sustitución de banderas de alcance (reemplace la línea codex exec review ... anterior; ninguna lleva PROMPT):

codex exec review --uncommitted -o "$OUT" >/dev/null 2>"$ERR"   # No confirmados (staged + unstaged + untracked)
codex exec review --base main   -o "$OUT" >/dev/null 2>"$ERR"   # Diferencia con la rama base
codex exec review --commit <SHA> -o "$OUT" >/dev/null 2>"$ERR"  # Commit específico

Para revisiones con perspectiva, use 2a (codex exec - + git diff). Las banderas de alcance y las instrucciones personalizadas no se pueden usar juntas.
La revisión debe ejecutarse dentro del repositorio objetivo (-C no está disponible, así que haga cd antes de llamar). Si está fuera del repositorio, se puede usar --skip-git-repo-check, pero no tiene sentido si no hay diff que revisar.

3. Validación de plan/migración (Receta B)

Pruebe de resistencia el plan o los pasos de migración antes de implementar, identificando las brechas que deben resolverse antes de comenzar. Haga que Codex verifique los contratos del código actual en modo de solo lectura.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' 'Revisa el plan antes de implementar y enumera solo las brechas que deben resolverse antes de codificar.
Plan: Si la sincronización de eventos es rechazada por el servidor, establecer repair_required, enviar un snapshot compacto, y solo después de que el servidor confirme la secuencia coherente, reanudar los eventos incrementales.
Relacionado: @src/sync/event-syncer.ts @src/db/sync-state.ts @api/types.ts.
Lee el código actual para verificar los contratos existentes antes de evaluar.
Puntos de enfoque: Compatibilidad de esquemas, límite de tamaño del snapshot, condiciones de borde de la secuencia de reanudación, impacto de backfill/migración, falta de pruebas.
Salida: Solo los cambios necesarios en el plan antes de comenzar, más un veredicto de una oración: "¿Es seguro implementar así?".' \
  | codex exec - -s read-only -C /path/to/repo -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="
cat "$OUT"

4. Investigación profunda (Receta B)

Investigación persistente de causas raíz de errores, fallos de pruebas, condiciones de carrera, caché obsoleto, etc. Añadir condiciones de éxito verificables ayuda a aprovechar la capacidad de investigación profunda de Codex. Como lleva tiempo, ejecútelo en segundo plano.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' 'La prueba TestBar en foo_test.go falla raramente en CI. Investiga la causa raíz.
Condición de éxito: Identificar la condición de reproducción y la ubicación de la causa (archivo:línea), y presentar una propuesta de solución mínima.
Si se sospecha que es causado por una biblioteca externa, consulta la documentación oficial de esa biblioteca con la búsqueda web.' \
  | codex exec - -s read-only -C /path/to/repo -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="
cat "$OUT"

Manejo de los resultados

Comunique los puntos clave al usuario a partir de la respuesta (Receta A: resultado de la herramienta; Receta B: salida en segundo plano después de la notificación de finalización). Si es larga, resuma, pero cite textualmente las observaciones importantes.
Codex puede hacer recomendaciones extremadamente defensivas (consideraciones excesivas de compatibilidad hacia atrás, etc.). Usted decide qué observaciones adoptar y cuáles rechazar. No las tome al pie de la letra; incorpore solo lo que tenga sentido.

Suee33/agent-skills

¿Qué es agent-skills?

Preguntar en tu IA favorita

Documentación