Subagentes en Cursor: De un Agente a un Equipo de IAs
TL;DR: Los subagentes de Cursor permiten dividir una tarea compleja entre varias IAs que trabajan en paralelo, cada una con su propio contexto. Combinados con SKILL.md (un estándar que comparten Claude Code, Copilot y Gemini CLI), convierten al agente en un equipo coordinado. En esta guía configuras ambos desde cero y aprendes a evitar los errores que rompen el flujo.
El problema: un agente, una cola de tareas
Cada vez que el agente de Cursor trabaja en algo complejo (refactorizar un módulo, escribir tests y actualizar documentación), lo hace de forma secuencial. Una tarea detrás de otra, en el mismo contexto. El resultado: la ventana de contexto se llena, las respuestas pierden precisión y tú esperas.
Este cuello de botella es el mismo que ya analizamos al hablar de cómo los agentes queman tokens innecesariamente. Un solo agente intenta abarcar todo, su ventana se satura y el coste (en tiempo y en tokens) se dispara.
Los subagentes atacan este problema dividiendo el trabajo.
¿Qué son los subagentes en Cursor?
Un subagente de Cursor es un agente hijo que se ejecuta con su propia ventana de contexto, acceso a herramientas independiente y, opcionalmente, un modelo diferente. El agente principal delega una subtarea, el subagente la resuelve y devuelve el resultado.
Cursor introdujo los subagentes en la versión 2.4 (22 de enero de 2026) y los amplió con la Agents Window de Cursor 3 (2 de abril de 2026). La diferencia con abrir otra conversación manualmente es que el agente principal orquesta el trabajo: decide qué delegar, recibe resultados y los integra.
Los subagentes predeterminados cubren tres funciones:
- Investigación del codebase: explorar archivos, dependencias y estructura sin contaminar el contexto principal.
- Ejecución en terminal: correr comandos, tests o scripts en paralelo.
- Generación paralela: producir código en múltiples archivos simultáneamente.
Si vienes de Claude Code, el concepto es similar a sus subagentes de tipo Explore o general-purpose. La diferencia clave: Cursor los ejecuta dentro de la interfaz visual del IDE, con preview de cambios integrado. Ya comparamos ambos enfoques en el análisis de VS Code Agents vs Cursor 3.
Antes y después: el impacto en un caso real
Para entender el cambio, veamos un escenario concreto. Necesitas añadir un endpoint a una API, con tests, validación y documentación.
| Paso | Sin subagentes | Con subagentes |
|---|---|---|
| Analizar dependencias | El agente lee archivos uno a uno | Subagente de investigación mapea el proyecto |
| Generar código | Secuencial: handler, schema, middleware | Paralelo: cada archivo en un subagente |
| Escribir tests | Espera a que el código esté listo | Subagente de tests trabaja en paralelo |
| Contexto consumido | Una sola ventana saturada | Distribuido entre agentes independientes |
El agente principal mantiene una visión de alto nivel mientras los subagentes se concentran en tareas acotadas. Esto reduce la saturación del contexto, una de las causas principales de context drift en agentes de código.
Cómo configurar subagentes personalizados
Cursor incluye subagentes predeterminados, pero puedes crear los tuyos. Se definen como archivos YAML en .cursor/agents/.
Un subagente para revisión de seguridad, por ejemplo:
# .cursor/agents/security-review.yaml
# Revisa cambios buscando vulnerabilidades comunes (OWASP Top 5)
name: security-review
description: "Revisa código buscando inyecciones SQL, XSS y secrets expuestos"
model: claude-sonnet-4-6
tools:
- file_read
- grep
- terminal
instructions: |
Analiza los archivos modificados buscando:
1. Inputs sin sanitizar que lleguen a queries o HTML
2. Variables de entorno hardcodeadas
3. Endpoints sin autenticación
Reporta con severidad (alta/media/baja) y línea exacta.Tres puntos clave sobre la configuración:
- Modelo independiente: cada subagente puede usar un modelo distinto. Usa uno rápido (Sonnet) para búsqueda y uno potente (Opus) para generación compleja.
- Herramientas restringidas: limita el acceso a lo necesario. Un subagente de investigación no necesita escribir archivos.
- Concurrencia controlada: en pruebas reportadas por la comunidad, más de 8 subagentes simultáneos ralentizan las respuestas en torno a un 40%. La zona óptima está entre 3 y 6.
SKILL.md: conocimiento reutilizable entre agentes
SKILL.md es un archivo markdown que enseña al agente cómo realizar una tarea específica. A diferencia de las rules (siempre activas), los skills se activan solo cuando la tarea es relevante.
Lo interesante: SKILL.md es un estándar abierto compartido entre varios agentes de código. Un skill que escribes una vez funciona en todos.
| Agente | Directorio de skills |
|---|---|
| Cursor | ~/.cursor/skills/ o .cursor/skills/ |
| Claude Code | ~/.claude/skills/ |
| GitHub Copilot | ~/.copilot/skills/ o .github/skills/ |
| Gemini CLI | ~/.gemini/skills/ |
Si ya trabajas con skills en Claude Code (como los skills autogenerados de AgentHandover), puedes reutilizarlos en Cursor copiándolos a la carpeta correspondiente.
Crear un skill paso a paso
Ejemplo: un skill que estandariza cómo crear componentes React en tu proyecto.
Primero, crea la estructura de carpetas:
# Estructura mínima: carpeta con nombre descriptivo + SKILL.md dentro
mkdir -p .cursor/skills/react-component
touch .cursor/skills/react-component/SKILL.mdDespués, define el skill con frontmatter YAML e instrucciones markdown:
---
name: react-component
description: Crea componentes React con TypeScript, tests y estructura estándar del proyecto.
---
# React Component Skill
Al crear un componente React en este proyecto:
1. Usa functional components con TypeScript
2. Props en interface separada: `ComponentNameProps`
3. Exporta desde `index.ts` del directorio
4. Crea test con React Testing Library en `__tests__/`
5. Usa CSS Modules para estilos (no inline styles)Cuando le pidas al agente "crea un componente de tabla de datos", detectará el skill automáticamente y aplicará las convenciones. La clave está en el campo description: es lo que el agente lee para decidir si activa el skill. Si la descripción es vaga, el skill no se activará cuando debería.
Regla práctica: escribe la descripción pensando en cómo le pedirías la tarea al agente, no como documentación técnica.
Generación de imágenes en el editor
La tercera funcionalidad que llegó con Cursor 2.4 es la generación de imágenes desde las conversaciones del agente. Tres usos concretos:
- Mockups rápidos: "Genera un wireframe de la página de login" produce una imagen en
assets/. - Diagramas de arquitectura: visualizar flujos de datos antes de implementar.
- Assets de placeholder: iconos o imágenes temporales durante prototipos.
No sustituye a Figma ni a un diseñador. Es una herramienta de prototipado para validar ideas antes de invertir tiempo en implementación detallada. Las imágenes se guardan en assets/ por defecto y se referencian directamente desde tu código.
En Producción
La diferencia entre un tutorial de subagentes y usarlos en un proyecto real:
Conflictos de escritura. Dos subagentes pueden intentar modificar el mismo archivo. Cursor muestra un diff para resolverlo, pero es mejor prevenir: asigna archivos o directorios específicos a cada subagente en las instrucciones. Algo como "Solo modifica archivos dentro de src/tests/" evita colisiones.
Coste en tokens. Cada subagente consume tokens de forma independiente. En un plan Pro de Cursor (20 €/mes), los requests premium son limitados. Tres subagentes en paralelo consumen tres veces más rápido que uno solo. Usa modelos económicos (Sonnet, Haiku) para subagentes de investigación y reserva Opus para el agente principal.
Contexto compartido. Los subagentes no comparten contexto entre sí. Si uno descubre algo que otro necesita, el agente principal hace de intermediario. Un patrón que funciona: los subagentes escriben hallazgos en un archivo temporal (.cursor/context/research.md) que otros pueden leer.
Skills en equipos. Coloca los skills en .cursor/skills/ dentro del repositorio (no en el directorio home). Así se versionan con git y todo el equipo trabaja con las mismas convenciones. Mantén cada SKILL.md por debajo de 500 líneas; si necesitas más detalle, usa una subcarpeta references/ con archivos de apoyo.
Errores comunes y depuración
Error: el subagente no se activa. Causa: el archivo YAML no está en .cursor/agents/ o tiene errores de sintaxis. Solución: verifica la ruta y valida el YAML con yq o cualquier linter online.
Error: el skill no se detecta automáticamente. Causa: el campo description no coincide con la forma en que describes la tarea. Solución: reescribe la descripción simulando cómo le pedirías la tarea al agente. Invoca manualmente con /nombre-del-skill para verificar que funciona.
Error: subagentes que se sobreescriben. Causa: dos subagentes editando el mismo archivo en paralelo. Solución: añade reglas de alcance en las instrucciones: "Solo modifica archivos dentro de src/tests/".
Error: respuestas lentas con muchos subagentes. Causa: más de 8 subagentes simultáneos saturan la orquestación. Solución: reduce a 4-6 y agrupa tareas relacionadas en un solo subagente.
Preguntas frecuentes
¿Los subagentes de Cursor funcionan con cualquier modelo?
Sí. Cada subagente puede usar un modelo diferente: Opus para tareas complejas, Sonnet para investigación rápida, Haiku para clasificación simple. La selección se define en el archivo YAML de configuración del subagente con el campo model.
¿SKILL.md es compatible con otros agentes de código?
Sí. SKILL.md es un estándar abierto compatible con Claude Code, GitHub Copilot, Cursor y Gemini CLI. El formato (frontmatter YAML + instrucciones markdown) es idéntico en todos. Solo cambia el directorio de instalación.
¿Cuántos subagentes puedo ejecutar en paralelo?
No hay un límite técnico estricto, pero en la práctica, más de 6-8 subagentes simultáneos degradan el rendimiento. La recomendación es usar entre 3 y 6 para un equilibrio entre paralelismo y velocidad de respuesta.
Los subagentes convierten al agente de Cursor en un equipo coordinado en lugar de un trabajador secuencial. Combinados con SKILL.md, permiten que ese equipo siga las convenciones de tu proyecto sin repetir instrucciones en cada sesión. La clave está en delegar con límites claros: un subagente por responsabilidad, archivos de alcance definidos y modelos ajustados al coste de cada tarea.
Si ya apuestas por un stack de IA reducido y enfocado, los subagentes encajan como una forma de hacer más con las mismas herramientas, no de añadir nuevas.
¿Has configurado subagentes o skills en tu proyecto? Cuéntame qué patrones te funcionan en Twitter @sergiomarquezp_. La próxima semana exploraremos cómo auditar qué código escribió la IA y qué escribiste tú, una pregunta cada vez más relevante en equipos.