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.
What: Commands for managing specialized Claude AI agent sessions with optional agent blueprints and MCP server integration.
When to use:
Key Benefits:
Prerequisites:
ao-start - Start new sessionuv 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 sessionuv 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 stateuv 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 sessionuv 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 sessionsuv 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 blueprintsuv run --script commands/ao-list-blueprints
Use when: Need to see what specialized agent blueprints are available.
ao-show-config - Display session configurationuv 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 sessionsuv run --script commands/ao-delete-all
Use when: Need to delete all session data. Use with caution.
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:
<skill-root>/commands/ao-*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"
<session-name> - Alphanumeric + dash/underscore, max 60 chars (e.g., research-task, code_review_123)-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)# 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
# 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
# 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
not_existent - Session doesn't existrunning - Session active, ready to resumefinished - Session complete, result available--project-dir with ao-start to override; other commands retrieve it from the session APIao-status <name> → only resume if running or finished-p flag, not both (stdin takes precedence)finished sessions - check status firstao-list-blueprints before using --agentcommands/ folderCommon 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 |
0 - Success1 - Error (invalid input, session not found, etc.)Want to start a new agent conversation? → ao-start <name>
--agent <agent-name>--project-dir <path>Want to continue a conversation? → ao-resume <name>
ao-status <name> firstWant to see the result? → ao-get-result <name>
ao-status <name> (must be finished)Want to see what exists?
ao-list-sessionsao-list-blueprintsWant session details? → ao-show-config <name>
Want to delete all? → ao-delete-all (removes all sessions)
references/AGENT-ORCHESTRATOR.mdreferences/ENV_VARS.md
