Stream

Stream - skill router + CLI

This skill picks the track from the user's input. Building (web + platform) and docs go to dedicated sub-skills; CLI tasks - querying data, configuring an app, onboarding, installing skills - are handled here (see Stream CLI below), since the getstream CLI underlies every track.

Read first: `RULES.md`. Non-negotiable rules apply, including the Peer skills procedure. `peers.yaml` (schema: `peers.schema.json`) is the single source of truth for peer names, Glob paths, install commands, and routing signals.

>

Install a missing peer on demand per its policy in peers.yaml (Glob its path, run its install command - getstream skills <name>), then invoke via the Skill tool or Read it inline. Don't call Skill before the Glob; it surfaces a confusing "Unknown skill" error. Do not stop after naming the track.

---

By task

Build or integrate Stream in a platform-specific app -> peer pack from `peers.yaml` (check peer signals first)

• Match user input or cwd against each peer's signals (e.g. swift / swiftui / .xcodeproj -> stream-swift; react native / expo / stream video react native -> stream-react-native)
• All peers install on demand - install if missing, then route, no prompt
• Peer signals take precedence over the web rows below. A request like "add a video call to my Expo app" or "scaffold a React Native app with Stream Video" matches stream-react-native, not the web packs - the platform token wins.

Build / enhance / audit / migrate a web app with Stream (React / Next.js) -> use the stream-react skill (the default web pack when no other platform signal is present)

• "build me a Chat/Video/Feeds app", "scaffold", "create a new ...", "add Chat to this app", "integrate Video", "drop Feeds into ...", "upgrade/migrate ... to vN" - and no platform signal (no react native, expo, swift, ios, android, etc.)
• React / Next.js tokens (stream-chat-react, @stream-io/video-react-sdk, useCreateChatClient, MessageList, ...) with a build/integrate verb also route here
• Covers Track A (scaffold, Steps 0-7), Track E (enhance an existing project), Track F (read-only best-practices audit), Track M (migrate/upgrade an SDK version)

Build with the framework-agnostic builder -> use the stream-builder skill only when the user names it explicitly ("use stream-builder", "/stream-builder")

• stream-builder is the generic builder being extended to other app kinds; web React/Next.js defaults to stream-react above

Audit/review an existing Stream Video integration against best practices (read-only - no scaffolding, no CLI, no build steps)

• Peer signal (react native / expo) -> stream-react-native; web / React / Next.js or no platform signal -> stream-react (Track F)
• Video only. The dedicated best-practices audit covers Stream Video. Chat/Feeds have no dedicated audit checklist yet - stream-react handles those requests with a general docs-based review and says so up front.
• Triggers: "audit/review my video integration", "is my video app production-ready?", "what am I missing before launch?"
• Routes here even when the request contains "check" - the audit intent takes precedence over the CLI "check {anything}" route below

Query Stream data or run a CLI command -> handled here (see Stream CLI below)

• "list calls", "show channels", "any flagged", "find users", a literal getstream command, or "install the CLI" / "set up stream"

Search Stream SDK documentation -> use the stream-docs skill

• "docs", "documentation", explicit SDK token (Chat React, Video iOS, Feeds Node, Moderation)
• "how do I ... in <framework>", "how does <hook/component/method> work?", "what does <SDK thing> do?"
• No CLI needed - answers come from getstream.io with citations

---

Pick a track

Scan the user's input for the signals below in order. The classifier is deterministic - no probes, no fetches, no CLI checks at this stage.

Onboarding carve-outs. stream-docs answers from documentation only - no shell, no project inspection. Read-only / local-only tracks also skip onboarding: a platform pack's audit track (e.g. stream-react Track F) and migrate track (e.g. stream-react Track M) only inspect/edit local files and the live docs - they do not provision orgs/apps or call getstream api, so they need no CLI onboarding. Only build/integrate work (scaffold a new app, add a product to an existing one) runs getstream init before doing real work.

Docs vs platform packs. A pure how-to or method-lookup question about an iOS/Android/etc. SDK symbol stays in stream-docs - don't pull in a platform pack for a documentation answer. Platform packs (e.g. stream-swift) are for building or integrating - scaffolding projects, wiring packages, generating views.

React framework scope. stream-react scaffolds (Track A) a Next.js app. For enhance / audit / migrate on a non-Next.js React project (Vite, CRA, Remix, TanStack Start, etc.) stream-react still owns it - the Stream SDK wiring is identical - but the agent must adapt the Next.js-specific bits: the server-side token route lives in the project's own backend (not a Next.js /api route), and verification uses the project's build command (npm run build), not next build. Never assume Next.js APIs on a non-Next project.

Disambiguator. If the input fits more than one row (typically operational verb + how-to phrasing), ask one short question and wait. Don't probe before the answer:

Want me to look up the SDK method (docs) or run it now via CLI?

After the answer, route as if the user had given that signal directly.

Bare `/stream` with no args. Render the menu under "Quick navigation" verbatim, then wait for input. No shell execution, no probing, no install.

---

Stream CLI

CLI tasks - querying data, configuring an app, onboarding, installing skills - are handled here; the getstream CLI is the substrate every track uses. Run getstream -h for the command list and getstream <command> -h for usage, and follow what the CLI prints. Safety and posture (no guessing, confirm before writing): `RULES.md` > CLI safety. If getstream isn't installed, ask the user to install it from https://getstream.io and wait - never fetch or run an install script.

---

Sendbird data migration (shared, language-agnostic)

A platform pack's Sendbird migration covers the code/SDK swap (e.g. stream-swift sendbird-migration.md). Moving the data (users, channels, message history, reactions) is server-side and SDK-independent, so it lives once, here, in `sendbird-data-migration.md` - any platform pack hands off to it. It picks a strategy (hard switch / uni-directional / bi-directional sync), exports from Sendbird, builds the JSONL import file, validates, and imports via the getstream CLI (CreateImportURL -> upload -> CreateImport -> GetImport). Read it when a code migration finishes and the user wants their history brought over.

---

Quick navigation

For a bare /stream (and whenever the user wants to pick a skill directly), output the block below verbatim - keep the Core / Platform SDKs split, the examples, and the closing line - then wait:

Stream - Chat - Video - Feeds - Moderation. Tell me what you want, or pick a skill directly:

>

Core

- /stream-react - scaffold, enhance, audit, or migrate a React / Next.js web app with Stream (the default for web) - e.g. "build me a chat app"

- /stream-docs - search live SDK docs, with citations - e.g. "how does useChannel work?"

- /stream-builder - the framework-agnostic builder (web defaults to /stream-react; pick this only if you name it explicitly)

>

Platform SDKs

- /stream-swift - Swift - SwiftUI - UIKit - iOS

- /stream-android - Android - Jetpack Compose - Kotlin

- /stream-react-native - React Native - Expo

- /stream-flutter - Flutter - Dart

>

Or just ask - query data or run getstream commands directly: "list my channels". New to a skill? Just describe the task and I'll install the right one automatically.

The closing line is load-bearing: typing an uninstalled slash command errors with "Unknown skill" before this router runs, so natural-language description is the only dead-end-proof path - it routes here and the missing peer is installed per `peers.yaml`. Keep this menu in sync with peers.yaml: every peer there appears here under Core or Platform SDKs, and new platforms get a bullet under Platform SDKs when their entry is added.

---

Hand-off

See preamble: install if missing, invoke via Skill tool, don't stop. Cross-cutting rules in `RULES.md` apply to every sub-skill, including Cross-track follow-ups (offer, don't auto-execute, the natural next action across track boundaries).

---

Support

If the user asks for support or how to contact someone, direct them to getstream.io/contact.

Stream - non-negotiable rules

Every rule below is stated once. Other files reference this file - do not duplicate these rules inline.

---

Peer skills

The Stream pack ships a router (this skill) plus a set of peer skills declared in `peers.yaml` (schema: `peers.schema.json`). To check whether a peer is installed, Glob the entry's glob path. To install a missing peer per its install_policy, run its install command. To use it after install, Skill tool if listed in the system reminder's available-skills, otherwise Read the file inline (available-skills doesn't refresh mid-session).

When adding a new peer pack, edit peers.yaml only.

---

Secrets

Never Read/Edit `.env` / `.env.local` in chat - the secret leaks into the conversation. Let the CLI own it: getstream env writes the platform's API key var (and the secret, for server targets) into the right file, and that's all you need. Don't grep, don't cat, don't echo >> a file holding the secret. Never hardcode the secret in code.

The secret is server-side only - never in the client bundle, never NEXT_PUBLIC. The public API key may be client-exposed: getstream env writes it with the framework's client prefix (e.g. NEXT_PUBLIC_STREAM_API_KEY, EXPO_PUBLIC_STREAM_API_KEY). The client may read that var directly or receive apiKey from the /api/token response; either way the token is minted server-side (with the secret) and returned by /api/token.

`.gitignore` before any `.env` write. Before any tool writes secrets to .env (notably getstream env in builder Task B), confirm a line covering .env* exists in .gitignore and add one if missing. The Next.js scaffold's default already does - this rule covers the edge case where the project's .gitignore was hand-edited or doesn't exist yet.

No auto-seeding

Never auto-create demo users (alex, maya, jake, sarah) or sample posts/channels/content. The /api/token route upserts only the requesting user and returns their token(s). Seed functions are opt-in only when the user explicitly asks for sample data.

Login Screen first

Every app opens with a Login Screen as its root page (app/page.tsx). The app never auto-connects or hardcodes a user. Credentials (token, apiKey, userId) live in React state - not localStorage - so each browser tab can operate as an independent user. Layout and behavior details: the active builder pack's builder-ui.md > Login Screen (`stream-react` for web React; `stream-builder` when explicitly invoked).

Strict mode protection

React packs only (stream-react, stream-react-native, and stream-builder's web flow) - not applicable to the Swift/Android/Flutter packs. Protection is per-SDK, not one blanket pattern:

• Chat (client-side): use the official useCreateChatClient() hook - it handles strict mode internally. Never getInstance() on the client (singletons break strict mode).
• Feeds (client-side): useCreateFeedsClient() handles the connection internally. Only feed.getOrCreate() needs the manual setTimeout(50ms) + mounted guard + cleanup in useEffect.
• Video (client-side): the StreamVideoClient constructor is synchronous - plain useState + useEffect with disconnectUser() cleanup; no timer, no mounted flag, never useMemo.
• Server-side: StreamChat.getInstance(apiKey, apiSecret) is fine (singleton OK).
• Never use `useRef` as a "run once" guard in setup effects with cleanup - the ref survives strict mode's unmount->remount cycle, so the second mount skips initialization entirely.

Authoritative detail and canonical snippets live in the React pack's own rules: `stream-react/RULES.md` > Strict mode protection (web; includes the carve-outs and the canonical video snippet). stream-react-native carries its own RULES.md.

Base UI (not Radix)

Shadcn components use @base-ui/react, NOT @radix-ui. Key differences:

• Never use `asChild` - it does not exist in Base UI. Trigger components render children directly.
• Style triggers by passing className directly to <DropdownMenuTrigger>, <PopoverTrigger>, etc.
• Do NOT wrap triggers with <Button> - style the trigger element itself.

CLI safety

The getstream CLI owns onboarding, auth, and credentials. Drive it from the Stream CLI section of `SKILL.md` and read the CLI's output to understand what happened - it explains failures and next steps the same way for an agent as for a person. There are no exit-code conventions to memorize.

• No guessing. Endpoint names, parameters, and body shapes come from getstream api -h (or stream -h), never from training-data recall. If you're about to type a getstream api <Endpoint> you haven't confirmed this turn, stop and look it up first. This applies to every sub-skill, including stream-builder follow-ups and one-off "let me just check" queries.
• Confirm before writing. Default to read-only. Before any operation that creates, changes, or deletes - or any outward-facing action - describe it and get the user's confirmation. When the CLI refuses an operation and asks for an explicit flag or confirmation, it is flagging a dangerous action: surface it, confirm, then re-run with the flag the CLI named.
• Sign-in opens a browser. getstream init / getstream login launch a browser flow - run them as their own invocation (never chained with && or wrapped in a heredoc). If sign-in hangs, ask the user to run it themselves with ! <command>.

Onboarding & phase order

Onboarding is owned by the CLI: getstream init authenticates, selects or creates the org + app, and writes project credentials; getstream env provisions the app's server-side secret without exposing it. If getstream isn't installed, ask the user to install it from https://getstream.io and wait - never fetch or run an install script. The `stream-docs` skill skips onboarding entirely and never runs the CLI except an on-demand read-only probe when the SDK can't be resolved from user input.

• Do not load references/*.md (in the stream-builder skill) until the user names the product(s).
• Do not load builder-ui.md (in the stream-builder skill) before Step 4.
• Shadcn/ui is always installed during Step 3 - never skip. Third-party frontend skills (vercel-labs/*, anthropics/*) require one explicit user confirmation per session before install - see the stream-builder skill's SKILL.md Task A.2.

Shell discipline

• Never `bash -ce` or `set -e` in probes or batched phases. grep (and friends) return exit 1 on "no match," which under -e aborts the whole script and leaves you with partial output. Tolerate specific failures explicitly (|| echo NOT_FOUND, || true) instead.
• One `bash -c` per phase where possible. Chain with && on a single line to minimize sandbox approval prompts. If you need to read JSON and then act on it, use one call to read and one batched call for the writes.
• Browser sign-in stays its own invocation. getstream init / getstream login open a browser - never chain with &&, embed in a heredoc, or bundle with other commands. Hang recovery is in CLI safety above.

Cross-track follow-ups

A result from one sub-skill can naturally enable an action in another. Surface a follow-up offer when it genuinely helps the user - not as boilerplate on every turn.

• `stream-docs` -> CLI: a docs answer that names a runnable operation can offer "want me to run that now via CLI?" (only if read-safe or clearly operational intent).
• CLI -> `stream-docs`: a CLI result that has a relevant docs page can offer "want the page that explains this?" (link only - don't fetch unprompted).
• `stream-builder` -> `stream-docs`: after scaffold or integration completes, mention that the SDK + version is preloaded and ask-anything is available.
• `stream-docs` -> `stream-builder`: a docs answer that describes a setup-heavy flow can mention scaffold / integrate is available - without running it.

Do not auto-execute a cross-skill action. Offer, then wait for the user to confirm. The skill switch happens through the user's reply, which re-enters the stream router or jumps straight to the named sub-skill.

Theme

Use whatever theme Shadcn generates. Do not modify globals.css after init - no dark mode overrides, no custom variable blocks. The scaffold includes next-themes with a ThemeProvider (system default, class-based toggle) - use it as-is.

Reference authority

Reference files are the only source of truth for HTML structure, SDK wiring, and property paths. Do not generate Stream SDK code from training data. Before writing each component, map it to the relevant references sections (Blueprint -> JSX structure, Wiring table -> data fetching/mutations, Requirements -> setup, App Integration -> routes and patterns).

Package manager

Always use `npm`. Never use bun. Always `--legacy-peer-deps` for Stream packages.

Moderation is Dashboard-only

Never build a moderation review queue, review panel, or flagged-item UI in the app. Moderation review always happens in the Stream Dashboard. The app's role is limited to:

• CLI setup during scaffold (blocklists, automod config via references/MODERATION.md Setup)
• End-user actions (report, block, mute) if the product needs them
• Do not load Review Queue, Flagged Item, or Auto-Mod Status blueprints from MODERATION-blueprints.md

---

Sandboxed / blocked shell fallback

If terminal is denied or offline: print commands for the user to run locally; continue with Read/file work only.

Sendbird -> Stream Chat data migration (language-agnostic)

Migrates the data (users, channels, message history, reactions, members, devices) from Sendbird into Stream Chat. It is server-side and SDK-independent - the same procedure applies whether the client is Swift, Kotlin, Flutter, React, or React Native. A platform pack's code migration (e.g. stream-swift sendbird-migration.md) swaps the SDK; this file moves the history behind it.

The docs are the source of truth - fetch them, don't reproduce them. This file is an orchestrator: it picks the strategy with the user, points at the exact doc pages, and adds only the three things the docs don't give you - the interactive decision flow, the verified `getstream` CLI import sequence (the docs show the older standalone stream-cli), and the Sendbird -> Stream transform gotchas. Everything else - strategy pros/cons, field-mapping tables, the JSONL schema, validation errors, the Sendbird event list, the webhook URL - lives in the docs. Fetch the .md twins at run time and follow them:

• Migration guide (strategies, Sendbird->Stream field mappings, real-time sync + webhook +

event list): https://getstream.io/chat/docs/node/migrating-from-sendbird.md

• Import (JSONL format, object schema, ordering, validation, limits):

https://getstream.io/chat/docs/node/import.md

When to run: after the code migration builds and connects. A migrated app talks to an

empty Stream app until you import. Ask the user first - never start a data migration

unsolicited (it touches production data and may incur attachment-transfer cost).

---

Step 1 - Pick a strategy (ASK the user; this is the branch point)

The guide describes three approaches. Summarize them, recommend one, and let the user choose - fetch the guide for the full pros/cons:

• A. No Sync (hard switch) - simplest; needs a maintenance window; users update the app.
• B. Uni-directional sync - zero downtime, the most common choice. Lead with this.
• C. Bi-directional sync - zero downtime, no forced app update; most complex (Enterprise).

All three share the same bulk import (steps 2-4). B and C add real-time sync on top (step 5). So run 2-4 regardless, then add step 5 for B/C.

Ask, e.g.:

The SDK migration is done. Do you also want to migrate your Sendbird data (users,

channels, message history, reactions)? If so: A hard switch (simplest, needs a window),

B uni-directional sync (zero downtime, most common), or C bi-directional sync (zero

downtime, no forced app update, Enterprise)?

---

Step 2 - Export from Sendbird

Pull users, channels, members, messages (reactions ship inline on messages) via the Sendbird Platform API (server-side; needs your Sendbird app id + API token), or the Data Export API for very large datasets. This is the only language-specific step - any HTTP client in any language works; paginate every endpoint and handle rate limits. Keep the raw export on disk for step 3.

---

Step 3 - Build + validate the import file

Read `import.md` for the exact format and follow it - JSONL, one { "type", "data" } object per line, the per-type schema, the required object ordering, the 300 MB / 5 KB / RFC3339 / 64-char limits, and the JSON-Schema validation. Map Sendbird fields to Stream fields per the table in `migrating-from-sendbird.md`. Don't hand-roll either from memory - re-read them.

What those docs don't spell out - the Sendbird -> Stream transform gotchas (this is the real value of doing it as a migration rather than a generic import):

• Channel id length: Sendbird channel_url often exceeds Stream's 64-char id limit ->

hash/truncate to a stable id and keep a url->id map so members and messages line up.

• Timestamps: Sendbird emits epoch milliseconds; Stream needs RFC3339. Convert every one.
• Reactions are aggregated in Sendbird ({ key, user_ids: [...] }) -> emit **one Stream

reaction row per user**, not per key.

• Channel type: map Sendbird group channels -> messaging, open channels ->

livestream (or your own choice); distinct/1:1 channels use member_ids and omit `id`.

• Attachments need publicly reachable URLs; set migrate_resources: true to copy them onto

Stream's CDN instead of hot-linking Sendbird.

Validate against the JSON Schema before uploading - it catches almost everything offline.

---

Step 4 - Import via the getstream CLI

The import docs show the older standalone stream-cli. This pack uses `getstream`, which drives the same import API. Run inside an initialized project (getstream init) so the API key/secret are picked up:

# 1. Get a signed upload URL + the import path
getstream api CreateImportURL --request '{"filename":"migration.jsonl"}'
#    -> returns an upload_url (signed S3) and a path

# 2. Upload the file to that signed URL (PUT, raw body)
curl -X PUT --upload-file migration.jsonl \
  -H 'Content-Type: application/octet-stream' "<upload_url>"

# 3. Start the import. mode: "upsert" (overwrite) or "insert" (skip existing).
#    Add "merge_custom": true to merge custom fields instead of replacing on upsert.
getstream api CreateImport --request '{"path":"<path>","mode":"upsert"}'
#    -> returns the created import; note its id

# 4. Poll until completed/failed; list past imports
getstream api GetImport --id <import-id>
getstream api ListImports

Start tiny - import a few users + one channel + a few messages, verify in the dashboard (or getstream api QueryChannels), then run the full export. A full historical import is asynchronous and can take hours-to-days at scale; split exports larger than 300 MB into multiple ordered files.

For strategy A, that's it: schedule the window, run the full import, verify, deploy. Stop here.

---

Step 5 - Real-time sync (strategies B and C only)

Bulk import is a snapshot; B/C also mirror new Sendbird activity into Stream so nothing is lost between the snapshot and cutover. Stream supports Sendbird sync out of the box - read the "real-time sync" section of migrating-from-sendbird.md for the exact webhook URL and the supported-event list. In short: give Stream your Sendbird app id + token, point Sendbird's webhook at the Stream endpoint, and enable the events you need.

• B (uni-directional): Sendbird -> Stream only; flip clients to Stream when ready, then

disable the webhook.

• C (bi-directional): also Stream -> Sendbird so un-upgraded clients keep working during a

gradual rollout - the Enterprise path; involve Stream support to configure both directions.

---

Step 6 - Cut over and verify

Confirm the import finished (GetImport state) and spot-check counts (users, channels, messages) against Sendbird; open a migrated channel and check history, reactions, threads, and attachments in-app; then switch client traffic to Stream. For B/C keep the sync running through the rollout, then disable the Sendbird webhook and decommission Sendbird.

---

Source

• https://getstream.io/chat/docs/node/migrating-from-sendbird.md
• https://getstream.io/chat/docs/node/import.md

Cite these when you apply the runbook, and if anything here disagrees with the live .md, the docs win - re-fetch and follow them.