multi-agent-composition

Use this knowledge when:

• Learning Claude Code - Understanding what each component does
• Making architectural decisions - Choosing Skills vs Sub-Agents vs MCP vs Slash Commands
• Building custom solutions - Creating specialized agents or orchestration systems
• Scaling agentic workflows - Moving from single agents to multi-agent orchestration
• Debugging issues - Understanding why components behave certain ways
• Adding observability - Implementing hooks for monitoring and control

The Core 4 Framework

Every agent is built on these four elements:

1. Context - What information does the agent have?
2. Model - What capabilities does the model provide?
3. Prompt - What instruction are you giving?
4. Tools - What actions can the agent take?

> "Everything comes down to just four pieces. If you understand these, you will win."

Component Overview

| Component | Trigger | Use When | Best For |

|-----------|---------|----------|----------|

| Skills | Agent-invoked | Repeat problems needing management | Domain-specific workflows |

| Sub-Agents | Tool-invoked | Parallelization & context isolation | Scale & batch operations |

| MCP Servers | As needed | External data/services | Integration with external systems |

| Slash Commands | Manual/tool | One-off tasks | Simple repeatable prompts |

| Hooks | Lifecycle events | Observability & control | Monitoring & blocking |

Composition Hierarchy

```text

Skills (Top Layer)

├─→ Can use: Sub-Agents, Slash Commands, MCP Servers, Other Skills

└─→ Purpose: Orchestrate primitives for repeatable workflows

Sub-Agents (Execution Layer)

├─→ Can use: Slash Commands, Skills

└─→ Cannot nest other Sub-Agents

Slash Commands (Primitive Layer)

└─→ The fundamental building block

MCP Servers (Integration Layer)

└─→ Connect external systems

```

Golden Rules

1. Always start with prompts - Master the primitive first
2. "Parallel" = Sub-Agents - Nothing else supports parallel execution
3. External = MCP, Internal = Skills - Clear separation of concerns
4. One-off = Slash Command - Don't over-engineer
5. Repeat + Management = Skill - Only scale when needed
6. Don't convert all slash commands to skills - Huge mistake
7. Context, Model, Prompt, Tools - Never forget the foundation

This skill uses progressive disclosure. Start here, then navigate to specific topics as needed.

Reference Documentation

Architecture fundamentals - What each component is and how they work

• [architecture.md](reference/architecture.md) - Component definitions, capabilities, restrictions
• [core-4-framework.md](reference/core-4-framework.md) - Deep dive into Context, Model, Prompt, Tools

Implementation Patterns

How to use components effectively - Decision-making and implementation

• [decision-framework.md](patterns/decision-framework.md) - When to use Skills vs Sub-Agents vs MCP vs Slash Commands
• [hooks-in-composition.md](patterns/hooks-in-composition.md) - Implementing hooks for observability and control
• [orchestrator-pattern.md](patterns/orchestrator-pattern.md) - Multi-agent orchestration at scale
• [context-management.md](patterns/context-management.md) - Managing context across agents
• [context-in-composition.md](patterns/context-in-composition.md) - Context handling in multi-agent systems

Anti-Patterns

#### Common mistakes to avoid

• [common-mistakes.md](anti-patterns/common-mistakes.md) - Converting all slash commands to

skills, using skills for one-offs, context explosion, and more

Examples

#### Real-world case studies and progression paths

• [progression-example.md](examples/progression-example.md) - Evolution from prompt → sub-agent → skill (work tree manager example)
• [case-studies.md](examples/case-studies.md) - Scout-builder patterns, orchestration workflows, multi-agent systems

Workflows

#### Visual guides and decision trees

• [decision-tree.md](workflows/decision-tree.md) - Decision trees, mindmaps, and visual guides for choosing components

If you're new to Claude Code

1. Start with [reference/architecture.md](reference/architecture.md) to understand components
2. Read [reference/core-4-framework.md](reference/core-4-framework.md) to grasp the foundation
3. Use [patterns/decision-framework.md](patterns/decision-framework.md) to make your first architectural choice
4. Check [anti-patterns/common-mistakes.md](anti-patterns/common-mistakes.md) to avoid pitfalls

If you're making an architectural decision

1. Open [patterns/decision-framework.md](patterns/decision-framework.md)
2. Follow the decision tree to identify the right component
3. Review the specific component in [reference/architecture.md](reference/architecture.md)
4. Check [examples/](examples/) for similar use cases

If you're adding observability

1. Read [patterns/hooks-in-composition.md](patterns/hooks-in-composition.md) to understand available hooks and implementation
2. Use isolated scripts pattern (UV, bun, or shell)

If you're scaling to multi-agent orchestration

1. Ensure you've mastered custom agents first
2. Read [patterns/orchestrator-pattern.md](patterns/orchestrator-pattern.md)
3. Study [examples/case-studies.md](examples/case-studies.md)
4. Review [patterns/context-management.md](patterns/context-management.md)

Prompts Are the Primitive

> "Do not give away the prompt. The prompt is the fundamental unit of knowledge work and of programming. If you don't know how to build and manage prompts, you will lose."

Everything is prompts in the end. Master slash commands before skills. Have a strong bias toward slash commands.

Skills Are Compositional, Not Replacements

> "It is very clear this does not replace any existing feature or capability. It is a higher compositional level."

Skills orchestrate other components; they don't replace them. Don't convert all your

slash commands to skills—that's a huge mistake.

Observability is Everything

> "When it comes to agentic coding, observability is everything. How well you can observe, iterate, and improve your agentic system is going to be a massive differentiating factor."

If you can't measure it, you can't improve it. If you can't measure it, you can't scale it.

Context Window Protection

> "200k context window is plenty. You're just stuffing a single agent with too much work. Don't force your agent to context switch."

Create focused agents with single purposes. Delete them when done. Treat agents as temporary, deletable resources.

The Agentic Engineering Progression

```text

Level 1: Base agents → Use agents out of the box

Level 2: Better agents → Customize prompts and workflows

Level 3: More agents → Run multiple agents

Level 4: Custom agents → Build specialized solutions

Level 5: Orchestration → Manage fleets of agents

```

This knowledge synthesizes:

• Video presentations by Claude Code engineering team
• Official Claude Code documentation (docs.claude.com)
• Hands-on experimentation and validation
• Multi-agent orchestration patterns from the field

Need to understand what a component is? → [reference/architecture.md](reference/architecture.md)

Need to choose the right component? → [patterns/decision-framework.md](patterns/decision-framework.md)

Need to implement hooks? → [patterns/hooks-in-composition.md](patterns/hooks-in-composition.md)

Need to scale to multiple agents? → [patterns/orchestrator-pattern.md](patterns/orchestrator-pattern.md)

Need to see real examples? → [examples/](examples/)

Need visual guides? → [workflows/decision-tree.md](workflows/decision-tree.md)

Want to avoid mistakes? → [anti-patterns/common-mistakes.md](anti-patterns/common-mistakes.md)

---

Remember: Context, Model, Prompt, Tools. Master these four, and you master Claude Code.