stitch-kit 1.5.0

package/skills/stitch-remotion/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: stitch-remotion
+description: Generates walkthrough videos from Stitch projects using Remotion. Downloads screenshots from Stitch screens, builds a Remotion composition with transitions and text overlays, and renders to MP4. Use with stitch-mcp-list-screens and stitch-mcp-get-screen for screen discovery.
+allowed-tools:
+  - "stitch*:*"
+  - "Bash"
+  - "Read"
+  - "Write"
+---
+
+# Stitch → Remotion Walkthrough Videos
+
+**Constraint:** Only use this skill when the user explicitly mentions "Stitch" and walkthrough video, demo, or Remotion.
+
+You are a video production specialist creating walkthrough videos from Stitch app designs. You retrieve Stitch screenshots and build a Remotion composition — slide transitions, zoom animations, and text overlays.
+
+## Prerequisites
+
+- Stitch MCP Server (or screen IDs already known)
+- Node.js 18+ and npm
+- Remotion CLI (`npm install -g remotion` or use via `npx`)
+
+## Step 1: Gather Stitch assets
+
+### Discover screens
+
+1. Run `list_tools` → find Stitch MCP prefix
+2. Call `[prefix]:list_projects` → select the project
+3. Call `[prefix]:list_screens` with `projects/[projectId]` → list all screens
+4. For each screen you want in the video, call `[prefix]:get_screen` with numeric IDs
+
+### Download screenshots
+
+For each screen:
+
+```bash
+# Download screenshot to assets directory
+curl -L "[screenshot.downloadUrl]" -o "video/public/assets/[screen-name].png"
+```
+
+Or use the fetch script:
+
+```bash
+bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/[screen-name].html"
+# Screenshots are separate — download via curl with the screenshot URL
+```
+
+### Build screens manifest
+
+Create `screens.json` describing the video:
+
+```json
+{
+  "projectName": "My App",
+  "fps": 30,
+  "screens": [
+    {
+      "id": "home",
+      "title": "Home Screen",
+      "description": "Main dashboard with key metrics",
+      "imagePath": "./public/assets/home.png",
+      "width": 390,
+      "height": 844,
+      "durationSeconds": 4
+    },
+    {
+      "id": "profile",
+      "title": "User Profile",
+      "description": "Settings and account management",
+      "imagePath": "./public/assets/profile.png",
+      "width": 390,
+      "height": 844,
+      "durationSeconds": 3
+    }
+  ]
+}
+```
+
+## Step 2: Set up Remotion project
+
+```bash
+# Create new Remotion project inside the working directory
+cd video
+npm create video@latest -- --blank
+cd walkthrough-video
+npm install @remotion/transitions
+```
+
+## Step 3: Build the composition
+
+### ScreenSlide component
+
+```tsx
+// video/src/ScreenSlide.tsx
+import { AbsoluteFill, Img, interpolate, spring, useCurrentFrame, useVideoConfig } from 'remotion'
+
+interface ScreenSlideProps {
+  /** Path to the screenshot image */
+  imagePath: string
+  /** Screen title displayed as overlay */
+  title: string
+  /** Supporting description text */
+  description: string
+  /** Whether to zoom in slightly during display */
+  withZoom?: boolean
+}
+
+/**
+ * Single screen slide with optional zoom effect and text overlay.
+ * Fades in, holds, then fades out.
+ */
+export function ScreenSlide({ imagePath, title, description, withZoom = true }: ScreenSlideProps) {
+  const frame = useCurrentFrame()
+  const { fps, durationInFrames } = useVideoConfig()
+
+  // Fade in over first 15 frames
+  const fadeIn = spring({ fps, frame, config: { damping: 200 } })
+
+  // Subtle zoom: 100% → 105% over the duration
+  const scale = withZoom
+    ? interpolate(frame, [0, durationInFrames], [1, 1.05], { extrapolateRight: 'clamp' })
+    : 1
+
+  return (
+    <AbsoluteFill style={{ backgroundColor: '#000' }}>
+      {/* Screenshot */}
+      <AbsoluteFill style={{ opacity: fadeIn, transform: `scale(${scale})`, transformOrigin: 'center' }}>
+        <Img src={imagePath} style={{ width: '100%', height: '100%', objectFit: 'contain' }} />
+      </AbsoluteFill>
+
+      {/* Bottom text overlay */}
+      <AbsoluteFill
+        style={{
+          justifyContent: 'flex-end',
+          padding: '40px 60px',
+          background: 'linear-gradient(transparent, rgba(0,0,0,0.7))',
+          opacity: fadeIn,
+        }}
+      >
+        <h2 style={{ color: '#fff', fontSize: 36, fontWeight: 700, margin: 0 }}>{title}</h2>
+        {description ? (
+          <p style={{ color: 'rgba(255,255,255,0.8)', fontSize: 20, margin: '8px 0 0' }}>
+            {description}
+          </p>
+        ) : null}
+      </AbsoluteFill>
+    </AbsoluteFill>
+  )
+}
+```
+
+### Walkthrough composition
+
+```tsx
+// video/src/WalkthroughComposition.tsx
+import { Series, TransitionSeries } from '@remotion/transitions'
+import { fade } from '@remotion/transitions/fade'
+import { slide } from '@remotion/transitions/slide'
+import screensData from '../../screens.json'
+import { ScreenSlide } from './ScreenSlide'
+
+const TRANSITION_FRAMES = 15  // 0.5s at 30fps
+
+/**
+ * Main walkthrough composition — one screen per slide, fade/slide transitions.
+ */
+export function WalkthroughComposition() {
+  return (
+    <TransitionSeries>
+      {screensData.screens.map((screen, i) => (
+        <>
+          <TransitionSeries.Sequence
+            key={screen.id}
+            durationInFrames={screen.durationSeconds * screensData.fps}
+          >
+            <ScreenSlide
+              imagePath={screen.imagePath}
+              title={screen.title}
+              description={screen.description}
+            />
+          </TransitionSeries.Sequence>
+          {/* Add transition between screens (except after the last) */}
+          {i < screensData.screens.length - 1 && (
+            <TransitionSeries.Transition
+              key={`t-${screen.id}`}
+              timing={fade({ durationInFrames: TRANSITION_FRAMES })}
+            />
+          )}
+        </>
+      ))}
+    </TransitionSeries>
+  )
+}
+```
+
+### Register in Root.tsx
+
+```tsx
+// video/src/Root.tsx
+import { Composition } from 'remotion'
+import { WalkthroughComposition } from './WalkthroughComposition'
+import screensData from '../../screens.json'
+
+const TOTAL_FRAMES = screensData.screens.reduce(
+  (acc, s) => acc + s.durationSeconds * screensData.fps,
+  0
+)
+
+export const RemotionRoot = () => (
+  <>
+    <Composition
+      id="Walkthrough"
+      component={WalkthroughComposition}
+      durationInFrames={TOTAL_FRAMES}
+      fps={screensData.fps}
+      width={screensData.screens[0]?.width ?? 390}
+      height={screensData.screens[0]?.height ?? 844}
+    />
+  </>
+)
+```
+
+## Step 4: Preview and render
+
+```bash
+# Preview in browser
+cd video/walkthrough-video
+npm run dev
+
+# Render to MP4
+npx remotion render Walkthrough output.mp4
+
+# Higher quality render
+npx remotion render Walkthrough output.mp4 --jpeg-quality 95 --concurrency 4
+```
+
+## Common video styles
+
+| Style | Configuration |
+|-------|--------------|
+| Quick demo (1–2 min) | 2–3s per screen, fade transitions, title only |
+| Feature walkthrough | 4–5s per screen, zoom + slide, title + description |
+| Presentation deck | 5–8s per screen, fade only, full description overlay |
+| Social media clip | 1–2s per screen, fast cuts, music track |
+
+## File structure
+
+```
+project/
+├── screens.json             ← Screen manifest
+├── scripts/fetch-stitch.sh  ← GCS downloader
+└── video/
+    ├── public/
+    │   └── assets/          ← Downloaded screenshots
+    └── walkthrough-video/
+        ├── src/
+        │   ├── WalkthroughComposition.tsx
+        │   ├── ScreenSlide.tsx
+        │   └── Root.tsx
+        ├── remotion.config.ts
+        └── package.json
+```
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| Blurry screenshots | Download full-resolution: use the screenshot URL directly, not a thumbnail |
+| Layout mismatch | Set Remotion composition dimensions to match screen's `width` + `height` from `get_screen` |
+| Transitions jarring | Increase `TRANSITION_FRAMES` or switch from `slide` to `fade` |
+| Build fails on ESM | Add `"type": "module"` to `package.json` and check Remotion version compatibility |
+| MP4 won't play | Check FFmpeg is installed: `ffmpeg -version` |
+
+## References
+
+- Remotion docs: https://www.remotion.dev/docs/
+- Remotion transitions: https://www.remotion.dev/docs/transitions
+- `scripts/fetch-stitch.sh` — Reliable GCS downloader
+- `stitch-mcp-list-screens` — Discover screens in a Stitch project
+- `stitch-mcp-get-screen` — Get screenshot download URLs

package/skills/stitch-setup/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: stitch-setup
+description: Step-by-step installer for the stitch-kit plugin and Stitch MCP server. Use this when setting up the plugin for the first time, diagnosing connection issues, or helping a new user get Stitch running in Claude Code or Codex CLI.
+allowed-tools:
+  - "Bash"
+  - "Read"
+  - "Write"
+---
+
+# stitch-kit Setup Guide
+
+Walks users through two setup tasks:
+1. **Stitch MCP Server** — connect Claude to Google Stitch's generation tools
+2. **stitch-kit Plugin** — install the skills that orchestrate the Stitch workflow
+
+---
+
+## When to use this skill
+
+- User says "how do I set this up", "it's not working", "Stitch isn't available"
+- Agent can't find Stitch MCP tools after running `list_tools`
+- First-time setup in a new environment
+
+---
+
+## Step 1: Verify what's already installed
+
+Run `list_tools` (or check the tool list). Look for any of:
+- `create_project`
+- `generate_screen_from_text`
+- `get_screen`
+
+**If found:** Stitch MCP is working. Skip to Step 4 (plugin install).
+**If not found:** Continue with MCP setup below.
+
+---
+
+## Step 2: Install Stitch MCP Server
+
+### Claude Code
+
+Add to `~/.claude/config.json` (or via `/mcp add` command):
+
+```json
+{
+  "mcpServers": {
+    "stitch": {
+      "command": "npx",
+      "args": ["-y", "@google/stitch-mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+Or using the Claude Code CLI:
+
+```bash
+claude mcp add stitch npx @google/stitch-mcp
+```
+
+### Codex CLI (OpenAI)
+
+Add to your Codex configuration file:
+
+```json
+{
+  "tools": [
+    {
+      "type": "mcp",
+      "server": {
+        "command": "npx",
+        "args": ["-y", "@google/stitch-mcp"]
+      }
+    }
+  ]
+}
+```
+
+### VS Code / Cursor / Windsurf
+
+Check your AI extension's settings for "MCP Servers" and add:
+- **Command:** `npx`
+- **Args:** `["-y", "@google/stitch-mcp"]`
+
+### Manual verification
+
+After adding, restart the client and run `list_tools`. You should see tools prefixed with `stitch:` or similar.
+
+---
+
+## Step 3: Authenticate with Google
+
+Stitch MCP requires a Google account with access to Stitch. On first run:
+
+1. The MCP server will open a browser for Google OAuth
+2. Sign in with a Google account
+3. Authorize Stitch access
+4. Return to the terminal — authentication is saved
+
+If you see "authentication required" errors, run:
+
+```bash
+npx @google/stitch-mcp auth
+```
+
+Or visit: https://stitch.withgoogle.com and sign in to pre-authorize.
+
+---
+
+## Step 4: Install stitch-kit plugin (Claude Code)
+
+```bash
+/plugin marketplace add https://github.com/gabelul/stitch-kit.git
+/plugin install stitch-kit@stitch-kit
+```
+
+All 26 skills in one command. The `stitch-kit` agent is included — it shows up automatically in `/agents` under "Plugin agents" after restart.
+
+---
+
+## Step 5: Verify the full setup
+
+Run the orchestrator to confirm everything works:
+
+```
+"Use Stitch to design a simple login screen"
+```
+
+Expected behavior:
+1. `stitch-orchestrator` activates
+2. It runs `list_tools` and finds Stitch MCP tools
+3. It generates a Design Spec
+4. It creates a project via `create_project`
+5. It generates a screen via `generate_screen_from_text`
+6. It retrieves the screen via `get_screen`
+7. It asks you which framework to convert to
+
+If this completes, you're fully set up.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---------|-------------|-----|
+| `list_tools` doesn't show Stitch tools | MCP not installed or not started | Redo Step 2; restart your client |
+| "Authentication failed" | OAuth not completed | Run `npx @google/stitch-mcp auth` |
+| `create_project` fails with 403 | Account doesn't have Stitch access | Visit stitch.withgoogle.com and request access |
+| `generate_screen_from_text` returns empty | Bad prompt or project ID format | Use `stitch-mcp-generate-screen-from-text` skill — it includes ID format rules |
+| `get_screen` returns 404 | Wrong ID format | **projectId and screenId must be numeric only** — no `projects/` prefix |
+| Generated HTML won't download | GCS URL expired or requires redirects | Use `bash scripts/fetch-stitch.sh "[url]" "temp/output.html"` |
+| Plugin not activating | Wrong install command or repo URL | Verify you used `@stitch-kit` — not `@stitch-pro` or `@stitch-skills` |
+
+---
+
+## Network requirements
+
+Stitch MCP makes outbound requests to:
+- `stitch.withgoogle.com` — API
+- `storage.googleapis.com` — file downloads (HTML, screenshots)
+- `accounts.google.com` — OAuth
+
+If you're behind a corporate proxy or VPN, ensure these domains are allowed.
+
+---
+
+## Offline / no-MCP mode
+
+If you cannot install Stitch MCP, the orchestrator still works in **prompt-only mode**:
+- Steps 1–3 run normally (spec generation, prompt assembly)
+- Instead of generating the screen, it outputs a ready-to-copy Stitch prompt
+- You paste that prompt at stitch.withgoogle.com manually
+- Then you can still use the conversion skills on the downloaded HTML
+
+---
+
+## References
+
+- Official Stitch MCP guide: https://stitch.withgoogle.com/docs/mcp/guide/
+- Plugin repo: https://github.com/gabelul/stitch-kit
+- Skills index: `docs/skills-index.md`
+- MCP tool reference: `docs/mcp-naming-convention.md`