codex-relay-skill
starsforks
How to install codex-relay-skill?
agentworkforce/relay/codex-relay-skill
$npx -y skills add AgentWorkforce/relay --skill codex-relay-skillUse when you need Codex to coordinate multiple agents through Agent Relay for peer-to-peer messaging, lead/worker handoffs, or shared status tracking across sub-agents and terminals.
SKILL.md
| 1 | # Agent Relay |
| 2 | |
| 3 | Use this skill when Codex needs real-time coordination across multiple agents. It gives Codex a repeatable workflow for: |
| 4 | |
| 5 | - connecting to an Agent Relay workspace |
| 6 | - spawning relay-aware workers |
| 7 | - sending direct messages, channel updates, and thread replies |
| 8 | - keeping lead and worker state synchronized through ACK, STATUS, BLOCKED, and DONE signals |
| 9 | |
| 10 | Relay fills the peer-to-peer gap in Codex sub-agent workflows. Codex can spawn and collect worker results, but Agent Relay gives those workers a shared message bus so they can talk to the lead and to each other. |
| 11 | |
| 12 | ## Auto-setup |
| 13 | |
| 14 | On first activation, this skill auto-configures Codex by running `scripts/setup.sh`. This adds the Agent Relay MCP server to `.codex/config.toml`, enables hooks, installs `hooks.json`, and copies the `relay-worker.toml` agent definition. No manual setup is required after installing the skill. |
| 15 | |
| 16 | ## Startup protocol |
| 17 | |
| 18 | Every relay-connected Codex agent must complete these steps IN ORDER before substantive work: |
| 19 | |
| 20 | 1. **Set up a workspace.** |
| 21 | - If `RELAY_WORKSPACE_KEY` is set in the environment, call `set_workspace_key` with that key. |
| 22 | - If only the legacy `RELAY_API_KEY` alias is set, treat it as the same workspace key. |
| 23 | - If no key is available, call `create_workspace` to auto-create one. This returns a workspace key — save it for workers. |
| 24 | |
| 25 | 2. **Register as an agent.** Call `register_agent` with your agent name and `type: "agent"`. Use `RELAY_AGENT_NAME` from the environment if set, otherwise derive a name from the task context (e.g., `lead`, `auth-worker`). |
| 26 | |
| 27 | 3. **Tell the user** they can follow the conversation live at `https://agentrelay.com/observer?key=<workspace_key>` (use the workspace key from step 1). This lets them watch all agent messages in real time. |
| 28 | |
| 29 | 4. **Check the relay inbox.** Call `check_inbox` to see if there are any pending messages or task assignments. |
| 30 | |
| 31 | 5. **Send an ACK.** If you received a task assignment, send `ACK: <one-sentence understanding>` to your lead via `send_dm`. If the assignment is unclear, send `BLOCKED: <question>` instead of guessing. |
| 32 | |
| 33 | 6. **When the task is complete**, send `DONE: <summary with evidence>` before stopping. |
| 34 | |
| 35 | If workspace creation or registration fails, retry once, then report the failure to the user — do not proceed without a relay connection. |
| 36 | |
| 37 | ## Critical rule |
| 38 | |
| 39 | **Do not assume the current MCP session already has an active Agent Relay workspace.** Always call `set_workspace_key` or `create_workspace` before registering. |
| 40 | |
| 41 | ## Working rules |
| 42 | |
| 43 | - Include `as: "<agent-name>"` on relay calls that support explicit attribution. |
| 44 | - Keep the relay identity stable for the whole task. Do not switch names mid-task. |
| 45 | - Check the inbox again after meaningful milestones, before long-running work, and before stopping. |
| 46 | - Prefer direct messages for lead/worker coordination. Use channels only when multiple agents need the same update. |
| 47 | - Keep status messages short, factual, and scoped to the assigned work. |
| 48 | - Do not spawn additional relay workers unless the lead explicitly asks for more delegation. |
| 49 | - If the lead updates the task, follow the newest explicit instruction. |
| 50 | |
| 51 | ## Message templates |
| 52 | |
| 53 | - `ACK: I understand the assignment and I am starting work on <scope>.` |
| 54 | - `STATUS: Finished <milestone>; next I am doing <next-step>.` |
| 55 | - `BLOCKED: I cannot continue because <blocker>.` |
| 56 | - `DONE: Completed <scope>. Evidence: <files changed, commands run, tests, or decisions>.` |
| 57 | |
| 58 | ## Worker patterns |
| 59 | |
| 60 | There are two current ways to involve more agents. Use the right one for the |
| 61 | job. |
| 62 | |
| 63 | ### Registered workspace identities |
| 64 | |
| 65 | Use `register_agent` for an agent process that is already running and only |
| 66 | needs a Relay identity. Registration does not start a new model runtime. |
| 67 | |
| 68 | **Lead steps:** |
| 69 | |
| 70 | 1. Ensure workspace exists (`set_workspace_key` or `create_workspace`). |
| 71 | 2. Register the lead (`register_agent`). |
| 72 | 3. Give the other running process the workspace key and tell it to call |
| 73 | `register_agent` with a stable name. |
| 74 | 4. Send the assignment via `send_dm(to: "worker-name", text: "...")`. |
| 75 | 5. Poll lead inbox for ACK (`check_inbox`). |
| 76 | |
| 77 | **Worker steps:** |
| 78 | |
| 79 | 1. Call `set_workspace_key` with the shared key. |
| 80 | 2. Register with `register_agent`. |
| 81 | 3. Check inbox (`check_inbox`). |
| 82 | 4. Send ACK to lead via `send_dm`. |
| 83 | 5. Perform the assigned scope. |
| 84 | 6. Send DONE to lead via `send_dm`. |
| 85 | |
| 86 | ### Relay-spawned workers |
| 87 | |
| 88 | Use `add_agent` when the lead should ask Relay to start a provider-backed |
| 89 | worker. The current tool requires `name`, `cli`, and `task`; optional fields |
| 90 | include `channel`, `persona`, and `model`. |
| 91 | |
| 92 | **Lead steps:** |
| 93 | |
| 94 | 1. Ensure workspace exists and lead is registered. |
| 95 | 2. Spawn the worker with `add_agent(name: "worker-name", cli: "codex", task: "...")`. |
| 96 | 3. Include `https://agentrelay.com/skill`, the lead name, exact scope, and |
| 97 | comple |
People who liked this also viewed
6 picksType
- find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 2026
- grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026
- vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026
- improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026
- setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026
- triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026
