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.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
commands/ao-delete-allcommands/ao-get-resultcommands/ao-list-blueprintscommands/ao-list-sessionscommands/ao-resumecommands/ao-show-configcommands/ao-startcommands/ao-statuscommands/lib/__init__.pycommands/lib/agent_api.pycommands/lib/config.pycommands/lib/job_client.pycommands/lib/session_client.pycommands/lib/utils.pyreferences/AGENT-ORCHESTRATOR.mdreferences/ENV_VARS.mdWhat: 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 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 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 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 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 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 commands/ao-list-blueprints
Use when: Need to see what specialized agent blueprints are available.
ao-show-config - Display session configurationuv 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 sessionsuv run 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 <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"
<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 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
# 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
# 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
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 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 |
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