Contexto de Sesiones de Trabajo

Contexto de Sesiones de Trabajo

Archivo para retomar el trabajo sin perder contexto entre sesiones. Actualizar al final de cada sesión.

Última actualización: 2026-03-03 (sesión 3) Estado del proyecto: ✅ GUION v2.0 COMPLETO — Faltan skills #3 y #4 para el demo

---

Qué es este proyecto

Video de YouTube: “Claude Code Agent Teams: 4 Agentes que Crean Skills para Otros Agentes”

• Video 3 de 3 de la Trilogía Claude Code Avanzado
• Demo en vivo: Agent Team crea una skill y la publica en portal self-hosted (Hermit)
• Duración estimada: 45-48 min

---

Estado de los archivos

Archivo	Estado	Notas
CLAUDE.md	✅ Completo	Arquitectura de dos fases, model routing dinámico Investigador, exit conditions
GUION-VIDEO-v3.md	✅ v2.0	Fábrica de skills, 4 skills, MEGA PAYOFF auto-selección, sin DNS
DEMO-RUNBOOK.md	✅ Completo	Guía operacional día de grabación
README.md	✅ Completo	Setup instructions, arquitectura documentada
DEMO-RESULTADO-2026-03-03.md	✅ Nuevo	Resultado completo del pipeline en vivo — terraform-gcp-compute
skills/cloudflare-tunnels/SKILL.md	✅ Completo	69 líneas, Claude-facing
skills/terraform-gcp-compute/SKILL.md	✅ Creado por el Team	146 líneas — creado en demo en vivo el 2026-03-03
skills/github-actions-deploy/SKILL.md	🎬 En vivo	Se crea durante la grabación (corte rápido)
skills/mcp-server-setup/SKILL.md	🎬 En vivo	Se crea durante la grabación (corte rápido)
validate.sh	✅ Funcional	Valida SKILL.md en español/inglés, 0 errores 0 warnings
publish.sh	✅ Funcional	Publica a Hermit + instala en ~/.claude/skills/ (Momento 7)
.env.example	✅ Existe	HERMIT_TOKEN, HERMIT_URL

---

Decisiones de diseño tomadas (y por qué)

1. Arquitectura de dos fases — CONFIRMADA POR TEST EN VIVO

Descubrimiento crítico (probado 2026-03-03): Los teammates en un Agent Team NO tienen acceso al Task tool. No pueden lanzar subagentes. Solo el Lead puede.

Arquitectura resultante (Opción C):

FASE 1 — Solo el Lead:
  Lead → pregunta proveedor si es ambiguo
  Lead → lanza Investigador (subagente)
  Investigador → busca docs oficiales → devuelve resultados al Lead

FASE 2 — El equipo entra con contexto:
  Lead → spawna Arquitecto + Revisor + Optimizador con research en spawn prompt
  Arquitecto → escribe SKILL.md
  Revisor → debate con Arquitecto (máx 2 rondas)
  Optimizador → comprime (< 500 líneas, eliminó al menos 1 bloque)
  Lead → lanza Validador (subagente)
  Lead → lanza Publisher (subagente) si validación pasó

Por qué esta opción (vs alternativas):

• Opción A (Arquitecto pide al Lead que lance Investigador): demasiados saltos de mensajería
• Opción B (Arquitecto investiga directo con WebFetch): pierde el subagente de investigación
• Opción C (Lead pre-investiga): separación limpia, mejor pacing en el video, el equipo debate con información

Impacto en el video: Este descubrimiento se convirtió en contenido — sección [9:00] “La asimetría que nadie documenta”.

---

2. Skills son instrucciones PARA Claude, no tutoriales para humanos

• El SKILL.md no explica qué es un registro DNS, qué es un bucket, qué es OAuth
• Solo: comandos exactos, placeholders, edge cases, errores específicos
• La skill de Cloudflare Tunnels se reescribió de 346 líneas verbose → 69 líneas concisas

3. Model routing por rol

Rol	Modelo	Razón
Lead	Haiku	Coordina con criterios explícitos — no razona sobre contexto abierto
Arquitecto	Sonnet	Sintetiza docs no estructuradas
Revisor	Sonnet	Interpretación de ambigüedad, no aplicación mecánica
Optimizador	Haiku	Criterios de eliminación definidos explícitamente
Investigador	Haiku o Sonnet	Dinámico: Haiku para tools conocidas + docs estructuradas. Sonnet para tools nuevas, 3+ APIs, docs no estructuradas
Validador	Haiku	Ejecuta ./validate.sh — binario
Publisher	Haiku	Ejecuta ./publish.sh — binario

Validado por docs oficiales: “Use Sonnet for teammates. It balances capability and cost.” Opus no aparece — no hay tarea en el pipeline que lo justifique. Investigador dinámico: máx 2 fuentes primarias. Si usa Haiku, ~10-15x menos tokens que Sonnet sin restricción.

4. Exit conditions por rol

• Revisor: máximo 2 rondas de objeciones. Si en la segunda no hay problemas nuevos → aprueba.
• Arquitecto: termina cuando SKILL.md existe y Revisor aprobó. No itera más.
• Optimizador: termina cuando body < 500 líneas Y eliminó al menos 1 bloque. Ni antes ni después.

5. Demo: 4 skills de dominios distintos (fábrica, no una sola skill)

El prompt del demo principal es deliberadamente ambiguo: “Necesito una skill para crear infraestructura en Google Cloud.” El Lead pregunta: “¿Terraform, gcloud CLI o Pulumi?” → responder “Terraform”. → Esto muestra el contrato funcionando y produce la skill terraform-gcp-compute.

Después de la skill #1 en demo completo, se muestran 3 más con cortes rápidos:

• Skill #2 — cloudflare-tunnels (ya existe — 69 líneas)
• Skill #3 — github-actions-deploy (pendiente crear)
• Skill #4 — mcp-server-setup (pendiente crear)

El portal empieza vacío → va de 0 → 4 skills en el video.

Mensaje central: la fábrica puede crear cualquier skill — no hay restricción de dominio.

---

Hallazgos técnicos confirmados (docs oficiales)

Fuente: https://code.claude.com/docs/en/

Hallazgo	Confirmado	Notas
TeammateIdle hook — exit 2 mantiene al teammate trabajando	✅	Solo soporta type: "command", sin matchers
TaskCompleted hook — exit 2 bloquea la tarea	✅	Soporta los 4 tipos de hook; sin matchers
TeammateIdle y TaskCompleted usan exit codes only	✅	No hay JSON decision control para estos eventos
Skills name es opcional	✅	Usa el nombre del directorio si se omite
Skills description es “recommended”, no required	✅	Si se omite, usa el primer párrafo del markdown
7x token multiplier	✅	“~7x more tokens when teammates run in plan mode"
"Use Sonnet for teammates”	✅	Recomendación oficial — valida nuestro tiering
Teammates NO tienen Task tool	✅	Probado en vivo — solo Bash, Glob, Grep, Read, Edit, Write, WebFetch, WebSearch, SendMessage
Plan approval es autónomo por Lead	✅	“Lead makes approval decisions autonomously”
No nested teams	✅	Teammates no pueden spawnar otros teammates
Skills descriptions budget	✅	2% del context window, fallback 16,000 chars
CLAUDE.md < 500 líneas	✅	Best practice oficial

---

Estructura del demo en el video (v2.0)

[0:00-2:00]    Hook + Open Loops + Curiosity Gaps (3)
[2:00-5:00]    Recapitulación de la trilogía
[5:00-8:00]    El problema: la fábrica de skills (sin DNS)
[8:00-9:00]    Agent Teams vs Subagentes (tabla comparativa)
[9:00-10:00]   LA ASIMETRÍA DEL SISTEMA ← contenido exclusivo del test
[10:00-15:00]  El CLAUDE.md: 4 roles + task list de dos fases
[15:00-17:00]  El segundo contrato: model routing + exit conditions
[17:00-18:30]  Por qué es desarrollo, no producción
[18:30-20:00]  Setup (flag + tmux + Hermit + repo)
[20:00-35:00]  DEMO SKILL #1 — PIPELINE COMPLETO (terraform-gcp-compute)
[35:00-37:30]  SKILLS #2, #3, #4 — CORTES RÁPIDOS (editados)
[37:30-38:30]  NUEVA SESIÓN — CLAUDE ELIGE LA SKILL CORRECTA (MEGA PAYOFF)
[38:30-41:00]  Análisis post-demo (tabla contribuciones + model routing en acción)
[41:00-43:00]  Árbol de decisión: Teams vs Subagentes vs ADK
[43:00-45:00]  Cierre de la trilogía + CTA

Momentos WOW en el demo:

1. Lead pregunta “¿Terraform, gcloud o Pulumi?” (min 21)
2. Investigador buscando en registry.terraform.io en pantalla (min 23)
3. Los 3 panes de tmux aparecen simultáneamente (min 27) ← más impactante visualmente
4. Before/after del Optimizador: 179 → 146 líneas (min 34)
5. Portal va de 1 → 4 skills con cortes rápidos (min 37)
6. MEGA PAYOFF: Nueva sesión, Claude elige la skill correcta de 4 disponibles (min 38)

---

Pendientes antes de grabar

Críticos — Pendientes

• Verificar MEGA PAYOFF: una vez grabadas las 4 skills, abrir nueva sesión y confirmar que Claude elige la correcta de las 4 disponibles (o tener resultado pre-grabado como backup)

Críticos — Resueltos ✅

• Pipeline completo probado en vivo: validate.sh ✅ → publish.sh ✅ → portal Hermit ✅ → skill local ✅
• Hermit corriendo: confirmado, skill terraform-gcp-compute verificada en portal
• publish.sh instala localmente: copia a ~/.claude/skills/<name>/SKILL.md automáticamente
• Guion v2.0 completo: fábrica de skills, 4 dominios, sin DNS, MEGA PAYOFF auto-selección
• Model routing Investigador dinámico: Haiku/Sonnet según complejidad, máx 2 fuentes primarias

Setup de grabación

• Flag Agent Teams en settings: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1" ✅ (ya configurada)
• tmux instalado: tmux -V
• Portal vacío para el demo (borrar skills existentes antes de grabar)
• .env con HERMIT_TOKEN configurado
• Red estable (Agent Teams lanza múltiples sesiones)

Día de grabación

• Leer el DEMO-RUNBOOK.md completo
• Probar transición de 1 pane → 3 panes en tmux antes de grabar
• Prompt exacto del demo preparado (sin necesitar escribirlo en vivo)

---

Prompt exacto del demo

Necesito una skill para crear infraestructura en Google Cloud.

Activa el Agent Team con estos roles:
- Arquitecto: diseña la skill como instrucciones para Claude —
  no para humanos. Usa el research que te proveo.
  Si falta información para algún paso, dilo.
- Revisor: verifica que Claude ejecutaría bien estas instrucciones.
  Busca ambigüedades, hardcode, y problemas en el description.
- Optimizador: comprime. Elimina todo lo que Claude ya sabe.

No intervengo en el debate técnico.

Cuando lleguen a consenso, usa subagentes para
validar y publicar en Hermit.

Respuesta cuando el Lead pregunta la herramienta: “Terraform”

Prompts para skills #2, #3, #4 (cortes rápidos en edición):

• Necesito una skill para exponer servicios locales a internet con Cloudflare Tunnels.
• Necesito una skill para configurar deploy automático con GitHub Actions.
• Necesito una skill para crear un servidor MCP en Python que le dé herramientas nuevas a Claude.

Prompts para el MEGA PAYOFF (nueva sesión, sin contexto):

1. Quiero exponer un servicio local a internet sin abrir puertos en mi router. → Claude usa cloudflare-tunnels
2. Quiero que Claude tenga acceso a mi base de datos Postgres como herramienta. → Claude usa mcp-server-setup

---

Recursos y referencias

• Docs Agent Teams: https://code.claude.com/docs/en/agent-teams
• Docs Sub-agents: https://code.claude.com/docs/en/sub-agents
• Docs Skills: https://code.claude.com/docs/en/skills
• Docs Hooks: https://code.claude.com/docs/en/hooks
• Docs Costs: https://code.claude.com/docs/en/costs
• Portal Hermit: http://localhost:8080 (local)
• Repo del video: github.com/nneira/skills-portal-demo (pendiente publicar)

---

Historial de decisiones mayores

Fecha	Decisión	Razón
2026-03-03	Skills = instrucciones para Claude, no tutoriales	Cambio filosófico fundamental — el Redactor se eliminó
2026-03-03	Redactor → Optimizador	El rol que suma texto fue reemplazado por uno que resta
2026-03-03	Lead pregunta antes de arrancar	Ambigüedades bloqueantes deben resolverse antes de crear tareas
2026-03-03	Model routing Haiku/Sonnet	Criterio: ¿razona sobre contexto no estructurado? → Sonnet
2026-03-03	Exit conditions por rol	Sin ellas los agentes iteran después de terminar su trabajo
2026-03-03	Arquitectura de dos fases (Opción C)	Teammates no tienen Task tool — confirmado por test en vivo
2026-03-03	SKILL.md reescrito a 69 líneas	De 346 líneas verbose → conciso y Claude-facing
2026-03-03	Demo = terraform-gcp-compute (sesión 2)	Pipeline probado en vivo: 179→146 líneas, 4 issues Revisor, publicada en Hermit
2026-03-03	Investigador model dinámico + máx 2 fuentes	Sesión 2 usó 31,998 tokens — reducción ~10-15x con Haiku para tools conocidas
2026-03-03	Guion v2.0: fábrica de 4 skills (sesión 3)	“Una skill es un resultado. Una fábrica produce cualquier resultado que le pidas.”
2026-03-03	DNS eliminado del demo	El concepto es la fábrica, no una herramienta específica — 4 dominios distintos