Subagentes y Skills · 2025

Orquestando
inteligencia

Subagentes, skills y la arquitectura de
agentes que escalan.

Claude Code OpenCode CLAUDE.md AGENTS.md Skills
Alejandro de la Fuente

Alejandro de la Fuente

Technical Leader · NTT Data · GDNE

🌐 🐙 💼
El Reto

¿Por qué un solo agente no escala?

Cuando la complejidad supera la capacidad de un agente individual.

🧠

Contexto limitado

Un solo agente tiene una ventana de contexto finita. Tareas grandes desbordan su capacidad de atención.

🔧

Sin especialización

Un agente generalista no puede ser experto en todo. Testing, review, documentación... cada tarea requiere expertise diferente.

⏱️

Ejecución secuencial

Un solo agente procesa una cosa a la vez. Sin paralelismo, los proyectos complejos se eternizan.

💡

La solución no es un agente más grande. Es un equipo de agentes que colaboran.
Fundamentos

Anatomía de un Subagente

Un agente invocado por otro agente para una tarea específica.

🤖
Agente Principal Recibe el prompt, analiza y delega
🔍 Explore Buscar en codebase
🔧 Builder Implementar cambios
↓ resultados parciales ↓
✅ Contexto enriquecido al agente principal

Características clave

  • ✓
    Contexto aislado: Solo ve lo que el agente principal le pasa
  • ✓
    Tarea acotada: Una responsabilidad clara y específica
  • ✓
    Ciclo de vida efímero: Nace, ejecuta, muere
  • ✓
    Sin historial completo: No accede a toda la conversación
  • ✗
    NO es independiente: Siempre es invocado por otro agente
📌

Importante: Un subagente no decide QUÉ hacer. Solo CÓMO hacer lo que se le encarga.
Arquitectura

Patrones de Orquestación

Cómo los agentes coordinan el trabajo.

🎯

Single Agent

Un agente, múltiples herramientas. Simple pero limitado.

Ideal para tareas simples
🤝

Multi-Agent

Agentes peers que colaboran. Cada uno con su expertise.

Flexible pero complejo
🎭

Orchestrator

Un coordinador delega a workers especializados. Paralelismo real.

El más usado en producción
👁️

Supervisor

Un agente revisa y aprueba outputs de otros. Control de calidad.

Para precisión crítica
💡

En esta charla nos centramos en Orchestrator + Workers, el patrón que escala de verdad.
Ventajas

Por qué orquestar

Los beneficios reales de la arquitectura multi-agente.

⚡

Paralelismo

Múltiples subagentes trabajando simultáneamente

4-8x más rápido en tareas complejas
🎯

Especialización

Cada agente domina su tarea

↑ Calidad resultados más precisos y consistentes
🔒

Aislamiento de Contexto

Cada subagente ve solo lo necesario

↓ Ruido menos confusión, menos alucinaciones
💡

La orquestación no es overhead. Es la diferencia entre un junior que hace todo y un equipo senior que divide y vencerás.
Skills

¿Qué es un Skill?

La pieza que transforma un agente genérico en un experto.

📚

Un skill es un paquete de conocimiento especializado que modifica el comportamiento de un agente para una tarea o dominio concreto.

Un skill proporciona:

📜

Instrucciones

Reglas, patrones y convenciones que el agente debe seguir

🧠

Contexto

Información del dominio que el agente no tiene por defecto

🔧

Herramientas

Capacidades específicas que el agente puede invocar

💡

Analogy: Piensa en un skill como las especificaciones de un puesto de trabajo. Sin ellas, el empleado es capaz pero no sabe QUÉ hacer ni CÓMO hacerlo en tu empresa.
Estructura

Anatomía de un Skill

Los componentes que hacen funcionar un skill.

📄 skill-code-review.md
# Skill: Code Review Expert

## Instrucciones
- Revisar cada archivo modificado
- Buscar patrones de error comunes
- Verificar convenciones del proyecto

## Contexto del Proyecto
- Stack: TypeScript + React + Tailwind
- Patrón: Clean Architecture
- Tests: Vitest con coverage > 80%

## Herramientas disponibles
- lsp_diagnostics: errores del IDE
- grep: buscar patrones en el código
- bash: ejecutar tests y linters
📜

Instrucciones

Qué debe hacer el agente. Reglas específicas de comportamiento.

🧠

Contexto

Información del proyecto que el agente necesita conocer.

🔧

Herramientas

Capacidades específicas que el agente puede invocar.

✨

Un skill bien escrito es la diferencia entre un agente que ayuda y uno que estorba.
Implementación

Skills en la Práctica

CLAUDE.md, AGENTS.md y el ecosistema real de skills.

📄

CLAUDE.md

El archivo que define las reglas de tu proyecto para CUALQUIER agente de IA

# CLAUDE.md
// Reglas del proyecto

## Stack
- React 19 + TypeScript
- Tailwind 4
- Zustand para estado

## Patrones
- Container/Presenter
- Atomic Design
- TDD obligatorio

## Prohibido
- any type
- useEffect sin cleanup
- Props drilling
✓ Usado por: Claude Code, Cursor, todos los agentes compatibles
📁

AGENTS.md

Instrucciones más granulares, por directorio o por agente

# src/components/AGENTS.md

## Componentes UI
- Usar design tokens
- Accesibilidad AA
- Storybook para docs

## Naming
- PascalCase
- Prefijo por dominio:
  - Ui* (genéricos)
  - Feature* (dominio)
  - Layout* (estructura)
↳ Herencia: AGENTS.md en subdirectorios hereda del padre
⚡

.claude/skills/

Skills reutilizables como archivos Markdown con instrucciones detalladas

# ~/.claude/skills/react-19/SKILL.md

## React 19 Patterns

### Server Components
- 'use server' directive
- No hooks en server

### use() Hook
- Lee recursos en render
- Suspense boundary

### Actions
- form action prop
- useFormStatus()
∞ User-level (~/.claude) vs Project-level (./.claude)
💡

Clave: Los skills NO son mágicos. Son prompts estructurados que el agente carga automáticamente según el contexto. Cuanto más específico, mejor resultado.
Workshop

Crea tu Primer Skill

4 pasos para tener un skill funcional en 5 minutos.

1

Identifica el contexto

¿Qué tecnología/framework usas frecuentemente?

React 19, Tailwind 4, Zustand, Django...
💡 Empieza por lo que más repites
2

Crea la estructura

Crea el directorio y archivo SKILL.md

~/.claude/skills/mi-skill/SKILL.md
💡 El nombre del directorio = nombre del skill
3

Define el frontmatter

Nombre y descripción para que el agente sepa cuándo usarlo

name: react-19 description: Use when working with React 19...
💡 La descripción es clave para la activación automática
4

Añade contenido útil

Patrones, reglas, ejemplos de código

## Server Components ### use() Hook ### Actions
💡 Incluye DOs y DON'Ts

Tu reto: Antes de acabar esta sesión, crea un skill para tu framework favorito.

~/.claude/skills/[tu-framework]/SKILL.md
Potencia

Subagente + Skill

Cuando la orquestación se combina con el conocimiento especializado.

🎯 Tarea compleja del usuario
descompone
🎛️
Orquestador Analiza, planifica y despacha a subagentes especializados
dispatch
dispatch
dispatch
🎨 Subagente Frontend
⚡ React 19 Skill
→ Componentes tipados
🧪 Subagente Testing
⚡ Testing Skill
→ Tests E2E + unitarios
🔍 Subagente Review
⚡ Code Review Skill
→ Feedback estructurado
resultados convergen
✅ Resultado integrado y verificado
💡

Key Insight

El skill no hace al subagente más inteligente.
Lo hace más ENFOCADO.

¿Por qué funciona?

  • 1 El skill carga contexto específico SIN ocupar la ventana del orquestador
  • 2 Cada subagente opera con instrucciones PRECISAS para su dominio
  • 3 El orquestador consolida SIN conocer los detalles de cada skill
  • 4 Paralelismo real + especialización = mejor resultado en menos tiempo
⚠️

Anti-patrón: Pasar el skill completo al orquestador. El orquestador solo necesita SABER que existe el skill, no su contenido.
Contexto

Gestión de Contexto

El recurso más valioso y escaso en la orquestación.

Cómo fluye el contexto

👤 User Petición completa con todo el contexto
full context
🤖 Agent Recibe y procesa contexto completo
filtered context
⚡ Subagent Solo el contexto relevante para su tarea
relevant only
✅ Result Output + contexto relevante, no todo

Reglas de oro

01

Pasa SOLO lo necesario al subagente. Más contexto ≠ mejor resultado.

02

El resultado del subagente debe incluir contexto relevante, no solo el output.

03

El agente principal consolida resultados. No expone detalles internos al usuario.

04

Cada salto de contexto consume tokens. Diseña el flujo con eficiencia.

⚠️
80%

de los fallos en orquestación vienen de pasar demasiado o demasiado poco contexto.
Casos Reales

Patrones del Mundo Real

Cómo se usan subagentes y skills en herramientas reales.

🎯

Patrón común: Todas estas herramientas combinan orquestación inteligente + contexto especializado + iteración con memoria.
Cuidado

Errores Comunes

Lo que puede salir mal con subagentes y skills.

❌

Sobre-orquestar

No todo necesita subagentes. Una tarea simple con un orquestador es como matar moscas a cañonazos.

❌

Contexto excesivo

Pasar TODO el contexto a cada subagente. Más datos no es más inteligencia — es más ruido.

❌

Skills genéricos

Un skill que dice "haz buen código" no aporta nada. Los skills deben ser ESPECÍFICOS y CONCRETOS.

❌

No verificar outputs

Confiar ciegamente en el resultado de un subagente sin validación. Siempre verifica.

❌

Ignorar el coste

Cada subagente consume tokens. 5 subagentes haciendo lo que uno podría = 5x el coste.

⚠️

El 90% de los fracasos con agentes vienen de sobre-ingeniería. Empieza simple, escala cuando sea necesario.
Craftmanship

Buenas Prácticas

Los skills y subagentes son tan buenos como quien los diseña.

✅

Hazlo

✓ Define skills concretos con reglas específicas del proyecto
✓ Pasa el contexto mínimo necesario a cada subagente
✓ Usa CLAUDE.md como fuente de verdad del proyecto
✓ Verifica el output de cada subagente antes de integrarlo
✓ Empieza con un solo agente. Escala a orquestación solo cuando sea necesario
✓ Mantén tus skills versionados y documentados
❌

Evita

✗ Skills vagos: "escribe buen código" no es un skill
✗ Orquestación para tareas que un solo agente resuelve bien
✗ Subagentes sin instrucciones claras — producirán outputs inconsistentes
✗ Compartir el historial completo de conversación con subagentes
✗ Ignorar el coste en tokens de la multi-agentación
✗ Copiar skills entre proyectos sin adaptarlos al contexto local
🏗️

Tú eres el arquitecto. Los agentes son el equipo. Si el arquitecto no sabe lo que quiere, el equipo construye un desastre.
Hands-on

¡Vamos al Taller!

Es hora de construir tu primer skill desde cero.

🛠️

Skill de Arquitectura de Proyecto

Un skill que enseña al agente las convenciones, patrones y reglas de TU proyecto.

Pasos del taller:

1 Crear la estructura del skill (SKILL.md)
2 Definir las instrucciones del proyecto (stack, patrones, convenciones)
3 Configurar el contexto (archivos clave, dependencias)
4 Probar el skill con un agente real
5 Iterar y refinar basándote en los resultados
💡

Cómo un skill bien diseñado transforma por completo el output de cualquier agente.

Abre tu editor favorito. Vamos a programar.
Takeaways

Para llevarte a casa

01 Un solo agente no escala. La orquestación es el camino.
02 Los skills transforman agentes genéricos en expertos especializados.
03 CLAUDE.md es tu contrato con el agente. Escríbelo bien.
04 El contexto es oro. Pasa solo lo necesario, ni más ni menos.
05 Empieza simple. Un agente → skills → subagentes → orquestación completa.

Recursos

🔗 Claude Code🔗 OpenCode🔗 tellmealex.dev

Esta presentación fue construida con agentes de IA.

Código Sin Siesta · 2025
1 / 16
Navegación