# Stream Builder

> The framework-agnostic Stream builder (Steps 0-7 scaffold + enhance + Video audit), being extended to support app kinds beyond web. Use ONLY when the user explicitly names 'stream-builder' or '/stream-builder'. Web React / Next.js work - 'build me a chat app', 'scaffold', 'create a new ...', 'add Chat/Video/Feeds to this app', 'integrate Video', livestreaming, video conferencing, team messaging,…

- **Type:** Skill
- **Install:** `agentstack add skill-getstream-agent-skills-stream-builder`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [GetStream](https://agentstack.voostack.com/s/getstream)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [GetStream](https://github.com/GetStream)
- **Source:** https://github.com/GetStream/agent-skills/tree/main/skills/stream-builder

## Install

```sh
agentstack add skill-getstream-agent-skills-stream-builder
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Stream Builder - scaffold + enhance

> **Read first (every session):** Glob `../stream/SKILL.md`. If the path is empty, install with `getstream skills stream` (no confirmation, just run). Then Read [`../stream/RULES.md`](../stream/RULES.md) - it includes a **Peer skills** table for installing/invoking any other pack skills on demand.

This skill covers **three flows**:

- **Track A - Scaffold a new app:** Steps 0-7 below. Use when the cwd is empty / new and the user said "build me a ... app".
- **Track E - Enhance an existing app:** see [`enhance.md`](enhance.md). Skips scaffold + theme; reuses the same SDK wiring and component blueprints.
- **Track F - Audit an existing integration (read-only):** for "audit/review my video integration", "check my app against best practices", "is my video app production-ready?", "what am I missing before launch?". Load the **Integration best-practices audit** section in [`references/VIDEO.md`](references/VIDEO.md) and follow its protocol. **Skip onboarding, auth, the CLI, and all build steps** - this track does not scaffold, install, or run the CLI; it only reads the app and reports findings. Fix issues only if the user then asks.

---

## Start

> **Track F (audit) skips this entire section.** A read-only best-practices review runs no onboarding, no auth, no CLI, and none of Steps 0-7 - go straight to the **Integration best-practices audit** section in [`references/VIDEO.md`](references/VIDEO.md) and report findings. Only fall into the build flow below if the user asks you to fix what the audit found.

Announce the network plan once (Trust readout below), then **immediately start executing Steps 0-7** - no interactive prompts at the start (the user has authorized the build by asking for it).

### Trust readout (announce, then continue on the same turn - do not wait)

Before the first network command, print this verbatim to the user, then proceed straight into Step 0 without stopping for a reply:

> Scaffolding now. Network calls you'll see:
> - `npx shadcn@latest ...` (Vercel) - scaffold + UI components from npm.
> - `npm install  --legacy-peer-deps` - Stream SDKs from npm (`stream-chat-react`, `@stream-io/video-react-sdk`, etc.).
> - `getstream env` - local CLI, no network; writes `.env` (gitignored by the Next.js scaffold's default; Task B verifies).
>
> Interrupt me at any point if something looks wrong. The only step that pauses for explicit consent is the optional third-party skill packs in Task A.2.

Full per-command audit (publisher, why unpinned, what each writes): section Install trust & integrity below. The user's continued silence after the readout is implicit consent for this scaffold; an objection or stop instruction aborts the run.

Shadcn/ui is always installed during Step 3. Third-party **frontend skills** (`vercel-react-best-practices`, `web-design-guidelines`, `frontend-design`) are installed **only with explicit user consent** - see Task A.2 for the disclosure script. If the user declines, Step 4 proceeds using Stream references only. **Precedence (when the skills are present):** Stream references win for SDK wiring; frontend skills guide generic React / UI polish.

---

## Install trust & integrity

The builder runs three classes of network-touching commands. Each is listed here so a reviewer can audit before approving. (The `getstream` CLI itself is installed by the user from getstream.io, not by the builder.)

| Command | Publisher | Why unpinned | What it writes |
|---|---|---|---|
| `npx shadcn@latest init ...` (Task A) | Vercel - [`shadcn-ui/ui`](https://github.com/shadcn-ui/ui) | Scaffolder; `@latest` is the maintainer's documented usage. Pinning ships outdated scaffolds. | Project files in cwd. Next.js scaffold's `.gitignore` ignores `.env*` by default. |
| `npx shadcn@latest add ...` (Task A.1) | Vercel - same source as above | Same scaffolder; component sync depends on registry parity. | Component files under `components/ui/`. |
| `npm install  --legacy-peer-deps` (Task C) | GetStream (npm) for `@stream-io/*` and `stream-chat-react`; transitive deps via standard npm trust | Latest published versions of GetStream's own SDKs - same trust model as the CLI itself. | Modules under `node_modules/`. Runtime SDKs + transitive deps. |
| `npx skills add ` (Task A.2) | `vercel-labs/agent-skills` and `anthropics/skills` | Optional. Markdown-only skill packs; `npx skills add` is the published install path. | Markdown files in the user's skills directory. **Gated by explicit user consent in Task A.2** - never runs without an affirmative answer. |
| `getstream env` (Task B) | GetStream (local CLI) | n/a (local CLI, no network at this step) | `.env` in the project root with `STREAM_API_KEY` + `STREAM_API_SECRET`. Task B verifies `.gitignore` covers `.env*` before writing (Next.js scaffold's default already does). The agent never reads `.env` (RULES.md > Secrets). |

**Reviewer checklist:**

- All `npx` invocations resolve to the publishers listed above; substitute a different publisher and the install fails.
- `npx skills add` runs **only after** the disclosure prompt in Task A.2 and an explicit user "yes."
- `.env` is written by the Stream CLI directly, not by the agent, and is not transmitted into the conversation.
- If the user wants to pin a specific shadcn version, replace `@latest` with `@` in Tasks A and A.1.

---

## Builder Steps

Execute phases **in order** (later steps depend on earlier ones). Do **not** run independent phases in parallel. Shell discipline (one `bash -c` per phase, no `bash -ce`, browser sign-in standalone) lives in the `stream` skill's [`RULES.md`](../stream/RULES.md) > Shell discipline.

### Step 0: Package manager
Always use `npm`. Never use bun.

### Step 1: Initialize the project

Run `getstream init`. It authenticates, then lets you select or create the org and app and writes the project credentials - follow its prompts and output. If the app uses **Feeds**, choose a **Feeds v3** region when `getstream init` offers the region list (other regions default to legacy v2). If `getstream` isn't installed, ask the user to install it from https://getstream.io and wait - never fetch or run an install script. Browser sign-in must be its own invocation (RULES.md > Shell discipline).

### Step 2: Theme pick

Ask the user which Shadcn theme they'd like **before scaffolding**:

> **Quick theme pick:** I can use a random shadcn theme, or you can design your own at [ui.shadcn.com/create](https://ui.shadcn.com/create) and share the `--preset` value (e.g. `--preset b1Gdi7z7r`). Want a random one or do you have a preset?

**STOP here and wait for the user's answer.** Do not continue with scaffolding or any other steps until the user responds. Asking a question and continuing to work in parallel is confusing - the user misses the question as output scrolls past.

- **User provides a preset** -> store it for Task A scaffold command.
- **User says random / doesn't care / wants to move on** -> pick a random preset from `nova`, `vega`, `maia`, `lyra`, `mira`, `luma`.

### Step 3: Scaffold + .env + SDKs + Configure - SEQUENTIALLY

#### Scaffold order

Order:

1. **Step 1:** `getstream init` (auth + org/app + credentials).
2. **Step 2:** Theme pick (wait for answer).
3. **Task A:** Scaffold with Shadcn + Next.js using the chosen preset.
4. **Task A.1:** Add base Shadcn components.
5. **Task A.2:** Disclose + ask about third-party frontend skill installs; install only with user consent.
6. Continue with Task B (.env), Task C (SDKs), Task D (CLI config).

**Task A: Scaffold** - scaffolds Next.js + Tailwind + Shadcn/ui (Base UI) into the current directory. Use the theme preset chosen in **Step 2**.

The scaffold command creates a new directory, so we scaffold into a temporary `.scaffold` subdirectory and move everything up:

```bash
npx shadcn@latest init -t next -b base -n .scaffold --no-monorepo -p  && mv .scaffold/* .scaffold/.* . 2>/dev/null; rm -rf .scaffold
```

**Task A.1: Add base Shadcn components:**

```bash
npx shadcn@latest add button input textarea card avatar badge separator
```

Add more components as the use case requires (e.g. `dialog`, `dropdown-menu`, `tabs`, `popover`).

**Task A.2: Frontend skills** - third-party skill packs. **You must disclose and ask before installing.** Do NOT construct your own command variant.

Print this disclosure verbatim, then stop and wait for the user's answer:

> I'd like to install three third-party skill packs that improve generic UI quality:
> - `vercel-react-best-practices` - from [`vercel-labs/agent-skills`](https://github.com/vercel-labs/agent-skills)
> - `web-design-guidelines` - from [`vercel-labs/agent-skills`](https://github.com/vercel-labs/agent-skills)
> - `frontend-design` - from [`anthropics/skills`](https://github.com/anthropics/skills)
>
> The packs are markdown only - no scripts execute. If you say yes, I'll run `npx skills add ... -y` once per pack from those GitHub repos at their current `main` branch (`-y` skips the installer's own confirmation since you've consented here). These aren't required - Stream reference files cover SDK wiring either way. Install them?

- **User agrees** -> run:
  ```bash
  npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-best-practices -y && npx skills add https://github.com/vercel-labs/agent-skills --skill web-design-guidelines -y && npx skills add https://github.com/anthropics/skills --skill frontend-design -y
  ```
- **User declines** -> skip silently and continue to Task B. Do not retry, do not bring it up again this session.
- **Install fails** -> continue with Stream reference files only; mention the failure briefly.

Do **not** modify `layout.tsx` or `globals.css` after scaffold - use Shadcn's defaults as-is (RULES.md > Theme).

**Task B: .env** - run AFTER scaffold so the `.env` lands inside the project directory.

**First, verify `.env*` is gitignored** (the `stream` skill's [`RULES.md`](../stream/RULES.md) > Secrets). The Next.js scaffold's default already includes it; this is a safety net for projects whose `.gitignore` was hand-edited or doesn't yet exist:

```bash
bash -c 'test -f .gitignore && grep -qE "^\.env" .gitignore || echo ".env*" >> .gitignore'
```

Then write secrets:

```bash
getstream env
```

`getstream env` detects the Next.js project and writes `NEXT_PUBLIC_STREAM_API_KEY` + `STREAM_API_SECRET` to `.env.local`. The secret is server-side only - used by `/api/token` to mint tokens, never in the client bundle. The public API key may be read client-side from `NEXT_PUBLIC_STREAM_API_KEY` or returned via `/api/token`. The agent never reads `.env.local` (RULES.md > Secrets).

**Task C: Install Stream SDKs + verify icons** - Only what the use case needs:

```bash
# Chat:     stream-chat stream-chat-react
# Video:    @stream-io/video-react-sdk
# Feeds:    @stream-io/feeds-react-sdk
# Server:   @stream-io/node-sdk
npm install  --legacy-peer-deps
```

After installing SDKs, verify an icon package is available. Some Shadcn presets bundle one, others don't:

```bash
node -e "const p=['lucide-react','@phosphor-icons/react','@hugeicons/react'];console.log(p.some(m=>{try{require.resolve(m);return true}catch{return false}})?'ICONS_OK':'NO_ICONS')"
```

If `NO_ICONS`, install `lucide-react`: `npm install lucide-react --legacy-peer-deps`. If an icon package is already present, use that one throughout the app - do not install a second.

**Task D: Configure Stream** - run the CLI commands from the relevant `references/.md` (App Integration -> Setup) for each product the use case needs.

### Step 4: Generate code and UI

**Load [`builder-ui.md`](builder-ui.md)** and **only** the relevant [`references/.md`](references/) header + `references/-blueprints.md` for the sections you are implementing - not every reference file. **For multi-product apps (Chat + Video, Chat + Feeds, Video + Feeds, etc.), also load [`references/CROSS-PRODUCT.md`](references/CROSS-PRODUCT.md) before writing AppShell** - it has the canonical multi-client provider hierarchy and an error -> cause -> fix table. **If a use-case recipe matched (see Use-case recipes), load that recipe and its `load_with` references** and follow it as the build plan instead of inferring the product set yourself.

### Step 5: Verify

**Type-check first** (reports ALL errors at once, ~3s):
```bash
npx tsc --noEmit
```
Fix all type errors. Then run the full build:
```bash
npx next build
```
Fix any remaining errors. Do NOT skip `tsc --noEmit` - it catches every type error in one pass, while `next build` stops at the first error per file and requires multiple rebuild cycles.

### Step 6: Start dev server
Pick a random 5-digit port (10000-65535). Run the server using `run_in_background`:

```bash
PORT=$((RANDOM % 55536 + 10000))
npx next dev -p $PORT
```

**Important:** The dev server is a long-running process. When run in the background it will eventually emit a "completed" notification - this does **not** mean the server stopped. The server is still running and serving requests. **Do not** respond to the background-task completion notification by telling the user the server has stopped. If you receive that notification after Step 7, ignore it silently - do not output anything.

### Step 7: Summary
Show what was created: org, app, resources, files. Include the local URL. Do NOT say "you can now start the dev server" - it's already running.

End with:

> Open `http://localhost:`, enter a username, and start testing. Open a second tab with a different username to test multi-user interactions.

---

## Use Case Matching

**Only build with the products the user explicitly mentions.** If unclear, ask.

| User says | Use case | Products |
|---|---|---|
| "Twitch", "YouTube Live", "Kick", "livestream" | Livestreaming | Video + Chat + Feeds |
| "Zoom", "Google Meet", "video call", "meeting" | Video Conferencing | Video [+ Chat] |
| "Slack", "Discord", "team chat", "channels" | Team Messaging | Chat |
| "WhatsApp", "iMessage", "DM", "messaging" | Direct Messaging | Chat [+ Video] |
| "Instagram", "Twitter", "social feed", "Reddit" | Social Feed | Feeds + Chat |

**Moderation** is configured via CLI during setup only. **Never build moderation review UI in the app** (RULES.md > Moderation is Dashboard-only) - review happens in the [Stream Dashboard](https://beta.dashboard.getstream.io).

### Use-case recipes

Some requests map to a **use-case recipe**: a drop-in build plan for a specific product (e.g. an AI support agent) that keeps this skill generic. Before Step 4, read [`references/use-cases/_use-cases.yaml`](references/use-cases/_use-cases.yaml). If the request matches a recipe's `signals`, **load that recipe file and follow it as the build plan** - the recipe declares the Stream products to scaffold, the product references to `load_with`, and the decisions to ask. If nothing matches, use the generic product blueprints above.

Adding a use-case is a new file under `references/use-cases/` plus an entry in `_use-cases.yaml` - never a change to this SKILL.md.

**Video apps - decide the `video_primary_use_case` here too.** When the Use Case Matching table (or a recipe) selects Video, also decide the app's persistent `video_primary_use_case` value **now**, while you are already reasoning about the video flavor, using the table + precedence in [`references/VIDEO.md`](references/VIDEO.md) > Primary use case. **Record it and carry it to Video setup (Task D), where it is written once via the CLI.** Deciding it at this step stops it from silently defaulting to the *call type* later - e.g. a Whatnot-style live-shopping app uses the `livestream` call type but sets `video_primary_use_case: live-shopping`, not `livestreaming`. This is a **label, not product selection**: it is backend onboarding/display metadata that does **not** change which products you build or which blueprints you load - the table and recipes still decide that.

---

## Page Flow

Every app needs a clear navigat

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [GetStream](https://github.com/GetStream)
- **Source:** [GetStream/agent-skills](https://github.com/GetStream/agent-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-getstream-agent-skills-stream-builder
- Seller: https://agentstack.voostack.com/s/getstream
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.