Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

feat(cursor): advertise slash commands over ACP (#6525)

Wolf Mermelstein6a93adaab331
diff --git a/crates/agent_harness/src/outbound/cursor/manager/test.rs b/crates/agent_harness/src/outbound/cursor/manager/test.rs
index 0e72bc2766..77917e7a85 100644
--- a/crates/agent_harness/src/outbound/cursor/manager/test.rs
+++ b/crates/agent_harness/src/outbound/cursor/manager/test.rs
@@ -965,9 +965,35 @@ fn count(frames: &[serde_json::Value], pointer: &str, value: &str) -> usize {
.count()
}
+/// Whether this frame is the slash-command catalog, not conversation history.
+fn is_available_commands_update(frame: &serde_json::Value) -> bool {
+ frame
+ .pointer("/params/update/sessionUpdate")
+ .and_then(|found| found.as_str())
+ == Some("available_commands_update")
+}
+
+/// Consume the `available_commands_update` that follows a successful load so
+/// leftover catalog frames do not precede the next initialize or look like
+/// unsolicited history.
+async fn drain_available_commands_update(
+ receiver: &mut tokio::sync::mpsc::UnboundedReceiver<ToServerMessage>,
+) {
+ let frames = collect_until(receiver, is_available_commands_update).await;
+ assert_eq!(
+ frames.len(),
+ 1,
+ "session/load is followed by the slash-command catalog and nothing else: {frames:?}"
+ );
+}
+
/// The recovery handshake as the session actor performs it: `initialize`,
/// then `session/load`. Returns the history replayed before the load's
/// response after asserting the load succeeded and only history preceded it.
+///
+/// The catalog notification that follows a successful load is drained, the
+/// same way the Cursor fold helpers do, so a leftover metadata frame cannot
+/// poison the next handshake.
async fn reload(
sender: &super::super::pipe::PipeSender,
receiver: &mut tokio::sync::mpsc::UnboundedReceiver<ToServerMessage>,
@@ -1005,7 +1031,12 @@ async fn reload(
),
"only history travels before a load's response, got {frame}"
);
+ assert!(
+ !is_available_commands_update(frame),
+ "the catalog is advertised after the load result, not as history: {frame}"
+ );
}
+ drain_available_commands_update(receiver).await;
replayed
}
diff --git a/crates/cursor_cloud_agents/src/domain/mod.rs b/crates/cursor_cloud_agents/src/domain/mod.rs
index 3796c881d6..0a90fa25e3 100644
--- a/crates/cursor_cloud_agents/src/domain/mod.rs
+++ b/crates/cursor_cloud_agents/src/domain/mod.rs
@@ -17,6 +17,9 @@ pub mod model;
/// Cursor model catalog expressed as ACP configuration.
pub mod model_options;
+/// Slash commands advertised over ACP (`available_commands_update`).
+pub mod slash_commands;
+
/// The capabilities the domain requires from the outside.
pub mod ports;
diff --git a/crates/cursor_cloud_agents/src/domain/service/test/fold.rs b/crates/cursor_cloud_agents/src/domain/service/test/fold.rs
index 5450763f66..cbaf1d57cb 100644
--- a/crates/cursor_cloud_agents/src/domain/service/test/fold.rs
+++ b/crates/cursor_cloud_agents/src/domain/service/test/fold.rs
@@ -131,6 +131,27 @@ pub(super) async fn load(
break;
}
}
+ // Commands are advertised after the load result, same as session/new.
+ // Drain that metadata notification so leftover catalog frames do not
+ // look like unsolicited history or poison the next load.
+ drain_available_commands_update(client).await;
+}
+
+/// Consume the `available_commands_update` that follows a successful load.
+async fn drain_available_commands_update(client: &mut agent_client_protocol::Channel) {
+ let frame = tokio::time::timeout(std::time::Duration::from_secs(5), client.rx.next())
+ .await
+ .expect("available_commands_update after session/load")
+ .expect("the connection stayed open");
+ let TransportFrame::Single(frame) = frame else {
+ panic!("single frame")
+ };
+ let value = serde_json::to_value(&frame).unwrap();
+ assert_eq!(value["method"], "session/update", "{value}");
+ assert_eq!(
+ value["params"]["update"]["sessionUpdate"], "available_commands_update",
+ "session/load is followed by the slash-command catalog, got {value}"
+ );
}
/// The served transport stays silent: recovered history never streams live.
diff --git a/crates/cursor_cloud_agents/src/domain/slash_commands.rs b/crates/cursor_cloud_agents/src/domain/slash_commands.rs
new file mode 100644
index 0000000000..4e2b3e1823
--- /dev/null
+++ b/crates/cursor_cloud_agents/src/domain/slash_commands.rs
@@ -0,0 +1,150 @@
+//! Slash commands this agent advertises over ACP.
+//!
+//! Cursor's Cloud Agents API has a models list (`GET /v1/models`) and no
+//! skills list. The website catalog (`cursor.com/api/dashboard/get-managed-skills`)
+//! is cookie-authenticated and not callable with the `crsr_…` key this crate
+//! holds. The commands here are the cloud-usable subset of that catalog:
+//! skills Cursor's cloud runtime actually honors when `/name` arrives as
+//! ordinary prompt text.
+//!
+//! IDE-only, CLI-only, and local-only skills (`rename-chat`, `statusline`,
+//! `clone`, …) stay out. A name that is not in this table is still valid
+//! prompt text; it is just not offered in the client's `/` menu.
+
+#[cfg(test)]
+mod test;
+
+use agent_client_protocol::schema::v1::{
+ AvailableCommand, AvailableCommandInput, UnstructuredCommandInput,
+};
+
+/// One curated command: a name, a description, and an optional input hint.
+struct CatalogEntry {
+ name: &'static str,
+ description: &'static str,
+ input_hint: Option<&'static str>,
+}
+
+/// Cloud-usable Cursor skills, in the order the `/` menu should list them.
+///
+/// Descriptions are the short catalog copy from Cursor's managed-skills list,
+/// not the full `SKILL.md` bodies. Hints match the skills that parse leftover
+/// text (`/goal <objective>`, `/loop [interval] <prompt>`, `/shell <command>`).
+const CATALOG: &[CatalogEntry] = &[
+ CatalogEntry {
+ name: "autopilot",
+ description: "Keep a PR merge-ready by triaging comments, resolving conflicts, and fixing CI.",
+ input_hint: None,
+ },
+ CatalogEntry {
+ name: "canvas",
+ description: "Create a durable standalone canvas artifact beside the chat.",
+ input_hint: None,
+ },
+ CatalogEntry {
+ name: "create-hook",
+ description: "Create Cursor hooks for agent lifecycle events.",
+ input_hint: None,
+ },
+ CatalogEntry {
+ name: "create-rule",
+ description: "Create Cursor rules for persistent AI guidance.",
+ input_hint: None,
+ },
+ CatalogEntry {
+ name: "create-skill",
+ description: "Create a Cursor Agent Skill (SKILL.md).",
+ input_hint: None,
+ },
+ CatalogEntry {
+ name: "create-subagent",
+ description: "Create a custom subagent with a focused system prompt.",
+ input_hint: None,
+ },
+ CatalogEntry {
+ name: "deploy-with-vercel",
+ description: "Link this repository to Vercel and deploy it.",
+ input_hint: None,
+ },
+ CatalogEntry {
+ name: "env-setup",
+ description: "Explain, inspect, or improve a Cloud Agent environment.",
+ input_hint: None,
+ },
+ CatalogEntry {
+ name: "goal",
+ description: "Set a goal that Cursor will pursue to completion.",
+ input_hint: Some("<objective>"),
+ },
+ CatalogEntry {
+ name: "loop",
+ description: "Run a prompt or skill on a recurring interval.",
+ input_hint: Some("[interval] <prompt>"),
+ },
+ CatalogEntry {
+ name: "migrate-to-builds",
+ description: "Test that a Cloud Agent environment works with prebuilt builds.",
+ input_hint: None,
+ },
+ CatalogEntry {
+ name: "migrate-to-skills",
+ description: "Convert Cursor rules and slash commands to Agent Skills.",
+ input_hint: None,
+ },
+ CatalogEntry {
+ name: "review",
+ description: "Review code changes with Bugbot or Security Review.",
+ input_hint: None,
+ },
+ CatalogEntry {
+ name: "review-bugbot",
+ description: "Review code changes with the Bugbot subagent.",
+ input_hint: None,
+ },
+ CatalogEntry {
+ name: "review-security",
+ description: "Review code changes with the Security Review subagent.",
+ input_hint: None,
+ },
+ CatalogEntry {
+ name: "sdk",
+ description: "Guide integrations on the Cursor TypeScript or Python SDK.",
+ input_hint: None,
+ },
+ CatalogEntry {
+ name: "shell",
+ description: "Run the rest of the prompt as a literal shell command.",
+ input_hint: Some("<command>"),
+ },
+ CatalogEntry {
+ name: "split-to-prs",
+ description: "Split current work into small reviewable PRs.",
+ input_hint: None,
+ },
+ CatalogEntry {
+ name: "subscribe",
+ description: "Wait for GitHub, Origin, Slack, or Linear events instead of polling.",
+ input_hint: None,
+ },
+ CatalogEntry {
+ name: "walkthrough-artifacts",
+ description: "Create walkthrough screenshots and recordings of working changes.",
+ input_hint: None,
+ },
+];
+
+/// The slash commands this agent advertises on `session/new` and `session/load`.
+#[must_use]
+pub fn cursor_slash_commands() -> Vec<AvailableCommand> {
+ CATALOG.iter().map(catalog_command).collect()
+}
+
+fn catalog_command(entry: &CatalogEntry) -> AvailableCommand {
+ let command = AvailableCommand::new(entry.name, entry.description);
+ match entry.input_hint {
+ Some(hint) => command.input(AvailableCommandInput::Unstructured(
+ UnstructuredCommandInput::new(hint),
+ )),
+ None => command,
+ }
+}
diff --git a/crates/cursor_cloud_agents/src/domain/slash_commands/snapshots/cursor_cloud_agents__domain__slash_commands__test__advertised_commands_are_pinned_whole.snap b/crates/cursor_cloud_agents/src/domain/slash_commands/snapshots/cursor_cloud_agents__domain__slash_commands__test__advertised_commands_are_pinned_whole.snap
new file mode 100644
index 0000000000..dc7540d046
--- /dev/null
+++ b/crates/cursor_cloud_agents/src/domain/slash_commands/snapshots/cursor_cloud_agents__domain__slash_commands__test__advertised_commands_are_pinned_whole.snap
@@ -0,0 +1,95 @@
+---
+source: crates/cursor_cloud_agents/src/domain/slash_commands/test.rs
+expression: commands
+---
+[
+ {
+ "name": "autopilot",
+ "description": "Keep a PR merge-ready by triaging comments, resolving conflicts, and fixing CI."
+ },
+ {
+ "name": "canvas",
+ "description": "Create a durable standalone canvas artifact beside the chat."
+ },
+ {
+ "name": "create-hook",
+ "description": "Create Cursor hooks for agent lifecycle events."
+ },
+ {
+ "name": "create-rule",
+ "description": "Create Cursor rules for persistent AI guidance."
+ },
+ {
+ "name": "create-skill",
+ "description": "Create a Cursor Agent Skill (SKILL.md)."
+ },
+ {
+ "name": "create-subagent",
+ "description": "Create a custom subagent with a focused system prompt."
+ },
+ {
+ "name": "deploy-with-vercel",
+ "description": "Link this repository to Vercel and deploy it."
+ },
+ {
+ "name": "env-setup",
+ "description": "Explain, inspect, or improve a Cloud Agent environment."
+ },
+ {
+ "name": "goal",
+ "description": "Set a goal that Cursor will pursue to completion.",
+ "input": {
+ "hint": "<objective>"
+ }
+ },
+ {
+ "name": "loop",
+ "description": "Run a prompt or skill on a recurring interval.",
+ "input": {
+ "hint": "[interval] <prompt>"
+ }
+ },
+ {
+ "name": "migrate-to-builds",
+ "description": "Test that a Cloud Agent environment works with prebuilt builds."
+ },
+ {
+ "name": "migrate-to-skills",
+ "description": "Convert Cursor rules and slash commands to Agent Skills."
+ },
+ {
+ "name": "review",
+ "description": "Review code changes with Bugbot or Security Review."
+ },
+ {
+ "name": "review-bugbot",
+ "description": "Review code changes with the Bugbot subagent."
+ },
+ {
+ "name": "review-security",
+ "description": "Review code changes with the Security Review subagent."
+ },
+ {
+ "name": "sdk",
+ "description": "Guide integrations on the Cursor TypeScript or Python SDK."
+ },
+ {
+ "name": "shell",
+ "description": "Run the rest of the prompt as a literal shell command.",
+ "input": {
+ "hint": "<command>"
+ }
+ },
+ {
+ "name": "split-to-prs",
+ "description": "Split current work into small reviewable PRs."
+ },
+ {
+ "name": "subscribe",
+ "description": "Wait for GitHub, Origin, Slack, or Linear events instead of polling."
+ },
+ {
+ "name": "walkthrough-artifacts",
+ "description": "Create walkthrough screenshots and recordings of working changes."
+ }
+]
diff --git a/crates/cursor_cloud_agents/src/domain/slash_commands/test.rs b/crates/cursor_cloud_agents/src/domain/slash_commands/test.rs
new file mode 100644
index 0000000000..5526ff8301
--- /dev/null
+++ b/crates/cursor_cloud_agents/src/domain/slash_commands/test.rs
@@ -0,0 +1,62 @@
+use super::*;
+
+#[test]
+fn catalog_names_are_unique_and_stable() {
+ let names: Vec<&str> = CATALOG.iter().map(|entry| entry.name).collect();
+ let mut sorted = names.clone();
+ sorted.sort_unstable();
+ sorted.dedup();
+ assert_eq!(
+ names, sorted,
+ "catalog must stay unique and alphabetically ordered"
+ );
+}
+
+#[test]
+fn catalog_includes_cloud_skills_and_omits_local_only_ones() {
+ let names: Vec<&str> = CATALOG.iter().map(|entry| entry.name).collect();
+ for required in ["goal", "loop", "review", "env-setup", "subscribe", "shell"] {
+ assert!(
+ names.contains(&required),
+ "{required} is a cloud-usable Cursor skill and must be advertised"
+ );
+ }
+ for excluded in [
+ "rename-chat",
+ "statusline",
+ "clone",
+ "update-cursor-settings",
+ ] {
+ assert!(
+ !names.contains(&excluded),
+ "{excluded} is local/IDE-only and must not be advertised"
+ );
+ }
+}
+
+#[test]
+fn advertised_commands_carry_hints_only_when_the_skill_parses_leftover_text() {
+ let commands = cursor_slash_commands();
+ let hint = |name: &str| {
+ commands
+ .iter()
+ .find(|command| command.name == name)
+ .and_then(|command| match &command.input {
+ Some(AvailableCommandInput::Unstructured(input)) => Some(input.hint.as_str()),
+ _ => None,
+ })
+ };
+ assert_eq!(hint("goal"), Some("<objective>"));
+ assert_eq!(hint("loop"), Some("[interval] <prompt>"));
+ assert_eq!(hint("shell"), Some("<command>"));
+ assert_eq!(hint("review"), None);
+}
+
+#[test]
+fn advertised_commands_are_pinned_whole() {
+ let commands: Vec<serde_json::Value> = cursor_slash_commands()
+ .into_iter()
+ .map(|command| serde_json::to_value(command).expect("commands serialize"))
+ .collect();
+ insta::assert_json_snapshot!(commands);
+}
diff --git a/crates/cursor_cloud_agents/src/inbound/acp.rs b/crates/cursor_cloud_agents/src/inbound/acp.rs
index 1044791c39..52acc7cd54 100644
--- a/crates/cursor_cloud_agents/src/inbound/acp.rs
+++ b/crates/cursor_cloud_agents/src/inbound/acp.rs
@@ -34,15 +34,16 @@ use crate::domain::ports::{
ArtifactStore, CursorAgents, CursorArtifacts, RepositoryChooser, RunStream, SessionNotifier,
};
use crate::domain::service::CursorSessionService;
+use crate::domain::slash_commands::cursor_slash_commands;
use agent_client_protocol::schema::ProtocolVersion;
use agent_client_protocol::schema::v1::{
- AgentCapabilities, AuthenticateRequest, AuthenticateResponse, CancelNotification,
- CloseSessionRequest, CloseSessionResponse, ContentBlock, ContentChunk, Error as AcpError,
- HttpHeader, Implementation, InitializeRequest, InitializeResponse, LoadSessionRequest,
- LoadSessionResponse, McpCapabilities, McpServer as AcpMcpServer, Meta, NewSessionRequest,
- NewSessionResponse, PromptCapabilities, PromptRequest, PromptResponse, SessionConfigOption,
- SessionId, SessionNotification, SessionUpdate, SetSessionConfigOptionRequest,
- SetSessionConfigOptionResponse, TextContent,
+ AgentCapabilities, AuthenticateRequest, AuthenticateResponse, AvailableCommandsUpdate,
+ CancelNotification, CloseSessionRequest, CloseSessionResponse, ContentBlock, ContentChunk,
+ Error as AcpError, HttpHeader, Implementation, InitializeRequest, InitializeResponse,
+ LoadSessionRequest, LoadSessionResponse, McpCapabilities, McpServer as AcpMcpServer, Meta,
+ NewSessionRequest, NewSessionResponse, PromptCapabilities, PromptRequest, PromptResponse,
+ SessionConfigOption, SessionId, SessionNotification, SessionUpdate,
+ SetSessionConfigOptionRequest, SetSessionConfigOptionResponse, TextContent,
};
use agent_client_protocol::{
Agent, ByteStreams, Client, ConnectTo, ConnectionTo, on_receive_notification,
@@ -395,7 +396,13 @@ where
let mcp_servers = forwardable_mcp_servers(request.mcp_servers);
let session = service.new_session(&request.cwd, mcp_servers);
let options = session_config_options(&service, &session).await;
- responder.respond(NewSessionResponse::new(session).config_options(options))
+ let response = responder
+ .respond(NewSessionResponse::new(session.clone()).config_options(options));
+ // After the session exists, same as Cursor's own ACP agent:
+ // commands arrive on `session/update`, not on the new-session
+ // result. A failure here costs the `/` menu, not the session.
+ advertise_slash_commands(&notifier, &session).await;
+ response
}
},
on_receive_request!(),
@@ -454,6 +461,7 @@ where
responder.respond(LoadSessionResponse::new().config_options(options));
if response.is_ok() {
guard.complete();
+ advertise_slash_commands(&notifier, &session).await;
}
response
}
@@ -591,6 +599,27 @@ where
cursor_model_config_options(&models, current)
}
+/// Advertise the curated Cursor slash-command catalog as an
+/// `available_commands_update`.
+///
+/// There is no `GET /v1/skills` to fetch — see [`cursor_slash_commands`]. The
+/// fold stores whatever this notification carries, and the agents-block
+/// composer only opens `/` when that list is non-empty. Sending nothing is
+/// why Cursor sessions used to treat `/` as plain text.
+async fn advertise_slash_commands(notifier: &AcpNotifier, session: &SessionId) {
+ if let Err(error) = notifier
+ .notify(
+ session,
+ SessionUpdate::AvailableCommandsUpdate(AvailableCommandsUpdate::new(
+ cursor_slash_commands(),
+ )),
+ )
+ .await
+ {
+ tracing::warn!(error = %error, "could not advertise cursor slash commands");
+ }
+}
+
/// Concatenate a prompt's content blocks into the single string Cursor takes.
fn prompt_text(blocks: &[ContentBlock]) -> String {
blocks
diff --git a/crates/cursor_cloud_agents/src/inbound/acp/test.rs b/crates/cursor_cloud_agents/src/inbound/acp/test.rs
index dc14cef598..61b4f046c7 100644
--- a/crates/cursor_cloud_agents/src/inbound/acp/test.rs
+++ b/crates/cursor_cloud_agents/src/inbound/acp/test.rs
@@ -72,7 +72,7 @@ impl TestClient {
}));
loop {
let frame = self.next_frame().await;
- if method != "session/load" || frame.get("id") == Some(&serde_json::json!(id)) {
+ if frame.get("id") == Some(&serde_json::json!(id)) {
return frame;
}
assert!(
@@ -80,10 +80,25 @@ impl TestClient {
frame["method"].as_str(),
Some("session/update" | "_session/turn_complete")
),
- "load emits only replay facts before its response"
+ "expected the response or a session update, got {frame}"
);
}
}
+
+ /// The `available_commands_update` that follows `session/new` / `session/load`.
+ async fn expect_available_commands(&mut self, session: &str) -> Vec<serde_json::Value> {
+ let frame = self.next_frame().await;
+ assert_eq!(frame["method"], "session/update", "{frame}");
+ assert_eq!(frame["params"]["sessionId"], session);
+ assert_eq!(
+ frame["params"]["update"]["sessionUpdate"], "available_commands_update",
+ "{frame}"
+ );
+ frame["params"]["update"]["availableCommands"]
+ .as_array()
+ .unwrap_or_else(|| panic!("availableCommands is an array in {frame}"))
+ .clone()
+ }
}
/// A served connection over a [`Channel`] pair, plus the pieces the tests
@@ -411,6 +426,12 @@ async fn serve_runs_a_whole_conversation_over_an_in_process_pipe() {
.as_str()
.expect("a session id")
.to_owned();
+ let commands = next_client_frame(&mut client_frames).await;
+ assert_eq!(commands["method"], "session/update");
+ assert_eq!(
+ commands["params"]["update"]["sessionUpdate"],
+ "available_commands_update"
+ );
send_client_frame(
&mut client_writer,
@@ -770,6 +791,72 @@ async fn session_new_advertises_the_models_as_a_config_option() {
assert_eq!(values, vec!["composer-2.5", "gpt-5.5"]);
}
+/// `session/new` advertises Cursor's cloud slash commands after the session
+/// exists, which is how the agents-block composer learns to open `/`.
+#[tokio::test]
+async fn session_new_advertises_cursor_slash_commands() {
+ let (_service, _cursor, mut client) = harness();
+
+ let opened = client
+ .call(
+ 1,
+ "session/new",
+ serde_json::json!({"cwd": "/workspace", "mcpServers": []}),
+ )
+ .await;
+ let session = expect_result(&opened)["sessionId"]
+ .as_str()
+ .expect("a session id")
+ .to_owned();
+ let commands = client.expect_available_commands(&session).await;
+ let names: Vec<String> = commands
+ .iter()
+ .map(|command| command["name"].as_str().expect("a command name").to_owned())
+ .collect();
+ let expected: Vec<String> = crate::domain::slash_commands::cursor_slash_commands()
+ .into_iter()
+ .map(|command| command.name)
+ .collect();
+ assert_eq!(
+ names, expected,
+ "session/new must advertise the curated catalog, in catalog order"
+ );
+}
+
+/// `session/load` re-advertises the same catalog, so a resumed session's `/`
+/// menu is not empty until the next `session/new`.
+#[tokio::test]
+async fn session_load_advertises_cursor_slash_commands() {
+ let cursor = FakeCursor::new();
+ crate::testing::script_legacy_history(&cursor);
+ let (_service, mut client) = serve_over_channel(cursor, |service| {
+ service.restore_session(
+ SessionId::new("cursor-acp-3"),
+ Some(crate::domain::model::CursorAgentId::new("bc-restored")),
+ None,
+ None,
+ );
+ });
+
+ let loaded = client
+ .call(
+ 1,
+ "session/load",
+ serde_json::json!({"sessionId": "cursor-acp-3", "cwd": "/workspace", "mcpServers": []}),
+ )
+ .await;
+ expect_result(&loaded);
+ let commands = client.expect_available_commands("cursor-acp-3").await;
+ let names: Vec<&str> = commands
+ .iter()
+ .map(|command| command["name"].as_str().expect("a command name"))
+ .collect();
+ assert!(
+ names.contains(&"goal"),
+ "a resumed session must still advertise commands, got {names:?}"
+ );
+}
+
/// With two models of one family in the listing, the select goes out as ACP
/// groups headed by family — `Claude Opus` once, its versions under it — in
/// listing order, and the flat fixture above stays flat: singletons gain
@@ -1266,6 +1353,9 @@ async fn load_queues_all_native_history_before_its_response_and_repeats_without_
frame["method"].as_str(),
Some("session/update" | "_session/turn_complete")
));
+ if frame["params"]["update"]["sessionUpdate"] == "available_commands_update" {
+ continue;
+ }
replay.push(
frame["params"]
.get("update")
diff --git a/docs/AGENT_GUIDE/ai-chat.md b/docs/AGENT_GUIDE/ai-chat.md
index d4c4978b67..acb46d3dcb 100644
--- a/docs/AGENT_GUIDE/ai-chat.md
+++ b/docs/AGENT_GUIDE/ai-chat.md
@@ -355,7 +355,9 @@ transcript at `/app/agent/<uuid>` whose replies also stream back into the thread
An agent session is `/app/agent/<uuid>`. The composer placeholder is
**`Message the agent, @mention anything`**. Creating one (`c` then `a`, or
`Create` → `Agent`) leaves that composer focused — on mobile that is the same
-Create-menu `triggerFocusInput` as chat, so the keyboard opens. Type `@` to insert the same mention chips
+Create-menu `triggerFocusInput` as chat, so the keyboard opens. Type `/` to
+open slash commands the connected agent advertised (Claude, OpenCode, and
+Cursor). `/` stays ordinary text until that list arrives. Type `@` to insert the same mention chips
used in chat and channels; they serialize as mention-chip tags in the prompt
the agent sees (`<m-document-mention>` for docs/channels/chats/tasks/emails/calendar
events/skills, `<m-date-mention>` for a day or time, `<m-agent-session-mention>`