Update relay skills for v8 CLI surface + agent-relay MCP#69
Update relay skills for v8 CLI surface + agent-relay MCP#69willwashburn wants to merge 4 commits into
Conversation
Rewrite the skill for relay main: broker/agent verbs under `agent-relay local …`, all messaging through relay (the `message`/ `channel` groups, never the broker directly), and `mcp__agent-relay__*` tool names. Bump to 2.2.0. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
CodeAnt AI is reviewing your PR. |
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (7)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
The skill is maintained in AgentWorkforce/skills (skills/orchestrating-agent-relay); the copies under .claude/ and .agents/ in relay were stale duplicates. Updated canonical version: AgentWorkforce/skills#69. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the orchestrating-agent-relay skill documentation to reflect major CLI changes, specifically splitting commands into local lifecycle management (agent-relay local) and token-gated messaging through relay (agent-relay message). It also bumps the skill version to 2.2.0. The review feedback constructively suggests clarifying how an orchestrator can obtain the conversationId required for reading DM replies, both in the main guide and the common mistakes section.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| > **Read worker replies through relay, never from the broker.** ACKs, replies, | ||
| > and DONE signals are relay messages — read them with `message inbox check` / | ||
| > `message dm list`. Do not use `local tail` to "read" worker responses; it | ||
| > streams the broker's raw TTY output and is only a low-level debugging aid. |
There was a problem hiding this comment.
Clarification on <conversationId>
The documentation introduces the command agent-relay message dm list <conversationId> to read worker replies, but does not explicitly explain how the orchestrator can obtain the <conversationId>.
To make this guide more actionable for both human operators and autonomous orchestrators, consider adding a brief note explaining that the conversationId is returned in the JSON response when sending a DM via agent-relay message dm send, or can be extracted from the output of agent-relay message inbox check.
| | `Not registered. Call agent.register first.` | `message`/`channel`/`dm` are token-gated. Run `agent-relay agent register <name>` and set `RELAY_AGENT_TOKEN` (or pass `--token`). The `local` group is exempt | | ||
| | Spawn fails with `internal reply dropped` | Broker likely is not fully ready yet; wait for readiness, then spawn one worker first | | ||
| | Workers not connecting | Ensure broker started; check `agent-relay local agent list`, then `agent-relay local tail --agent <name>` to debug raw output | | ||
| | Reading worker replies with `local tail` / broker output | Messages go through relay — read them with `agent-relay message inbox check` / `message dm list <conversationId>`. `local tail` is raw broker output, not relay | |
There was a problem hiding this comment.
Clarification on <conversationId> in Common Mistakes
In the "Common Mistakes" table, the fix for "Reading worker replies with local tail" mentions message dm list <conversationId>. It would be highly beneficial to clarify here as well how the orchestrator can retrieve this ID (e.g., from the inbox check or the DM send confirmation).
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7fc3d4e18f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| agent-relay message list <channel> [--limit <n>] # channel history | ||
| agent-relay message dm send <agent> <text> # DM a worker | ||
| agent-relay message dm list <conversationId> [--limit <n>] # read a DM thread | ||
| agent-relay message dm send_group <text> # group DM |
There was a problem hiding this comment.
When someone copies this group-DM entry, the command exits before sending anything because the v8 CLI defines message dm send_group with a required --to <agents...> option (checked in packages/cli/src/cli/commands/message.ts via requiredOption('--to ...')). Please show the recipient flag here, e.g. agent-relay message dm send_group <text> --to Worker1 --to Worker2, so the reference is runnable.
Useful? React with 👍 / 👎.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
3 issues found across 2 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="prpm.json">
<violation number="1" location="prpm.json:92">
P2: Version metadata is now inconsistent: `prpm.json` says 2.2.0 while README still lists orchestrating-agent-relay as 2.1.2.</violation>
</file>
<file name="skills/orchestrating-agent-relay/SKILL.md">
<violation number="1" location="skills/orchestrating-agent-relay/SKILL.md:60">
P3: Quick reference incorrectly implies `agent register` auto-sets `RELAY_AGENT_TOKEN`; the doc’s own Step 3 shows the token must be exported manually.</violation>
<violation number="2" location="skills/orchestrating-agent-relay/SKILL.md:220">
P2: Add required recipient arguments to this group-DM command example; without `--to` targets, the command is not runnable.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| { | ||
| "name": "orchestrating-agent-relay", | ||
| "version": "2.1.2", | ||
| "version": "2.2.0", |
There was a problem hiding this comment.
P2: Version metadata is now inconsistent: prpm.json says 2.2.0 while README still lists orchestrating-agent-relay as 2.1.2.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At prpm.json, line 92:
<comment>Version metadata is now inconsistent: `prpm.json` says 2.2.0 while README still lists orchestrating-agent-relay as 2.1.2.</comment>
<file context>
@@ -89,7 +89,7 @@
{
"name": "orchestrating-agent-relay",
- "version": "2.1.2",
+ "version": "2.2.0",
"description": "The canonical way to run agent-relay - self-bootstrap the broker and autonomously spawn, monitor, and coordinate a team of worker agents without human intervention. Covers infrastructure startup, agent spawning, lifecycle monitoring, CLI-first reading, and team coordination.",
"format": "claude",
</file context>
Bring the remaining relay skills in line with relay main: - using-agent-relay (1.4.0): flat MCP tool names (send_dm, post_message, join_channel, …), `agent-relay.<tool>` mcporter shorthand, the `agent-relay local …` CLI surface. Drop sections for tools the MCP server doesn't expose (webhooks, subscriptions, command register/delete, file upload); keep actions (list_actions/invoke_action) and workspace. - openclaw-orchestrator (1.1.0): `agent-relay local …` lifecycle, relay messaging (`agent-relay message …` / `mcp__agent-relay__*`), `mcporter call agent-relay …`, channel-based teams. - choosing-swarm-patterns (1.1.4): `mcp__agent-relay__*` tool names, `.agentworkforce/relay/` state dir, agent-relay MCP server references. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
willwashburn
changed the title
|
Reviewed and fixed PR #69 locally. Key fixes:
Verification run:
|
…ame to agent-relay (#1034) * Remove vendored openclaw package; rename MCP server to agent-relay OpenClaw lives in its own repo (AgentWorkforce/agent-relay-openclaw); the copy under packages/openclaw was a stale duplicate re-added after the split and nothing in relay depends on it. Drop it (and its package-lock entries + the CI build step). Also align the customer-facing MCP surface with the binary name: - CLI uninstall now cleans up the `agent-relay` .mcp.json key and the legacy `relaycast` key. - Refresh the orchestrating-agent-relay skill for the v8 `local` CLI surface, relay-only messaging, and the `mcp__agent-relay__*` tools. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * style: auto-format with Prettier * Remove vendored orchestrating-agent-relay skill The skill is maintained in AgentWorkforce/skills (skills/orchestrating-agent-relay); the copies under .claude/ and .agents/ in relay were stale duplicates. Updated canonical version: AgentWorkforce/skills#69. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
There was a problem hiding this comment.
2 issues found across 4 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="skills/using-agent-relay/SKILL.md">
<violation number="1" location="skills/using-agent-relay/SKILL.md:222">
P2: Stale error message references old dot-notation `agent.register` instead of the new flat-style `register_agent`. The entire document was renamed from `relaycast.*` (dot-notation) to `agent-relay.*` (flat snake_case), and `agent_register` was renamed to `register_agent`. The server-side error almost certainly reflects this rename too, so documenting the old error text will confuse users who see a different message.</violation>
</file>
<file name="skills/openclaw-orchestrator/SKILL.md">
<violation number="1" location="skills/openclaw-orchestrator/SKILL.md:68">
P2: Channel names are inconsistent (`my-project` vs `my-team`), so the documented spawn flow and monitoring flow point to different channels.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
|
Reviewed PR #69 and made scoped fixes. Fixed:
Validation run:
Could not run |
|
✅ pr-reviewer applied fixes — committed and pushed Reviewed and fixed PR #69 locally. Changes made:
Validation run:
Note: no bot review artifacts were present under |
There was a problem hiding this comment.
2 issues found across 4 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="prpm.json">
<violation number="1" location="prpm.json:92">
P2: Version metadata is now inconsistent: `prpm.json` says 2.2.0 while README still lists orchestrating-agent-relay as 2.1.2.</violation>
</file>
<file name="skills/openclaw-orchestrator/SKILL.md">
<violation number="1" location="skills/openclaw-orchestrator/SKILL.md:16">
P3: The workspace credential name was changed to “Agent Relay workspace key”, which introduces inconsistent terminology for `rk_live_` service keys and can mislead setup instructions.</violation>
<violation number="2" location="skills/openclaw-orchestrator/SKILL.md:160">
P3: Rate-limit guidance now labels 429s as “Agent Relay” errors, creating service-name inconsistency in a section where users diagnose provider limits.</violation>
</file>
Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic
| ## Rate Limiting | ||
|
|
||
| - Add 15s gaps between sequential spawns to avoid Relaycast 429 errors | ||
| - Add 15s gaps between sequential spawns to avoid Agent Relay 429 errors |
There was a problem hiding this comment.
P3: Rate-limit guidance now labels 429s as “Agent Relay” errors, creating service-name inconsistency in a section where users diagnose provider limits.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At skills/openclaw-orchestrator/SKILL.md, line 160:
<comment>Rate-limit guidance now labels 429s as “Agent Relay” errors, creating service-name inconsistency in a section where users diagnose provider limits.</comment>
<file context>
@@ -157,7 +157,7 @@ agent-relay local down
## Rate Limiting
-- Add 15s gaps between sequential spawns to avoid Relaycast 429 errors
+- Add 15s gaps between sequential spawns to avoid Agent Relay 429 errors
- Use unique agent names per run (append UUID suffix) to avoid 409 conflicts
- The SDK uses `registerOrRotate` pattern: on 409, rotates the agent token
</file context>
|
|
||
| - `agent-relay` CLI installed (`npm i -g agent-relay`) | ||
| - Relaycast workspace key (`rk_live_...`) — get one at https://agentrelay.com/openclaw or run `agent-relay up` to auto-create | ||
| - Agent Relay workspace key (`rk_live_...`) — get one at https://agentrelay.com/openclaw or run `agent-relay local up` to auto-create |
There was a problem hiding this comment.
P3: The workspace credential name was changed to “Agent Relay workspace key”, which introduces inconsistent terminology for rk_live_ service keys and can mislead setup instructions.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At skills/openclaw-orchestrator/SKILL.md, line 16:
<comment>The workspace credential name was changed to “Agent Relay workspace key”, which introduces inconsistent terminology for `rk_live_` service keys and can mislead setup instructions.</comment>
<file context>
@@ -13,7 +13,7 @@ Run headless multi-agent sessions: start infrastructure, join a workspace, creat
- `agent-relay` CLI installed (`npm i -g agent-relay`)
-- Relaycast workspace key (`rk_live_...`) — get one at https://agentrelay.com/openclaw or run `agent-relay local up` to auto-create
+- Agent Relay workspace key (`rk_live_...`) — get one at https://agentrelay.com/openclaw or run `agent-relay local up` to auto-create
- For Claude agents: `ANTHROPIC_API_KEY` or `claude auth login`
</file context>
|
✅ pr-reviewer applied fixes — committed and pushed Reviewed and fixed PR #69 locally. Fixed:
Local checks run:
Source checked for bot reviews: #69 |
There was a problem hiding this comment.
1 issue found across 6 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="commands/spawn.md">
<violation number="1" location="commands/spawn.md:32">
P2: Spawn command hardcodes `--channels orchestrator`, so the documented user-specified channel path is ignored.</violation>
</file>
Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic
| 5. **Spawn the worker.** Construct the spawn command from parsed args: | ||
| ```text | ||
| agent-relay spawn <auto-name> $1 [--model <model>] [--team orchestrator] "<task>" | ||
| agent-relay local agent spawn $1 --name <auto-name> [--model <model>] --channels orchestrator --task "<task>" |
There was a problem hiding this comment.
P2: Spawn command hardcodes --channels orchestrator, so the documented user-specified channel path is ignored.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At commands/spawn.md, line 32:
<comment>Spawn command hardcodes `--channels orchestrator`, so the documented user-specified channel path is ignored.</comment>
<file context>
@@ -21,26 +21,26 @@ Bootstrap the agent-relay broker (if not already running) and spawn a worker on
5. **Spawn the worker.** Construct the spawn command from parsed args:
```text
- agent-relay spawn <auto-name> $1 [--model <model>] [--team orchestrator] "<task>"
+ agent-relay local agent spawn $1 --name <auto-name> [--model <model>] --channels orchestrator --task "<task>"
```
- `<auto-name>` should be unique per run (e.g., `worker-<short-uuid>`) to avoid 409 conflicts.
</file context>
| agent-relay local agent spawn $1 --name <auto-name> [--model <model>] --channels orchestrator --task "<task>" | |
| agent-relay local agent spawn $1 --name <auto-name> [--model <model>] --channels <channel> --task "<task>" |
|
Reviewed and fixed PR #69 locally. Key fixes:
Checks run:
|
|
Reviewed and fixed the PR locally. Fixed:
Validated:
|
1 participant
Summary
Brings the relay-related skills in line with relay
main: theagent-relay local …CLI surface (the flat 7.1.1 commands are gone), relay-only messaging, and the customer-facingmcp__agent-relay__*tool names (wasrelaycast).Skills updated
agent-relay local …lifecycle, messaging always through relay (message/channelgroups, never the broker),mcp__agent-relay__*. Canonical home; the stale relay-repo copies are removed in Remove vendored openclaw package and orchestrating skill; align MCP name to agent-relay relay#1034.send_dm,post_message,join_channel,add_agent, …),agent-relay.<tool>mcporter shorthand, modernized CLI section. Removed sections for tools the MCP server does not expose (webhooks, subscriptions,command_register/command_delete,file_upload); kept the real ones (list_actions/invoke_action, workspace,get_message_readers).agent-relay local …lifecycle +agent-relay message …/mcp__agent-relay__*coordination,mcporter call agent-relay …,list_messages(wasget_messages), channel-based teams, MCP-tool task template.mcp__agent-relay__*tool names,.agentworkforce/relay/state dir, "agent-relay MCP server" references.Verified against relay source
Tool names checked against the 30
registerToolentries inagent-relay-mcp.ts; CLI commands against thelocalcommand tree inpackages/cli. Therelaycastproduct name is preserved where it means the service (workspace keys, hosts, rate limits).Related
🤖 Generated with Claude Code