name: orchestrator description: Use this skill when you need to orchestrate specialized Claude agents in separate sessions. Perfect for long-running tasks, specialized agents with MCP tools, and resumable workflows.

Orchestrator Skill

What & When

What: Commands for managing specialized Claude AI agent sessions with optional agent blueprints and MCP server integration.

When to use:

Delegate tasks to specialized sessions with different MCP configurations
Run long-running operations that can be resumed later
Use agent blueprints for specialized behavior (research, testing, etc.)
Manage multiple concurrent agent conversations
Work with persistent sessions using simple names (no session ID management)

Key Benefits:

Session names instead of session IDs (simpler tracking)
Automatic session management via backend APIs
Built-in result extraction (no manual JSON parsing)
Optional agent blueprints for specialized capabilities
Sessions can be resumed (even after finished)

Prerequisites:

Backend services must be running (Agent Runtime and Agent Registry)

Quick Reference

`ao-start` - Start new session

uv run commands/ao-start <session-name>

Use when: Starting a new Claude agent session. Reads prompt from stdin or -p flag.

`ao-resume` - Continue existing session

uv run commands/ao-resume <session-name>

Use when: Adding messages to an existing session. Reads prompt from stdin or -p flag.

`ao-status` - Check session state

uv run commands/ao-status <session-name>

Use when: Need to know if session is running, finished, or not_existent.

`ao-get-result` - Extract result from finished session

uv run commands/ao-get-result <session-name>

Use when: Session is finished and you need the final result text.

`ao-list-sessions` - List all sessions

uv run commands/ao-list-sessions

Use when: Need to see available sessions with their IDs and project directories.

`ao-list-blueprints` - List available agent blueprints

uv run commands/ao-list-blueprints

Use when: Need to see what specialized agent blueprints are available.

`ao-show-config` - Display session configuration

uv run commands/ao-show-config <session-name>

Use when: Need to see session metadata (project dir, agent used, timestamps, etc.).

`ao-delete-all` - Delete all sessions

uv run commands/ao-delete-all

Use when: Need to delete all session data. Use with caution.

Command Location

IMPORTANT: All commands are located in the commands/ subdirectory of this skill folder. Don't use cd to change directories instead run them with their full path.

Before using commands for the first time:

Locate this skill's root folder (same directory as this SKILL.md)
Commands are in: <skill-root>/commands/ao-*
Execute using: uv run <skill-root>/commands/ao-<command> <args>

Example:

# If skill is at /path/to/skills/orchestrator
uv run /path/to/skills/orchestrator/commands/ao-start my-session -p "Research topic X"

Parameters Reference

Required

<session-name> - Alphanumeric + dash/underscore, max 60 chars (e.g., research-task, code_review_123)

Common Options

-p "prompt" or --prompt "prompt" - Provide prompt via CLI instead of stdin
--agent <agent-name> - Use specialized agent blueprint (only for ao-start)
--project-dir <path> - Override project directory (only for ao-start, default: current directory)

Typical Workflows

Basic Session Workflow

# Start new session
echo "Analyze this codebase structure" | uv run commands/ao-start analysis

# Check status
uv run commands/ao-status analysis  # Output: finished

# Get result
uv run commands/ao-get-result analysis

# Resume with follow-up
echo "Now focus on security patterns" | uv run commands/ao-resume analysis

Using Specialized Agents

# List available blueprints
uv run commands/ao-list-blueprints

# Start session with specific agent blueprint
uv run commands/ao-start research-task --agent web-researcher -p "Research Claude AI capabilities"

# View agent configuration
uv run commands/ao-show-config research-task

Managing Sessions

# List all active sessions
uv run commands/ao-list-sessions

# Check specific session
uv run commands/ao-status my-session

# Delete all sessions
uv run commands/ao-delete-all

Key Concepts

Session States

not_existent - Session doesn't exist
running - Session active, ready to resume
finished - Session complete, result available

Working Directory

Sessions operate in the project directory set at creation (default: current directory)
All file operations within the session are relative to this directory
Use --project-dir with ao-start to override; other commands retrieve it from the session API

Blueprints vs Sessions

Blueprint: Reusable configuration (system prompt + MCP tools) stored in Agent Registry
Session: Running conversation instance managed by Agent Runtime
One blueprint can be used by multiple sessions
Sessions can run without blueprints (general purpose)

Notes for AI Assistants

Always check status before resuming: ao-status <name> → only resume if running or finished
Session names must be unique and valid (no spaces, max 60 chars, alphanumeric + dash/underscore)
Prompt input: Use stdin (pipe) OR -p flag, not both (stdin takes precedence)
Get result only works on finished sessions - check status first
Blueprints - list them with ao-list-blueprints before using --agent
Sessions are persistent - stored in Agent Runtime database
Command location - Always use commands from this skill's commands/ folder
Async execution - Sessions run in Claude Code, commands return immediately after submission

Error Handling

Common errors and solutions:

Error	Cause	Solution
"Cannot connect to Agent Runtime"	Backend not running	Ask the user to the backend.
"Cannot connect to Agent Registry"	Backend not running	Ask the user to the backend.
"Session already exists"	Creating duplicate session	Use `ao-resume` or choose different name
"Session not found"	Wrong name or doesn't exist	Check `ao-list-sessions`
"Session is not finished"	Getting result from running session	Check `ao-status`, wait for `finished`
"Invalid session name"	Bad characters or too long	Use alphanumeric + dash/underscore, max 60 chars
"No prompt provided"	Missing `-p` and stdin	Provide prompt via stdin or `-p` flag
"Agent not found"	Blueprint not in registry	Check `ao-list-blueprints` for available blueprints

Exit Codes

0 - Success
1 - Error (invalid input, session not found, etc.)

Quick Decision Tree

Want to start a new agent conversation? → ao-start <name>

With specialized agent? → Add --agent <agent-name>
In specific directory? → Add --project-dir <path>

Want to continue a conversation? → ao-resume <name>

Not sure if it exists? → Check with ao-status <name> first

Want to see the result? → ao-get-result <name>

Must check status first → ao-status <name> (must be finished)

Want to see what exists?

Sessions → ao-list-sessions
Blueprints → ao-list-blueprints

Want session details? → ao-show-config <name>

Want to delete all? → ao-delete-all (removes all sessions)

Additional Resources

Architecture: See references/AGENT-ORCHESTRATOR.md
Environment Variables: See references/ENV_VARS.md

orchestrator