🗣️ El vocabulario: runtime, harness, skill, MCP, hook, handoff
Seis palabras van a aparecer durante todo el curso. Cada una tiene un significado preciso y un lugar en el disco. Este módulo las define todas desde cero, muestra dónde buscan cada cosa Claude Code y Codex, y separa lo que es tuyo de lo que es de la herramienta.
🧱 Modelo vs runtime vs harness
Cuando alguien dice "uso Claude", puede estar hablando de tres cosas distintas. El modelo es el cerebro de IA que genera texto (Claude Opus, GPT, DeepSeek). El runtime es el programa que abres en la terminal y que conversa con ese modelo (Claude Code, Codex CLI, dsh). El harness es la estructura alrededor del modelo que le da manos y ojos: leer archivos, ejecutar comandos, guardar el historial, llamar herramientas. En la práctica, runtime y harness suelen ser el mismo programa; la distinción importa cuando cambias uno y mantienes el otro.
¿Nuevo por aquí? Un LLM (modelo de lenguaje) es solo el modelo: recibe texto, devuelve texto. Por sí solo no abre ningún archivo. Lo que hace que Claude Code "edite tu código" es el harness que lo rodea, que transforma el texto del modelo en acciones reales y devuelve el resultado. El modelo piensa; el harness actúa.
De izquierda a derecha: el modelo está en el fondo de dos cajas azules que pertenecen a la herramienta. Lo que es tuyo queda fuera de ellas, a la derecha, y lo lee cualquier harness. Cambiar de harness es cambiar las cajas azules; la caja verde de la derecha no cambia.
✓ Es tuyo (portátil)
- ✓Las instrucciones del proyecto, en Markdown.
- ✓Las skills (procedimientos en SKILL.md).
- ✓El contexto, las decisiones y los handoffs.
✗ Es de la herramienta (nativo)
- ✗El loop de ejecución y el formato del historial.
- ✗Sandbox, permisos, confianza por carpeta.
- ✗Plugins, hooks y la memoria automática.
Conceptos clave
El LLM: entra texto, sale texto. No toca archivos.
El programa que ejecuta el loop lee → piensa → actúa.
Herramientas, historial, hooks, permisos alrededor del modelo.
Modelo + harness vistos desde afuera: lo que lee tu proyecto.
📜 Instrucciones (CLAUDE.md / AGENTS.md) y orden de lectura
Todo harness abre una carpeta y busca un archivo de instrucciones. Claude Code busca CLAUDE.md; Codex, Gemini y OpenCode buscan AGENTS.md. Ese es el único punto del sistema que realmente está atado al proveedor, y la solución es simple: el AGENTS.md pasa a ser la fuente, y el CLAUDE.md empieza con una línea que importa el AGENTS.md. Una regla, escrita una vez, leída por todos.
Objetivo: hacer que Claude lea el mismo archivo que Codex. Este es el CLAUDE.md completo de un proyecto adaptado:
@AGENTS.md
# Específico de Claude Code
- Nunca usar AskUserQuestion; preguntar en texto libre.
- Los plugins superpowers / context-mode / claude-mem son de Claude; no citarlos en nada portátil.Cómo verificar: abre una sesión nueva de Claude en el proyecto y pide "cita una regla del proyecto y el archivo de origen". La respuesta debe apuntar al AGENTS.md.
¿Nuevo por aquí? El orden de lectura es la lista, escrita al inicio del AGENTS.md, de lo que el agente debe leer y en qué secuencia: primero las reglas, después el contexto, después la tarea actual, por último el último handoff. Ningún harness carga esas carpetas por sí solo; solo lee lo que la instrucción le manda leer. Por eso el orden tiene que estar escrito.
AGENTS.md
Reglas estables y el orden de lectura. Corto. Cambia cuando cambia una regla.
context/overview.md y current-state.md
Qué es el proyecto y qué es verdad hoy.
tasks/current.md
Qué estamos haciendo ahora, quién es el responsable, cuál es el criterio de terminado.
handoffs/latest.md
Dónde se detuvo la última sesión y cuál es la próxima acción exacta.
Conceptos clave
Fuente de las instrucciones. Leído por Codex, Gemini, OpenCode.
La línea que hace que el CLAUDE.md importe la fuente.
Lo poco que solo Claude entiende, debajo de la línea de import.
Escrito al inicio; nada se carga automáticamente.
🧩 Skill (SKILL.md) y dónde busca cada runtime
Una skill es un procedimiento escrito para el agente: una carpeta con un archivo SKILL.md (nombre, descripción, cuándo usarla, pasos) y, opcionalmente, scripts y referencias al lado. El formato es el mismo entre Claude Code y Codex; lo que cambia es dónde busca cada uno. Esa diferencia de carpeta es lo que genera copias manuales, y las copias manuales son el camino más corto hacia versiones divergentes.
📂 Dónde busca skills cada runtime
- •Claude Code:
~/.claude/skills/(global) y.claude/skills/en el proyecto. - •Codex CLI:
~/.codex/skills/y~/.agents/skills/(global),.agents/skills/en el proyecto. - •dsh (DeepSeek en contenedor): una carpeta montada como
/work/.dsh/skills. - •En la máquina auditada: 117 skills en Claude, 27 en Codex, 3 copias a mano en dsh, 16 propias en un bot. Cuatro consumidores, ninguna fuente única.
¿Nuevo aquí? Una skill canónica es la versión fuente, guardada en un solo lugar. Las carpetas de cada runtime reciben copias generadas a partir de ella por una herramienta (el curso usa polyskill), con una verificación de drift: si alguien editó la copia en vez de la fuente, el sistema avisa. Editas un archivo; las N copias se regeneran.
✗ Sin fuente canónica
- ✗skill-claude, skill-codex, skill-gemini, skill-glm: cuatro archivos que mantener.
- ✗Corriges un bug en una y te olvidas de las otras.
- ✗Nadie sabe cuál es la versión correcta.
✓ Con fuente canónica
- ✓Una SKILL.md canónica → adaptador Claude, adaptador Codex, adaptador dsh.
- ✓El build regenera todas las copias de una vez.
- ✓Verificación de drift: [ok] o [DRIFT] por runtime.
Conceptos clave
Procedimiento en Markdown: nombre, cuándo usar, pasos.
Donde busca cada runtime. Difiere entre ellos.
La única versión editable; las demás se generan.
Divergencia entre copia y fuente. Debe detectarse, no descubrirse por accidente.
🔌 MCP: herramientas y datos, no memoria
MCP (Model Context Protocol) es un estándar para conectar un agente a servicios externos: un generador de imágenes, un programador de publicaciones, una base de datos. El agente gana herramientas nuevas ("generar imagen", "listar publicaciones") que cualquier harness compatible puede usar. Es la parte más fácil de confundir: MCP da acceso, no da recuerdo. No junta historiales de chat, no resuelve conflictos de memoria, no separa clientes.
¿Nuevo aquí? Piensa en MCP como un enchufe estandarizado. El servicio (Magnific, Metricool) ofrece el enchufe; el harness (Claude, Codex) tiene la clavija. Cada harness necesita registrar el enchufe por su cuenta, pero la clave de acceso es la misma y queda en un archivo .env referenciado, nunca copiado.
📊 El estado real en la máquina auditada
- •Claude: MCP global magnific y metricool, más dos por proyecto.
- •Codex: ningún MCP registrado.
- •Consecuencia: 15 skills que dependen de MCP solo funcionan en Claude hasta que Codex registre los mismos enchufes.
✓ Lo que MCP resuelve
- ✓Acceso a herramientas y datos externos, estandarizado.
- ✓El mismo servicio, conectado a N harnesses.
- ✓La memoria expuesta vía MCP se vuelve portátil (el texto base lo hace).
✗ Lo que MCP no hace por sí solo
- ✗Juntar historiales de chat de herramientas distintas.
- ✗Decidir qué versión de un hecho es la correcta.
- ✗Imponer separación entre clientes: eso es permiso de backend.
Conceptos clave
Protocolo de herramientas y datos para agentes.
Cada runtime conecta el mismo enchufe por su cuenta.
La clave queda en el .env; el registro apunta a ella.
MCP no recuerda nada por ti.
⚙️ Hooks, plugins, subagentes: qué es nativo
Tres cosas de Claude Code no cruzan el puente, y conviene saberlo antes de intentarlo. Un hook es un script que el harness dispara en un evento (al abrir la sesión, después de editar un archivo). Un plugin es un paquete que agrega comandos y comportamientos al harness. Un subagente es un agente hijo con rol propio, que el principal convoca. Los tres dependen de que el harness tenga ese evento, ese formato de paquete, ese mecanismo de convocatoria. Codex tiene hooks, pero eventos distintos; no tiene los plugins de Claude; no tiene subagentes en el mismo formato.
🔍 Comparación real de los dos harnesses
- •Hooks: Claude dispara en SessionStart (inyecta un playbook, ajusta caché); Codex dispara en PostToolUse y Stop. El evento "al abrir sesión" no existe en Codex.
- •Plugins: 7 en Claude (superpowers, claude-mem, context-mode…); 1 en Codex (github). Formatos incompatibles.
- •Subagentes: 7 en Claude (un "consejo" de roles); ningún equivalente 1:1 en Codex.
El hook se vuelve texto
Lo que el hook inyectaba al abrir la sesión (un playbook de ritmo, por ejemplo) pasa a ser una sección del AGENTS.md. Pierde la automatización, conserva el contenido.
El plugin se queda en el residuo
No se menciona un plugin en una instrucción portátil. Vive debajo del @AGENTS.md, en la parte que solo Claude lee.
El subagente se vuelve skill de rol
El prompt del "abogado del diablo" se convierte en un SKILL.md que cualquier harness invoca como procedimiento. Pierde la convocatoria automática, conserva el rol.
💡 Regla del texto base
"Pon la lógica reutilizable de hooks y verificaciones en scripts comunes; valida cada evento nativo, payload y configuración de confianza por separado." El script es portátil. El disparador es de la herramienta.
Conceptos clave
Script disparado por un evento del harness. Los eventos difieren.
Paquete del harness. No cruza.
Agente hijo con un rol. Se vuelve skill de rol.
Lo que solo existe en ese harness. Se queda en el residuo.
🔁 Handoff y prime: el resumen que viaja
Un handoff es el resumen estructurado que una sesión escribe antes de cerrar: decisiones tomadas, tareas inconclusas, próximos pasos, rutas de archivo. Va a un archivo Markdown, con un latest.md que apunta al más reciente. Prime es el acto inverso: la sesión nueva lee ese archivo antes de hacer cualquier cosa. El ciclo reemplaza la dependencia del historial en bruto, y es lo que permite que Claude se detenga y Codex continúe.
El archivo verde del medio es el único vínculo entre las dos sesiones azules. Fíjate en que la Sesión B no necesita ser el mismo harness que la Sesión A: el handoff es Markdown, así que cualquier ejecutor lo lee.
¿Nuevo aquí? Sin handoff, "continuar donde me quedé" significa reabrir la sesión antigua en el mismo harness, o hurgar en un archivo JSONL de miles de líneas. El handoff es un resumen de una página, hecho por el propio agente, que cabe en cualquier contexto. Es la diferencia entre transportar la conversación entera y transportar lo que importa de ella.
✓ Un buen handoff tiene
- ✓Decisiones tomadas y el motivo.
- ✓Tareas inconclusas y lo que falta.
- ✓Rutas exactas de los archivos tocados.
- ✓La próxima acción, concreta, en una línea.
✗ Un handoff malo
- ✗Narra la conversación en orden cronológico.
- ✗Dice "se modificaron varios archivos" sin decir cuáles.
- ✗Afirma que algo funciona sin decir qué prueba corrió.
- ✗Incluye credenciales o el historial en bruto.
Conceptos clave
Resumen estructurado escrito al cerrar la sesión.
La sesión nueva lee el handoff antes de actuar.
Puntero fijo al handoff más reciente.
Claude escribe, Codex retoma. O al revés.
Autoevaluación (opcional): ¿cuál de estos elementos es portátil entre Claude Code y Codex sin adaptación?
🎯 Resumen del módulo
Próximo módulo:
1.3 — Los tres niveles de migración: un clic, un comando, personal