MÓDULO 2.1

🩺 Diagnóstico del entorno

Antes de mover una coma: saber qué existe. En este módulo clonas el kit, ejecutas el doctor.sh para saber si la máquina está lista y el audit.sh para inventariar lo que Claude tiene y Codex no. Todo de solo lectura, con la salida real de esta máquina como ejemplo.

Temas

~30

Minutos

Básico

Nivel

Práctica

Tipo

📦 Clonar el kit

El kit agente-claude-codex es el "nivel 2, un solo comando" que la newsletter imaginó: un repositorio con cinco scripts bash, los mega-prompts en texto copiable y una plantilla de núcleo portátil. No instala nada en el sistema, no pide contraseña y no toca ~/.claude ni ~/.codex sin que tú lo ordenes. El primer paso es solo traer la carpeta a tu máquina.

🎯 Objetivo

Tener el kit en una carpeta local, con los scripts ejecutables, listo para correr el diagnóstico.

git clone https://github.com/inematds/agente-claude-codex
cd agente-claude-codex
ls scripts/
# adapt-instructions.sh  audit.sh  doctor.sh  init-core.sh  readback-test.sh  sync-skills.sh

Cómo verificar: el ls lista los seis scripts. Si alguno no tiene permiso de ejecución, chmod +x scripts/*.sh.

¿Nuevo por aquí? "Clonar" es descargar una copia completa de un repositorio git, con historial. "Script bash" es un archivo de texto con comandos de terminal que se ejecutan en secuencia. Ninguno de los scripts del kit necesita sudo.

scripts/

Los seis comandos: diagnosticar, auditar, adaptar, instalar núcleo, portar skill, probar.

prompts/

Prompt A, Prompt B, readback y handoff en texto para pegar en un agente.

template/

AGENTS.md, context/, tasks/, handoffs/ para copiar en cualquier proyecto.

Conceptos clave

Kit

Scripts + prompts + template, sin instalación global.

Solo lectura

doctor y audit no modifican nada; solo leen.

Sin sudo

Todo corre como tu usuario, en tu carpeta.

Reversible

Borrar la carpeta deshace todo lo que hace este módulo.

🩺 doctor.sh: ok / aviso / falta

El doctor responde la pregunta que viene antes que cualquier otra: ¿mi entorno está listo? Revisa git, python3, node, Claude Code (skills, CLAUDE.md, hooks), el Codex CLI (skills, config, sandbox, MCP), polyskill y los propios archivos del kit. Cada ítem sale en una de tres categorías, y el script termina con código 1 si falta algo esencial, lo que sirve para automatizar.

De izquierda a derecha: el doctor examina cada ítem y lo clasifica en ok, aviso o falta. Solo el rojo cambia el código de salida, así que un script de CI puede frenar la migración cuando falta algo esencial.

💻 Ejecuta el diagnóstico

Objetivo: saber, en 2 segundos, si falta algo antes de auditar.

scripts/doctor.sh
echo "exit=$?"

Cómo verificar: la última línea dice Pronto. Próximo passo: scripts/audit.sh y exit=0. Si dice Faltam itens essenciais, corrige lo que está en [FALTA] y vuelve a ejecutarlo.

Esta es la salida real en la máquina donde se construyó el kit, el 2026-09-14. Fíjate en que los dos avisos no impiden nada: solo dicen que las skills que dependen de MCP no van a funcionar en Codex hasta que registres el servidor, y que el Codex CLI no tiene el comando de import (el "un clic" es solo en la app de escritorio).

== Sistema ==
  [ok]     Linux aarch64, shell bash 5.2.21(1)-release
  [ok]     git 2.43.0
  [ok]     python3 3.12.3
  [ok]     node v24.13.0
== Claude Code (fonte) ==
  [ok]     claude 2.1.270 (Claude Code)
  [ok]     ~/.claude/skills: 117 skills
  [ok]     ~/.claude/CLAUDE.md existe (72 linhas)
  [ok]     settings.json: 2 hooks, 7 plugins
== Codex CLI (destino) ==
  [ok]     codex codex-cli 0.154.0
  [ok]     /home/<usuario>/.codex/skills: 27 skills
  [ok]     /home/<usuario>/.agents/skills: 29 skills
  [ok]     config.toml: sandbox_mode=danger-full-access
  [aviso]  nenhum MCP no Codex: skills marcadas 'adaptador' só funcionam após 'codex mcp add'
  [aviso]  Codex CLI sem comando import (o import 'um clique' é só no app desktop); use os scripts deste kit
== polyskill (passo 4) ==
  [ok]     polyskill 0.1.0
== Este kit ==
  [ok]     scripts/audit.sh
  [ok]     scripts/adapt-instructions.sh
  [ok]     scripts/init-core.sh
  [ok]     scripts/sync-skills.sh
  [ok]     scripts/readback-test.sh
  [ok]     template/AGENTS.md
  [ok]     prompts/01-migrate-claude.md
  [ok]     pasta gravável (relatorios/ será criada aqui)

Pronto. Próximo passo: scripts/audit.sh
exit=0

✓ Lo que hace el doctor

✓Lee versiones y carpetas; nunca escribe.
✓Indica el comando para resolver cada faltante.
✓Avisa si AppArmor va a romper el sandbox de Codex.
✓Marca un runtime ausente como aviso, no como error.

✗ Lo que NO hace

✗Instalar Claude, Codex o polyskill por ti.
✗Editar config.toml o settings.json.
✗Inventariar skill por skill (eso es el audit).
✗Garantizar que una sesión va a leer tus archivos (eso es el readback).

Conceptos clave

[ok]

Elemento presente y en el estado esperado.

[aviso]

Funciona, pero con una limitación conocida.

[FALTA]

Esencial ausente; cambia el código de salida a 1.

Código de salida

0 = listo; 1 = corrige antes. Sirve para CI.

🔍 audit.sh: inventario de solo lectura

Si el doctor pregunta "¿está listo?", el audit pregunta "¿qué existe?". Lee las dos casas, ~/.claude y ~/.codex, cuenta skills, comandos, subagentes, hooks, plugins y MCP, y produce un informe en Markdown con la matriz origen → destino: cada skill que solo existe en Claude recibe una clasificación. Es exactamente el paso 2 del Prompt A ("Inventory the working system"), automatizado.

El audit compara las listas de skills de las dos casas (a la izquierda), pasa cada skill exclusiva de Claude por una heurística de grep (en el centro) y guarda la matriz en cuatro clases (a la derecha). Los números son de esta máquina el 2026-09-14: 89 skills solo en Claude.

💻 Ejecuta la auditoría

Objetivo: generar el informe en relatorios/auditoria-<fecha>.md con la matriz de skills.

scripts/audit.sh
# Informe: relatorios/auditoria-2026-09-14.md
#   reutilizable:  72
#   adaptador:     15
#   nativo:        2
#   no resuelto:   1

Cómo verificar: la suma de las cuatro líneas tiene que coincidir con "Solo en Claude" dentro del informe (aquí, 72+15+2+1 = 90 líneas de tabla, 89 skills más 1 sin SKILL.md). Si no coincide, mira el tema 5.

💡 Consejo práctico

Ejecuta el audit antes Y después de cada ronda de migración y compara los dos informes con diff. Es la forma más barata de ver qué cambió de verdad, sin confiar en la memoria de nadie.

Conceptos clave

Inventario

Lista de lo que existe, con origen y cantidad.

Gap

Lo que está en un runtime y no en el otro.

Matriz origen → destino

Cada activo con su clasificación y qué hacer.

Informe fechado

Evidencia que se puede comparar mañana.

📊 Leer la matriz de skills

La matriz es una heurística por grep, no un veredicto. El audit abre el SKILL.md de cada skill exclusiva de Claude y busca pistas: una mención a una herramienta MCP (mcp__, magnific, heygen) la vuelve adaptador; una mención a AskUserQuestion, subagentes o plugins de Claude también la vuelve adaptador; una mención a un hook (SessionStart, PreToolUse) la vuelve nativa; el resto es reutilizable, es decir, Markdown y scripts comunes que Codex lee igual.

Reutilizable

Se porta vía polyskill sin cambios. Ej.: formato-curso-v5, roteirista-inema, video-explicativo, pixflow-motion, inemaref-serie.

Adaptador

Depende de un MCP o plugin de Claude. Solo funciona en Codex después de codex mcp add. Ej.: avatar-heygen-nei, heygen-cli, espiona-ads, ugc-seedance25, website-intelligence, las 8 variantes de printing-press.

Nativa

Depende del hook SessionStart, que Codex no tiene. fable-mindset y silver-platter se convierten en texto en el AGENTS.md.

Sin resolver

inemaref-referencias: carpeta sin SKILL.md. Decide a mano: archivar o completar.

✓ Cómo usar la matriz

✓Empieza por las reutilizables más usadas; victoria rápida.
✓Agrupa las de adaptador según el MCP que exigen.
✓Abre 3 o 4 SKILL.md al azar para comprobar la heurística.

✗ Errores comunes

✗Tratar "reutilizable" como "probado": es solo formato.
✗Portar las 72 de una vez; hazlo en lotes de 10.
✗Olvidar que los subagentes y plugins ni siquiera entran en la matriz: no migran.

Conceptos clave

Heurística

Regla práctica por grep; acierta en la mayoría, revisa el resto.

Reutilizable

Markdown y scripts comunes: se porta sin cambiar.

Adaptador

Necesita un MCP o equivalente en el destino.

Nativa

Atada a un evento del runtime; se convierte en texto o se queda.

🛡️ Sandbox de Codex y AppArmor: la falla real

Codex CLI ejecuta comandos dentro de un sandbox hecho con bwrap (bubblewrap), que aísla el proceso usando user namespaces de Linux. En Ubuntu reciente, AppArmor restringe esos namespaces para procesos sin privilegios, y bwrap muere al instante con loopback: Failed RTM_NEWADDR: Operation not permitted. No corre nada, ni siquiera un ls. Fue la primera falla real del kit, y la corrección fue de una línea.

⚠️ Qué pasó

El primer readback en Codex (módulo 2.5) forzaba -s read-only en la llamada. El sandbox intentó levantarse, AppArmor lo bloqueó, y Codex respondió "no pude leer ningún archivo". La sesión entera se perdió.

bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted

Diagnosticar

sysctl kernel.apparmor_restrict_unprivileged_userns devuelve 1. El doctor ya revisa esto y avisa.

Decidir

Máquina personal de confianza: apagar el sandbox en el config de Codex. Máquina compartida: habilitar el namespace en el sysctl (requiere root) y mantener el sandbox.

Corregir lo mínimo

En el kit: quitar el -s read-only del script y respetar el sandbox_mode del config. Registrado en FALHAS.md como prompt e infra.

💻 Comprobar y ajustar el sandbox

Objetivo: garantizar que Codex puede ejecutar comandos en esta máquina.

# 1. ¿AppArmor restringe los user namespaces?
sysctl -n kernel.apparmor_restrict_unprivileged_userns

# 2. si devolvió 1 y la máquina es solo tuya, en ~/.codex/config.toml:
sandbox_mode = "danger-full-access"

# 3. prueba rápida
codex exec --skip-git-repo-check "ejecuta 'echo sandbox-ok' y responde solo con la salida"

Cómo verificar: la respuesta contiene sandbox-ok. Si aparece bwrap en la salida, el config no fue leído: revisa la ruta y la ortografía de la clave.

¿Nuevo aquí? Un "sandbox" es una caja aislada donde un programa corre sin acceso al resto del sistema. "AppArmor" es el módulo de seguridad de Linux que decide qué puede hacer cada programa. danger-full-access apaga la caja: Codex pasa a tener el mismo poder que tú en la terminal. Aceptable en una máquina personal, peligroso en un servidor compartido.

Conceptos clave

bwrap

Bubblewrap, el aislador que Codex usa por defecto.

User namespace

Recurso del kernel que AppArmor puede bloquear.

sandbox_mode

Clave del config.toml; los scripts no deben sobrescribirla.

Corrección mínima

Una flag eliminada, no un script reescrito.

📄 El informe y qué hacer con él

El audit deja un archivo en relatorios/auditoria-<data>.md con seis secciones: versiones y raíces, gap de skills con la matriz, comandos, subagentes, hooks y plugins, hooks de Codex, MCP (solo nombres, nunca valores de clave) y una sección "no ejecutado" que recuerda que ningún comportamiento fue probado. Ese archivo es la evidencia del Prompt A: entregas la matriz, no una promesa.

📊 Las seis secciones del informe

1.Versiones y raíces: claude, codex, polyskill, conteos por carpeta, si existe import nativo.
2.Skills: cuántas en los dos, cuántas solo en Claude, y la matriz línea por línea.
3.Comandos, subagentes, hooks, plugins, runbooks, CLAUDE.md, memoria: destino y clasificación de cada uno.
4.Hooks de Codex hoy: qué eventos ya tienen handler.
5.MCP: nombres registrados en cada lado, sin valores.
6.No ejecutado: el recordatorio de que esto es inventario, no prueba.

💻 Extraer solo lo que hace falta

Objetivo: sacar del informe la lista de skills de adaptador para planificar los MCP.

grep '| adaptador |' relatorios/auditoria-<data>.md | cut -d'|' -f2
# avatar-heygen-nei, heygen-cli, heygen-mcp, espiona-ads, ...

Cómo verificar: la lista tiene 15 nombres en esta máquina. Reemplaza <data> por la fecha de tu informe.

💡 Consejo práctico

Una vez el resumen del audit me sumó 94 cuando el gap era 89. El grep contaba líneas de la sección 3 (subagentes, hooks) junto con la sección 2. Corrección mínima: restringir el grep a la sección 2.1. Está en FALHAS.md como "prompt". Si tus números no cierran, desconfía del contador antes de desconfiar de los datos.

Conceptos clave

Evidencia

Archivo fechado que cualquiera puede releer.

Sin secretos

El informe cita nombres de MCP, nunca claves.

No ejecutado

Inventario no es prueba; la prueba llega en el 2.5.

Diff entre rondas

Compara informes para medir el progreso real.

Autoevaluación (opcional): el audit clasificó una skill como "reutilizable". ¿Qué garantiza eso?

🎯 Resumen del módulo

✓

Clonar el kit — seis scripts, prompts y template, sin instalación global.

✓

doctor.sh — ok, aviso o falta; código de salida para automatizar.

✓

audit.sh y la matriz — 89 solo en Claude: 72 reutilizables, 15 adaptador, 2 nativo, 1 no resuelto.

✓

Sandbox e informe — la falla del bwrap y su corrección de una línea; el informe es evidencia, no prueba.

Próximo módulo:

2.2 — CLAUDE.md → AGENTS.md: portátil de un lado, residuo del otro

← Volver a la Ruta Próximo módulo →