🎯Lo que obtienes en este módulo
Salir de aquí sabiendo qué significa cada parte (CLAUDE.md, AGENTS.md, skills, sub-agents, MCP) en cada runtime. Nunca más te perderás al leer la documentación de uno sin tener una referencia mental del otro.
Contenido detallado
🤖 Qué es un coding agent (y qué NO es)
Un agente de programación es un LLM que ejecuta un loop autónomo: lee código, planifica una acción, edita archivos, ejecuta comandos en el terminal, observa el resultado y decide el siguiente paso — todo sin que tengas que indicarle cada movimiento. No es autocompletar ni un chatbot. Es un colaborador iterativo.
✓ Es un coding agent
- ✓Ejecuta la tarea de principio a fin (leer, planificar, actuar, revisar)
- ✓Tiene acceso a tools (shell, edición de archivos, web, MCP)
- ✓Mantén el contexto de la sesión e itera
- ✓Puedes delegar en subagentes especializados
- ✓Ejecuta hooks de eventos (PreToolUse, Stop, etc.)
✗ No es un coding agent
- ✗Autocompletado (Copilot inline): sugiere una línea
- ✗Chatbot puro (ChatGPT estándar) — sin tools
- ✗Linter/formatter — regla estática
- ✗Expansor de fragmentos: plantilla fija
- ✗Code search — solo consulta, no actúa
🔬El loop ReAct (Reason + Act)
Es el motor de cualquier coding agent. Se ejecuta en ciclos cortos:
Conceptos clave
Razonar + actuar de forma iterativa
Bash, Edit, Read, Web, MCP
Permitir/denegar/preguntar por herramienta
Eventos del harness
📘 CLAUDE.md vs AGENTS.md — el «system prompt del proyecto»
Los dos agentes leen un archivo markdown en la raíz del proyecto en inicio de cada sesión y se inyectan en el system prompt. Misma función, dos nombres:
💡Consejo práctico
Mantén el CLAUDE.md/AGENTS.md enfocado en 3 cosas:
- Comandos de build/test/lint en la parte superior (formato literal para copiar)
- Convenciones de código que no sean obvias (no repetir lo que el linter ya impone)
- Enlaces a documentación interna detallada (ADRs, runbooks)
Conceptos clave
Global → proyecto → subdirectorio
Todo entra en el system prompt
Lo específico prevalece sobre lo genérico
Cuidado con la inflación
📁 .claude/ vs .codex/ vs .agents/ — la anatomía
Carpeta oculta del proyecto donde reside la personalización del agente. Claude usa una sola carpeta. Codex usa dos carpetas con responsabilidades separadas. Esta es la diferencia estructural más importante:
Claude Code — una sola carpeta
.claude/ ├── CLAUDE.md ← também pode ficar na raiz ├── settings.json ← permissões, modelo, env, hooks ├── settings.local.json ← override local (.gitignore) ├── agents/ ← sub-agents em Markdown │ ├── code-reviewer.md │ └── doc-writer.md ├── skills/ ← skills auto-invocáveis │ └── my-skill/ │ ├── SKILL.md │ ├── scripts/ │ └── references/ ├── commands/ ← slash commands │ └── review.md └── hooks/ ← scripts de evento
Codex — dos carpetas, responsabilidades distintas
.codex/ ← config específica do Codex
├── config.toml ← settings em TOML
├── agents/ ← sub-agents em TOML
│ ├── code-reviewer.toml
│ └── doc-writer.toml
└── commands/ ← slash commands específicos
.agents/ ← spec ABERTA (compartilhada)
└── skills/
└── my-skill/
├── SKILL.md
├── agents/openai.yaml ← sidecar Codex
├── scripts/
└── references/
AGENTS.md ← na raiz, system prompt do projeto
⚠️Trampa #1 de la migración
Quien viene de Claude coloca la skill en .codex/skills/ pensando que es el equivalente directo de .claude/skills/. Se equivoca. La skill de Codex está en .agents/skills/ — porque .agents/ es la convención de la spec abierta Agent Skills, y Codex la respeta.
Conceptos clave
. al inicio = oculta
Nombre correcto, carpeta correcta
.codex vs .agents
Hacer commit de la skill, ignorar lo local
🧩 Skills — el concepto común, con pequeñas diferencias
Skill es una "competencia empaquetada": carpeta con SKILL.md + frontmatter YAML + cuerpo Markdown + carpetas convencionales. Ambos runtimes implementan el estándar Agent Skills (agentskills.io), así que el núcleo es portable. En qué difieren:
Los 4 pilares que SIEMPRE coinciden
SKILL.md — siemprename e description en YAMLscripts/, references/, assets/SKILL.md mínimo
--- name: minha-skill description: Úsala cuando necesites procesar X. Triggers comunes: "procesa X", "limpia Y". --- # Minha Skill Instrucciones en markdown que explican cómo ejecutar la tarea. Puede hacer referencia a archivos relativos: consulta `references/exemplo.md` para más detalles.
🔷 Claude Code agrega
- •
allowed-toolsen el frontmatter - •
disable-model-invocation(opt-in explícito) - • Inyección dinámica con
`!comando`(backtick-bang) - • Invocación automática por descripción
- • Slash:
/nome-skill
🟣 Codex agrega
- • Sidecar
agents/openai.yaml(branding, MCP) - • Límite oculto de ~8K caracteres en la description
- • Sin inyección dinámica nativa (usar prosa como alternativa)
- • Invocación automática por descripción (también)
- • Dollar:
$nome-skill
🦜Es exactamente aquí donde entra polyskill
Escribes UNA skill en el formato portable. polyskill genera dos versiones: una con las particularidades de Claude y otra con las de Codex (incluidos el sidecar y el ajuste de description). Consulta la Ruta 5 para los detalles.
Conceptos clave
Archivo canónico
name + description
Activación por descripción
Metadatos específicos
👥 Sub-agents — dos filosofías opuestas
Un subagente es un "persona especializada" que el agente principal puede delegar tareas. Aquí está la diferencia más engañosa entre Claude Code y Codex — afecta a casi todos los que migran:
Claude Code — invocación automática
Formato Markdown en .claude/agents/. El agente principal LEE la descripción y decide por sí solo si delega.
Escribes una description rica en disparadores ("Úsala de forma proactiva cuando..."), y Claude, como agente principal, detecta el sub-agent cuando el contexto coincide. Puede ejecutar varios en paralelo mediante la herramienta Task.
Codex — invocación explícita
Formato TOML en .codex/agents/. TIENES que mencionarlo por su nombre en el prompt.
Description te ayuda a recordar, pero no se activa automáticamente. «Usa el agent code-reviewer para revisar X» — sin eso, no se ejecuta. Desventaja: más predecible, menos ergonómico.
🚨El error #1 de quienes migran de Claude a Codex
Copia el sub-agent, tradúcelo a TOML y espera que se active solo como en Claude. No se activa. Pasas horas pensando "está fallando"; no es así. Codex requiere invocación explícita por diseño.
Conceptos clave
Claude lee la descripción y decide
Codex exige un nombre
Contexto separado
Varios simultáneos
🔌 MCP — el protocolo que ambos hablan
Model Context Protocol (MCP) es el denominador común de la pila. Patrón abierto para conectar LLM a herramientas externas (Slack, Gmail, GitHub, base de datos). El servidor MCP se ejecuta como un proceso independiente: Claude y Codex hablan el mismo protocolo.
La arquitectura MCP
🔷 Declaración en Claude Code
// .mcp.json
{
"mcpServers": {
"slack": {
"command": "npx",
"args": ["-y", "@mcp/slack"],
"env": { "TOKEN": "$SLACK_TOKEN" }
}
}
}
🟣 Declaración en Codex
# config.toml
[mcp_servers.slack]
command = "npx"
args = ["-y", "@mcp/slack"]
[mcp_servers.slack.env]
TOKEN = "${SLACK_TOKEN}"
💡La buena noticia
¿Configuraste un MCP server una vez? Los dos runtimes pueden usarlo. Solo cambia el formato de declaración (JSON×TOML). Server, env, herramientas expuestas: todo igual. Es la parte de la pila que MÁS sobrevive entre runtimes.
Conceptos clave
MCP es una especificación, no es propietario
Proceso separado
Dos transports
Naming convention
🎯Resumen del módulo
Siguiente módulo:
1.2 — Por qué usar ambos juntos (complementariedad, redundancia, tool-agnostic)