# Ao Orchestrator

Talk to a project's AO orchestrator: pass the user's request to it, wait for its reply...

- Repository: https://github.com/OrchestratorInc/agent-orchestrator (13995 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add OrchestratorInc/agent-orchestrator --skill ao-orchestrator -g -a claude-code -y`
Codex: `npx skills add OrchestratorInc/agent-orchestrator --skill ao-orchestrator -g -a codex -y`
Cursor: `npx skills add OrchestratorInc/agent-orchestrator --skill ao-orchestrator -g -a cursor -y`
Gemini CLI: `npx skills add OrchestratorInc/agent-orchestrator --skill ao-orchestrator -g -a gemini-cli -y`

## Description

Talk to a project's AO orchestrator: pass the user's request to it, wait for its reply and relay it. The default route for starting or changing work, "catch me up", "why", "what next" and plans. Use for "in <project>: <ask>", "tell the orchestrator ...", "catch me up on <project>", "start work on ...".

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

Follow the ao-rules skill ("Who does what: orchestrator first"). Sending a message is a write: do it only for what the user asked in this turn.

## 1. Pick the host and project
Match the user's words against project ids on every host (`aoapi GET projects`). One match: use it. The same project id on two hosts (two separate projects that share a folder name): ask which host, unless the user named one or memory has a default for that project. No match: list the projects and ask.

## 2. Find the orchestrator
```sh
f(){ <aoapi helper>; aoapi GET "sessions?orchestratorOnly=true&active=true&project=<project>" | python3 -c '
import json,sys
for s in json.load(sys.stdin)["sessions"]: print(s["id"], (s.get("activity") or {}).get("state",""), s.get("provisionState",""))'; }; f
```
- One line: that is the orchestrator. Its state tells you if it is busy (`active`).
- `exited`: resume it first with `aoapi POST "sessions/<id>/resume-agent" '{}'`, then go on.
- Provision state `failed`: AO could not create its workspace, and messages to it fail. Read the reason with `aoapi GET "sessions/<id>"` (field `provisionError`), tell the user in plain words, and ask them to fix it in AO. Stop here.
- No line: ask "There's no orchestrator in <project> on <host>. Start one with your request?" On yes, start it with the request as its first message (step 3's file and tag), then go to step 4. Its reply is its first turn:

The rest: https://github.com/OrchestratorInc/agent-orchestrator/blob/HEAD/integrations/grok-bot/skills/ao-orchestrator/SKILL.md