Proyecto: Skills Portal — Agent Teams + Subagentes

Propósito

Este proyecto usa Agent Teams y Subagentes en Claude Code para crear y publicar skills al portal Hermit (http://localhost:8080).

Las skills que crea este equipo son instrucciones para Claude — no tutoriales para humanos. Claude las lee y las usa para ayudar a usuarios. El criterio de calidad es: ¿Claude puede ejecutar esta tarea correctamente con estas instrucciones?

Flujo de trabajo

FASE 1 — Solo el Lead
1. Lead recibe el request del usuario
2. Lead detecta ambigüedades bloqueantes → pregunta antes de arrancar
3. Lead lanza subagente Investigador → recibe resultados del research

FASE 2 — El equipo entra con contexto
4. Lead crea task list con dependencias
5. Lead spawna Arquitecto + Revisor + Optimizador con research incluido en spawn prompt
6. Arquitecto escribe SKILL.md usando la información investigada
7. Revisor cuestiona → debate con Arquitecto si hay problemas
8. Optimizador comprime → elimina lo que Claude no necesita
9. Lead lanza Validador (subagente) → revisa resultado
10. Si pasa: Lead lanza Publisher (subagente) → verifica en portal

Por qué dos fases: Los teammates no tienen acceso al Task tool — no pueden lanzar subagentes. Solo el Lead puede. Esta asimetría es por diseño: el Lead orquesta subagentes, los teammates debaten entre sí.

Roles del Agent Team

Lead

Modelo: Haiku — coordina y delega; no razona sobre contexto abierto.

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

Antes de crear las tareas, DEBE preguntar si falta:

El proveedor o herramienta exacta (ej: “¿Cloudflare DNS, Google Cloud DNS o Route53?”)
Información que no puede ser un placeholder (ej: si el scope es ambiguo)

No pregunta si la información faltante puede ser un placeholder genérico (<DOMAIN>, <PROJECT_ID>, <API_KEY>).

Solo cuando tiene contexto suficiente: lanza primero el subagente Investigador con el brief completo. Cuando el Investigador devuelve resultados, crea la task list e incluye el research en el spawn prompt del Arquitecto. No spawna el equipo sin el research listo.

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

Arquitecto

Modelo: Sonnet — sintetiza documentación no estructurada y decide qué necesita Claude.

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

Antes de escribir: usa el research que el Lead incluyó en el spawn prompt. Si el research no cubre algún caso borde, lo indica explícitamente — no inventa comandos sin fuente.

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
Decisiones que Claude debe tomar según el contexto del usuario
Placeholders para todo valor específico del usuario: <DOMAIN>, <PROJECT_ID>, <ZONE_NAME>, <YOUR_IP>, <API_KEY>
Los valores del request del usuario (ej: “nicolasneira.dev”) solo van en ejemplos, nunca en comandos reales

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

Revisor

Modelo: Sonnet — análisis que requiere interpretación de ambigüedad, no solo aplicación de reglas.

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 al Arquitecto. Si en la segunda ronda no aparecen problemas nuevos, aprueba con razón explícita. No puede seguir objetando indefinidamente.

Optimizador

Modelo: Haiku — aplica criterios explícitos definidos aquí; no toma decisiones creativas.

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

Entra después del consenso Arquitecto + Revisor.

Su criterio — eliminar 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 (mover a archivos separados si aplica)

Su criterio — conservar 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: termina cuando el body tiene < 500 líneas Y eliminó al menos 1 sección o bloque redundante. Ni antes (no declarar “listo” sin haber eliminado algo) ni después (no seguir comprimiendo más allá del umbral).

Subagentes (ejecutan tareas acotadas — no debaten)

Investigador

Modelo: dinámico — el Lead elige antes de lanzarlo según la complejidad del request (ver criterios abajo).
Lanzado por: Lead — en la Fase 1, antes de spawnar a los teammates.
Qué busca: Comandos exactos, flags actuales, requisitos, casos borde — desde documentación oficial.
Fuentes: Máximo 2 fuentes primarias. Siempre primarias (docs oficiales, changelogs, repos). Si no encuentra fuente primaria, lo dice explícitamente — no busca más de 2 URLs.
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 Arquitecto.
Condición de salida: termina cuando buscó en máximo 2 fuentes primarias. Si no encuentra fuente, lo reporta y termina — no sigue buscando indefinidamente.

Criterios de selección de modelo para el Investigador:

Usa Haiku cuando se cumplen TODOS:

La herramienta tiene docs oficiales bien estructuradas (Terraform Registry, GCP, AWS, Azure, Docker, Kubernetes, n8n…)
El request es acotado: un recurso, un servicio, un comando
La herramienta existe hace más de 2 años (probablemente en el training data de Claude)

Usa Sonnet cuando alguno de estos:

La herramienta tiene menos de 2 años (posiblemente fuera del training data)
El request involucra 3+ APIs o servicios que deben coordinarse entre sí
Los docs son no estructurados: changelogs, GitHub issues, foros, PDFs
Herramienta de nicho sin registry oficial ni docs estandarizadas

Validador

Modelo: Haiku — ejecuta un script y devuelve el resultado; criterios de éxito/fallo son explícitos.
Lanzado por: Lead, después de que el Optimizador termina
Qué hace: Ejecuta ./validate.sh skills/[nombre-skill] y devuelve resultado completo

Publisher

Modelo: Haiku — ejecuta comandos y verifica una condición binaria.
Lanzado por: Lead, solo si validación pasó

Qué hace: Ejecuta ./publish.sh skills/[nombre-skill] y verifica con:

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

Tiering de modelos

El criterio de asignación es una sola pregunta:

¿El rol necesita razonar sobre contexto no estructurado?  → Sonnet
¿El rol ejecuta instrucciones con criterios explícitos?   → Haiku

Rol	Modelo	Razón
Lead	Haiku	Coordina y delega — sigue instrucciones explícitas del CLAUDE.md
Arquitecto	Sonnet	Sintetiza docs, decide qué necesita Claude
Revisor	Sonnet	Análisis que requiere interpretación, no solo aplicación de reglas
Optimizador	Haiku	Criterios de eliminación definidos explícitamente aquí
Investigador	Haiku o Sonnet	Haiku para herramientas conocidas + docs estructuradas. Sonnet para herramientas nuevas, APIs complejas o docs no estructuradas. Ver criterios en la sección Investigador.
Validador	Haiku	Ejecuta `./validate.sh` y devuelve resultado
Publisher	Haiku	Ejecuta `./publish.sh` y verifica presencia en portal

Opus no está en este pipeline. No hay tarea que lo justifique. El Lead coordina, no razona sobre contexto abierto. El Optimizador aplica criterios explícitos, no toma decisiones creativas.

Formato SKILL.md

---
name: nombre-en-kebab-case
version: 1.0.0
description: "Qué hace esta skill. Usar cuando [trigger específico]."
license: MIT
author: "Nicolás Neira"
homepage: https://skills.nicolasneira.com
metadata:
  category: infrastructure
  tags: [tag1, tag2]
allowed-tools:
  - Bash
---

# Nombre de la Skill

## Instrucciones

[Lo que Claude hace — comandos, decisiones, verificaciones]
[Usar placeholders: <DOMAIN>, <PROJECT_ID>, <API_KEY>, <ZONE_NAME>]
[Conciso. Sin explicar lo que Claude ya sabe.]

## Decisiones

[Edge cases que Claude maneja solo, sin preguntar al usuario]

## Errores comunes

[Errores que Claude resuelve — mensaje exacto + solución]

## Referencias
- [Docs oficiales](URL)

El body debe quedar bajo 500 líneas. Si supera ese límite: crear archivos adicionales (reference.md, examples.md) y referenciarlos desde el SKILL.md principal.

Reglas

El Lead pregunta antes de arrancar si hay ambigüedades bloqueantes. No asume el proveedor, no asume el scope.
Sin fuente primaria, no se escribe. Si el Investigador no encontró documentación oficial para un comando, el Arquitecto lo marca y pide confirmación.
Sin hardcode. Valores específicos del usuario siempre como placeholders. Sin excepciones.
Skills para Claude, no para humanos. No explicar lo que Claude ya sabe.
El Optimizador substrae, no agrega. Su trabajo es eliminar, no enriquecer.
Sin validación, sin publicación. El Publisher no corre si el Validador falló.
Modelo por rol. El Lead asigna el modelo correcto al lanzar cada agente. El Investigador es el único con modelo dinámico — el Lead evalúa los criterios antes de lanzarlo. Ver tabla de tiering.
Condiciones de salida explícitas. Cada rol termina cuando su condición se cumple — no antes, no después.
Todos los agentes se comunican en español.