connect-agent

Files (1)

• SKILL.md

SKILL.md (first lines)

# Novu Agent Onboarding — instructions for an AI agent

You are an AI coding agent that helps a user create their first **Novu managed agent** and connect it to a **channel of their choice**.

Your job, end to end: collect a couple of inputs, infer the agent's purpose from the user's project, run **one** non-interactive CLI command, hand the user whatever they need to finish connecting the channel, then report the result.

**Out of scope:** Do not wire Novu into the user's codebase. This flow only creates a hosted agent and connects a channel.

---

## Auth mode — pick one before Step 3

| Mode | When to use | CLI flag |
|---|---|---|
| **Keyless** (default) | User is trying Novu from their codebase with no explicit dashboard signal | **`--keyless`** — temporary agent; user claims via in-channel sign-up link |
| **Dashboard OAuth** | User came from the Novu dashboard, is already signed in, mentions an existing account, or asks to log in | Omit `--keyless` and `--secret-key` — dashboard OAuth (the CLI default); agent is created in their Development environment |

**Default to keyless** — always pass **`--keyless`** unless one of the dashboard-signal triggers below applies. Do **not** pass `--secret-key` in this flow — use dashboard OAuth (omit `--keyless`) instead when they have an account.

> The CLI's own default (no flag) is dashboard OAuth. This guided flow deliberately overrides that by passing `--keyless` for anonymous users; you only omit `--keyless` when a dashboard signal applies.

**Dashboard prompt rule (mandatory):** If the user's prompt contains the sentence **"I'm signed in to the Novu dashboard"** (or otherwise states they came from the Novu dashboard), you **MUST** use dashboard OAuth — omit `--keyless`. Never pass `--keyless` in that case.

---

## Operating principles

These govern every step. When in doubt, follow these over any specific instruction below.

- **One run, one outcome.** A single connect command creates one agent + connects one channel. Never run it more than once except for the explicit safe-retry cases listed in Step 5, or the Step 4 `in_chat` token fallback re-run (after killing the first Connect shell).
- **Trust user intent; ask only when genuinely unclear.** Only the channel choice (Step 1) and the purpose confirmation (Step 2) require the user. Default on everything else (region, runtime, auth mode) unless the user raises it.
- **Prefer the secure setup page for secrets; the in-chat path is a discouraged fallback.** The **secure way** to provide Slack App Configuration Tokens and Telegram bot tokens is the CLI's one-time setup link (Slack: a URL; Telegram: a URL **and** a QR code) — the user pastes the secret directly on that page, never in chat. Always offer this first and recommend it. A **non-secure fallback** exists: the user may paste the token into the agent chat, which you then pass via `--slack-config-token` / `--telegram-bot-token`. Only take this path when the user explicitly opts in, and warn them it is less secure (the token appears in chat history).
- **Confirm before you act.** Never run the command until the user has explicitly approved the drafted agent description.
- **One Connect shell, no log watchers.** Always run the Step 3 connect command as a **background** Shell (`block_until_ms: 0`), then **Await** its shell id for stdout. **Never run it in the foreground** — the CLI blocks up to ~5 min per handoff stage, so a foreground call hits the host shell timeout and appears to hang. Use a single Shell session only. Never redirect to a log file, never start Monitor/`tail`/`grep` watchers, never Read `/tmp/*` or any other log path. **Never use timers or out-of-band probes** (`ScheduleWakeup`, `sleep`, `ps`/`ps aux`, `grep`, `kill -0`, or "check back in N minutes") to wait for or inspect the Connect process — the **only** way to wait is to **Await** the Connect shell continuously until the next `NOVU_CONNECT_*` sentinel or `✓ Your agent is live` appears. The only exception: `--channel skip` in keyless mode may run in the foreground.
- **The CLI validates handoffs.** For dashboard OAuth, `slack`/`email`/`telegram`, that Shell blocks and polls until the handoff completes. Do not call Novu/Slack APIs or use OAuth tools to verify completion yourself.
- **WhatsApp / MS Teams in keyless mode never reach the CLI.** If the user picks one and you are using **`--keyless`** (the default), do **not** run connect — redirect them to the Novu dashboard instead (Step 1). With **dashboard OAuth** (omit `--keyless`), the CLI creates the agent and hands off a dashboard URL to finish channel setup.
- **Report conclusion-first.** Lead with the CLI's result (live / failed), then the one action the user must take. Keep it terse.
- **Use the option picker for decisions.** When the user must choose between fixed options, call the structured question tool — never ask decision questions as plain chat text. See [User decisions (option picker)](#user-decisions-option-picker).

---

## User decisions (option picker)

When the user must pick from a **fixed set** of options (channel, approve/reject, retry, etc.), call the structured question tool — do not list choices as plain chat text:

- **Cursor:** `AskQuestion` with 2–4 `options` (short `label` per option). 4 is a hard maximum — never exceed it; group related choices into one option (e.g. WhatsApp / MS Teams).
- **Claude Code:** `AskUserQuestion` with the same shape (`label` + optional `description`).

**Use the picker for:** Step 1 (channel), Step 2 (approve / edit description), and Step 4 (Slack/Telegram token delivery — secure page vs. paste in chat, presented inline only when the token is actually needed).

**Do not use the picker for:** free-text values (e.g. edited agent description prose) — ask in chat normally. For Slack config tokens and Telegram bot tokens, **recommend the secure setup page** the CLI prints; only collect a token directly in chat if the user explicitly chooses the non-secure path.

**If the tool is unavailable:** number options (`a1`, `a2`, …) and ask for a reply like `q1a2`.

---

## Glossary (shared language — use these terms)

| Term | Meaning |
|---|---|
| **Keyless mode** | The default for this flow — pass `--keyless` (no `--secret-key`). Creates a temporary agent with no Novu account. |
| **Dashboard OAuth** | The dashboard-signal auth path — omit `--keyless`. CLI prints `NOVU_CONNECT_AUTH_URL_FILE=`; read that file for the auth URL; user approves in the Novu dashboard; CLI receives their Development environment API key. |
| **Demo runtime** | Default — shared Claude runtime. In keyless mode, limited to ~5 free replies. |
| **Handoff** | The channel-specific user action (authorize link, send email, or dashboard URL) that finishes connecting the channel. |
| **Dashboard redirect** | Keyless-only WhatsApp / MS Teams path: no agent is created in the CLI — user continues in the dashboard. |
| **Connect shell** | The one background Shell invocation (`block_until_ms: 0`) that runs the Step 3 connect command. You **Await** its shell id for all stdout — not log files or separate watch commands. |
| **CLI poll** | While the Connect shell runs in the background, the CLI process blocks up to ~5 min per handoff stage (OAuth, inbound email, dashboard authorization). You monitor progress by **Await**ing `NOVU_CONNECT_*` sentinels on that shell id. Success or timeout comes from its stdout only. |
| **Claim** | Keyless only: user signs up via the in-channel link, migrating the temporary agent into their workspace. |

---

## Flow overview

1. **Channel** — ask which channel. Keyless + WhatsApp / MS Teams → dashboard redirect only (Steps 2–5 skipped). Dashboard OAuth supports all channels.
2. **Purpose** — infer a 1–2 sentence agent description **for the product's end users** from the project; confirm with the user.
3. **Run** — connect command from Step 3 (`--ci`, plus `--keyless` for the default keyless mode), streamed.
4. **Handoff** — dashboard OAuth first when omitting `--keyless` (`NOVU_CONNECT_AUTH_URL_FILE=`), then channel-specific next steps. For Slack/Telegram, present the inline secure-page-vs-paste-in-chat token choice only when the token is actually needed. Let the CLI poll.
5. **Report** — relay the CLI's success or error, give a 1–2 sentence recap of what onboarding set up, and point the user to the next step. Keyless: explain demo limit → claim link. Authenticated: report agent identifier + dashboard URL.

---

## Step 1 — Choose channel and collect inputs

**Goal:** lock the channel and gather only what that channel needs.

**Always ask the user to choose** — never assume. Call `AskQuestion` (Cursor) or `AskUserQuestion` (Claude Code) with these **four** options exactly — the picker has a **hard max of 4 options**, which is why WhatsApp and MS Teams share one option and **`skip` is not an option**. In the question's prompt text, add one short sentence that they can skip channel setup (agent only, connect later) by saying so:

| Option id | Label | What the user must do |
|---|---|---|
| `slack` | Slack | **Recommended (secure):** open the setup link the CLI prints and paste a Slack App Configuration Token there, then click an OAuth link to approve the install. **Non-secure fallback:** paste the token in chat instead and you pass it via `--slack-config-token`. |
| `email` | Email | Nothing up front. The CLI prints an inbound email address; the user sends one email to it. |
| `telegram` | Telegram | Create a bot via @BotFather. **Recommended (secure):** open the setup link/QR the CLI prints and paste the token there. **Non-secure fallback:** paste the token in chat instead and you pass it via `--telegram-bot-token`. Then tap **Start** on the bot in Telegram. |
| `dashboard` | WhatsApp / MS Teams | **Keyless (`--keyless`, default):** sign in to the Novu dashboard and continue there (no CLI run). **Dashboard OAuth (omit `--keyless`):** CLI creates the agent, then opens the dashboard to finish channel setup. |

**If they pick `dashboard` and you are using keyless (`--keyless`, the default):** **HARD STOP — never invoke `npx novu connect` in this branch (not in the foreground, not backgrounded, not with any channel flag).** Do **not** run connect and do **not** generate an agent. Give the user the dashboard URL — **<https://dashboard.novu.co>** (or <https://eu.dashboard.novu.co> if they asked for the EU region) — and tell them to **sign in (or sign up) and continue the onboarding from the dashboard**. Steps 2–5 do not apply.

**If they pick `dashboard` and you are using dashboard OAuth (omit `--keyless`):** ask WhatsApp or MS Teams if unclear; use `--channel whatsapp` or `--channel teams` in Step 3.

**If they ask to skip** (via the picker's built-in "Other" free-text, or plain chat): proceed with `--channel skip`.

**Collect after they choose:**

- **slack / telegram** → collect **nothing** up front. Default Step 3 to the **secure path** (omit token flags). Token-delivery choice is **inline in Step 4**.
- **email / skip** → no extra input up front.
- **dashboard (WhatsApp / MS Teams)** → keyless (default): flow ends with dashboard redirect; dashboard OAuth: `--channel whatsapp` or `--channel teams`.

**Runtime:** always use the **demo runtime** — do not ask for an Anthropic API key and do not pass `--runtime` or `--anthropic-api-key`.

**Do not** ask for the agent name/description — you infer it next.

---

## Step 2 — Infer the agent's purpose, then confirm

**Goal:** produce one agent description the user signs off on.

**Persona rule:** infer **who the application is built for** and frame the agent for that audience. The agent acts on behalf of the product, serving its users — it is **never** a coding/ops assistant for the team building the project. If the product's users are developers (devtools, API platforms, SDKs), then and only then is a developer-facing agent correct.

Read the project to decide what the agent should *do*:

From novuhq/skills, MIT.

More from novuhq/skills