dpetrocelli blog

Cofee, tech and community

[
[
[

]
]
]

Claude Agent Orchestration: Subagents, Skills, MCP Servers & More

Claude Agent Orchestration: Subagents, Skills, MCP Servers & More

AI Agent Orchestration - Photo by Google DeepMind on Unsplash

📊 Level 300 — Advanced
⏱️ Reading time: ~15 minutes

This article assumes familiarity with LLMs, CLI tools, and basic agent concepts.

TL;DR

  • Subagents: Spawn specialized agents for complex tasks (exploration, code review, planning)
  • Skills: Auto-triggered knowledge modules that load contextual information
  • MCP Servers: External tools and data sources that extend Claude’s capabilities
  • Hooks: Deterministic automation that runs on specific events (file changes, tool calls)
  • Task Tool: Programmatic interface for launching agents with specific configurations

Introduction

If you’ve been using Claude Code, you’ve likely noticed that complex tasks often require different approaches: sometimes you need deep exploration, other times you need specialized knowledge, and occasionally you need to integrate external tools.

Claude Code provides five distinct orchestration mechanisms, each designed for specific use cases:

Component Purpose
Subagents Complex autonomous tasks
Skills Auto-load contextual knowledge
MCP Servers External tools & APIs
Hooks Event-driven automation
Task Tool Programmatic control (launches all above)

This guide will help you understand when to use each mechanism and how they work together.

Prerequisites

  • Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)
  • Basic understanding of LLMs and prompt engineering
  • Familiarity with CLI tools and shell scripting
  • (Optional) Node.js for custom MCP servers

What You’ll Learn

  • The five orchestration mechanisms in Claude Code
  • When to use each mechanism for optimal results
  • How to configure and customize each option
  • Best practices for combining multiple mechanisms
  • Real-world use cases and examples

Section 1: Subagents – Spawning Specialized Agents

Subagents - Multiple AI agents working together - Photo by Possessed Photography on Unsplash

Subagents are Claude Code’s mechanism for delegating complex tasks to specialized agents that run autonomously. Think of them as expert colleagues you can summon for specific jobs.

Built-in Subagent Types

Type Description Best For
general-purpose Full-featured agent with all tools Complex multi-step research
Explore Optimized for codebase exploration Finding files, understanding architecture
Plan Architecture and planning agent Designing implementation strategies
claude-code-guide Documentation specialist Claude Code/SDK questions

How to Use Subagents

Subagents are launched via the Task tool:

// Example: Launching an exploration agent
{
"subagent_type": "Explore",
"prompt": "Find all API endpoints in this codebase and explain the authentication flow",
"description": "Explore API endpoints"
}
view raw code-1.js hosted with ❤ by GitHub

Thoroughness Levels (Explore Agent)

The Explore agent supports three thoroughness levels:

Level Description
"quick" Basic search, 1-2 patterns
"medium" Moderate exploration, multiple patterns
"thorough" Comprehensive analysis, all conventions

When to Use Subagents

✅ Use subagents when:
– Task requires multiple search rounds
– You need autonomous research
– Task benefits from parallel execution
– Complex multi-file analysis needed

❌ Don’t use subagents when:
– You know the exact file to read
– Simple single-file search
– Quick grep/glob would suffice

Section 2: Skills – Auto-Triggered Knowledge

Skills and Knowledge - Photo by Patrick Tomasso on Unsplash

Skills are knowledge modules that Claude automatically loads when relevant. They’re defined in markdown files and triggered by specific user requests.

Skill Structure

~/.claude/skills/
├── my-project/
│ ├── deployment.md # Deployment procedures
│ ├── architecture.md # System architecture docs
│ └── coding-standards.md
└── global/
└── company-standards.md
view raw code-2.text hosted with ❤ by GitHub

Skill Definition Example

Deployment Skill

Triggers

  • «deploy»
  • «release»
  • «push to production»

Content

When deploying to production:

  1. Run all tests: npm test
  2. Build the project: npm run build
  3. Deploy via: ./scripts/deploy.sh

Important Notes

  • Always check the #deployments channel before deploying
  • Deployments are blocked during freeze periods
view raw code-3.md hosted with ❤ by GitHub

Skills vs. CLAUDE.md

Feature Skills CLAUDE.md
Auto-triggered ✅ Yes ❌ No
Always loaded ❌ No ✅ Yes
Scoped ✅ Per-trigger ❌ Project-wide
Best for Specific workflows General context

When to Use Skills

✅ Use skills for:
– Project-specific procedures
– Repeated workflows (deploy, review, test)
– Domain knowledge that’s contextually relevant
– Reducing repetitive instructions

Section 3: MCP Servers – External Tool Integration

MCP Servers - Connecting external tools - Photo by Taylor Vick on Unsplash

MCP (Model Context Protocol) servers extend Claude’s capabilities by providing access to external tools, APIs, and data sources.

How MCP Works

Data Flow: Claude Code → MCP Client (built-in) → MCP Server (external) → External Resource (DB, API, etc.)

Step Component Role
1 Claude Code Initiates tool request
2 MCP Client Built-in protocol handler
3 MCP Server External process (you configure)
4 Resource Database, API, filesystem, etc.

MCP Server Configuration

Configure MCP servers in ~/.claude/mcp.json:

{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "postgresql://localhost/mydb"
}
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
view raw code-4.json hosted with ❤ by GitHub

Popular MCP Servers

Server Purpose Use Case
server-postgres PostgreSQL access Query databases
server-github GitHub API Manage repos, PRs
server-filesystem Extended file access Read external files
server-slack Slack integration Send notifications

Building Custom MCP Servers

You can build custom MCP servers in any language:

// Simple MCP server in TypeScript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
const server = new Server({
name: "my-custom-server",
version: "1.0.0"
}, {
capabilities: { tools: {} }
});
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [{
name: "my_tool",
description: "Does something useful",
inputSchema: { type: "object", properties: {} }
}]
}));
const transport = new StdioServerTransport();
await server.connect(transport);
view raw code-5.ts hosted with ❤ by GitHub

Section 4: Hooks – Deterministic Automation

Hooks - Automated workflows - Photo by JJ Ying on Unsplash

Hooks are shell commands that execute in response to specific events. Unlike the AI-driven mechanisms above, hooks are deterministic – they always run the same way.

Hook Configuration

Configure hooks in .claude/settings.json:

{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"command": ["npm", "run", "lint", "–", "$FILE_PATH"]
}
],
"PreToolUse": [
{
"matcher": "Bash",
"command": ["./scripts/validate-command.sh"]
}
],
"UserPromptSubmit": [
{
"command": ["./scripts/log-prompt.sh"]
}
]
}
}
view raw code-6.json hosted with ❤ by GitHub

Available Hook Events

Event When Use Case
PreToolUse Before tool executes Validation, safety checks
PostToolUse After tool executes Linting, formatting
UserPromptSubmit User sends message Logging, augmentation
Notification Claude sends notification External alerting

Hook Environment Variables

Hooks receive context through environment variables:

# Common variables
$TOOL_NAME # Name of the tool being used
$FILE_PATH # Path of file being modified
$TOOL_INPUT # JSON input to the tool
$SESSION_ID # Current session ID
view raw code-7.sh hosted with ❤ by GitHub

Hook Blocking

Hooks can block tool execution by returning non-zero:

#!/bin/bash
# validate-command.sh
# Block any rm -rf commands
if echo "$TOOL_INPUT" | grep -q "rm -rf"; then
echo "BLOCKED: Dangerous command detected"
exit 1
fi
exit 0
view raw code-8.sh hosted with ❤ by GitHub

Section 5: Task Tool – Programmatic Agent Control

Task Tool - Programmatic control - Photo by Markus Spiske on Unsplash

The Task tool is the programmatic interface for launching subagents. It provides fine-grained control over agent behavior.

Task Tool Parameters

{
"description": "Short task description", // Required
"prompt": "Detailed instructions", // Required
"subagent_type": "Explore", // Required
"model": "haiku", // Optional: haiku|sonnet|opus
"run_in_background": true, // Optional: async execution
"resume": "agent_id_here" // Optional: continue previous
}
view raw code-9.js hosted with ❤ by GitHub

Background Execution Pattern

// Launch agent in background
const taskId = await Task({
description: "Long analysis",
prompt: "Analyze entire codebase",
subagent_type: "Explore",
run_in_background: true
});
// Continue with other work…
// Later, get results
const result = await TaskOutput({
task_id: taskId,
block: true,
timeout: 60000
});
view raw code-10.js hosted with ❤ by GitHub

Parallel Agent Execution

Launch multiple agents simultaneously for maximum efficiency:

// Single message with multiple Task calls runs in parallel
[
Task({ subagent_type: "Explore", prompt: "Find auth code" }),
Task({ subagent_type: "Explore", prompt: "Find API routes" }),
Task({ subagent_type: "Plan", prompt: "Design new feature" })
]
view raw code-11.js hosted with ❤ by GitHub

Comparison Matrix

Feature Subagents Skills MCP Hooks
Trigger Task tool Auto/keywords Tool call Event
Execution AI-driven Context load External Deterministic
Use case Complex tasks Knowledge Integration Automation
Parallel ✅ Yes N/A ✅ Yes ❌ No
Blocking Optional N/A N/A ✅ Yes
Custom Via prompts .md files Any language Shell

Best Practices

Practice Why It Matters
Use Explore agent for codebase questions Reduces context usage, parallel search
Combine Skills with CLAUDE.md Skills for workflows, CLAUDE.md for always-on context
Prefer MCP over bash for external data Better security, structured responses
Use hooks for deterministic requirements Linting, formatting, validation
Launch parallel agents when possible Faster execution, better efficiency

Common Pitfalls

❌ Over-using subagents for simple searches
– Use Glob/Grep directly for simple pattern matching

❌ Loading all context in Skills
– Skills should be focused and trigger-specific

❌ Ignoring hook return codes
– Hooks can block operations – handle errors gracefully

❌ Running sequential agents that could be parallel
– Always parallelize independent agent tasks

Decision Guide

Ask yourself these questions in order:

Question If YES If NO
Is the task complex and multi-step? Use Subagents Continue below
Need codebase exploration? Use Explore agent —
Need implementation plan? Use Plan agent —
Is external data/tools needed? Use MCP Servers Continue below
Is deterministic automation needed? Use Hooks Continue below
Is contextual knowledge needed? Use Skills Use basic Claude tools

Conclusion

Bringing it all together - Photo by Growtika on Unsplash

Claude Code’s orchestration mechanisms are designed to work together:

  1. Start with Skills for project-specific knowledge
  2. Add MCP servers for external integrations
  3. Configure Hooks for automated workflows
  4. Use Subagents for complex, multi-step tasks
  5. Leverage Task tool for fine-grained control

The key is choosing the right mechanism for each scenario:
– Subagents = Complex autonomous tasks
– Skills = Contextual knowledge loading
– MCP = External tool integration
– Hooks = Deterministic automation

Resources

📚 Official Documentation:
– Claude Code Documentation
– Claude Agent SDK

🔧 MCP Resources:
– MCP Protocol Specification
– MCP Server Examples

📖 Further Reading:
– Building Custom MCP Servers
– Anthropic Cookbook – Agent Patterns

👋 About the Author

I’m a Cloud Architect and AI enthusiast focused on helping developers build practical AI solutions. Follow me for more content on:

  • 🤖 AI Engineering — LLMs, agents, and automation
  • ☁️ Cloud Architecture — AWS, serverless, and infrastructure
  • 💻 Developer Tools — Productivity and workflow optimization

Did you find this article helpful?

👉 Like and share to help others discover it!
💬 Comment below with your questions or experiences with Claude agents.
🔔 Follow for more AI Engineering content!

Deja un comentario