multi-agent-composition

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: multi-agent-composition
description: >
  Decision frameworks and patterns for choosing and composing Claude Code components —
  skills, sub-agents, hooks, MCP servers, and slash commands — into effective
  multi-component agentic systems with proper orchestration and context management.
when_to_use: >
  Use when choosing between skill and agent, composing a multi-agent system,
  orchestrating agents, managing agent context, designing component architecture,
  deciding when to use hooks vs MCP, or building orchestrator workflows.
---

# Multi-Agent Composition

**Master Claude Code's components, patterns, and principles** to build effective agentic systems.

## When to Use This Knowledge

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

## Quick Reference

### 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

## Documentation Structure

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](pattern