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:

Error	Cause	Solution
"Cannot connect to Agent Coordinator"	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