🎯 Por qué componer
Una skill resuelve un problema. Una composición resuelve un workflow completo. La diferencia no es el tamaño, sino la intención. Cuando llamas a 3 skills «porque se te ocurrió», eso es uso aislado. Cuando diseñas A → B → C antes de empezar y cada resultado alimenta el siguiente, eso es composición.
💡 Consejo fundamental
Skill individual resuelve 1 problema (generar un PRD, hacer grilling, escribir una prueba). Composición resuelve un workflow (descubrir → alinear → dividir → implementar → revisar). Si estás repitiendo la misma secuencia de 3+ skills en distintos proyectos, ya tienes un pipeline; solo falta ponerle nombre.
✓ Encadenar de forma consciente
- ✓Diseña el pipeline antes: "grill → PRD → issues → TDD"
- ✓Cada skill recibe la salida de la anterior como input explícito
- ✓Revisar la salida intermedia antes de avanzar
- ✓CONTEXT.md acumula términos y decisiones entre etapas
- ✓Saber cuándo parar y retroceder una etapa si es necesario
✗ Llamar skills por separado
- ✗"Ejecuta el /tdd ahí" sin tener PRD ni issues
- ✗Omitir el grilling: implementa rápido y descubre el problema después
- ✗Cada turno empieza desde cero, sin aprovechar el contexto anterior
- ✗La salida de una skill nunca indica la entrada de la siguiente
- ✗Rehace la misma secuencia cada vez sin nombrar el pipeline
🧩 Patrones de composición
Hay cuatro patrones que cubren el 90% de los pipelines reales. Cada uno tiene una forma y un caso de uso claros. Memorizar los cuatro te da un vocabulario para diseñar workflows.
Secuencial (A → B → C)
Cada etapa depende de la anterior. Patrón por defecto.
A ──▶ B ──▶ C ──▶ D grill PRD issues TDD
Uso: workflow lineal (descubrir, planificar, ejecutar).
Fan-out (A → B + C + D)
Una skill activa varias en paralelo.
┌─▶ B (testes) A ─────┼─▶ C (docs) plan └─▶ D (impl)
Uso: paralelizar trabajo independiente.
Fan-in (B + C → D)
Varias salidas convergen en una skill final.
B (pesquisa) ─┐
├─▶ D (sintese)
C (entrev.) ─┘
Uso: consolidar entradas (revisión, síntesis).
Bucle (A → B → A)
Iteración hasta cumplir el criterio de detención.
A ──▶ B ──┐ ▲ │ └─────────┘ (revisa ate aprovar)
Uso: refinamiento iterativo (PRD con grilling, revisión de código).
🧠 Combinaciones
Los pipelines reales combinan patrones. Por ejemplo: secuencial en el esqueleto (grill → PRD → issues), con loop dentro del grill (Codex hace el grill, Claude revisa, hasta LGTM), y fan-out en la implementación (cada issue se convierte en una branch paralela).
📜 Ejemplo canónico: grill → PRD → issues → tdd
El pipeline más usado en features de complejidad media. Cinco skills encadenadas, cada una con una tarea específica y cada salida alimentando la siguiente. Memoriza esta secuencia.
/grill-with-docs aligns
Pon a prueba la idea frente al lenguaje del proyecto. Resultado: términos canónicos, premisas explícitas, conflictos con decisiones anteriores.
"El término 'cascade' ya existe en CONTEXT.md como 'materialization cascade'. Usa este término en el PRD para mantener un lenguaje ubicuo."
/to-prd synthesizes
Transforma el resultado del grill en un PRD estructurado (problema, solución, alcance, fuera de alcance, éxito).
Lee los términos del CONTEXT.md y úsalos literalmente. El PRD se convierte en un documento duradero, no en un borrador.
/to-issues slices
Divide el PRD en issues accionables (de 1 a 3 días cada una). Resultado: lista de issues con criterios de aceptación.
"Issue #1: crear tabla materialization_cascade. Issue #2: implementar el trigger de invalidación..."
/triage prioritizes
Ordena los issues por dependencia + riesgo + valor. Decide qué entra en el primer sprint.
"Issue #1 (tabla) bloquea #2 y #3. Empieza por #1 y deja #4 (UI) para el final."
/tdd implementa
Toma una issue priorizada e impleméntala con test-first. Resultado: código + pruebas + PR.
"Issue #1: escribe una prueba que falle para el schema, crea la migración, haz que la prueba pase y crea un commit."
Prompts reales que conectan cada etapa
# Turno 1 /grill-with-docs Quero adicionar cache materializado por usuario. # Turno 2 (apos grill atualizar CONTEXT.md) /to-prd Use os termos definidos no CONTEXT.md (materialization cascade, cache invalidation trigger). Gere PRD em docs/prd/cache.md. # Turno 3 /to-issues Le docs/prd/cache.md. Cria issues no GitHub com label "cache". # Turno 4 /triage Le issues com label "cache". Prioriza por dependencia. # Turno 5 /tdd Pega issue #1 (mais alta prioridade). Test-first.
🧠 Estado compartido mediante CONTEXT.md
El secreto de una buena composición no es tener skills perfectas, sino tener memoria entre ellos. CONTEXT.md funciona como caché duradera: la skill A escribe un término, la skill B lo lee y lo usa. Sin eso, cada skill empieza desde cero y vuelves a aprender el lenguaje cada vez.
📝 Cómo CONTEXT.md se convierte en un puente
CONTEXT.md tiene secciones vivas: Glossary (términos canónicos), Decisions (ADR ligeros), Open questions (lo que aún no se decidió). Cada skill que cambia algo duradero escribe aquí. Cada skill que comienza lee primero.
- •Glossary: nombres oficiales (entidades, conceptos, eventos)
- •Decisions: "decidimos X porque Y, alternativas rechazadas: Z"
- •Open questions: ambigüedades que deben resolverse
Turno A: /grill escribe en CONTEXT.md
## Glossary
- materialization cascade: sequencia de invalidacoes
disparadas quando uma fonte upstream muda. Substitui o termo
informal "atualizacao em cadeia".
## Decisions
- ADR-007: cache materializado por usuario, nao global.
Motivo: isolamento de tenant. Alternativa rejeitada:
cache global com chave composta (complexidade > beneficio).
Turno B: /to-prd lee y usa los términos
# PRD: Cache materializado ## Problema Consultas pesadas rodam toda vez. Precisamos de materialization cascade por usuario. ## Solucao Conforme ADR-007 (ver CONTEXT.md), implementar cache materializado por usuario. Nao global. ## Termos materialization cascade: ver Glossary do CONTEXT.md.
⚡ Truco
Antes de llamar a la siguiente skill en el pipeline, haz un turno explícito: "actualiza el CONTEXT.md con lo que descubrimos". Sin esto, la memoria queda en la conversación (efímera) y la siguiente skill lo pierde todo.
🏗️ Cuándo crear una skill macro
Macro skill = una skill que llama a otras skills en secuencia. Útil cuando el pipeline es recurrente. Inútil (y peligroso) cuando intentas "automatizar el pensamiento".
✓ Macro útil
- ✓Workflow recurrente (3+ proyectos usan la misma secuencia)
- ✓Todo el equipo la usa, no solo tú
- ✓Las etapas tienen entradas y salidas bien definidas
- ✓Hay un checkpoint humano entre las fases (revisión)
- ✓Más fácil de explicar que volver a explicar 5 skills
✗ Macro inútil
- ✗Llamadas aisladas que cambian cada vez
- ✗Lógica condicional compleja ("si X, haz Y; de lo contrario, Z")
- ✗Macro hecha para «ahorrar 1 prompt» — genera más bugs que ahorro
- ✗Omite la revisión humana entre etapas críticas
- ✗Solo 1 persona entiende lo que hace
📦 Plantilla de skill macro
--- name: /feature-pipeline description: Pipeline padrao de feature media. Grill -> PRD -> issues -> TDD. --- # Skill: feature-pipeline ## Quando usar Feature nova de complexidade media (2-5 issues). ## Passos 1. /grill-with-docs <descricao da feature> - PARE aqui. Revise o CONTEXT.md atualizado. 2. /to-prd Use termos do CONTEXT.md. - PARE. Aprove o PRD antes de fatiar. 3. /to-issues Le o PRD. Cria issues com label. 4. /triage Prioriza. 5. /tdd Pega a primeira issue. ## Checkpoints humanos Entre passos 1-2 e 2-3 SEMPRE. Nao pula.
🔧 Ejemplo práctico: refactorización completa
Escenario real: código heredado con 3 sistemas de caché duplicados. Vamos a refactorizar usando 5 skills encadenadas. Fíjate en el punto de control humano entre cada una.
/zoom-out — mapea el área
Diagrama de quién llama a quién, dónde viven los 3 cachés, dependencias.
Salida: "Cache A en src/api/, Cache B en src/jobs/, Cache C en src/web/. Se superponen en 7 funciones."
/improve-codebase-architecture — encuentra oportunidades
Lee el mapa del zoom-out. Propón unificación.
Salida: "Unificar en src/cache/. Las cachés A y B usan la misma semántica (TTL). La caché C necesita invalidación manual: mantenla como subtipo."
/grill-with-docs — alinea el enfoque
Pon a prueba la propuesta frente a CONTEXT.md.
Salida: "El término correcto es 'cache backend' (ADR-003), no 'cache provider'. Actualiza Glossary."
/to-issues — genera issues
Divide el refactor en 4 issues secuenciales.
Salida: "#1 crear interfaz CacheBackend; #2 migrar Cache A; #3 migrar Cache B; #4 adaptar Cache C como subtipo."
/tdd — implementa
Toma la issue #1. Primero, las pruebas.
Salida: PR con interfaz + pruebas verdes. Listo para el issue #2.
Salida resumida de cada turno
[1] /zoom-out -> mapa.md (3 caches, 7 sobreposicoes) [2] /improve-arch -> propostas.md (unificar em src/cache/) [3] /grill-with-docs -> CONTEXT.md++ (Glossary: cache backend) [4] /to-issues -> 4 issues no GH (labels: refactor/cache) [5] /tdd -> PR #142 (interface + testes)
⚠️ Antipatrones de composición
Los dos errores más comunes son opuestos: saltarse las skills para «ir más rápido» y no revisar los resultados intermedios. Ambos generan retrabajo exponencial.
✓ Composición saludable
- ✓Cada etapa tiene una salida en un archivo (PRD.md, issues.json, CONTEXT.md)
- ✓Revisa la salida antes de llamar a la siguiente skill
- ✓Cuando algo está mal, vuelve un paso atrás; no intentes corregirlo en el siguiente
- ✓Cada skill asume que la anterior hizo su trabajo correctamente
✗ Composición rota
- ✗Omitir el grill «para ahorrar tiempo» → PRD con términos incorrectos → issues sin sentido → retrabajo 3 veces mayor
- ✗No leer los resultados intermedios → el error se propaga y se acumula en las etapas siguientes
- ✗"Corrige en /tdd" lo que debería estar en el PRD → el alcance crece en silencio
- ✗Llamadas en secuencia sin CONTEXT.md → cada skill vuelve a aprender el vocabulario
🚨 Atención
El costo de saltarse un paso no aparece de inmediato: aparece 2 o 3 skills después, cuando descubres que la salida del /tdd no coincide con lo que pedía el PRD. Ese «ahorro» de 5 minutos se convierte en 2 horas de volver a ejecutar el pipeline.
🌐 Composición entre proyectos
La composición no tiene que quedarse dentro de un proyecto. Cuando dos proyectos comparten un dominio (ej.: marketplace + admin), usar grill+CONTEXT.md de uno para informar el PRD del otro mantiene el lenguaje ubicuo entre repos.
🔗 Flujo entre proyectos
- El Proyecto A (marketplace) usa
/grill-with-docsy consolida términos en el CONTEXT.md. - Copia (o crea un symlink de) la sección Glossary para el proyecto B (admin).
- El Proyecto B usa
/to-prdque hacen referencia al mismo Glossary. - Ambos PRDs dicen "product listing" (no "producto" en uno y "anuncio" en el otro).
- Cuando una entidad cambia en A, actualiza Glossary; B vuelve a importarla.
💡 Consejo avanzado
Para equipos con varios repos, mantener un SHARED_CONTEXT.md en un repo separado (como "docs/") que todos los proyectos importan funciona mejor que copiar y pegar manualmente. Las Skills leen este archivo central y evitan la divergencia de vocabulario.
🏋️ Ejercicio práctico
Elige 1 feature pendiente de tu backlog. Combina 3 skills para entregarla. Documenta cada turno: prompt, salida resumida, decisión tomada.
Guion del ejercicio
- Elige la feature: algo de 1-3 días de trabajo. Ni demasiado grande ni demasiado trivial.
- Diseña el pipeline: escribe en papel "skill A → skill B → skill C". Justifica cada una.
- Ejecuta el turno 1: llama a la primera skill. Registra el prompt exacto.
- Revisa la salida: antes de avanzar, lee lo que salió. ¿Se puede usar?
- Ejecuta los turnos 2 y 3: el mismo proceso. Cada salida alimenta la siguiente.
- Documenta: crea un archivo
pipeline-log.mdcon prompts, resultados, decisiones. - Reflexiona: donde tú casi ¿te saltaste una etapa? ¿Dónde te salvó la salida intermedia?
🎯 Criterio de éxito
Lograste entregar la funcionalidad con 3 skills encadenadas, sin volver a "corregir" en la siguiente etapa lo que faltó en la anterior. Si volviste, anótalo en el log dónde e por qué — este es el aprendizaje real.
📚 Resumen del módulo
Siguiente módulo:
3.2 — Pipelines avanzados y debugging de composición