Por qué fallan las habilidades de agente en cadena y la solución de tres capas que funciona
Las cadenas de habilidades avanzadas sobrecargan el contexto de un agente. Construye en lugar de eso con átomos, moléculas y compuestos, con ejemplos para Claude Code, LangGraph, CrewAI y Agno.
Fuentes: Why AI Agent Skills Break When We Chain Them and the Three-Layer Fix
Cuanto más capas tenga una cadena de habilidades del agente, más olvida este. Un patrón de composición de tres capas mantiene las habilidades fiables en cualquier profundidad, y es aplicable en Claude Code, LangGraph, CrewAI y Agno.
Por qué los gráficos de habilidades planos fallan
Sobre el papel, el gráfico de habilidades parece atractivo: se conectan las habilidades entre sí, el agente puede recorrer el gráfico y combinar capacidades según sea necesario. Una habilidad de marketing llama a una habilidad de investigación, que a su vez llama a una habilidad de extracción de datos, creando así un proceso automatizado.
En la práctica, este sistema falla en Claude Code, Codex, Cursor y en cualquier otro agente cuya ventana de contexto sea finita.
Aquí está el mecanismo. El agente carga primero solo las descripciones de las habilidades, lo cual es suficiente para saber qué existe. El contenido completo de una habilidad se carga cuando se invoca, y luego permanece en la sesión, ocupando espacio de contexto. Claude Code documenta abiertamente sus limitaciones: una vez que se compacta una sesión, una sola habilidad puede contener como máximo 5,000 tokens, y todas las habilidades juntas comparten 25,000. Ya cinco habilidades completas alcanzan ese límite. Si se cargan diez, algo se descarta sin previo aviso. Otros agentes chocan contra barreras similares, aunque con números diferentes.
Los desarrolladores de distintos frameworks describen la misma tendencia. Una llamada directa de A a B funciona de manera fiable. Una llamada de A a B a C da resultados variables. Una llamada de A a B a C a D es más esperanza que ingeniería. El agente termina con demasiadas instrucciones compitiendo por atención y muy poco espacio para almacenarlas.
Las habilidades de composición no son la idea errónea; lo que lo es es representarlas como un gráfico plano. Los ejemplos aquí utilizan el formato SKILL.md de Claude Code porque su documentación es la más clara, pero el patrón de átomos, moléculas y compuestos se aplica a cualquier agente que cuente con habilidades, herramientas o complementos.
Tres niveles que corresponden a la composición real
La mayoría de los frameworks de agentes ya organizan las cosas en capas: herramientas directas, flujos de trabajo en cadena y delegación a subagentes. Claude Code lo hace explícito mediante su jerarquía de comandos, habilidades y tareas. Los tres niveles mencionados corresponden a Codex (habilidades y comandos), Cursor (reglas y herramientas) y cualquier sistema que permita llamar a herramientas y ejecutar subprocesos.
Átomos: una habilidad, una tarea
Un átomo es un SKILL.md para una tarea específica, con un comportamiento casi determinista. No llama a otras habilidades ni toma decisiones subjetivas. Tiene una entrada clara y una salida clara.
---
name: verify-email
description: Verify an email address using Hunter.io API.
Use when validating email deliverability before outreach.
allowed-tools: Bash
---
## Verify Email
1. Read the Hunter API key from $HUNTER_API_KEY
2. Call the Hunter email-verifier endpoint
3. Return: status (deliverable/risky/undeliverable), score, smtp_check
4. If the API errors, report the error. Do not guess.
Una prueba sencilla: si puedes describir toda la habilidad en una oración sin usar “y”, se trata de un átomo. Otros ejemplos son extraer contenido de una URL y convertirlo a formato Markdown, ejecutar un conjunto de pruebas, analizar un archivo en busca de errores, obtener la diferencia entre solicitudes de integración o buscar registros DNS.
Moléculas: cadenas de átomos escritas
Una molécula resuelve un problema más complejo al hacer que dos a diez átomos funcionen en un orden específico. Lo que la diferencia de un grafo de habilidades es que la orquestación está escrita por escrito. La molécula no depende de que el modelo descubra qué átomos existen ni intente adivinar el orden en tiempo de ejecución.
---
name: qualify-lead
description: Research a company, find the right contact, verify
their email, output a qualified lead card.
allowed-tools: Bash Read Write
---
## Qualify Lead
Execute these steps IN ORDER.
### Step 1: Company Research
Use /research-company. Capture: size, industry, funding, tech stack.
### Step 2: Find Contact
Use /find-contact. Target: VP Eng, CTO, Head of Platform.
### Step 3: Find & Verify Email
Use /find-email, then /verify-email.
If undeliverable, return to Step 2 (max 3 attempts).
### Step 4: Output Lead Card
Write structured markdown to leads/{company-slug}.md
Observe lo que el archivo evita mencionar. Nunca indica al agente que determine qué habilidades necesita. Enumera la secuencia: investigar la empresa, encontrar al contacto, hallar el correo electrónico y, luego, verificarlo, en ese orden.
Esa claridad es la fuente de la fiabilidad. Una instrucción vaga como “investiga la empresa y encuentra la mejor forma de contactarlos” hace que el modelo elija elementos en tiempo de ejecución; a veces omite un paso o improvisa un flujo de trabajo que ignora por completo esos elementos.
Compuestos: orquestación de subagentes
Los compuestos surgen cuando una sola ventana de contexto no puede contener todo. Utilizan la herramienta Task de Claude Code para iniciar subagentes, cada uno con su propia ventana de contexto y sus propias habilidades precargadas.
---
name: outbound-playbook
description: Run the full outbound playbook for a target segment.
Spawns parallel agents to qualify leads and draft emails.
disable-model-invocation: true
allowed-tools: Bash Read Write Task Teammate
---
## Outbound Playbook
### Phase 1: Build Lead List
Ask the user for: target segment, company size range, geography.
Use /scrape-directory to pull matching companies.
### Phase 2: Parallel Lead Qualification (Task tool)
For each company (batch of 5):
- Spawn a subagent with qualify-lead preloaded
- Each subagent qualifies one company independently
### Phase 3: Draft Emails (Task tool)
For each qualified lead:
- Spawn a subagent with draft-email preloaded
### Phase 4: Human Review Checkpoint
STOP. Present sample drafts. Ask: "Review these. Adjust or proceed?"
Do NOT proceed without explicit user approval.
### Phase 5: Campaign Summary
Compile results to outbound/{segment}/campaign-summary.md
Hay dos características que diferencian a los compuestos. Primero, los subagentes cuentan con ventanas de contexto separadas, por lo que la tarea de calificar leads no compite con la redacción de correos electrónicos por espacio. Por eso, los compuestos pueden escalar más allá del límite que impide el funcionamiento de cadenas complejas.
Segundo, disable-model-invocation: true significa que solo una persona puede iniciar el playbook. El modelo no puede decidir por sí mismo lanzar una campaña externa. Los compuestos activan acciones en el mundo real, por lo que debe haber un humano al mando.
Disposición de carpetas
.claude/skills/
# ATOMS — single purpose, near-deterministic
verify-email/SKILL.md
find-email/SKILL.md
find-contact/SKILL.md
research-company/SKILL.md
scrape-url/SKILL.md
# MOLECULES - explicit chains of atoms
qualify-lead/SKILL.md
review-and-test/SKILL.md
draft-blog-post/SKILL.md
# COMPOUNDS - subagent orchestration, human-driven
outbound-playbook/SKILL.md
feature-build-ship/SKILL.md
Los nombres son flexibles. Lo que importa es la separación.
La misma idea en otros lugares
Nada de lo aquí expuesto es específico de SKILL.md. Cada framework de agentes importante cuenta con equivalentes, y aunque la sintaxis varía, la lógica de composición se mantiene igual.
LangGraph: herramientas, cadenas, subgrafos
En LangGraph, los átomos son funciones decoradas con @tool; las moléculas son grafos secuenciales con un orden de nodos explícito; y los compuestos son subgrafos con estado independiente.
from langgraph.graph import StateGraph
from langchain_core.tools import tool
# ATOM: a single tool
@tool
def verify_email(email: str) -> dict:
"""Verify email deliverability via Hunter.io."""
response = requests.get(f"https://api.hunter.io/v2/email-verifier?email={email}")
return response.json()
# MOLECULE: explicit sequential graph
workflow = StateGraph(LeadState)
workflow.add_node("research", research_company)
workflow.add_node("find_contact", find_contact)
workflow.add_node("verify", verify_email)
workflow.add_edge("research", "find_contact")
workflow.add_edge("find_contact", "verify")
graph = workflow.compile()
# COMPOUND: subgraph composition
parent = StateGraph(CampaignState)
parent.add_node("qualify", qualify_subgraph) # each is a compiled graph
parent.add_node("draft", email_subgraph) # with its own state
parent.add_node("review", human_review_node)
La diferencia con Claude Code es que una molécula de LangGraph es un grafo con aristas explícitas en lugar de una lista de instrucciones, por lo que la orquestación es estructural y no textual. Las condiciones, los bucles y las ramas paralelas surgen de manera más natural de esta forma, aunque su configuración requiere más código.
CrewAI: herramientas, tareas y equipos dentro de flujos
CrewAI realiza un mapeo claro. Los átomos son herramientas, las moléculas son tareas enlazadas con dependencias de contexto, y los compuestos son equipos ejecutados por flujos.
from crewai import Agent, Task, Crew, Flow
from crewai.tools import tool
# ATOM: a tool
@tool
def verify_email(email: str) -> str:
"""Verify email deliverability."""
return requests.get(f"https://api.hunter.io/v2/email-verifier?email={email}").text
# MOLECULE: tasks chained via context
researcher = Agent(role="Researcher", goal="Find company info", tools=[search_tool])
verifier = Agent(role="Verifier", goal="Verify contacts", tools=[verify_email])
research_task = Task(description="Research {company}", agent=researcher)
verify_task = Task(description="Verify the contact", agent=verifier, context=[research_task])
crew = Crew(agents=[researcher, verifier], tasks=[research_task, verify_task])
# COMPOUND: Crews inside a Flow
class OutboundFlow(Flow):
@start()
def qualify_leads(self):
return qualify_crew.kickoff(inputs={"segment": self.state.segment})
@listen(qualify_leads)
def draft_emails(self, qualified):
return email_crew.kickoff(inputs={"leads": qualified})
@listen(draft_emails)
def human_review(self, drafts):
return drafts # pause for human approval
El parámetro context=[research_task] representa el vínculo explícito. Ese parámetro indica a la tarea de verificación que espere hasta que finalice la tarea de investigación y que lea los resultados obtenidos. Si no se incluye, cada tarea se ejecuta por separado, por lo que la cadena de procesos desaparece.
Agno: herramientas, agentes, equipos
Agno cuenta con el mapeo más sencillo. Los átomos son funciones @tool, una molécula es un agente que contiene varias herramientas además de una descripción que determina el orden de ejecución, y los compuestos utilizan la estructura de equipo.
from agno.agent import Agent
from agno.models.anthropic import Claude
from agno.tools import tool
# ATOM
@tool
def verify_email(email: str) -> str:
"""Verify email deliverability via Hunter.io."""
return requests.get(f"https://api.hunter.io/v2/email-verifier?email={email}").text
# MOLECULE: agent with ordered tools
qualify_agent = Agent(
model=Claude(id="claude-sonnet-4-6"),
description="Qualify a lead: research company, find contact, verify email. Execute in that order.",
tools=[research_company, find_contact, find_email, verify_email],
)
# COMPOUND: team of agents
from agno.team import Team
outbound_team = Team(
agents=[qualify_agent, email_drafter, campaign_reporter],
description="Run the full outbound playbook for a target segment.",
)
Dado que el orden se define en la descripción, la molécula de Agno se asemeja más al enfoque de SKILL.md que a los bordes estructurales de LangGraph. Es más sencillo de escribir y su orden es ligeramente menos determinista.
Una arquitectura, muchas sintaxis
Los detalles de implementación difieren, pero la estructura no. Cualquier framework que vaya más allá de demostraciones simples termina teniendo las mismas tres capas, ya que las restricciones son idénticas en todas partes: contexto finito, enlace automático poco fiable y necesidad de supervisión humana en tareas de alto riesgo.
Donde sigue fallando
- Los átomos débiles arruinan todo lo que está por encima de ellos. Si un átomo para verificar correos informa éxito cuando en realidad la API falló, toda molécula o compuesto que dependa de él generará resultados erróneos. Pruebe los átomos uno por uno antes de combinarlos.
- Las moléculas con más de diez átomos resultan poco fiables. En Claude Code, el presupuesto total después de la compactación constituye un techo rígido, y los demás agentes también tienen sus propios límites. Mantenga las moléculas entre dos y diez átomos y coloque los pasos críticos al principio.
- Los compuestos con entre ocho y diez moléculas también alcanzan su propio límite. El orquestador debe seguir qué subagentes han finalizado, qué han producido y qué viene a continuación; más allá de un tamaño determinado, pierde el hilo de los procesos. Divida un compuesto más grande en dos, colocando un punto de control humano entre las dos partes.
- La invocación automática es menos fiable que la invocación explícita. Las evaluaciones de agentes publicadas por Vercel indicaron que ciertas habilidades no se activaban en una gran parte de los casos de prueba, y es probable que este patrón se mantenga fuera de Claude Code. Esto es tolerable para los átomos. En el caso de moléculas y compuestos, desactive la invocación automática e invoquelas usted mismo.
Tú eres el conductor y el agente es el motor.
Por qué es importante
El recurso escaso no es la capacidad de procesamiento ni los tokens. Es tu atención. Escribir “verificar este correo electrónico” y escribir “ejecutar acciones externas para el segmento fintech” requieren aproximadamente el mismo esfuerzo mental para iniciarse y monitorearse, pero los resultados difieren enormemente.
En resumen, los átomos proporcionan al agente unidades de trabajo predecibles; las moléculas unen esas unidades en secuencias que logran algo; y los compuestos ejecutan varias secuencias simultáneamente en ventanas de contexto separadas. Cada nivel genera más resultados, mientras que tu propia atención se mantiene más o menos constante.
La arquitectura ya cuenta con soporte, de forma explícita en Claude Code y a través de estructuras equivalentes en otros lugares. Lo que la mayoría de los desarrolladores aún no han creado es el patrón de composición.
La documentación de habilidades de Claude Code se encuentra en code.claude.com/docs/en/skills, y el formato SKILL.md sigue el estándar abierto Agent Skills que funciona en varios herramientas de IA. Los átomos, moléculas y compuestos son un patrón propuesto, y el código mostrado es pseudocódigo destinado a explicar los conceptos.