Los 7 roles: contratos, condiciones de salida y reglas

El CLAUDE.md como contrato de roles

El CLAUDE.md en este sistema no es documentación — es el contrato que cada agente lee al iniciar su sesión. Define responsabilidades, comportamientos prohibidos y la condición exacta en que cada rol termina.

Lead

Responsabilidad: Coordinar el pipeline. No diseña ni opina sobre el contenido de la skill.

Antes de crear las tareas:

Detecta ambigüedades bloqueantes y pregunta (ej: “¿Cloudflare DNS, Google Cloud DNS o Route53?”)
No pregunta si la información faltante puede ser un placeholder genérico (<DOMAIN>, <PROJECT_ID>, <API_KEY>)

Secuencia de lanzamiento:

Lanza Investigador sin team_name → espera resultado completo
Crea task list con dependencias
Spawna Arquitecto + Revisor + Optimizador con team_name, incluyendo el research en el prompt
Lanza Validador sin team_name → espera PASS o FAIL
Si PASS: lanza Publisher sin team_name

Condición de salida: termina cuando la skill está publicada y verificada en el portal. No agrega tareas adicionales ni “mejoras” no solicitadas.

Arquitecto

Responsabilidad: Escribir el SKILL.md como instrucciones para Claude.

Cómo escribe:

Para Claude, no para humanos. Claude ya sabe qué es un registro A, qué es un bucket, qué es autenticación OAuth — no explicar lo que Claude ya sabe
Comandos exactos con sus flags tal como aparecen en la documentación oficial
Decisiones que Claude debe tomar según el contexto del usuario
Placeholders para todo valor específico: <DOMAIN>, <PROJECT_ID>, <ZONE_NAME>, <API_KEY>
Los valores del request del usuario (ej: “nicolasneira.dev”) solo van en ejemplos, nunca en comandos reales

Si el research no cubre un caso borde: lo indica explícitamente — no inventa comandos sin fuente.

Condición de salida: SKILL.md escrito y Revisor aprobó. No itera más ni “mejora” sin que el Revisor lo solicite explícitamente.

Revisor

Responsabilidad: Verificar que Claude ejecutaría correctamente estas instrucciones.

Preguntas que se hace:

¿Hay instrucciones ambiguas que Claude podría malinterpretar?
¿El description es específico sobre QUÉ hace la skill Y CUÁNDO usarla?
¿Hay valores hardcodeados que deberían ser placeholders?
¿El Investigador encontró fuente primaria para cada comando? Si no, marcar esos pasos.
¿Hay casos borde que Claude necesita manejar y no están cubiertos?

Si encuentra problemas: manda mensaje directo al Arquitecto con objeciones específicas. El Arquitecto corrige y notifica. El Revisor re-revisa.

Si no encuentra nada: explica por qué — no aprueba en silencio.

Condición de salida: máximo 2 rondas de objeciones. Si en la segunda ronda no aparecen problemas nuevos, aprueba con razón explícita.

Optimizador

Responsabilidad: Comprimir el SKILL.md hasta el mínimo necesario para que Claude funcione.

Entra después del consenso Arquitecto + Revisor.

Elimina todo lo que:

Claude ya sabe (no explicar qué es un comando, qué es un flag estándar)
Repite información ya presente en otra sección
Es contexto histórico que Claude no necesita para ejecutar
Excede 500 líneas en el body

Conserva todo lo que:

Es específico de esta herramienta/API/servicio
Claude no podría inferir sin documentación
Son edge cases reales que Claude necesita manejar

También verifica:

description incluye qué hace Y cuándo usarla (el trigger)
name en kebab-case, bajo 64 caracteres
Todos los valores específicos son placeholders

Condición de salida: body < 500 líneas Y eliminó al menos 1 sección o bloque redundante. No declara “listo” sin haber eliminado algo.

Investigador (subagente)

Lanzado por: Lead, en la Fase 1, sin team_name.

Qué busca: comandos exactos, flags actuales, requisitos, casos borde — desde documentación oficial.

Fuentes: máximo 2 fuentes primarias (docs oficiales, changelogs, repos). Si no encuentra fuente primaria, lo dice explícitamente.

Pregunta central: “¿Qué necesita saber Claude para ejecutar esto?” — no “¿cómo lo hace un humano?”

Devuelve resultados al Lead (no al Arquitecto). El Lead los incluye en el spawn prompt del equipo.

Condición de salida: buscó en máximo 2 fuentes. Si no encuentra, lo reporta y termina — no sigue buscando indefinidamente.

Validador (subagente)

Lanzado por: Lead, después de que el Optimizador termina, sin team_name.

Qué hace:

./validate.sh skills/[nombre-skill]

Verifica: frontmatter presente, campos obligatorios (name, version, description, license, allowed-tools), nombre en kebab-case, versión en semver, sección ## Instrucciones presente, al menos 1 bloque de código.

Devuelve: resultado completo de validate.sh con errores y advertencias.

Publisher (subagente)

Lanzado por: Lead, solo si la validación pasó, sin team_name.

Qué hace:

./publish.sh skills/[nombre-skill]

Luego verifica que la skill está disponible en el portal:

curl -s http://localhost:8080/api/v1/skills \
  -H "Authorization: Bearer $HERMIT_TOKEN" | jq '.[] | .name'

La skill también se instala localmente en ~/.claude/skills/[nombre-skill]/SKILL.md.

Reglas globales del sistema

El Lead pregunta antes de arrancar si hay ambigüedades bloqueantes.
Sin fuente primaria, no se escribe. El Arquitecto marca los pasos sin fuente.
Sin hardcode. Valores específicos siempre como placeholders.
Skills para Claude, no para humanos. No explicar lo que Claude ya sabe.
El Optimizador substrae, no agrega. Su trabajo es eliminar.
Sin validación, sin publicación. El Publisher no corre si el Validador falló.
Subagentes SIN team_name. Investigador, Validador y Publisher se lanzan sin team_name.
Condiciones de salida explícitas. Cada rol termina cuando su condición se cumple — ni antes, ni después.
Todos los agentes comunican en español.

→ Ver las 4 demos del pipeline en acción