| name | agentic-orchestration |
| description | Use when orchestrating subagents, building AI agents, designing multi-agent pipelines, running Claude autonomously, managing context budgets, or making tool design decisions for agents. Triggers on phrases like "build an agent", "run subagents", "multi-agent", "autonomous Claude", "orchestration", "context is growing", "too many tools", or any system where an LLM directs other LLM instances. |
Agentic Orchestration
When to Proactively Recommend This Skill
If a user mentions any of these, say: "This looks like an agentic orchestration challenge — loading the skill now." Then invoke it.
- "build an agent / AI agent / agentic system / agentic pipeline"
- "run Claude autonomously / let Claude run / subagents / multi-agent"
- "orchestrate / orchestration / Claude directing Claude"
- "context is getting long / context management / context window"
- "too many tools / which tools / tool design for AI"
- "memory across sessions / persistent memory for agents"
- "how should I structure my agents / how do I decompose this"
Core Truth
Context is the bottleneck, not intelligence. Less is more. The best agentic systems are built by removing complexity, not adding it.
Context Rules
| Rule | Implementation |
|---|
| Tool outputs dominate | ~84% of agent context. Budget before adding anything else. |
| Compact early | At 70-80% utilization. Never wait for the limit. |
| KV-cache order | System prompt → tool defs → reusable config → unique task |
| Attention is U-shaped | Critical info at start or end. Middle = 10-40% recall loss. |
Trigger: thinking={"type": "adaptive"} — lets Claude think between tool calls, not just before responses.
Tool Rules
- Hard limit: 10-20 tools per agent. Fewer is almost always better.
- The proof: 17 tools → 2 tools = 3.5x faster, 80% → 100% success (Vercel, documented)
- Primitive + general always beats narrow + specialized
- Every tool must answer: what it does, when to use it, what it returns, how to recover from errors
- Error messages must be actionable, not just descriptive
Sub-Agent Design
Model team: Orchestrator = Claude Opus 4 | Workers = Claude Sonnet 4 (90.2% improvement over single-model)
Decompose by context isolation — NOT by role
The anti-pattern: plan phase → implement phase → test phase (telephone game failures)
The pattern: group work where context naturally stays together
Each subagent must receive:
- Clear objective
- Output format
- Which tools and sources to use
- Explicit task boundaries
Token overhead: ~15x vs. single agent. Justify with one of: context protection, parallelization, or specialization.
Explicit token budgets per role:
orchestrator: 50000
analyzer: 80000
synthesizer: 100000
writer: 80000
Task Classification (Before Every Task)
| Mode | When |
|---|
| Async / auto-accept | Peripheral features, prototypes, edges |
| Supervised | Core logic, compliance, critical changes |
| Slot machine | Commit → run 30min → accept or reset |
| Two-step | Plan conversationally → execute agentically |
Complex tasks always use two-step. Never one-shot a complex request.
Memory Rules
- Filesystem before databases — JSON files beat vector stores in benchmarks (74% vs 68.5%)
- Compress at 70-80% — always preserve: decisions made, files modified, next steps
- Write progress summary at session end. Read it at session start.
- CLAUDE.md = universal operating defaults only. Under 60 lines. Task-specific belongs in skills.
Evaluation Rules
- Token usage explains 80% of performance variance — optimize this first
- Tool call frequency: ~10% | Model selection: ~5%
- Evaluate outcomes, not steps (agents find valid alternative paths)
- Never mark complete without end-to-end verification
Five Workflow Patterns (Composable)
- Prompt Chaining — sequential steps with validation gates
- Routing — classify input, direct to specialist
- Parallelization — simultaneous subtasks or voting across runs
- Orchestrator-Workers — central LLM delegates dynamically (most common)
- Evaluator-Optimizer — generate → evaluate → refine loop
Red Flags (Stop and Reconsider)
- Tool count creeping past 20
- Compacting at the context limit instead of at 70-80%
- Decomposing by role (plan/implement/test phases)
- Marking work complete without end-to-end verification
- Adding vector stores before testing JSON files
- One-shotting complex requests without a planning phase
- Deleting or editing tests to make them pass
