Tu primer sub-agente en 30 minutos

Los sub-agentes son la respuesta a "hago lo mismo cada día y prompteo veinte veces". Encapsulas la instrucción y el flujo una vez en un sub-agente, y Claude Code lo spawnea desde ese momento al pulsar un botón. Todo lo que aprendiste en el Nivel 5 sobre el patrón CEO/Worker, en un build concreto de 30 minutos.

Si lo haces, acabas con un sub-agente que por ejemplo hace "convierte este ticket en un título y body limpios para PR de GitHub" sin que tengas que explicar las convenciones cada vez.

1. Elegir caso de uso

Busca una tarea que hagas al menos tres veces por semana a mano y que tenga input y output claros. Ejemplos que funcionan bien:

• De una descripción de bug generar un título + labels limpios para issue de GitHub
• De una transcripción de voicenote sacar una lista de tareas
• De un hilo de email con cliente armar un snippet de update de CRM
• De una idea escribir una variante de post Reddit en segunda persona

Mal caso de uso: "investigar XY". Demasiado abierto; para eso necesitas el research agent (Nivel 5), no un sub-agente pequeño.

Un consejo: si no decides, coge el primero de la lista. Lo necesita todo el mundo y puedes transferir lo aprendido a otros casos.

2. Crear la carpeta agents

En tu setup de Claude Code (o globalmente en ~/.claude/agents/ o por proyecto en .claude/agents/):

mkdir -p ~/.claude/agents
cd ~/.claude/agents
touch ticket-formatter.md

El nombre de archivo es el slug del agent. Sin espacios, usa guiones.

3. Escribir el frontmatter

Arriba de ticket-formatter.md va frontmatter YAML con tres campos: name, description, tools.

---
name: ticket-formatter
description: "Use this agent when the user pastes a raw bug description or Slack message and wants a clean GitHub-Issue title + body + labels. Trigger when user says 'turn this into a ticket' or 'format as issue'."
tools: ["Read", "Write"]
---

La description es el campo más importante. Claude Code lo lee y decide solo cuándo invocar el sub-agente. Sé específico, usa frases-trigger concretas que el usuario probablemente diga.

Un consejo: si description es vago ("helps with tickets"), el agente se triggea o nunca o demasiado a menudo. Mejor nombrar dos frases-trigger concretas explícitamente que una descripción general.

4. Escribir el system prompt

Bajo el frontmatter va el system prompt real. Es Markdown. Estructúralo así:

You are a GitHub Issue Formatter. Your job is to take raw text
(bug reports, Slack pastes, voice memo transcripts) and turn it
into a clean GitHub Issue.

Output Format (always exactly this structure):
- Title: max 70 chars, imperative ("Fix login redirect", not "Login is broken")
- Body: 3-5 short sentences max, no marketing
- Labels: pick from {bug, feat, docs, infra, security}
- Priority: pick from {p0, p1, p2, p3} based on user pain

Rules:
- Title MUST be in English even if input is German.
- Body in same language as input.
- If input is too vague, write "Title: NEEDS CLARIFICATION" and list 2 questions.

Spec de output concreta > instrucciones vagas. El agente es bueno cuando el output es formalmente consistente, no cuando es creativo.

5. Mantener la lista de tools mínima

En tools: solo lista las tools que el agente realmente necesita. Para ticket-formatter no hace falta ninguna (recibe texto, devuelve texto), pero Read/Write es útil por si tiene que leer convenciones de un CONVENTIONS.md.

Si omites tools:, el agente tiene acceso a todas. Suele ser demasiado y desfocaliza al agente.

6. Primer test

En Claude Code:

"Formatea esto como ticket de GitHub: [paste raw bug-text]"

Claude Code matchea la description, spawnea el sub-agente automáticamente. Ves en la salida que ticket-formatter está activo. Sale el output.

Si Claude Code NO lo spawnea: description demasiado vaga o frase-trigger demasiado lejos del prompt del usuario. Afina la description.

Un consejo: también puedes invocar sub-agentes explícitamente con "use the ticket-formatter agent on this text". Salta el auto-detect. Útil en fase inicial para probar.

7. Comprobar output con tarea real

Coge dos o tres bug reports reales de tu backlog y deja que el agente los formatee. Comprueba:

• ¿El title es consistente en forma (imperativo, máx 70 chars)?
• ¿Los labels son acertados?
• ¿Se pasó o se quedó corto en priority?
• En inputs vagos: ¿usó la lógica "NEEDS CLARIFICATION"?

Si no, el system prompt no es bastante específico. Itera.

8. Construir edge cases

¿Qué pasa si el usuario mezcla dos bugs en un texto? ¿Si el texto está en español? ¿Si mete un feature request en lugar de un bug?

La primera versión de un sub-agente no maneja estos casos. Los machaca en un mal output. Construyes el manejo en el system prompt:

If input contains MULTIPLE distinct issues, output one ticket per issue
in a numbered list.
If input is in Spanish or German, body language follows input.
If input is a feature request (not a bug), use Title prefix "[Feat]" 
and body must include "Why this matters: ..." section.

Pruébalo. Itera.

9. Ponerlo en uso

Cuando el agente sea estable, úsalo una semana en todos los tickets. Recoge los dos o tres casos donde la lía. Itera el system prompt otra vez.

Los sub-agentes no salen perfectos a la primera. El valor viene de dos o tres iteraciones con inputs reales. Inviertes una hora al principio y ahorras cinco por semana.

10. Construir más sub-agentes con el mismo formato

Cuando el primer sub-agente esté estable, puedes repetir el patrón para tres a cinco tareas más. Ejemplos:

• commit-msg-writer (de un diff sacar un commit message limpio)
• slack-summarizer (de una conversación Slack una nota de decisión)
• lead-qualifier (de una consulta por email score de lead + next action)

La ventaja de varios sub-agentes pequeños frente a uno universal: cada uno tiene un trigger claro y un output claro. Claude Code elige el correcto automáticamente. Mantenimiento por agente es bajo.

Si en algún momento tienes veinte sub-agentes y Claude Code tiene problemas para elegir el correcto, necesitas triggers especiales (slash-commands, hot-words). Pero eso es fase dos. De inicio, tres agentes es un buen estado.