Skip to content

fix(skills): correct using-agent-relay drift and stale MCP names in sdk rule #1423

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
willwashburn wants to merge 2 commits into
base: main
Choose a base branch
from
+114 −65
Open

fix(skills): correct using-agent-relay drift and stale MCP names in sdk rule #1423

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bd4cf11
fix(skills): correct using-agent-relay drift in the vendored copies
claude Aug 3, 2026
848cf17
style: auto-format with Prettier
github-actions[bot] Aug 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 53 additions & 31 deletions .agents/skills/using-agent-relay/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,10 +40,10 @@ The current Agent Relay MCP server registers flat tool names. Use the final
tool name exactly as listed here.

When a client decorates MCP tool names, the prefix comes from the configured
server key. Workflow prompts commonly show forms like
`mcp__relaycast__send_dm`; a server configured as `agent-relay` may expose
`mcp__agent_relay__send_dm`. In every case, the canonical tool name is the flat
suffix, such as `send_dm`.
server key. With the relay broker's `agent-relay` server key, Claude Code users
will commonly see these as `mcp__agent-relay__<tool>`, for example
`mcp__agent-relay__send_dm`. Codex and opencode users see the bare canonical
names, such as `send_dm`.

Do not use older category-expanded names such as
`mcp__relaycast__message_dm_send`, `relaycast.message.dm.send`, or
Expand Down Expand Up @@ -76,6 +76,7 @@ Do not use older category-expanded names such as
| --------------------- | -------------------------------------------------- |
| `send_dm` | Send a direct message to one agent |
| `send_group_dm` | Create a group DM and send the first message |
| `list_dms` | List your direct-message conversations |
| `post_message` | Post to a channel |
| `list_messages` | Read channel history |
| `reply_to_thread` | Reply to an existing message |
Expand Down Expand Up @@ -187,48 +188,69 @@ Release workers after their work is accepted:
remove_agent(name: "reviewer-1", reason: "Review accepted")
```

## Current CLI Reference
## CLI Reference

Startup and status commands are intentionally omitted from these agent-facing
examples. Published Agent Relay versions through 11.3.0 can print live
workspace credentials when those commands run in a transcribed session. Upgrade
to Agent Relay 11.3.1 or later before running them there.
Prefer the MCP tools above for messaging. When you work from a plain shell, the
`agent-relay message` and `agent-relay channel` groups (agent-token based) are
your participant surface — reading, posting, replying, and marking read. The
`agent-relay node` group is broker lifecycle and debug only.

These are the current CLI forms for local broker and SDK-backed messaging
operations:
Messaging (agent token; these are how a participant reads and replies):

```bash
agent-relay status
agent-relay node agent list
agent-relay node agent spawn claude --name Worker --task "Use https://agentrelay.com/skill and ACK over Relay."
agent-relay node tail --agent Worker
agent-relay node agent attach Worker --mode view
agent-relay node agent release Worker

agent-relay agent register Worker --workspace-key rk_live_...
agent-relay agent list --workspace-key rk_live_...
agent-relay message inbox check --workspace-key rk_live_... --token at_live_...
agent-relay message inbox mark_read msg_123 --workspace-key rk_live_... --token at_live_...
agent-relay message dm send Lead "ACK: I am online." --workspace-key rk_live_... --token at_live_...
agent-relay message dm list <conversationId> --workspace-key rk_live_... --token at_live_... # persistent DM history (unlike unread-only inbox check)

@coderabbitai coderabbitai Bot Aug 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Use a shell-safe conversation identifier placeholder.

Bash interprets <conversationId> as redirection syntax.

  • .agents/skills/using-agent-relay/SKILL.md#L204-L204: Replace <conversationId> with CONVERSATION_ID.
  • .claude/skills/using-agent-relay/SKILL.md#L204-L204: Apply the same placeholder correction.
🧰 Tools
🪛 SkillSpector (2.4.4)

[warning] 21: [AS3] Skill Enumeration: Skill enumerates or reads other installed skills. Access to other skills' SKILL.md files or the skills directory reveals prompt instructions, capabilities, and secrets that should be invisible to peer skills.

Remediation: Remove all code or instructions that list or read other skills' files or directories. Skills should operate independently; cross-skill access is a privilege escalation.

(Agent Snooping (AS3))

[warning] 54: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 75: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 91: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 93: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 94: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 95: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 96: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 99: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 248: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 250: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 251: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 252: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 254: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 255: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 256: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

📍 Affects 2 files
  • .agents/skills/using-agent-relay/SKILL.md#L204-L204 (this comment)
  • .claude/skills/using-agent-relay/SKILL.md#L204-L204
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.agents/skills/using-agent-relay/SKILL.md at line 204, Replace the
angle-bracket conversation identifier placeholder in the `agent-relay message dm
list` example with the shell-safe `CONVERSATION_ID` placeholder at
`.agents/skills/using-agent-relay/SKILL.md:204-204` and apply the same change at
`.claude/skills/using-agent-relay/SKILL.md:204-204`.

agent-relay message post general "Status update" --workspace-key rk_live_... --token at_live_...
agent-relay message list general --workspace-key rk_live_... --token at_live_...
agent-relay message reply msg_123 "Thread reply" --workspace-key rk_live_... --token at_live_...
agent-relay message get_thread msg_123 --workspace-key rk_live_... --token at_live_...
agent-relay channel list --workspace-key rk_live_... --token at_live_...
Comment on lines 201 to +209

@coderabbitai coderabbitai Bot Aug 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Keep credentials out of command-line examples.

The messaging examples place workspace keys and agent tokens in process arguments. Use the documented environment variables instead.

  • .agents/skills/using-agent-relay/SKILL.md#L201-L209: Rewrite the examples to use RELAY_WORKSPACE_KEY and RELAY_AGENT_TOKEN.
  • .claude/skills/using-agent-relay/SKILL.md#L201-L209: Apply the same credential-handling correction.
🧰 Tools
🪛 SkillSpector (2.4.4)

[warning] 21: [AS3] Skill Enumeration: Skill enumerates or reads other installed skills. Access to other skills' SKILL.md files or the skills directory reveals prompt instructions, capabilities, and secrets that should be invisible to peer skills.

Remediation: Remove all code or instructions that list or read other skills' files or directories. Skills should operate independently; cross-skill access is a privilege escalation.

(Agent Snooping (AS3))

[warning] 54: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 75: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 91: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 93: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 94: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 95: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 96: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 99: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 248: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 250: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 251: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 252: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 254: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 255: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

[warning] 256: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.

Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.

(Memory Poisoning (MP2))

📍 Affects 2 files
  • .agents/skills/using-agent-relay/SKILL.md#L201-L209 (this comment)
  • .claude/skills/using-agent-relay/SKILL.md#L201-L209
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.agents/skills/using-agent-relay/SKILL.md around lines 201 - 209, Remove
inline workspace keys and agent tokens from the messaging command examples,
replacing them with the documented RELAY_WORKSPACE_KEY and RELAY_AGENT_TOKEN
environment variables in .agents/skills/using-agent-relay/SKILL.md lines 201-209
and .claude/skills/using-agent-relay/SKILL.md lines 201-209; apply the same
correction to every listed command while preserving their arguments and
behavior.

```

Workspace identity:

```bash
agent-relay agent register Worker --workspace-key rk_live_...
agent-relay agent list --workspace-key rk_live_...
```

Local broker lifecycle and debug (lifecycle only — read replies through the
`message` group above, never `node tail`):

```bash
agent-relay status # workspace + cloud + broker overview
agent-relay node up --background --verbose
agent-relay node status --wait-for 10
agent-relay node agent list
agent-relay node agent spawn claude --name Worker --task "Use https://agentrelay.com/skill and ACK over Relay."
agent-relay node agent attach Worker --mode view
agent-relay node agent release Worker
agent-relay node tail --agent Worker # worker output/TTY, not durable messages
agent-relay node tail # broker debug events (unfiltered), not messages
```

These lifecycle commands live under `agent-relay node …`. The old flat
`agent-relay local …` group still works as a hidden, deprecated alias (it prints
a removal warning) — prefer `node`.

Use environment variables instead of flags when available:

```bash
RELAY_WORKSPACE_KEY=rk_live_...
RELAY_AGENT_TOKEN=at_live_...
RELAY_BASE_URL=https://gateway.relaycast.dev
export RELAY_WORKSPACE_KEY=rk_live_...
export RELAY_AGENT_TOKEN=at_live_...
export RELAY_BASE_URL=https://cast.agentrelay.com
```

## Common Mistakes

| Mistake | Fix |
| --------------------------------------------- | ------------------------------------------------------------------------------ |
| Using `message_dm_send` or `message.post` | Use current flat tools: `send_dm`, `post_message`, `reply_to_thread` |
| Acting as orchestrator with participant tools | Use `orchestrating-agent-relay`, or register yourself first |
| Calling tools before selecting a workspace | Call `set_workspace_key` or `create_workspace` first |
| Spawning with `add_agent(name, type)` | `add_agent` needs `name`, `cli`, and `task`; use `register_agent` for identity |
| Forgetting to ACK | Send `ACK:` to the lead before starting work |
| Finishing silently | Send `DONE:` with evidence before stopping |
| Mistake | Fix |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Using `message_dm_send` or `message.post` | Use current flat tools: `send_dm`, `post_message`, `reply_to_thread` |
| Acting as orchestrator with participant tools | Use `orchestrating-agent-relay`, or register yourself first |
| Calling tools before selecting a workspace | Call `set_workspace_key` or `create_workspace` first |
| Reading peer replies via `node tail` | `node tail` streams broker events; `node tail --agent <name>` streams that worker's raw output — neither is durable messages. Read with `check_inbox` / `list_messages` / `get_message_thread` (or the `message` CLI group) |
| Spawning with `add_agent(name, type)` | `add_agent` needs `name`, `cli`, and `task`; use `register_agent` for identity |
| Forgetting to ACK | Send `ACK:` to the lead before starting work |
| Finishing silently | Send `DONE:` with evidence before stopping |
11 changes: 8 additions & 3 deletions .claude/rules/sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,9 +53,14 @@ The SDK uses subpath exports:

## Communication Protocol

- **Primary**: MCP tools (`mcp__relaycast__message_dm_send`,
`mcp__relaycast__message_inbox_check`, `mcp__relaycast__agent_list`,
`mcp__relaycast__agent_add`, `mcp__relaycast__agent_remove`)
- **Primary**: MCP tools. The canonical names are flat — `send_dm`,
`check_inbox`, `post_message`, `list_agents`, `add_agent`, `remove_agent`.
A client may decorate them with the configured server key, so Claude Code
users typically see `mcp__agent-relay__send_dm` while Codex and opencode see
the bare name.
- Do **not** use the older category-expanded forms
(`mcp__relaycast__message_dm_send`, `relaycast.message.dm.send`,
`message.post`). They are not registered by `agent-relay mcp`.

## No Storage Layer

Expand Down
84 changes: 53 additions & 31 deletions .claude/skills/using-agent-relay/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,10 +40,10 @@ The current Agent Relay MCP server registers flat tool names. Use the final
tool name exactly as listed here.

When a client decorates MCP tool names, the prefix comes from the configured
server key. Workflow prompts commonly show forms like
`mcp__relaycast__send_dm`; a server configured as `agent-relay` may expose
`mcp__agent_relay__send_dm`. In every case, the canonical tool name is the flat
suffix, such as `send_dm`.
server key. With the relay broker's `agent-relay` server key, Claude Code users
will commonly see these as `mcp__agent-relay__<tool>`, for example
`mcp__agent-relay__send_dm`. Codex and opencode users see the bare canonical
names, such as `send_dm`.

Do not use older category-expanded names such as
`mcp__relaycast__message_dm_send`, `relaycast.message.dm.send`, or
Expand Down Expand Up @@ -76,6 +76,7 @@ Do not use older category-expanded names such as
| --------------------- | -------------------------------------------------- |
| `send_dm` | Send a direct message to one agent |
| `send_group_dm` | Create a group DM and send the first message |
| `list_dms` | List your direct-message conversations |
| `post_message` | Post to a channel |
| `list_messages` | Read channel history |
| `reply_to_thread` | Reply to an existing message |
Expand Down Expand Up @@ -187,48 +188,69 @@ Release workers after their work is accepted:
remove_agent(name: "reviewer-1", reason: "Review accepted")
```

## Current CLI Reference
## CLI Reference

Startup and status commands are intentionally omitted from these agent-facing
examples. Published Agent Relay versions through 11.3.0 can print live
workspace credentials when those commands run in a transcribed session. Upgrade
to Agent Relay 11.3.1 or later before running them there.
Prefer the MCP tools above for messaging. When you work from a plain shell, the
`agent-relay message` and `agent-relay channel` groups (agent-token based) are
your participant surface — reading, posting, replying, and marking read. The
`agent-relay node` group is broker lifecycle and debug only.

These are the current CLI forms for local broker and SDK-backed messaging
operations:
Messaging (agent token; these are how a participant reads and replies):

```bash
agent-relay status
agent-relay node agent list
agent-relay node agent spawn claude --name Worker --task "Use https://agentrelay.com/skill and ACK over Relay."
agent-relay node tail --agent Worker
agent-relay node agent attach Worker --mode view
agent-relay node agent release Worker

agent-relay agent register Worker --workspace-key rk_live_...
agent-relay agent list --workspace-key rk_live_...
agent-relay message inbox check --workspace-key rk_live_... --token at_live_...
agent-relay message inbox mark_read msg_123 --workspace-key rk_live_... --token at_live_...
agent-relay message dm send Lead "ACK: I am online." --workspace-key rk_live_... --token at_live_...
agent-relay message dm list <conversationId> --workspace-key rk_live_... --token at_live_... # persistent DM history (unlike unread-only inbox check)
agent-relay message post general "Status update" --workspace-key rk_live_... --token at_live_...
agent-relay message list general --workspace-key rk_live_... --token at_live_...
agent-relay message reply msg_123 "Thread reply" --workspace-key rk_live_... --token at_live_...
agent-relay message get_thread msg_123 --workspace-key rk_live_... --token at_live_...
agent-relay channel list --workspace-key rk_live_... --token at_live_...
```

Workspace identity:

```bash
agent-relay agent register Worker --workspace-key rk_live_...
agent-relay agent list --workspace-key rk_live_...
```

Local broker lifecycle and debug (lifecycle only — read replies through the
`message` group above, never `node tail`):

```bash
agent-relay status # workspace + cloud + broker overview
agent-relay node up --background --verbose
agent-relay node status --wait-for 10
agent-relay node agent list
agent-relay node agent spawn claude --name Worker --task "Use https://agentrelay.com/skill and ACK over Relay."
agent-relay node agent attach Worker --mode view
agent-relay node agent release Worker
agent-relay node tail --agent Worker # worker output/TTY, not durable messages
agent-relay node tail # broker debug events (unfiltered), not messages
```

These lifecycle commands live under `agent-relay node …`. The old flat
`agent-relay local …` group still works as a hidden, deprecated alias (it prints
a removal warning) — prefer `node`.

Use environment variables instead of flags when available:

```bash
RELAY_WORKSPACE_KEY=rk_live_...
RELAY_AGENT_TOKEN=at_live_...
RELAY_BASE_URL=https://gateway.relaycast.dev
export RELAY_WORKSPACE_KEY=rk_live_...
export RELAY_AGENT_TOKEN=at_live_...
export RELAY_BASE_URL=https://cast.agentrelay.com
```

## Common Mistakes

| Mistake | Fix |
| --------------------------------------------- | ------------------------------------------------------------------------------ |
| Using `message_dm_send` or `message.post` | Use current flat tools: `send_dm`, `post_message`, `reply_to_thread` |
| Acting as orchestrator with participant tools | Use `orchestrating-agent-relay`, or register yourself first |
| Calling tools before selecting a workspace | Call `set_workspace_key` or `create_workspace` first |
| Spawning with `add_agent(name, type)` | `add_agent` needs `name`, `cli`, and `task`; use `register_agent` for identity |
| Forgetting to ACK | Send `ACK:` to the lead before starting work |
| Finishing silently | Send `DONE:` with evidence before stopping |
| Mistake | Fix |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Using `message_dm_send` or `message.post` | Use current flat tools: `send_dm`, `post_message`, `reply_to_thread` |
| Acting as orchestrator with participant tools | Use `orchestrating-agent-relay`, or register yourself first |
| Calling tools before selecting a workspace | Call `set_workspace_key` or `create_workspace` first |
| Reading peer replies via `node tail` | `node tail` streams broker events; `node tail --agent <name>` streams that worker's raw output — neither is durable messages. Read with `check_inbox` / `list_messages` / `get_message_thread` (or the `message` CLI group) |
| Spawning with `add_agent(name, type)` | `add_agent` needs `name`, `cli`, and `task`; use `register_agent` for identity |
| Forgetting to ACK | Send `ACK:` to the lead before starting work |
| Finishing silently | Send `DONE:` with evidence before stopping |