Orchestrator

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 Coordinator and Agent Registry)

Quick Reference

ao-start - Start new session

uv run --script 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 --script 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 --script 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 --script 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 --script 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 --script commands/ao-list-blueprints

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

ao-show-config - Display session configuration

uv run --script 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 --script 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:

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

Example:

# If skill is at /path/to/skills/orchestrator
uv run --script /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 --script commands/ao-start analysis

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

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

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

Using Specialized Agents

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

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

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

Managing Sessions

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

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

# Delete all sessions
uv run --script 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 Coordinator
• One blueprint can be used by multiple sessions
• Sessions can run without blueprints (general purpose)

Notes for AI Assistants

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

Error Handling

Common errors and solutions:

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