¿Qué resuelve este módulo?
Antes de entrar en MCP, Skills, Hooks o SDK necesitas ver el mapa completo. Este módulo responde una pregunta clave: ¿qué nivel del ecosistema necesito para mi problema? Con 8 niveles posibles — desde un prompt hasta un sistema de agentes operando 24/7 — elegir el equivocado significa sobreingeniería o suboptimización.
La analogía que conecta todo, abajo.
El Arquitecto y sus Herramientas
Imagina un arquitecto senior con múltiples formas de trabajar según la complejidad del encargo:
Infraestructura Transversal (no son niveles)
Estos componentes funcionan en cualquier nivel — no son un peldaño en la escalera, son el esqueleto que conecta todo con el mundo exterior.
Model Context Protocol
Conecta Claude a herramientas externas (Gmail, Slack, DBs, GitHub). Estándar abierto — adoptado por OpenAI, Google, Microsoft. A
Software Development Kit
Programa agentes desde tu código en Python o TypeScript. Mismas capacidades que Claude Code, vía API programática. A
REST Endpoint directo
Llamada HTTP pura. Prompt caching ahorra 90% del costo en llamadas repetidas. Batch API: 50% de reducción. A
Paquetes distribuibles
Combinan slash commands + MCP + hooks + subagentes en una instalación. Distribuibles via marketplace (git repo). A
"Claude Code es un sistema donde prompts, skills, agentes, multi-agentes y sistemas de agentes representan niveles crecientes de complejidad y autonomía, conectados al mundo exterior mediante MCP, programables vía SDK y API, con memoria persistente (CLAUDE.md), hooks para automatización y plugins para distribución."
Los 8 Niveles del Ecosistema
Haz clic en cada nivel para ver: qué es, cuándo usarlo, cuándo no, y casos reales. La tabla resumen al final.
Prompt directo
Consultar a un experto en una sola reunión. Te da la mejor respuesta posible en ese momento, pero la próxima semana no recuerda haberte visto. Cada conversación empieza desde cero.
Qué es: Instrucción en lenguaje natural dentro de una conversación. Sin archivos, sin estructura, sin persistencia. A
Formato: Texto plano — lo que escribes en claude.ai, Claude Desktop o la terminal de Claude Code.
Ventana de contexto: ~200K tokens con Claude Sonnet 4.6, hasta 1M con configuraciones extendidas. A
✅ Cuándo es suficiente: Tareas de una sola vez, preguntas puntuales, generación de código simple, brainstorming, explicaciones conceptuales.
❌ Cuándo NO: Cuando repites la misma instrucción en cada conversación. Cuando necesitas acceso a archivos, APIs o herramientas. Cuando necesitas consistencia entre sesiones.
Ejemplo concreto: "Explica la diferencia entre MCP y SDK en términos simples." Un prompt directo resuelve esto en segundos. No necesitas nada más.
CLAUDE.md — Memoria persistente
El manual de bienvenida que le das a un nuevo empleado el primer día. Lo lee una vez y aplica esas reglas en todo proyecto futuro — el stack que usamos, el estilo de código, cómo nombramos variables, qué comandos de build usamos. Sin ese manual, el empleado es brillante pero ignorante del contexto de tu empresa.
Qué es: Archivo markdown especial que Claude lee automáticamente al inicio de cada sesión. Instrucciones persistentes, reglas del proyecto, comandos de build, estilo de código. A
Formato: Archivo .md en la raíz del proyecto (o en ~/.claude/CLAUDE.md para config global). Recomendado: menos de 200 líneas por archivo.
Sistema de memoria completo — 4 capas:
- CLAUDE.md (tú escribes) → instrucciones persistentes que controlas A
- Auto Memory (Claude escribe) → insights de debugging, hábitos de workflow A
- Memory Tool → crea/lee/actualiza archivos entre sesiones, mejoró rendimiento +39% en benchmarks A
- Context Editing → limpieza automática de tool calls obsoletas cuando el contexto llega al límite A
✅ Cuándo usarlo: Siempre. Todo proyecto debería tener al menos un CLAUDE.md básico de 5 líneas.
❌ Cuándo NO: Información que cambia con cada conversación — para eso es el prompt directo.
Skill — Expertise empaquetado
Una caja de herramientas donde cada herramienta está afilada para un tipo de trabajo específico. No usas el mismo martillo para clavar y para atornillar. Una skill de "generación de reportes financieros" tiene las plantillas exactas, los formatos requeridos, y las instrucciones precisas — no para otro trabajo.
Qué es: Carpeta organizada con instrucciones, scripts y recursos que Claude puede descubrir y cargar dinámicamente. Extiende capacidades empaquetando expertise en recursos componibles. A
Estructura mínima:
mi-skill/ ├── SKILL.md ← obligatorio (nombre + descripción + instrucciones) ├── templates/ ← plantillas para completar ├── examples/ ← ejemplos del formato esperado ├── scripts/ ← scripts que Claude puede ejecutar └── resources/ ← docs de referencia, esquemas
⚡ Principio clave — Progressive Disclosure: Claude lee SKILL.md primero y solo carga recursos adicionales cuando los necesita. El contenido de una skill es prácticamente ilimitado — no satura el contexto. A
🌐 Estándar abierto: Agent Skills publicados en 2025 — portables entre Claude Code, Cursor, Gemini CLI. El repositorio awesome-agent-skills (GitHub) tiene 1,000+ skills de equipos oficiales y comunidad. A
✅ Cuándo usarla: Cuando repites una tarea con frecuencia y quieres consistencia y plantillas específicas.
❌ Cuándo NO: Tarea única que no se repetirá. Necesitas acceso a servicios externos en tiempo real → combinar con MCP.
Slash Commands — Atajos explícitos
Los atajos de teclado de tu computadora. Ctrl+C y Ctrl+V existen porque copiar y pegar se hace cientos de veces al día — tener que ir al menú cada vez sería absurdo. Los slash commands son eso: /review en lugar de escribir "activa la skill de revisión de código con estos parámetros" cada vez.
Qué es: Atajos que invocan skills o acciones predefinidas. Se escriben con / al inicio. Nativos o custom (creados por usuario o via plugins). A
Comandos nativos clave:
/review→ invoca la skill de revisión de código/init→ inicializa CLAUDE.md con documentación del codebase/plugin→ gestiona plugins (instalar, listar, marketplaces)/mcp→ ver estado de servidores MCP conectados/memory→ gestionar notas de memoria del agente
✅ Cuándo usarlos: Acceso rápido a skills frecuentes. Distribuir workflows a un equipo con interfaz consistente.
❌ Cuándo NO: Si tienes que explicar a un usuario qué slash command usar, probablemente la skill debería activarse sola por contexto.
Hooks — Automatización determinística
El sistema de alarmas y sensores de una tienda. No depende de que el empleado recuerde cerrar la alarma al final del día — el sensor lo detecta automáticamente y dispara la acción. Los hooks son esa capa de automatización determinística: garantizan que ciertas acciones SIEMPRE ocurran, sin depender del juicio del LLM.
Qué es: Comandos shell que se ejecutan en puntos específicos del ciclo de vida de Claude Code. Determinístico — pasa siempre, sin depender del modelo. A
Los 7 eventos del ciclo de vida:
| Evento | Cuándo se dispara | Caso de uso típico |
|---|---|---|
SessionStart | Al iniciar sesión | Cargar variables de entorno |
UserPromptSubmit | Usuario envía prompt | Validación de input, logging |
PreToolUse | Antes de ejecutar tool | Bloquear directorios sensibles |
PostToolUse | Después de completar tool | Formateo automático post-edición |
Notification | Claude envía notificación | Alertas personalizadas |
Stop | Agente principal termina | Resumen de cambios, cleanup |
SubagentStop | Subagente termina | Consolidar resultados paralelos |
✅ Cuándo usarlos: Auditoría, compliance, formateo, seguridad — todo lo que NO puede depender del "tal vez" del LLM.
❌ Cuándo NO: Cuando la acción depende del juicio contextual. No todo necesita ser determinístico.
Agente individual — Claude autónomo
Un consultor autónomo al que le asignas un proyecto completo y trabaja días enteros sin supervisión constante. Lee los archivos, ejecuta experimentos, depura errores, toma decisiones, y te reporta cuando hay algo importante que decidir. No necesita que lo guíes paso a paso.
Qué es: Claude operando autónomamente — leyendo archivos, ejecutando comandos, usando herramientas, tomando decisiones y iterando hasta completar una tarea. Claude Code en sí mismo es un agente. A
El núcleo de Claude Code es sorprendentemente simple: un while-loop que llama al modelo, ejecuta tools, y repite. La complejidad real vive en los sistemas alrededor: sistema de permisos con clasificador ML, pipeline de compactación de contexto en 5 capas, 4 mecanismos de extensibilidad (MCP, plugins, skills, hooks). A
🏢 Caso real — Stripe: 1,370 ingenieros usando Claude Code. Un equipo completó una migración de 10,000 líneas Scala→Java en 4 días (estimado original: 10 semanas). Ratio: ~12.5x. A
✅ Cuándo usarlo: Refactors, migraciones, debugging complejo, implementación de features completas.
❌ Cuándo NO: Tareas simples que un prompt resuelve en segundos. Cuando la tarea requiere múltiples especialidades en paralelo (escalar a multi-agente).
Multi-agente — Coordinación especializada
Un equipo de consultores especializados coordinados por un director. El experto en seguridad revisa los endpoints. El de performance analiza las queries. El de UX evalúa los flujos. El director consolida y decide. Cada uno trabaja en paralelo — algo imposible para un solo consultor.
Qué es: Múltiples agentes coordinados para resolver un problema que excede la capacidad de uno solo — ya sea por tamaño, múltiples especialidades, o necesidad de paralelismo. A
Los 4 patrones de orquestación:
| Patrón | Estructura | Cuándo usar | Ejemplo real |
|---|---|---|---|
| Pipeline | A→B→C secuencial | Pasos dependientes con orden fijo | Code review → test → deploy |
| Swarm | N paralelos → fusión | Subtareas independientes | Refactoring masivo multi-archivo |
| Supervisor/Worker | 1 supervisor + N workers | Criterio central de calidad | Council de 5 perspectivas + Chairman |
| Peer-to-peer | Agentes negocian entre sí | Expertise único en cada agente | Sistemas de trading multi-estrategia |
🏢 Caso real — Wiz: Migración Python→Go de 50,000 líneas en 20 horas de desarrollo activo (estimado manual: 2-3 meses). Patrón swarm con git worktrees — múltiples agentes sin conflictos de merge. A
🌐 Ecosistema 2026: OpenAI lanzó Agents SDK en marzo 2025 con "handoff" como abstracción central. Google lanzó ADK en abril 2025 con soporte nativo A2A Protocol. Claude Code puede interoperar con ambos vía MCP. A
✅ Cuándo usarlo: Problema que requiere múltiples especialidades. Tarea demasiado grande para un contexto. Subtareas independientes paralelizables.
❌ Cuándo NO: La coordinación añade complejidad, latencia y costo. No sobreingeniería.
Sistema de agentes — Orquestación a escala
Montar una empresa completa con múltiples departamentos operando 24/7. Tiene presupuesto (control de costos), métricas de performance (monitoreo), procesos de aprobación (human-in-the-loop), planes de contingencia (recuperación de fallos), y canales de comunicación entre departamentos (memoria compartida + MCP). Una empresa bien diseñada funciona aunque el CEO esté durmiendo.
Qué es: Combinación de múltiples patrones de orquestación operando a escala, con monitoreo, human-in-the-loop, recuperación de fallos y operación continua. B
Componentes típicos:
- Múltiples swarms y pipelines coordinados
- Monitoreo de rendimiento, latencia y costos en tiempo real
- Gates de aprobación humana en decisiones críticas (merge, deploy, emails)
- Recuperación automática de fallos (retry con backoff, fallback a modelo económico)
- Memoria compartida entre agentes (via archivos o MCP de base de datos)
- MCP servers para CI/CD, Slack, dashboards
🏢 Adopción enterprise: Deloitte → ~470,000 empleados (rollout enterprise más grande documentado). 70% de Fortune 100 usan Claude. Cognizant → 350,000 empleados entrenados. A
💰 Costo operativo estimado: ~$50-500/día dependiendo de número de agentes, frecuencia y modelos usados. C
✅ Cuándo usarlo: Operación continua 24/7. Múltiples especialidades a gran escala. Valor del output justifica la infraestructura.
❌ Cuándo NO: La sobreingeniería es el riesgo principal — una startup de 2 personas no necesita 37 agentes.
Tabla Resumen Comparativa
| Nivel | Nombre | Analogía | Persistencia | Autonomía | Costo aprox. | Riesgo |
|---|---|---|---|---|---|---|
| 0 | Prompt | Reunión con experto | No | Ninguna | ~$0.01-0.10 | Bajo |
| 1 | CLAUDE.md | Manual del empleado | Sí (archivo) | Ninguna | $0 | Bajo |
| 2 | Skill | Caja de herramientas | Sí (archivos) | Baja | Bajo | Medio |
| 3 | Slash | Atajos de teclado | Sí | Baja | Bajo | Bajo |
| 4 | Hooks | Sistema de alarmas | Sí | Media | Bajo | Medio |
| 5 | Agente | Consultor autónomo | Por sesión | Alta | ~$0.50-5/tarea | Medio |
| 6 | Multi-agente | Equipo de consultores | Por sesión | Muy alta | ~$2-50/sesión | Alto |
| 7 | Sistema | Empresa completa 24/7 | Continua | Máxima | ~$50-500/día | Alto |
¿Qué nivel necesito?
Usa este árbol de decisión antes de diseñar cualquier solución con Claude Code. Comenzar con el nivel equivocado es el error más común — demasiado complejo o demasiado simple para el problema.
Árbol de Decisión Interactivo
Vista Completa (referencia)
Principios para no sobreingeniería
Empieza en el nivel más bajo
Siempre empieza con el nivel más simple que podría funcionar. Escala solo si hay evidencia de que necesitas más.
La complejidad tiene costo
Multi-agente cuesta más en tokens, latencia y debugging. El beneficio debe superar ese costo claramente.
CLAUDE.md siempre, sin excepción
Cualquiera sea el nivel que uses, tener CLAUDE.md es la inversión de 10 minutos con mayor ROI en el ecosistema.
Contexto de Mercado — Claude Code no está solo
En 2026 el ecosistema de AI coding agéntico tiene múltiples jugadores. Entender el paisaje competitivo es esencial para elegir correctamente — y para saber qué combinar.
Claude Code en números (Q1 2026)
Los Cuatro Jugadores Principales
El Stack Profesional 2026 — No es elegir uno
Lo más frecuente no es elegir uno — es combinarlos:
Un arquitecto usa diferentes herramientas para diferentes tareas. Lo mismo aplica aquí. La pregunta no es "¿cuál es mejor?" sino "¿cuál es la herramienta correcta para ESTA tarea?". B
La Advertencia Honesta sobre Productividad
Muchos vendors afirman 50-100% de mejora de productividad. Los datos controlados cuentan otra historia.
¿Qué significa esto en práctica?
Las métricas individuales (líneas de código, commits) suben 20-40%. Pero las métricas organizacionales (lead time, deployment frequency) se mantienen o empeoran — por cuellos de botella en code review y QA. B
La ventaja real viene del uso correcto del nivel correcto: un agente autónomo haciendo una migración de 50K líneas genera un ROI claro y medible. Un desarrollador usando AI para completar frases, no tanto. Este módulo es la inversión para hacer ese uso correcto.
Casos Reales con Empresas Nombradas
Resultados reportados por las empresas o documentados por Anthropic. Los ratios de mejora son indicativos del potencial — los resultados dependen del tipo de tarea, equipo e implementación. B — nota epistémica
Contexto: 1,370 ingenieros usando Claude Code. Tarea: migrar 10,000 líneas de Scala a Java.
Resultado: 4 días de desarrollo activo vs. 10 semanas estimadas de trabajo de ingeniero.
Ratio de eficiencia: ~12.5x
Nivel utilizado: Agente individual — un solo agente leyendo el codebase, ejecutando conversiones, validando tests.
La migración Scala→Java es una tarea de transformación sistemática — no requiere decisiones de arquitectura complejas. Un agente puede aplicar patrones de conversión con consistencia superior a la humana para 10K líneas.
A — Anthropic case study
Contexto: Migración de 50,000 líneas Python a Go — el doble del tamaño del caso Stripe.
Resultado: 20 horas de desarrollo activo vs. 2-3 meses de estimado manual.
Técnica: Patrón swarm con git worktrees — múltiples agentes trabajando en diferentes partes del codebase en paralelo, sin conflictos de merge.
Por qué swarm y no agente individual: 50K líneas excede una ventana de contexto. Las subtareas (migrar módulo A, módulo B, módulo C) son independientes entre sí — ideales para paralelismo.
Git worktrees permite tener múltiples checkouts del mismo repositorio en directorios diferentes. Cada agente trabaja en su propio worktree — sin pisarse los archivos. El director consolida con merges al final.
A — Anthropic case study
Contexto: Ramp es una empresa fintech de gestión de gastos. Necesitaban reducir el tiempo de investigación de incidentes financieros — correlacionar miles de transacciones para detectar patrones anómalos.
Resultado: 80% de reducción en tiempo de investigación. Un agente puede correlacionar miles de transacciones en un solo contexto — algo que requería horas de trabajo manual de múltiples analistas.
Técnica: Integración via SDK de Python. El agente recibe un reporte de incidente, consulta la base de datos de transacciones (via MCP), identifica patrones y genera un análisis estructurado.
El SDK permite a Ramp integrar Claude dentro de su pipeline existente de incidentes — no requieren que los analistas salgan a otra herramienta. Claude opera como un componente del sistema interno.
A — Anthropic case study
Contexto: Rakuten — e-commerce y servicios digitales. Desafío: reducir el tiempo de entrega de nuevas features.
Resultado feature delivery: De 24 días laborables a 5 días — reducción de 4.8x. Los ingenieros corren múltiples sesiones de Claude Code en paralelo, delegando tareas simultáneas en el mismo codebase.
Resultado estratégico: Desplegaron agentes en 5 funciones de negocio: producto, ventas, marketing, finanzas y operaciones. No solo coding — Claude opera como sistema transversal a toda la empresa.
Rakuten no solo usó agentes para código — escaló a un sistema donde distintos departamentos tienen sus propios agentes especializados, coordinados por una infraestructura compartida. Eso es un Sistema de agentes (Nivel 7).
A — Anthropic case study
Contexto: Deloitte — una de las Big 4 de consultoría. El rollout enterprise más grande públicamente documentado de Claude.
Resultado: ~470,000 empleados con acceso a Claude. Uso multi-nivel: desde prompts directos para analistas junior hasta sistemas de agentes para procesos repetitivos de auditoría.
Por qué importa: Demuestra que el ecosistema Claude Code escala a nivel corporativo con governance, compliance y control centralizados.
70% de las empresas Fortune 100 usan Claude. Cognizant → 350,000 empleados entrenados. Accenture → 30,000 entrenados. El ecosistema no es solo para startups técnicas. A
A — Anthropic partnerships 2025-2026
Resumen Ejecutivo
| Empresa | Qué hicieron | Nivel | Resultado |
|---|---|---|---|
| Stripe | Migración Scala→Java (10K líneas) | Nivel 5 | 4 días vs. 10 semanas (12.5x) |
| Wiz | Migración Python→Go (50K líneas) | Nivel 6 Swarm | 20h vs. 2-3 meses (>50x) |
| Ramp | Investigación incidentes financieros | SDK + Agente | 80% reducción tiempo |
| Rakuten | Features + 5 funciones de negocio | Nivel 5-7 | 24 días → 5 días (4.8x) |
| Deloitte | Rollout enterprise | Multi-nivel | 470,000 empleados |
⚠️ Nota epistémica: Los ratios de mejora son resultados reportados por las empresas o por Anthropic, no estudios independientes controlados. Son indicativos del potencial, no garantías. Los resultados dependen del tipo de tarea, equipo e implementación. B
Ruta de Aprendizaje Recomendada
5 fases progresivas — cada una construye sobre la anterior. No saltes fases: los fundamentos de las primeras fases hacen que las últimas sean mucho más efectivas.
Vista general
Fase 1 — Fundamentos
- Usar prompts directos en Claude Code / claude.ai hasta sentirse cómodo con las capacidades de base — experimenta con diferentes tipos de tareas.
- Crear tu primer CLAUDE.md con las reglas de tu proyecto actual — aunque sean 5 líneas. Stack, convenciones de código, comandos de build.
- Entender el concepto de ventana de contexto — ~200K tokens con Claude Sonnet 4.6. Saber cuándo una tarea "excede" una ventana es crucial para los niveles superiores.
- Observar a Claude Code actuando como agente — nota cómo lee archivos, ejecuta comandos bash, itera sobre errores. Ese while-loop en acción.
Fase 2 — Skills y Automatización
- Instalar una skill existente del repositorio awesome-agent-skills (1,000+ disponibles) — elige una para una tarea que ya haces.
- Crear tu primera skill custom con SKILL.md + templates para una tarea que repites. 30 minutos de inversión, semanas de ahorro.
- Configurar un hook simple — ej: formateo automático post-edición con prettier o black. Ver la diferencia entre "Claude lo hace si recuerda" y "SIEMPRE pasa".
- Usar slash commands para invocar skills rápidamente — comparar velocidad vs. prompt largo para la misma acción.
Fase 3 — Agentes y Conexión Externa
- Conectar un MCP server pre-built — ej: Google Drive o GitHub. Ya existen, solo configurar. Ver cómo Claude accede a recursos externos sin código propio.
- Usar subagentes para paralelizar una tarea que ya tienes — ver el speedup en tiempo real. Ejemplo: analizar 10 archivos en paralelo vs. en secuencia.
- Explorar plugins — instalar uno del marketplace y ver cómo combina slash commands + MCP + hooks en una instalación.
Fase 4 — SDK y API
- Hacer tu primera llamada API directa — curl o Python requests al endpoint
/v1/messages. Ver la respuesta raw. Desmitificar qué hay debajo del SDK. - Usar el SDK de Python o TypeScript para construir un agente simple con tools — el SDK envuelve la complejidad del loop de herramientas.
- Implementar tool use en el SDK — dale herramientas a tu agente y observa cómo razona sobre cuándo usarlas vs. cuándo no.
- Crear un MCP server propio para un servicio que tú ya usas — Python, ~50 líneas, completamente viable. Tu primera contribución al ecosistema.
Fase 5 — Multi-agente y Producción
- Diseñar un pipeline de 2-3 agentes para una tarea compleja real — no un ejercicio. Un problema tuyo con una solución que genere valor inmediato.
- Experimentar con swarm usando git worktrees — ver cómo múltiples agentes trabajan el mismo codebase sin pisarse. El patrón de Wiz.
- Implementar human-in-the-loop en puntos de decisión — Claude propone, humano aprueba antes de merge, antes de enviar email, antes de deploy.
- Monitorear costos y rendimiento — construir un sistema sin métricas es construir a ciegas. Saber cuánto cuesta cada agente por tarea.
Recursos para Continuar
- → code.claude.ai/docs — Claude Code docs A
- → anthropic.com/engineering — Engineering blog A
- → modelcontextprotocol.io — MCP spec A
- → awesome-agent-skills (1,000+ skills) A
- → awesome-mcp-servers (17K+ servidores MCP) A
- → Módulo 02: Skills en profundidad
- → Módulo 03: Agentes — tipos y patrones
- → Módulo 07: MCP — protocolo y servidores