🎯 Why compose
One skill solves a problem. A composition solves a entire workflow. The difference isn’t size—it’s intent. When you call 3 skills “because it seemed like a good idea,” that’s standalone use. When you map out A → B → C before you start, and each output feeds the next, that's composition.
💡 Essential Tip
Standalone skill solves 1 problem (generate a PRD, do grilling, write a test). Composition handles a workflow (discover → align → break down → implement → review). If you're repeating the same sequence of 3+ skills across different projects, you already have a pipeline—you just need to give it a name.
✓ Chain intentionally
- ✓Design the pipeline first: "grill → PRD → issues → TDD"
- ✓Each skill receives the previous skill’s output as explicit input
- ✓Review the intermediate output before moving on
- ✓CONTEXT.md accumulates terms and decisions across stages
- ✓Know when to stop and go back one step if needed
✗ Call skills in isolation
- ✗"Run /tdd there" without a PRD or issues
- ✗Skipping grilling: implement quickly, discover the gap later
- ✗Each turn starts from scratch, without using previous context
- ✗The output of one skill never tells you the input for the next
- ✗Repeats the same sequence every time without naming the pipeline
🧩 Composition patterns
There are four patterns that cover 90% of real pipelines. Each has a clear form and use case. Memorizing all four gives you vocabulary for designing a workflow.
Sequential (A → B → C)
Each stage depends on the previous one. Default pattern.
A ──▶ B ──▶ C ──▶ D grill PRD issues TDD
Use: linear workflow (discover, plan, execute).
Fan-out (A → B + C + D)
One skill triggers several in parallel.
┌─▶ B (testes) A ─────┼─▶ C (docs) plan └─▶ D (impl)
Use: parallelize independent work.
Fan-in (B + C → D)
Several outputs converge into a final skill.
B (pesquisa) ─┐
├─▶ D (sintese)
C (entrev.) ─┘
Use: consolidate inputs (review, synthesis).
Loop (A → B → A)
Iterate until the stopping criterion is met.
A ──▶ B ──┐ ▲ │ └─────────┘ (revisa ate aprovar)
Use: iterative refinement (PRD with grilling, code review).
🧠 Combinations
Real pipelines combine patterns. For example: sequential in the skeleton (grill → PRD → issues), with loop inside the grill (Codex grills, Claude reviews, until LGTM), and fan-out in the implementation (each issue becomes a parallel branch).
📜 Canonical example: grill → PRD → issues → tdd
The most commonly used pipeline for medium-complexity features. Five skills chained together, each with a specific job, each output feeding the next. Memorize this sequence.
/grill-with-docs aligns
Stress-tests the idea against the project's language. Output: canonical terms, explicit assumptions, conflicts with previous decisions.
"The term 'cascade' already exists in CONTEXT.md as 'materialization cascade'. Use this term in the PRD to keep the language ubiquitous.”
/to-prd synthesizes
Turns the grill results into a structured PRD (problem, solution, scope, out of scope, success).
Read the terms in CONTEXT.md and use them verbatim. The PRD becomes a durable document, not a draft.
/to-issues slices
Break the PRD into actionable issues (1–3 days each). Output: a list of issues with acceptance criteria.
"Issue #1: create table materialization_cascade. Issue #2: implement invalidation trigger..."
/triage prioritizes
Sort the issues by dependency + risk + value. Decide what goes into the first sprint.
"Issue #1 (table) blocks #2 and #3. Start with #1, leave #4 (UI) for last."
/tdd implements
Pick a prioritized issue and implement it test-first. Output: code + tests + PR.
"Issue #1: write a failing test for the schema, create a migration, make the test pass, commit."
Real prompts connecting each step
# 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.
🧠 Shared state via CONTEXT.md
The secret to good composition isn’t having perfect skills—it’s having memory between them. CONTEXT.md works as a durable cache: skill A writes a term, skill B reads and uses it. Without this, every skill starts from scratch, and you have to relearn the terminology every time.
📝 How CONTEXT.md becomes a bridge
CONTEXT.md has living sections: Glossary (canonical terms), Decisions (lightweight ADRs), Open questions (what hasn’t been decided yet). Every skill that changes something durable writes here. Every skill that starts reads this first.
- •Glossary: official names (entities, concepts, events)
- •Decisions: "we decided X because Y, rejected alternatives: Z"
- •Open questions: ambiguities that need to be resolved
Turn A: /grill writes to 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).
Turn B: /to-prd reads it and uses the terms
# 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.
⚡ Trick
Before calling the next skill in the pipeline, make an explicit turn: "update the CONTEXT.md with what we discovered". Without this, the memory stays in the conversation (ephemeral), and the next skill loses everything.
🏗️ When to create a macro skill
Macro skill = a skill that calls other skills in sequence. Useful when the pipeline is recurring. Useless (and dangerous) when you're trying to "automate thinking."
✓ Useful macro
- ✓Recurring workflow (3+ projects use the same sequence)
- ✓The whole team uses it, not just you
- ✓Stages have well-defined inputs and outputs
- ✓There’s a human checkpoint between phases (review)
- ✓Easier to explain than to re-explain 5 skills
✗ Useless macro
- ✗Isolated calls that change every time
- ✗Complex conditional logic ("if X, do Y; otherwise, do Z")
- ✗A macro made to “save 1 prompt” creates more bugs than savings
- ✗Skips human review between critical steps
- ✗Only 1 person understands what it does
📦 Macro skill template
--- 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.
🔧 Practical example: complete refactor
Real-world scenario: legacy code with 3 duplicated cache systems. We’ll refactor using 5 chained skills. Note the human checkpoint between each one.
/zoom-out — maps the area
Diagram of who calls whom, where the 3 caches live, dependencies.
Output: "Cache A in src/api/, Cache B at src/jobs/, Cache C at src/web/. They overlap in 7 functions.”
/improve-codebase-architecture — finds opportunities
Read the zoom-out map. Propose a unification.
Output: "Unify into src/cache/. Caches A and B use the same semantics (TTL). Cache C needs manual invalidation — keep it as a subtype."
/grill-with-docs — aligns the approach
Stress-tests the proposal against CONTEXT.md.
Output: "The correct term is 'cache backend' (ADR-003), not 'cache provider'. Update Glossary."
/to-issues — generates issues
Break the refactor into 4 sequential issues.
Output: "#1 create CacheBackend interface; #2 migrate Cache A; #3 migrate Cache B; #4 adapt Cache C as a subtype."
/tdd — implements
Pick issue #1. Test-first.
Output: PR with interface + passing tests. Ready for issue #2.
Summarized output from each turn
[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)
⚠️ Composition anti-patterns
The two most common mistakes are opposites: skipping skills to “go faster” and not reviewing intermediate outputs. Both lead to exponentially more rework.
✓ Healthy composition
- ✓Every step produces an output file (PRD.md, issues.json, CONTEXT.md)
- ✓Review the output before calling the next skill
- ✓When something is wrong, go back one step; don't try to fix it in the next one
- ✓Each skill assumes the previous one did its job correctly
✗ Broken composition
- ✗Skip the grill “to save time” → PRD with wrong terms → meaningless issues → 3x more rework
- ✗Not reading intermediate output → errors propagate and accumulate in later steps
- ✗"Fix it in /tdd" when it should be in the PRD → scope quietly grows
- ✗Calls in sequence without CONTEXT.md → each skill relearns the vocabulary
🚨 Attention
The cost of skipping a step doesn’t show up right away—it appears 2 or 3 skills later, when you discover that the output from the /tdd doesn't match what the PRD called for. That "5-minute saving" turns into 2 hours of rerunning the pipeline.
🌐 Cross-project composition
Composition doesn't have to stay within a project. When two projects share a domain (e.g., marketplace + admin), use grill+CONTEXT.md from one to inform the other’s PRD maintains a ubiquitous language across repos.
🔗 Cross-project workflow
- Project A (marketplace) uses
/grill-with-docsand consolidates terms in CONTEXT.md. - Copy (or symlink) the section Glossary for project B (admin).
- Project B uses
/to-prdreferencing the same Glossary. - Both PRDs say "product listing" (not "product" in one and "ad" in the other).
- When an entity changes in A, update Glossary; B imports it again.
💡 Advanced Tip
For multi-repo teams, maintain a SHARED_CONTEXT.md in a separate repo (like "docs/") that all projects import works better than manual copy-pasting. Skills read from this central file, preventing vocabulary drift.
🏋️ Hands-on exercise
Choose 1 pending feature from your backlog. Combine 3 skills to deliver it. Document each turn: prompt, summarized output, decision made.
Exercise outline
- Choose the feature: something that takes 1–3 days of work. Not too big, not too trivial.
- Design the pipeline: write "skill A → skill B → skill C" on paper. Justify each one.
- Run turn 1: call the first skill. Record the exact prompt.
- Review the output: before moving forward, read what came out. Is it usable?
- Run turns 2 and 3: same process. Each output feeds into the next.
- Document: create a file
pipeline-log.mdwith prompts, outputs, decisions. - Reflect: where you almost Did you skip a step? Where did the intermediate output save you?
🎯 Success criteria
You managed to deliver the feature with 3 chained skills without going back to "fix" in the next step what was missing from the previous one. If you went back, note it in the log where e why — this is the real learning.
📚 Module Summary
Next Module:
3.2 — Advanced pipelines and composition debugging