La forma más rápida de notar que alguien no entiende cómo funcionan los agentes de IA es escucharlo decir esta frase: "le voy a dar un prompt muy detallado para que haga lo que necesito". Si el prompt fuera la solución, ya estaría resuelto.
Lo que estamos aprendiendo en 2026, después de un año largo de experimentación con agentes en producción, es que un subagente bien construido no es un prompt largo. Es una arquitectura de archivos. Cada archivo cumple una función específica, y la suma de todos define una personalidad operativa que puede ser invocada de forma consistente, afinada con el tiempo, y reutilizada entre proyectos.
En este artículo voy a comparar cómo dos sistemas resuelven esa arquitectura: OpenClaw, una plataforma de orquestación de agentes que estoy usando para mi propio trabajo, y Claude Code, la herramienta de Anthropic para desarrolladores. Ambos llegaron a soluciones parecidas por caminos distintos, y entender la diferencia ayuda a decidir cuándo usar cada una.
"Construir un agente bien definido cuesta menos que construirlo mal tres veces."
Qué es realmente un subagente
Un subagente es un asistente de IA especializado en una tarea o dominio específico, que opera dentro de su propia ventana de contexto y puede ser invocado por un agente principal o por el usuario directamente. La diferencia con un asistente general es importante: el subagente tiene una identidad estable, herramientas limitadas a su rol, y un sistema de memoria propio.
¿Por qué importa esto? Porque cuando uno trabaja con un asistente general en una conversación larga, el contexto se va llenando de información irrelevante: búsquedas pasadas, archivos leídos, decisiones tomadas. Eso degrada la calidad de las respuestas. Un subagente resuelve este problema delegando la tarea especializada a un contexto separado, y devolviendo solo el resultado al hilo principal.
La pregunta práctica entonces es: ¿cómo se le da personalidad y memoria a ese subagente? Ahí entra la arquitectura de archivos.
La arquitectura de OpenClaw
OpenClaw representa cada agente con una carpeta que contiene varios archivos .md, cada uno con un propósito único. Esta es la estructura que estoy usando para mi agente de comunicación, llamado Ogilvy:
capacidad-comunicacion/
├── IDENTITY.md → Quién es el agente
├── SOUL.md → Sus principios y límites
├── OBJECTIVES.md → Sus metas operacionales
├── MEMORY.md → Lo que sabe del usuario y su contexto
├── README.md → Cómo invocarlo y reglas operacionales
└── skills/
├── linkedin-post-generator/
│ └── SKILL.md → Habilidad específica con su workflow
└── ogilvy-content-optimizer/
├── SKILL.md
├── references/
└── assets/
La separación tiene una lógica que vale la pena entender en detalle.
IDENTITY.md: la presentación del agente
Este archivo responde a una pregunta simple: ¿quién eres? Define el nombre, la inspiración detrás del agente (el mío toma el nombre de David Ogilvy, el publicista), el tono general y la "criatura" que representa dentro de la arquitectura. Es la primera respuesta cuando alguien le pregunta al agente quién es.
SOUL.md: los principios y los límites
Acá viven las reglas no negociables. Para mi agente Ogilvy, por ejemplo, hay tres principios que sigue siempre: nunca inventar datos, escribir pensando en el lector y no en el escritor, y respetar el flujo de aprobación humana antes de publicar cualquier cosa. SOUL.md también define el "vibe", que es el tono específico que debe mantener.
La diferencia entre IDENTITY y SOUL es sutil pero importante: IDENTITY es quién soy (cara visible), SOUL es cómo opero (cara invisible que guía cada decisión).
OBJECTIVES.md: las metas operacionales
Lista numerada de los objetivos del agente, en orden de prioridad. Cuando hay tensión entre dos tareas, este archivo define qué prevalece. En el mío, por ejemplo, la verdad siempre prevalece sobre la optimización SEO. Eso significa que si un dato preciso requiere romper una palabra clave, gana el dato.
MEMORY.md: lo que el agente sabe
Acá vive el contexto persistente sobre el usuario. En mi caso, MEMORY.md contiene mi voz como autor, las palabras que evito, los regionalismos que sí uso y los que no, mi lector ideal definido como una persona concreta llamada Carlos, los artículos publicados en mi blog y los servicios que ofrezco. Cada vez que el agente arranca una tarea, lee este archivo primero.
README.md: cómo se usa
Es la documentación operativa. Cómo invocarlo, qué pasos seguir antes de operar sobre el blog, qué reglas tiene el repositorio del proyecto, qué archivos consultar antes de escribir. Funciona como manual del operador, no como definición del agente.
skills/: las habilidades específicas
Cada habilidad es una subcarpeta con su propio SKILL.md y, opcionalmente, archivos de referencia y plantillas. Una habilidad describe un workflow concreto, paso a paso. Mi agente Ogilvy tiene dos habilidades activas: una para escribir posts de LinkedIn y otra para optimizar artículos del blog. Cada una sigue una metodología distinta y tiene sus propios recursos.
Esta separación entre identidad, principios, memoria y habilidades es lo que permite afinar el agente sin romperlo. Si descubro que su tono está mal calibrado, ajusto SOUL.md y MEMORY.md. Si descubro que sus posts de LinkedIn son flojos, ajusto la skill correspondiente sin tocar nada más.
La arquitectura de Claude Code
Claude Code, la herramienta oficial de Anthropic para desarrolladores, llegó a una solución más compacta. Acá un subagente es un solo archivo markdown con YAML frontmatter, ubicado en una carpeta específica.
Según la documentación oficial de Claude Code, un subagente puede tener un directorio de memoria persistente en ~/.claude/agent-memory/ que usa para acumular insights entre conversaciones, como patrones de codebase y problemas recurrentes. Los subagentes pueden tener alcance global (usuario) o de proyecto.
Estructura de archivos de Claude Code
La estructura típica del directorio .claude/ en un proyecto incluye archivos como CLAUDE.md (instrucciones del equipo), settings.json (permisos y configuración), y subcarpetas para commands, rules, skills y agents. Los subagentes específicamente viven en .claude/agents/ (proyecto) o ~/.claude/agents/ (global, todos los proyectos).
La estructura típica del directorio .claude/ se ve así:
~/.claude/
├── CLAUDE.md → Memoria global del usuario
├── settings.json → Configuración y permisos
├── agents/
│ ├── code-reviewer.md → Subagente: un archivo, todo adentro
│ └── doc-writer.md → Subagente: un archivo, todo adentro
└── skills/
└── deploy/
└── SKILL.md → Habilidad reutilizable
Cada subagente es un archivo único como este:
--- name: code-reviewer description: Expert code reviewer. Use PROACTIVELY when reviewing PRs. model: sonnet tools: Read, Grep, Glob --- You are a senior code reviewer with a focus on correctness and maintainability. When reviewing code: - Flag bugs, not just style issues - Suggest specific fixes, not vague improvements - Check for edge cases and error handling gaps
Toda la personalidad cabe en un archivo. El YAML frontmatter define los metadatos, y el cuerpo es el system prompt que describe el comportamiento.
Las piezas que sí son separadas
Claude Code separa otras cosas en archivos distintos, pero a nivel de proyecto o usuario, no a nivel de subagente:
- CLAUDE.md funciona como memoria global del usuario o del proyecto. Es el equivalente más cercano a MEMORY.md de OpenClaw, pero opera a nivel de Claude Code completo, no por agente.
- skills/ son workflows reutilizables que cualquier subagente puede invocar. Equivalentes a las skills de OpenClaw, con el mismo formato (
SKILL.mdcon YAML frontmatter). - rules/ son archivos modulares de instrucciones que se pueden inyectar en CLAUDE.md cuando crece demasiado.
Comparación práctica: cuándo usar cada arquitectura
Las dos arquitecturas tienen virtudes distintas y la elección depende del caso de uso. Esta tabla resume las diferencias clave:
| Aspecto | OpenClaw | Claude Code |
|---|---|---|
| Archivos por subagente | 5 + carpeta de skills | 1 archivo único |
| Complejidad inicial | Alta | Baja |
| Tiempo para tener algo funcionando | Horas | 15 minutos |
| Memoria persistente | MEMORY.md por agente | ~/.claude/agent-memory/ |
| Costo de iteración de diseño | Alto (tokens orquestados) | Bajo (suscripción base) |
| Caso ideal | Personalidad rica, transversal | Especialista técnico acotado |
| Mejor para | Marketing, ventas, contenido, soporte | Code review, tests, docs |
| Curva de aprendizaje | Media-alta | Baja |
| Reutilización entre proyectos | Alta (capacidades transversales) | Alta (alcance global) |
A continuación, los detalles de cuándo conviene cada una.
OpenClaw funciona mejor cuando
El agente tiene una personalidad rica que necesita afinarse en el tiempo. Un agente de comunicación, ventas, soporte o cualquier rol donde el tono y la identidad importan tanto como la capacidad técnica, se beneficia de tener archivos separados para identidad, alma, objetivos y memoria.
También es mejor cuando varios agentes deben compartir una memoria operativa o cuando el agente principal necesita orquestar múltiples subagentes con identidades muy distintas. La separación explícita en archivos hace más fácil mantener consistencia entre proyectos y reutilizar capacidades.
Claude Code funciona mejor cuando
El subagente es un especialista técnico con un rol claro y acotado: revisor de código, generador de tests, escritor de documentación. La compacidad de un solo archivo facilita la creación rápida y la distribución entre equipos. Si el rol del subagente es relativamente estable y no necesita evolucionar mucho, no hace falta la complejidad de cinco archivos separados.
Además, Claude Code tiene una ventaja operacional importante: vive dentro del flujo de desarrollo. Si el caso de uso es codear, hacer commits, ejecutar tests, no tiene sentido salir de la terminal hacia otro sistema.
Lo que comparten
Ambas arquitecturas reconocen el mismo principio fundamental: un buen subagente requiere separación entre cuatro capas. La diferencia está en cuántos archivos se usan para representar esas capas, no en si las capas existen.
CUATRO CAPAS DE TODO SUBAGENTE
┌──────────────────────────────────────────────────┐
│ 1. IDENTIDAD quién es el agente │
│ 2. PRINCIPIOS cómo opera y sus límites │
│ 3. MEMORIA qué sabe del usuario │
│ 4. HABILIDADES qué puede hacer y cómo │
└──────────────────────────────────────────────────┘
↓ ↓
OpenClaw: 5+ archivos Claude Code: 1 archivo
separados por carpeta con YAML frontmatter
Si una de estas cuatro capas falta o está mezclada con otra, el agente se vuelve frágil: empieza a contradecirse, a olvidar contexto, o a perder consistencia entre sesiones.
El error que cometí al empezar con OpenClaw (y cómo evitarlo)
Cuando comencé a explorar OpenClaw, hice exactamente lo que no se debe hacer: intenté diseñar la personalidad del agente principal y de los subagentes desde cero, dentro del propio OpenClaw, iterando estructuras complejas con cada conversación. Construí una arquitectura sobredimensionada, con archivos que se cruzaban entre sí, responsabilidades que se solapaban, y reglas que se contradecían en silencio. Al final tuve que eliminar todo y empezar de nuevo.
El problema no fue solo el tiempo perdido. Cada iteración dentro de OpenClaw consume tokens, y los tokens cuestan dinero real. Cuando estás afinando la definición de un agente, no estás ejecutando trabajo útil: estás escribiendo y reescribiendo archivos de configuración.
Pagar precios de orquestación para diseñar la arquitectura es como cobrar tarifa de Uber para mover muebles dentro de tu casa.
La recomendación práctica que me hubiera ahorrado plata: planear y diseñar la estructura de los agentes por fuera, en una herramienta más económica o incluso gratuita, y solo cuando la arquitectura esté estable, llevarla a OpenClaw para ejecutar el trabajo real. Una conversación con un asistente general es órdenes de magnitud más barata que una con un agente orquestado, y para la fase de diseño funciona igual de bien o mejor.
Esto no es un problema exclusivo de OpenClaw. Aplica a cualquier sistema de agentes en producción: el costo operacional está pensado para que ejecuten tareas valiosas, no para que sirvan de borrador. Diseña afuera, ejecuta adentro.
Cómo empezar a construir tu propio subagente
Si nunca has construido un subagente, este es el camino que recomiendo, en orden:
1. Empieza por Claude Code para entender el patrón.
La barrera de entrada es baja: instala la CLI, crea un archivo en ~/.claude/agents/ con el frontmatter mínimo (name, description, tools) y un system prompt que describa el rol. En 15 minutos tienes algo funcionando, sin gastar más allá de tu suscripción base.
2. Itera con casos reales pequeños. Empieza con un subagente simple que resuelva una tarea concreta: revisar un PR, redactar un email tipo, generar tests para un módulo. La mayoría de los aprendizajes vienen de iterar con un agente simple, ver dónde falla, y entender qué pieza necesita más definición.
3. Diseña afuera, ejecuta adentro. Cuando estés listo para arquitecturas más ricas como OpenClaw, diseña la estructura de archivos en una herramienta económica (un asistente general, un editor de texto, lo que sea más barato), y solo migra la versión estable al sistema de producción. Iterar dentro de un agente orquestado quema dinero rápido.
4. Crece hacia la complejidad solo cuando el caso lo justifique. La pregunta clave no es cuál arquitectura es más sofisticada, sino cuál resuelve mejor el problema real y a qué costo. Un agente de cinco archivos no es mejor que uno de un archivo si el caso de uso no lo necesita.
Conclusiones Clave
- Los subagentes de IA no son prompts largos sino arquitecturas de archivos que separan identidad, memoria, objetivos y habilidades específicas.
- OpenClaw usa una carpeta con cinco archivos de definición (IDENTITY, SOUL, OBJECTIVES, MEMORY, README) más subcarpetas de skills, ideal para agentes con personalidad rica que se afinan en el tiempo.
- Claude Code usa un solo archivo markdown por subagente con YAML frontmatter, ideal para especialistas técnicos con roles acotados que viven dentro del flujo de desarrollo.
- Ambas arquitecturas comparten el mismo principio fundamental: separar las piezas de la personalidad de un agente para poder afinarlas individualmente.
- Diseña la arquitectura del agente por fuera del sistema de producción, en herramientas más económicas, y solo lleva la versión estable a OpenClaw o al sistema final. Iterar dentro de un agente orquestado quema dinero rápido.
- La elección entre una arquitectura y otra depende del caso de uso, no del nivel de sofisticación. Empezar simple y crecer hacia lo complejo suele ser el camino más eficiente.
- La memoria operativa del agente, donde sea que viva, debe contener tanto contexto sobre el usuario como definición del lector ideal al que el agente le habla.
Descarga un agente de ejemplo para empezar hoy
Para que no tengas que partir desde cero, preparé dos plantillas listas para usar de un agente de investigación llamado Sherlock, en las dos arquitecturas que cubre este artículo. Sherlock es un agente genérico que puedes adaptar a cualquier industria: análisis competitivo, due diligence, investigación de mercado o verificación de datos.
Cada plantilla incluye todos los archivos de definición, un skill de investigación profunda en cinco fases, y un README con instrucciones de instalación y personalización.
- Descargar Sherlock para OpenClaw: estructura completa con IDENTITY, SOUL, OBJECTIVES, MEMORY, README y skill de investigación.
- Descargar Sherlock para Claude Code: subagente listo para
~/.claude/agents/más skill complementaria, con instrucciones de instalación.
Las dos plantillas están pensadas como punto de partida, no como producto final. Edítalas, adáptalas, rómpelas y reconstrúyelas. Esa iteración es exactamente la fase de diseño que te recomiendo hacer fuera del sistema de producción.
¿Necesitas construir tus propios agentes especializados?
Si tu empresa está empezando a explorar la implementación de agentes de IA para áreas específicas como contenido, ventas o soporte, en Automatización con Agentes de IA y MCP ayudo a equipos B2B a diseñar la arquitectura, definir los roles y conectar los agentes con las herramientas reales del negocio.
Sobre el Autor
Juan Pablo Franco es consultor en marketing digital B2B, eCommerce y automatización con agentes de IA. Dirige Elefante, agencia de marketing digital, y publica sobre comercio agéntico, IA aplicada a negocios B2B y estrategia digital en su blog franco.com.co/blog. Trabaja con empresas industriales y distribuidores en Colombia y Latinoamérica.
Referencias
[1] Claude Code. Create custom subagents. Documentación oficial de Anthropic. https://code.claude.com/docs/en/sub-agents
[2] Chawla, A. Anatomy of the .claude/ Folder. Daily Dose of DS, 2026. https://blog.dailydoseofds.com/p/anatomy-of-the-claude-folder