rush-ai 0.6.0 → 0.7.0

package/dist/plugin-assets/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: rush-task
-description: "在 Claude Code 中创建 Rush Agent 任务并跟踪执行过程。当用户想让 Rush Agent（如 UI 生成、代码分析、文档撰写等）执行任务时使用此 Skill。"
-version: 0.2.0
+description: "Create and track tasks on the Rush platform from an IDE (Cursor, Claude Code, etc). Use this when the user wants a Rush agent to build / generate / analyze something — hand off the context you already have, then watch it run."
+version: 0.3.0
 author: kanyun
 tags:
   - rush
@@ -10,80 +10,87 @@ tags:
 argument-hint: <prompt>
 ---
 
-# Rush Task — Agent 任务执行
+# Rush Task — hand off work to a Rush agent
 
-你可以通过 Rush MCP 工具来创建和管理 Agent 任务。
+Use this skill when the user is talking to you and the next step belongs on the Rush platform. You already have full context from the conversation; don't make them restate it.
 
-## 前置条件
+## Primary path: `rush-ai` CLI
 
-在执行任何操作前，确认以下条件：
-- MCP server "rush" 已连接（tools 列表中有 `rush_*` 开头的工具）
-- 如果 MCP 工具不可用，提示用户运行 `rush-ai plugin doctor` 诊断问题
+The CLI is the primary interface — it works in any shell, needs no per-IDE setup, and is always in sync with the platform.
 
-## 使用流程
+### Prerequisites
 
-### Step 1: 列出可用 Agent
+- `rush-ai` is on PATH, or you can run it via `npx rush-ai`. If neither is true, ask the user to install with `npm i -g rush-ai` (or just use `npx`).
 
-调用 `rush_agent_list` 获取当前可用的 Agent 列表。
+### Canonical flow
 
-**失败处理：**
-- 如果返回鉴权错误（`Not authenticated`），提示用户运行 `rush-ai auth login`
-- 如果连接失败或超时，提示用户运行 `rush-ai plugin doctor` 检查配置
+```bash
+# 1. Confirm auth — this MUST be the first step.
+npx rush-ai auth status --json
+# If the response says not authenticated: STOP. Print to the user:
+#   "Rush 还没登录。请在终端里跑 `npx rush-ai auth login`（会打开浏览器），登录成功后告诉我一声。"
+# Do NOT run auth login yourself — it needs a browser / CAS.
 
-### Step 2: 选择 Agent
+# 2. (Optional) Browse the agent shelf. Start narrow, widen only if needed.
+npx rush-ai agent list --default --json          # just the built-in defaults
+npx rush-ai agent list --search "人力" --json    # fuzzy-filter by name / desc
+npx rush-ai agent list --all --json              # full catalog (can be long)
 
-- 如果只有一个 Agent，直接使用
-- 如果有多个 Agent，向用户展示列表（名称 + 能力描述），让用户选择
-- 如果没有可用 Agent，告知用户当前无可用 Agent，建议联系管理员配置
+# 3. Create the task. Use --json whenever you need to parse the result.
+npx rush-ai task create -a <agent> -p "<prompt synthesized from context>" --json
 
-### Step 3: 执行任务（策略分流）
+# 4. Poll status until it reaches a terminal state
+#    (completed / failed / cancelled). Poll every ~15–30s.
+npx rush-ai task status <id> --json
 
-根据任务复杂度选择执行策略：
+# 5. Iterate on the same task — don't create a new one for tweaks.
+npx rush-ai task send <id> -p "<follow-up>" --json
 
-**短任务（简单查询、快速操作）：**
-使用 `rush_task_run` 同步执行，直接返回结果。
-- 适用场景：用户明确说"快速"、"简单查询"、"查看状态"
+# 6. If the user wants live output, stream instead of polling.
+npx rush-ai task watch <id>
+```
 
-**长任务（复杂生成、多步骤处理）：**
-1. 调用 `rush_task_create` 创建异步任务
-2. 调用 `rush_task_watch` 跟踪进度（默认超时 5 分钟）
-3. 向用户实时展示进度信息
-- 适用场景：用户要求"生成"、"创建"、"分析"、"重构"
+### Which agent to pass to `-a`?
 
-**判断策略：**
-- 用户明确说"快速"、"简单查询" → 短任务（`rush_task_run`）
-- 用户要求"生成"、"创建"、"分析"等复杂操作 → 长任务（`rush_task_create`）
-- 不确定时默认使用异步模式（`rush_task_create`）
+| Situation | Agent |
+|---|---|
+| The user wants a live website / landing page / marketing page — anything that ends with a shareable preview URL | `web-builder` (returns `previewUrl` + `gitRepoUrl` on completion) |
+| General-purpose task (chat, analysis, generation) | `rush` (the platform default) |
+| The user explicitly named a specialist agent | that agent's name verbatim (confirm with `agent list --search`) |
 
-### Step 4: 获取结果
+When in doubt, run `agent list --all --json` and pick by name / description. Never invent an agent name.
 
-- 调用 `rush_task_result` 获取最终结果
-- 如果任务失败，展示错误信息并建议：
-  - 修改 prompt 重试
-  - 检查 Agent 是否支持该类型任务
-- 如果有输出文件，调用 `rush_task_files` 列出并展示：
-  - 代码文件（code）：展示文件路径和内容摘要
-  - 图片文件（image）：展示 URL 供用户查看
-  - 文档文件（document）：展示内容
+### What to give the user
 
-### Step 5: 后续操作
+- One-liner confirmation right after `task create`: task id + "running on Rush, I'll watch it".
+- When `task status` returns `completed`:
+  - For `web-builder`: present `previewUrl` (primary) and `gitRepoUrl`.
+  - For other agents: present `result`.
+- If `status == failed`: surface `error` verbatim, ask whether to retry via `task send` or abort. Do not silently retry.
 
-- 用户可以基于结果继续对话（"修改一下..."、"重新生成..."）
-- 继续操作时创建新任务，在 prompt 中引用之前的 task_id 提供上下文
-- 用户可以随时用 `rush_task_cancel` 取消运行中的任务
-- 用 `rush_task_list` 查看历史任务
+### Anti-patterns (don't do these)
 
-## 可用 MCP 工具参考
+- ❌ Re-prompting the user for requirements they already stated in-thread.
+- ❌ Creating a new task for every tweak — always prefer `task send <id>`.
+- ❌ Running `auth login` yourself (it needs a browser).
+- ❌ Ignoring `--json` when you need to parse the result — the table view is for humans.
 
-| 工具 | 用途 |
-|------|------|
-| `rush_agent_list` | 列出可用 Agent |
-| `rush_agent_info` | 获取 Agent 详细信息 |
-| `rush_task_run` | 同步执行任务（阻塞直到完成） |
-| `rush_task_create` | 创建异步任务 |
-| `rush_task_status` | 查询任务状态 |
-| `rush_task_result` | 获取任务结果 |
-| `rush_task_watch` | 实时跟踪任务进度（SSE） |
-| `rush_task_list` | 列出历史任务 |
-| `rush_task_files` | 列出任务输出文件 |
-| `rush_task_cancel` | 取消运行中的任务 |
+For the complete playbook, run `npx rush-ai skill hand-off`. For sub-agent / workflow composition, run `npx rush-ai skill agent-shelf`.
+
+## Optional path: MCP tools
+
+If the Rush MCP server is installed and the IDE exposes its tools (`rush_task_create`, `rush_task_status`, ...), you can use them instead of shelling out. The MCP path is functionally equivalent to the CLI path; use whichever is available. Mapping:
+
+| CLI command | MCP tool |
+|-------------|----------|
+| `rush-ai agent list` | `rush_agent_list` |
+| `rush-ai agent info <name>` | `rush_agent_info` |
+| `rush-ai task create` | `rush_task_create` (async) / `rush_task_run` (short/sync) |
+| `rush-ai task status <id>` | `rush_task_status` |
+| `rush-ai task result <id>` | `rush_task_result` |
+| `rush-ai task watch <id>` | `rush_task_watch` |
+| `rush-ai task list` | `rush_task_list` |
+| `rush-ai task files <id>` | `rush_task_files` |
+| `rush-ai task cancel <id>` | `rush_task_cancel` |
+
+If MCP tools aren't present — the common case — **just use the CLI**. Don't wait on MCP; don't try to configure it mid-conversation.

package/dist/skills/README.md

@@ -0,0 +1,48 @@
+# Rush-ai skills for AI agents
+
+`rush-ai` is a CLI for the Rush platform. If you are an AI agent (Cursor, Claude Code, a local sub-agent) reading this, these guides tell you when and how to invoke `rush-ai` on behalf of the user.
+
+## When to use rush-ai
+
+Pick the guide that matches the situation:
+
+- **You are in the middle of a conversation with the user (inside an IDE) and part of the work belongs on Rush.**
+  → Read [`hand-off.md`](./hand-off.md). Typical trigger: "build me a landing page", "turn this sketch into a site", "generate the docs site".
+
+- **You are composing a workflow and need a specialist agent as one of the steps.**
+  → Read [`agent-shelf.md`](./agent-shelf.md). Typical trigger: a workflow node that needs domain expertise you don't have (HR analytics, observability Q&A, physics reasoning, etc).
+
+Still unsure? Run `npx rush-ai agent list` first — seeing the available agents usually makes the decision obvious.
+
+## Cheat sheet
+
+```bash
+# Discover
+npx rush-ai agent list --default               # just the built-in defaults (web-builder, rush, skill-publisher, ...)
+npx rush-ai agent list --search "人力"         # fuzzy-filter the full shelf
+npx rush-ai agent list --all                   # everything (can be long)
+npx rush-ai agent info <agent>                 # inspect one agent's skills / MCP servers
+
+# Hand off
+npx rush-ai task create -a <agent> -p "<prompt>"   # create a task
+npx rush-ai task status <task-id>                  # check status (includes preview / git URLs when ready)
+npx rush-ai task send <task-id> -p "<follow-up>"   # iterate on a running task
+npx rush-ai task watch <task-id>                   # stream execution (SSE)
+
+# Defaults
+-a rush           # general-purpose agent; this is the CLI default, so `-a` can be omitted when you want `rush`
+-a web-builder    # site/landing-page builder; returns previewUrl + gitRepoUrl
+-a <other>        # any other agent name from `agent list` — confirm it exists first
+```
+
+`--json` on any command gives machine-readable output; use it when you need to parse the result.
+
+## Prerequisites the agent should enforce
+
+Before creating a task, make sure the user is authenticated:
+
+```bash
+npx rush-ai auth status
+```
+
+If not authenticated, tell the user to run `npx rush-ai auth login` in their terminal (the command is interactive and requires a browser — you cannot complete it on their behalf).

package/dist/skills/agent-shelf.md

@@ -0,0 +1,102 @@
+# Skill: Call a Rush agent as your sub-agent
+
+Use this skill when you are composing a workflow — your own, or one the user described — and a step calls for domain expertise you don't have. Rush hosts a shelf of specialist agents. You can invoke any of them with one `rush-ai task create` call and feed the result back into your workflow.
+
+## When this skill applies
+
+Triggers:
+
+- The user's instructions name a specialist by role ("use the HR analytics expert", "ask the physics reasoning agent", "let the observability agent check it").
+- You're drafting a multi-step plan and one node is outside your competence (e.g. "analyze RUM data", "write a physics problem set", "summarize an HR report").
+- The user asks "what can Rush do that I can't?" — that's a prompt to show the shelf.
+
+Do NOT use this skill when:
+
+- The task fits the default general-purpose agent (`rush`) — that's a hand-off, not a sub-agent call. See `hand-off.md`.
+- The task needs a live web artifact — use `web-builder` via `hand-off.md`.
+
+## Playbook
+
+### 1. Discover — don't guess
+
+Always start by listing the shelf, unless the user already named a specific agent. Use the right scope for the question at hand:
+
+```bash
+# Just the built-in defaults — useful when you're looking for the general fallback
+npx rush-ai agent list --default --json
+
+# Fuzzy-filter when the user hinted at a domain
+npx rush-ai agent list --search "人力" --json
+
+# Full catalog — use sparingly, can be hundreds of entries
+npx rush-ai agent list --all --json
+```
+
+Pick the best match by name + description. If multiple are plausible, inspect one:
+
+```bash
+npx rush-ai agent info <agent-name> --json
+```
+
+If nothing fits, tell the user what's available and ask how to proceed — don't force-fit a wrong agent.
+
+### 2. Call it as a node in your workflow
+
+Treat the agent call like a pure function: input prompt, output task result. Compose your own prompt with the context the agent needs (not the whole conversation — just the inputs for this step).
+
+```bash
+npx rush-ai task create -a <agent-name> \
+  -p "<focused prompt — inputs + expected output format>" \
+  --json
+```
+
+For a workflow node you need synchronously, poll:
+
+```bash
+npx rush-ai task status <id> --json
+```
+
+When `status == completed`, the response has the output. For agents that produce structured results, request `--json` and parse it.
+
+### 3. Feed the result back into your workflow
+
+The sub-agent's output is just another piece of context for the next step of your plan. Incorporate it into the next action the way you would any tool result.
+
+If the output is unsatisfactory, either:
+
+- refine via `task send <id> -p "<clarification>"` (same sub-agent, same context), or
+- fall back to your plan B (try a different agent, or escalate to the user).
+
+## Example
+
+User: "帮我分析一下 Q1 的部门人效，然后根据结论写一段给 CEO 的周会汇报。"
+
+Your plan:
+
+1. Call a data-analysis sub-agent on Rush to do the number-crunching.
+2. Use the analysis output to draft the exec-summary locally.
+
+```bash
+# Step 1 — find the HR analytics specialist (--json returns { agents, pagination })
+npx rush-ai agent list --search "人力" --json | jq '.agents[] | {name, description}'
+# → matches "人力资源分析专家"
+
+# Step 2 — call it as a sub-agent node
+npx rush-ai task create -a 人力资源分析专家 \
+  -p "分析 Q1 各部门人效趋势，输出 3 条关键结论。" \
+  --json
+# → {"id": "t_abc", "status": "pending"}
+
+# Step 3 — wait for the node to finish
+npx rush-ai task status t_abc --json
+# → {"status": "completed", "result": "..."}
+
+# Step 4 — you take the result and draft the exec summary locally.
+```
+
+## Anti-patterns
+
+- ❌ Inventing an agent name. If `agent list` doesn't show it, it doesn't exist — tell the user.
+- ❌ Passing the entire original conversation as the sub-agent's prompt. Give it only the inputs it needs.
+- ❌ Using `web-builder` for non-website work. It's specialized for producing deployable sites.
+- ❌ Abandoning the workflow if the sub-agent call fails. Surface the error, offer a fallback.

package/dist/skills/hand-off.md

@@ -0,0 +1,163 @@
+# Skill: Hand off the task to Rush
+
+Use this skill when the user is talking to you inside an IDE (Cursor, Claude Code, or similar) and the next step belongs on the Rush platform. You already have full context from the conversation — `rush-ai` exists so you can relay that context to Rush's cloud agents without making the user summarize it again.
+
+## When this skill applies
+
+Triggers (not exhaustive — use judgement):
+
+- "Build me a landing page / product site / marketing page."
+- "Turn this spec / sketch / Figma link into a site."
+- "Spin up a demo site for X."
+- Any time the conversation points at producing a running web artifact the user will want to **share a link** for.
+
+Do NOT use this skill for:
+
+- Small local edits the user wants you to apply directly in the current repo.
+- Questions about Rush itself ("what is rush-ai", "how do I log in") — answer those from docs instead of creating a task.
+
+## Decision: which agent?
+
+| Situation | Agent to pass to `-a` |
+|---|---|
+| Build a website, landing page, marketing page, or anything that should render as a live preview URL | `web-builder` |
+| General-purpose conversation / analysis / generation the user would have asked a chat agent for | `rush` (the platform default) |
+| User named a specific specialist agent (e.g. "use the HR analytics agent") | that agent name verbatim |
+
+If you are unsure, start with `npx rush-ai agent list --default` — that shows just the built-in defaults (`web-builder`, `rush`, `skill-publisher`, ...), which is usually all you need for a hand-off. Widen with `--search <keyword>` or `--all` only when the user clearly asked for a specialist. When in doubt between `rush` and `web-builder`, ask the user — but if the output is going to be a URL, default to `web-builder`.
+
+## Playbook
+
+### 1. Verify auth (once per session)
+
+```bash
+npx rush-ai auth status --json
+```
+
+The response includes a boolean `authenticated` (or equivalent) plus an auth method. **Read it before you do anything else.** There are only two cases — no third case, no "maybe":
+
+- **Authenticated** → proceed to step 2.
+- **Not authenticated** → STOP. Print this exact message to the user and wait:
+
+  > Rush 还没登录。请在终端里跑 `npx rush-ai auth login`（会打开浏览器完成 CAS 登录），登录成功后告诉我一声。
+
+  Do NOT run `auth login` yourself — it opens a browser and waits for human interaction.
+  Do NOT invent workarounds (don't try API keys, don't edit `~/.rush/auth.json`).
+  Do NOT fall through to `task create` anyway — it will return 401 and confuse the user.
+
+When the user returns, re-run `auth status --json` to confirm before continuing.
+
+### 2. Create the task, carrying the context you already have
+
+Write the prompt from the conversation. Do **not** ask the user to restate requirements you already know. Include any constraints they have already mentioned (brand, style, pages, copy).
+
+```bash
+npx rush-ai task create \
+  -a web-builder \
+  -p "<prompt synthesized from the conversation>" \
+  --json
+```
+
+The JSON response contains `id`. Keep it; you'll need it for every follow-up.
+
+### 3. Report the handoff to the user
+
+Tell the user, in one line:
+
+- the task id
+- that it's running on Rush
+- how they can watch (either "I'll poll for you" or "open the Rush web UI")
+
+Don't dump the full JSON unless they ask.
+
+### 4. Poll status until ready
+
+```bash
+npx rush-ai task status <id> --json | jq -r '.status'
+```
+
+Terminal states: `completed`, `failed`, `cancelled`. Poll every ~15–30s; don't hammer it.
+
+**Pipe directly** — don't round-trip the JSON through a shell variable:
+
+```bash
+# good — JSON stays as raw bytes, no shell re-interpretation
+npx rush-ai task status <id> --json | jq -r '.status'
+
+# bad — zsh's builtin `echo` re-interprets \n as a real newline;
+#       jq then rejects the result with "control characters must be escaped".
+#       (bash's echo usually doesn't, but behavior is shell-dependent.)
+STATUS=$(npx rush-ai task status <id> --json)
+echo "$STATUS" | jq .     # ← breaks in zsh once the JSON contains \n
+
+# acceptable alternatives when you really need the variable:
+printf '%s' "$STATUS" | jq .   # portable — printf never re-interprets escapes
+jq . <<< "$STATUS"             # here-string — does not re-interpret backslash escapes
+```
+
+When `status == completed`, the response contains (for `web-builder`):
+
+- `previewUrl` — shareable live preview (e.g. `https://<id>-preview.rush.zhenguanyu.com/`)
+- `gitRepoUrl` — cloneable repo (e.g. `https://gitlab-ee.zhenguanyu.com/rush/online/<id>`)
+
+Present both to the user. The preview URL is the primary artifact they care about.
+
+### 5. Iterate via `task send`, not by creating new tasks
+
+If the user says "change the button color" / "add a testimonials section" / "make the hero bigger", **do not create a new task** — send a follow-up to the existing one:
+
+```bash
+npx rush-ai task send <id> -p "<the change they asked for>" --json
+```
+
+The preview URL stays the same; it will refresh after the send completes. Poll `task status <id>` again.
+
+Only create a fresh task if the user explicitly starts a new, unrelated project.
+
+### 6. Failure handling
+
+If `status == failed`, the response has an `error` field. Surface it to the user verbatim and ask whether to:
+
+1. retry with a revised prompt via `task send`,
+2. cancel and start over, or
+3. dig in themselves (give them the task id so they can look it up).
+
+Do not silently retry.
+
+## Example end-to-end
+
+User (in Cursor): "帮我做个公司官网首页，风格大气专业。"
+
+Your actions:
+
+```bash
+# 1. check auth (assume ok)
+npx rush-ai auth status --json
+
+# 2. create (prompt synthesized from the prior conversation — brand, tone, pages)
+npx rush-ai task create -a web-builder \
+  -p "做一个公司官网首页，包含导航、Hero、核心特性、客户评价和底部联系信息，风格大气专业。" \
+  --json
+# → {"id": "lodig8oknq0r", "status": "pending", ...}
+
+# 3. tell the user
+# "已经派到 Rush 的 web-builder，任务 id lodig8oknq0r，我帮你盯着。"
+
+# 4. poll
+npx rush-ai task status lodig8oknq0r --json
+# ...wait...
+# → {"status": "completed", "previewUrl": "https://lodig8oknq0r-preview.rush.zhenguanyu.com/", "gitRepoUrl": "..."}
+
+# 5. present
+# "跑完了：
+#    预览: https://lodig8oknq0r-preview.rush.zhenguanyu.com/
+#    代码: https://gitlab-ee.zhenguanyu.com/rush/online/lodig8oknq0r
+#  要改哪儿继续说，我走 task send 不新起任务。"
+```
+
+## Anti-patterns
+
+- ❌ Asking the user to re-describe requirements they already told you in-thread.
+- ❌ Creating a new task for every tweak — use `task send`.
+- ❌ Hiding the task id from the user (they may want to reopen the Rush UI later).
+- ❌ Running `task watch` when all you need is final status — it streams verbosely, use `task status` for quick polls.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rush-ai",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Rush CLI - Command-line interface for the Rush AI platform",
   "private": false,
   "type": "module",
@@ -15,7 +15,9 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
+    "AGENTS.md",
     "LICENSE"
   ],
   "publishConfig": {

package/skills/README.md

@@ -0,0 +1,48 @@
+# Rush-ai skills for AI agents
+
+`rush-ai` is a CLI for the Rush platform. If you are an AI agent (Cursor, Claude Code, a local sub-agent) reading this, these guides tell you when and how to invoke `rush-ai` on behalf of the user.
+
+## When to use rush-ai
+
+Pick the guide that matches the situation:
+
+- **You are in the middle of a conversation with the user (inside an IDE) and part of the work belongs on Rush.**
+  → Read [`hand-off.md`](./hand-off.md). Typical trigger: "build me a landing page", "turn this sketch into a site", "generate the docs site".
+
+- **You are composing a workflow and need a specialist agent as one of the steps.**
+  → Read [`agent-shelf.md`](./agent-shelf.md). Typical trigger: a workflow node that needs domain expertise you don't have (HR analytics, observability Q&A, physics reasoning, etc).
+
+Still unsure? Run `npx rush-ai agent list` first — seeing the available agents usually makes the decision obvious.
+
+## Cheat sheet
+
+```bash
+# Discover
+npx rush-ai agent list --default               # just the built-in defaults (web-builder, rush, skill-publisher, ...)
+npx rush-ai agent list --search "人力"         # fuzzy-filter the full shelf
+npx rush-ai agent list --all                   # everything (can be long)
+npx rush-ai agent info <agent>                 # inspect one agent's skills / MCP servers
+
+# Hand off
+npx rush-ai task create -a <agent> -p "<prompt>"   # create a task
+npx rush-ai task status <task-id>                  # check status (includes preview / git URLs when ready)
+npx rush-ai task send <task-id> -p "<follow-up>"   # iterate on a running task
+npx rush-ai task watch <task-id>                   # stream execution (SSE)
+
+# Defaults
+-a rush           # general-purpose agent; this is the CLI default, so `-a` can be omitted when you want `rush`
+-a web-builder    # site/landing-page builder; returns previewUrl + gitRepoUrl
+-a <other>        # any other agent name from `agent list` — confirm it exists first
+```
+
+`--json` on any command gives machine-readable output; use it when you need to parse the result.
+
+## Prerequisites the agent should enforce
+
+Before creating a task, make sure the user is authenticated:
+
+```bash
+npx rush-ai auth status
+```
+
+If not authenticated, tell the user to run `npx rush-ai auth login` in their terminal (the command is interactive and requires a browser — you cannot complete it on their behalf).

package/skills/agent-shelf.md

@@ -0,0 +1,102 @@
+# Skill: Call a Rush agent as your sub-agent
+
+Use this skill when you are composing a workflow — your own, or one the user described — and a step calls for domain expertise you don't have. Rush hosts a shelf of specialist agents. You can invoke any of them with one `rush-ai task create` call and feed the result back into your workflow.
+
+## When this skill applies
+
+Triggers:
+
+- The user's instructions name a specialist by role ("use the HR analytics expert", "ask the physics reasoning agent", "let the observability agent check it").
+- You're drafting a multi-step plan and one node is outside your competence (e.g. "analyze RUM data", "write a physics problem set", "summarize an HR report").
+- The user asks "what can Rush do that I can't?" — that's a prompt to show the shelf.
+
+Do NOT use this skill when:
+
+- The task fits the default general-purpose agent (`rush`) — that's a hand-off, not a sub-agent call. See `hand-off.md`.
+- The task needs a live web artifact — use `web-builder` via `hand-off.md`.
+
+## Playbook
+
+### 1. Discover — don't guess
+
+Always start by listing the shelf, unless the user already named a specific agent. Use the right scope for the question at hand:
+
+```bash
+# Just the built-in defaults — useful when you're looking for the general fallback
+npx rush-ai agent list --default --json
+
+# Fuzzy-filter when the user hinted at a domain
+npx rush-ai agent list --search "人力" --json
+
+# Full catalog — use sparingly, can be hundreds of entries
+npx rush-ai agent list --all --json
+```
+
+Pick the best match by name + description. If multiple are plausible, inspect one:
+
+```bash
+npx rush-ai agent info <agent-name> --json
+```
+
+If nothing fits, tell the user what's available and ask how to proceed — don't force-fit a wrong agent.
+
+### 2. Call it as a node in your workflow
+
+Treat the agent call like a pure function: input prompt, output task result. Compose your own prompt with the context the agent needs (not the whole conversation — just the inputs for this step).
+
+```bash
+npx rush-ai task create -a <agent-name> \
+  -p "<focused prompt — inputs + expected output format>" \
+  --json
+```
+
+For a workflow node you need synchronously, poll:
+
+```bash
+npx rush-ai task status <id> --json
+```
+
+When `status == completed`, the response has the output. For agents that produce structured results, request `--json` and parse it.
+
+### 3. Feed the result back into your workflow
+
+The sub-agent's output is just another piece of context for the next step of your plan. Incorporate it into the next action the way you would any tool result.
+
+If the output is unsatisfactory, either:
+
+- refine via `task send <id> -p "<clarification>"` (same sub-agent, same context), or
+- fall back to your plan B (try a different agent, or escalate to the user).
+
+## Example
+
+User: "帮我分析一下 Q1 的部门人效，然后根据结论写一段给 CEO 的周会汇报。"
+
+Your plan:
+
+1. Call a data-analysis sub-agent on Rush to do the number-crunching.
+2. Use the analysis output to draft the exec-summary locally.
+
+```bash
+# Step 1 — find the HR analytics specialist (--json returns { agents, pagination })
+npx rush-ai agent list --search "人力" --json | jq '.agents[] | {name, description}'
+# → matches "人力资源分析专家"
+
+# Step 2 — call it as a sub-agent node
+npx rush-ai task create -a 人力资源分析专家 \
+  -p "分析 Q1 各部门人效趋势，输出 3 条关键结论。" \
+  --json
+# → {"id": "t_abc", "status": "pending"}
+
+# Step 3 — wait for the node to finish
+npx rush-ai task status t_abc --json
+# → {"status": "completed", "result": "..."}
+
+# Step 4 — you take the result and draft the exec summary locally.
+```
+
+## Anti-patterns
+
+- ❌ Inventing an agent name. If `agent list` doesn't show it, it doesn't exist — tell the user.
+- ❌ Passing the entire original conversation as the sub-agent's prompt. Give it only the inputs it needs.
+- ❌ Using `web-builder` for non-website work. It's specialized for producing deployable sites.
+- ❌ Abandoning the workflow if the sub-agent call fails. Surface the error, offer a fallback.