agentic-orchestration

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:

1. Clear objective
2. Output format
3. Which tools and sources to use
4. 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   # Routing only
analyzer:     80000   # Pattern extraction
synthesizer: 100000   # Cross-source work
writer:       80000   # Generation tasks

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

1. Filesystem before databases — JSON files beat vector stores in benchmarks (74% vs 68.5%)
2. Compress at 70-80% — always preserve: decisions made, files modified, next steps
3. Write progress summary at session end. Read it at session start.
4. 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)

1. Prompt Chaining — sequential steps with validation gates
2. Routing — classify input, direct to specialist
3. Parallelization — simultaneous subtasks or voting across runs
4. Orchestrator-Workers — central LLM delegates dynamically (most common)
5. 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