ao-rules

GitHub

定义 ao-* 技能共享规则,包括 AO 主机管理、本地/远程访问规范及 aoapi 调用助手。确保多主机并行执行时的会话隔离与正确路由,是运行其他 ao-* 技能的前置必读指南。

integrations/grok-bot/skills/ao-rules/SKILL.md OrchestratorInc/agent-orchestrator

Trigger Scenarios

用户提及 ao-* 系列技能 需要配置或连接 Orchestrator 主机 询问 aoapi 使用方法 处理多主机会话冲突

Install

npx skills add OrchestratorInc/agent-orchestrator --skill ao-rules -g -y
More Options

Non-standard path

npx skills add https://github.com/OrchestratorInc/agent-orchestrator/tree/main/integrations/grok-bot/skills/ao-rules -g -y

Use without installing

npx skills use OrchestratorInc/agent-orchestrator@ao-rules

指定 Agent (Claude Code)

npx skills add OrchestratorInc/agent-orchestrator --skill ao-rules -a claude-code -g -y

安装 repo 全部 skill

npx skills add OrchestratorInc/agent-orchestrator --all -g -y

预览 repo 内 skill

npx skills add OrchestratorInc/agent-orchestrator --list

SKILL.md

Frontmatter
{
    "name": "ao-rules",
    "description": "Shared rules and the connection helper for every ao-* skill (run Orchestrator from chat). Read before running any ao-* skill."
}

AO rules

Every ao-* skill follows these rules. Other skills link here instead of repeating them.

AO hosts

An AO host is one computer that runs the Orchestrator daemon. Each host has its own projects, sessions and orchestrators, and Orchestrator never links them: a repo cloned on two hosts is two separate projects. Orchestrator names a project after its folder, so both can still get the same id, and then the same session id (for example agent-orchestrator-1-12) can exist on both. Always name a session as <host>/<session id>, and act only on the host that owns it.

Memory keeps one note named AO hosts, with one line per host:

Field Example Meaning
name Pro A short name: the user's pick, else the model word of the ListMachines label (Pro, Air, mini). Never the network hostname such as MacBookAir.lan
reach local or remote How you get to its Orchestrator
via laptop The ListMachines label of the computer whose shell you use
base http://192.168.1.20:7444 Remote only. The host's LAN address from Orchestrator's remote access settings
header ~/.ao-grok/studio.header Remote only. File on via that holds the host's password
  • local: the Grok Bot desktop app runs on the AO host. via is the host itself.
  • remote: the Grok Bot desktop app runs on another computer. You call the host's Orchestrator API over the network from via. The ao CLI on via talks only to via's own Orchestrator, so never use it for a remote host.

One computer can be via for itself (local) and for other hosts (remote) at the same time.

Every run: call ListMachines, then use every host whose via computer is connected, in parallel, labelled by host name. Say once which hosts you could not reach. Never hard-code machine ids or home paths.

Calling AO

Start every shell command that calls Orchestrator with this helper. It works in zsh and bash:

aoapi(){ # aoapi METHOD PATH [JSON]
  local base hdr=() data=() f="${AO_RUN_FILE:-$HOME/.ao/running.json}"
  if [ -n "$AO_REMOTE_BASE" ]; then base="$AO_REMOTE_BASE"; hdr=(-H @"$AO_REMOTE_HEADER")
  else [ -f "$f" ] || { echo "AO_NOT_RUNNING" >&2; return 3; }
    base="http://127.0.0.1:$(grep -o '"port": *[0-9]*' "$f" | grep -o '[0-9]*$')"; fi
  [ -n "$3" ] && data=(--data "$3")
  curl -sS --fail-with-body --max-time 30 -X "$1" "${hdr[@]}" -H 'Content-Type: application/json' "${data[@]}" "$base/api/v1/$2"
}
  • Local host: use aoapi as is.
  • Remote host: on the via computer, first set AO_REMOTE_BASE='<base>' AO_REMOTE_HEADER="$HOME/.ao-grok/<name>.header".
  • Build JSON bodies with python3 -c 'import json,sys; print(json.dumps(...))' "$ARG", never by pasting text into quotes.
  • Anything longer than one line goes in a file first: ~/.ao-grok/out/<date>-<short name>.md on via. The user can see what was sent.
  • Use the ao CLI only where a skill says "local only".

Errors

You see Meaning and next step
AO_NOT_RUNNING, or connection refused on a local host Orchestrator is not running there. Ask the user to open Orchestrator
Connection refused or timeout on a remote host The host is asleep, off this network, or remote access is off. Ask the user to check Orchestrator's remote access settings on the host
HTTP 401 or 403 on a remote host The host's password changed. Run ao-setup "Remote host" again
HTTP 404 on a session path No such session on that host. Check the host name
Any other error Orchestrator returns JSON with message. Relay it in plain words

Who does what: orchestrator first

Each project on a host has at most one live orchestrator: an agent that plans the project's work, starts and steers workers, and gets their reports. It has more context than you do. You are the user's phone line to it.

  • Send to the orchestrator (ao-orchestrator): starting or changing work, "catch me up", "why", "what next", plans, and anything that needs judgement about the code.
  • Do directly: status lists (ao-status), answering a pending request with the user's own pick (ao-answer), stop and interrupt, merges after the user's yes, files and screenshots (ao-actions).
  • Never start a worker yourself in a project that has a live orchestrator. Ask the orchestrator instead. With no orchestrator, ask the user whether to start one or to start the worker directly.
  • After you act directly on a worker (answer, stop, merge), the orchestrator sees it through Orchestrator. Don't send it a separate note.

Decisions

A worker asks for two kinds of decision. A question (user_input) asks what to build. An approval asks permission to run a command or change files. Who decides depends on the mode, saved in memory:

  1. Default mode: show each question or approval to the user as a card with the exact options. Answer only with their pick for that request. Never reuse a pick for a new request.
  2. Away mode starts when the user says something like "I'm away", "decide for me" or "keep it moving". Save the scope and the end time in memory. Then:
    • Answer routine questions yourself, and tell the user afterwards what you picked and why.
    • Accept low and normal approvals with the one-time option (kind allow_once). Never pick an allow_always option: it changes the agent's permissions for good. Never accept a high approval without the user's yes for that request.
    • Leave product direction, money, publishing and anything the user kept for themselves to the user.
    • Away mode ends at the end time or when the user is back. Say when it ended.
  3. Standing approvals: the user may list kinds of approvals to always accept. Follow the list exactly.

Orchestrator gives no risk level, so you judge it. Treat these as a floor. If a command looks riskier, call it high.

Risk Examples
high Deletes outside the session's worktree, rm -rf, git push --force, push to main or master, git reset --hard, history rewrites, deploy, publish, release, secrets, credentials, tokens, sudo, system installs, payments
low Reading or searching files, git status/diff/log, tests, lint, typecheck, builds
normal Everything else, such as edits and commits in the session's worktree, or pushing the session's own branch

Never invent the user's preferences. The worker decides how to do the work. The user decides what to build.

Writes

Change nothing on the user's computers unless the user approved that exact change in chat, or away mode or a standing approval covers it. Approval for one change is not approval for the next. Never delete or archive sessions or projects, never change Orchestrator settings, and never merge, publish or deploy without the user's yes for that item.

Secrets

  • The header file holds a host's password. Pass it only to curl as -H @<file>. Never open, print, copy or paste it.
  • Never read Orchestrator's own credential files: ~/.ao/mobile/, ~/.ao/data/agent-accounts/, ~/.ao/electron/, or any *token*, *auth*, .env or keychain item.
  • If session text contains a key, never repeat it.

Messages to agents

  • Before you send a follow-up, read the last turn (aoapi GET "sessions/<id>/history?offset=0&limit=1") so you don't repeat or contradict it.
  • Keep messages short and concrete: what is right so far, then the next step. Leave out check-ins, your own process and these rules.
  • Start every message you send with [via Grok Bot], so the user can tell it apart in Orchestrator.

Output

  • Answer first, in short plain words. Say what you could not check.
  • Write every session as <host name>/<session id>, every time, in every skill and every line, even when only one host has that id: Air/agent-orchestrator-31, Pro/agent-orchestrator-1-249. Add the display name when it helps.
  • Give times in the user's timezone.
  • One message per event. If two checks report the same thing, say it once. News (a merge, a finished review) is reported once: ao-status keeps a seen list.
  • Send files with SendToUser. Copy them to the box first with CopyToBox.

Memory

  • Save hosts, modes and preferences, not activity. A check where nothing changed is not worth a note.
  • When the user corrects you, save the correction.
  • A follow-up you promise for later ("I'll tell you when it's done") goes into a Routine, not only into memory.

Grok Bot only

These steps need tools only Grok Bot has. Any other agent (Claude Code, Codex, Cursor) runs on one computer and does this instead:

Grok Bot step Other agents
ListMachines, every connected computer Only the computer you run on, as a local host
Routines Run the check once when asked
Cards Plain text with numbered options
Memory Ask, or use the notes file the user names
SendToUser, CopyToBox Give the file path

Version History

  • aa6e65d Current 2026-11-16 19:56

Same Skill Collection

.agents/skills/ao-desktop-dev/SKILL.md
.agents/skills/bug-triage/SKILL.md
.agents/skills/pr-description/SKILL.md
.claude/skills/ao-desktop-dev/SKILL.md
.claude/skills/bug-triage/SKILL.md
backend/internal/skillassets/bug-triage/SKILL.md
backend/internal/skillassets/using-ao/SKILL.md
integrations/grok-bot/skills/ao-actions/SKILL.md
integrations/grok-bot/skills/ao-answer/SKILL.md
integrations/grok-bot/skills/ao-orchestrator/SKILL.md
integrations/grok-bot/skills/ao-setup/SKILL.md
integrations/grok-bot/skills/ao-status/SKILL.md
integrations/grok-bot/skills/ao-update/SKILL.md

Metadata

Files
0
Version
aa6e65d
Hash
11d5e275
Indexed
2026-11-16 19:56

inicio - Wiki
Copyright © 2011-2026 iteam. Current version is 2.156.0. UTC+08:00, 2026-11-16 23:10
浙ICP备14020137号-1