/setup

name: setup
description: First-run setup wizard for Remotion Superpowers. Checks dependencies, scaffolds a Remotion project if needed, installs and updates Remotion's 12 official Agent Skills (a required companion), walks through API key configuration, and verifies MCP server connections.

Remotion Superpowers — Setup Wizard

You are running the setup wizard for the Remotion Superpowers plugin. Follow these steps carefully and guide the user through each one.

Step 1: Check System Dependencies

Run these checks and report results:

node --version
npm --version
python3 --version 2>/dev/null || python --version 2>/dev/null
which uvx 2>/dev/null || echo "uvx not found"

**Required:**

• Node.js 22.18 or newer (needed for Remotion and MCP servers)
• npm (comes with Node.js)

**Recommended:**

• Python 3 + `uv`/`uvx` (only for the optional, deprecated ElevenLabs MCP server)
• If missing, tell user: `curl -LsSf https://astral.sh/uv/install.sh | sh`
• Nothing extra for captions: word-level captions use the official `remotion-captions` flow (local Whisper via WebGPU), or ElevenLabs Scribe when there's no GPU.

Report each as ✓ or ✗ with version.

Step 2: Check Remotion Project

Check if the current directory already has a Remotion project (a `remotion` dependency in `package.json`, usually with a `remotion.config.ts`).

**If YES:** Tell the user their Remotion project was detected.

**If NO:** Ask the user if they want to create one here or move to an existing project. To create one, scaffold it exactly as the official `remotion-create` skill says: 1. Inspect the current folder first, including hidden files (`ls -la`). Files such as `.env` or `.git` count as meaningful contents; only OS metadata such as `.DS_Store` is disposable. 2. Empty folder (or only disposable metadata, removed first):

   npx create-video@latest --yes --blank --no-tailwind .
   npm i

3. Folder with meaningful contents: scaffold into a subfolder and move into it:

   npx create-video@latest --yes --blank --no-tailwind my-video
   cd my-video
   npm i

Don't add TailwindCSS unless the user asks for it; the official skills scaffold without it.

Do NOT proceed until the user is in a Remotion project directory. If you moved into a new folder, restart the agent from there: the remotion-media tools write to `public/` of the directory the agent was launched from.

Step 3: Install Remotion's Official Agent Skills (required)

Remotion Superpowers layers on top of Remotion's official Agent Skills. They're a **required companion**: this plugin generates and sources the media, and the official skills own Remotion markup, scaffolding, preview, captions and rendering. Without them the workflows have no Remotion API guidance.

Check that all 12 are installed (for example in `.claude/skills/`, `.agents/skills/`, `.codex/skills/` or `.gemini/skills/`):

`remotion-best-practices`, `remotion-captions`, `remotion-create`, `remotion-docs`, `remotion-interactivity`, `remotion-maps`, `remotion-markup`, `remotion-multimedia`, `remotion-render`, `remotion-saas`, `remotion-studio`, `remotion-upgrade`

**If any are missing:**

npx skills add remotion-dev/skills

`npx skills` detects the installed agents (Claude Code, Codex, Gemini CLI, Cursor, Copilot…) and installs to each. If it asks which skills to install, select all 12.

**Keep them current.** Remotion ships often, and the skills change with each release. From the project, run:

npx remotion upgrade

This upgrades Remotion and its packages and also updates the project-local Remotion skills (official `remotion-upgrade`). If `@remotion/cli` isn't installed locally, update the skills directly:

npx skills update remotion-best-practices remotion-captions remotion-create remotion-docs remotion-interactivity remotion-maps remotion-markup remotion-multimedia remotion-render remotion-saas remotion-studio remotion-upgrade --yes

**Also install the provider skills** this plugin builds on:

npx skills add elevenlabs/skills   # voice, sound effects, music, transcription
npx skills add replicate/skills    # only if the user wants Replicate models

Tell the user: "Remotion's official skills are installed. Your agent now knows Remotion's current APIs, preview, captions and rendering; Remotion Superpowers adds media generation on top."

Step 4: Configure API Keys

Walk the user through each API key. For each one: 1. Explain what the service provides 2. Give the signup URL 3. Tell them the environment variable name 4. Ask them to set it: `export VAR_NAME=their-key` 5. Recommend adding to `~/.zshrc` or `~/.bashrc` for persistence

**Gemini CLI:** extensions don't inherit the shell environment. The keys are prompted for when the extension is installed; to change one later, run `gemini extensions config remotion-superpowers "ElevenLabs API key"` (or the matching setting name) instead of exporting it.

4a. ElevenLabs API Key (REQUIRED: voice, sound effects, music)

• **What:** Voiceovers, sound effects and music (Eleven Music, cleared for commercial use on paid plans), plus transcription for word-level captions when there's no GPU. Generated through the official ElevenLabs skills.
• **Signup:** https://elevenlabs.io (free tier available; a paid plan is needed for commercial music). Or run `npx -y @elevenlabs/cli@latest onboard init`, which signs in and stores a key for the project.
• **Variable:** `ELEVENLABS_API_KEY`
• **Command:** `export ELEVENLABS_API_KEY=your-key-here`
• **Persistence:** `echo 'export ELEVENLABS_API_KEY=your-key-here' >> ~/.zshrc`

4b. KIE API Key (REQUIRED: AI images and clips)

• **What:** AI image generation (Nano Banana Pro) and AI video clips (Veo 3.1) through the remotion-media server. It can also make cheap audio drafts, but KIE resells those models without their owners' licence, so final commercial audio should come from ElevenLabs.
• **Signup:** https://kie.ai (create an