diff --git a/plugins/runway-api/LICENSE.runway-api b/plugins/runway-api/LICENSE.runway-api
new file mode 100644
index 00000000..7aa33638
--- /dev/null
+++ b/plugins/runway-api/LICENSE.runway-api
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RunwayML, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/plugins/runway-api/README.md b/plugins/runway-api/README.md
new file mode 100644
index 00000000..ef9f6c69
--- /dev/null
+++ b/plugins/runway-api/README.md
@@ -0,0 +1,36 @@
+# runway-api
+
+Runway API skills for Cline users building or operating media generation workflows.
+
+## What It Does
+
+This plugin bundles skills for two related workflows:
+
+- Generating media directly with Runway's API, including text/image/video generation, audio generation, uploads, organization details, and general API calls.
+- Integrating Runway features into server-side apps, including compatibility checks, API key setup, video/image/audio endpoints, uploads, real-time avatar characters, document knowledge, and React avatar embeds.
+
+The plugin also includes the Python and Node helper scripts used by the direct-generation skills, plus bundled guidance for paid API calls, media uploads, outbound URL fetches, and API-key handling.
+
+## Install
+
+```bash
+cline plugin install runway-api
+```
+
+For local development from this repository:
+
+```bash
+cline plugin install ./plugins/runway-api --cwd .
+```
+
+## Requirements
+
+- A Runway developer account with available credits.
+- `RUNWAYML_API_SECRET` in the environment or a user-created local `.env` file when making API calls.
+- `uv` for the bundled Python generation helper scripts.
+- Node.js 20 or newer for the general `use-runway-api` helper script.
+- A server-side app when using integration skills. API keys must not be exposed in frontend code.
+
+## Security Notes
+
+Runway operations can spend credits and may upload or generate sensitive media. Cline should confirm paid generation, uploads, organization/account actions, external media URLs, output locations, and production code changes before acting.
diff --git a/plugins/runway-api/assets/logo.png b/plugins/runway-api/assets/logo.png
new file mode 100644
index 00000000..9a4f1f6d
Binary files /dev/null and b/plugins/runway-api/assets/logo.png differ
diff --git a/plugins/runway-api/index.ts b/plugins/runway-api/index.ts
new file mode 100644
index 00000000..85082753
--- /dev/null
+++ b/plugins/runway-api/index.ts
@@ -0,0 +1,10 @@
+import type { AgentPlugin } from "@cline/sdk"
+
+const plugin: AgentPlugin = {
+	name: "runway-api",
+	manifest: {
+		capabilities: ["skills"],
+	},
+}
+
+export default plugin
diff --git a/plugins/runway-api/package.json b/plugins/runway-api/package.json
new file mode 100644
index 00000000..2fcfa05f
--- /dev/null
+++ b/plugins/runway-api/package.json
@@ -0,0 +1,19 @@
+{
+  "name": "runway-api",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Cline plugin that bundles Runway API media generation and app integration skills.",
+  "cline": {
+    "plugins": [
+      {
+        "paths": [
+          "./index.ts"
+        ],
+        "capabilities": [
+          "skills"
+        ]
+      }
+    ]
+  }
+}
diff --git a/plugins/runway-api/scripts/generate_audio.py b/plugins/runway-api/scripts/generate_audio.py
new file mode 100644
index 00000000..73e76542
--- /dev/null
+++ b/plugins/runway-api/scripts/generate_audio.py
@@ -0,0 +1,130 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["requests"]
+# ///
+
+"""Generate audio using the Runway API (TTS, sound effects, voice isolation, dubbing)."""
+
+import argparse
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from runway_helpers import (
+    get_api_key,
+    api_post,
+    poll_task,
+    download_file,
+    ensure_url,
+    output_path,
+)
+
+AUDIO_TYPES = {
+    "tts": {
+        "endpoint": "/v1/text_to_speech",
+        "model": "eleven_multilingual_v2",
+        "description": "Text to speech",
+    },
+    "sfx": {
+        "endpoint": "/v1/sound_effect",
+        "model": "eleven_text_to_sound_v2",
+        "description": "Sound effect generation",
+    },
+    "isolate": {
+        "endpoint": "/v1/voice_isolation",
+        "model": "eleven_voice_isolation",
+        "description": "Isolate voice from audio",
+    },
+    "dub": {
+        "endpoint": "/v1/voice_dubbing",
+        "model": "eleven_voice_dubbing",
+        "description": "Dub to another language",
+    },
+    "sts": {
+        "endpoint": "/v1/speech_to_speech",
+        "model": "eleven_multilingual_sts_v2",
+        "description": "Voice conversion",
+    },
+}
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate audio with the Runway API")
+    parser.add_argument("--filename", required=True, help="Output filename (e.g. output.mp3)")
+    parser.add_argument(
+        "--type",
+        required=True,
+        choices=list(AUDIO_TYPES.keys()),
+        help="Audio type: tts, sfx, isolate, dub, sts",
+    )
+    parser.add_argument("--text", help="Text input (required for tts and sfx)")
+    parser.add_argument("--audio-url", help="Audio URL or local path (for isolate, dub, sts)")
+    parser.add_argument("--voice-id", help="Voice ID (for tts and sts)")
+    parser.add_argument("--target-language", help="Target language code (for dub, e.g. 'es')")
+    parser.add_argument("--output-dir", help="Output directory (default: cwd)")
+    args = parser.parse_args()
+
+    api_key = get_api_key()
+    audio_type = AUDIO_TYPES[args.type]
+    endpoint = audio_type["endpoint"]
+    model = audio_type["model"]
+
+    body = {"model": model}
+
+    if args.type == "tts":
+        if not args.text:
+            print("Error: --text is required for tts.", file=sys.stderr)
+            sys.exit(1)
+        body["promptText"] = args.text
+        body["voice"] = {"type": "runway-preset", "presetId": args.voice_id or "Maya"}
+
+    elif args.type == "sfx":
+        if not args.text:
+            print("Error: --text is required for sfx.", file=sys.stderr)
+            sys.exit(1)
+        body["promptText"] = args.text
+
+    elif args.type == "isolate":
+        if not args.audio_url:
+            print("Error: --audio-url is required for isolate.", file=sys.stderr)
+            sys.exit(1)
+        body["audioUri"] = ensure_url(args.audio_url, api_key)
+
+    elif args.type == "sts":
+        if not args.audio_url:
+            print("Error: --audio-url is required for sts.", file=sys.stderr)
+            sys.exit(1)
+        audio_uri = ensure_url(args.audio_url, api_key)
+        body["media"] = {"type": "audio", "uri": audio_uri}
+        body["voice"] = {"type": "runway-preset", "presetId": args.voice_id or "Maya"}
+
+    elif args.type == "dub":
+        if not args.audio_url:
+            print("Error: --audio-url is required for dub.", file=sys.stderr)
+            sys.exit(1)
+        if not args.target_language:
+            print("Error: --target-language is required for dub.", file=sys.stderr)
+            sys.exit(1)
+        body["audioUri"] = ensure_url(args.audio_url, api_key)
+        body["targetLang"] = args.target_language
+
+    print(f"Generating audio ({args.type}) with {model}...", file=sys.stderr)
+    task = api_post(api_key, endpoint, body)
+    task_id = task.get("id")
+    print(f"Task created: {task_id}", file=sys.stderr)
+
+    result = poll_task(api_key, task_id)
+    urls = result.get("output", [])
+
+    if not urls:
+        print("Error: No output URLs in result.", file=sys.stderr)
+        sys.exit(1)
+
+    out = output_path(args.filename, args.output_dir)
+    path = download_file(urls[0], out)
+    print(path)
+    print(f"Saved: {path}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/plugins/runway-api/scripts/generate_image.py b/plugins/runway-api/scripts/generate_image.py
new file mode 100644
index 00000000..93d6365a
--- /dev/null
+++ b/plugins/runway-api/scripts/generate_image.py
@@ -0,0 +1,103 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["requests"]
+# ///
+
+"""Generate images using the Runway API."""
+
+import argparse
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from runway_helpers import (
+    get_api_key,
+    api_post,
+    poll_task,
+    download_file,
+    ensure_url,
+    output_path,
+    IMAGE_MODELS,
+)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate images with the Runway API")
+    parser.add_argument("--prompt", required=True, help="Text description of the image")
+    parser.add_argument(
+        "--filename", required=True, help="Output filename (e.g. output.png)"
+    )
+    parser.add_argument(
+        "--model",
+        default="gemini_2.5_flash",
+        choices=list(IMAGE_MODELS.keys()),
+        help="Image model (default: gemini_2.5_flash / Nano Banana)",
+    )
+    parser.add_argument(
+        "--ratio", default=None, help="Aspect ratio. gemini_2.5_flash: 1344:768, 768:1344, 1024:1024, etc. Others: 1280:720"
+    )
+    parser.add_argument(
+        "--reference-images",
+        nargs="*",
+        metavar="TAG=URL",
+        help="Reference images as Tag=URL pairs (e.g. Style=https://...)",
+    )
+    parser.add_argument("--output-dir", help="Output directory (default: cwd)")
+    args = parser.parse_args()
+
+    api_key = get_api_key()
+
+    if args.ratio:
+        ratio = args.ratio
+    elif args.model == "gemini_2.5_flash":
+        ratio = "1344:768"
+    else:
+        ratio = "1280:720"
+
+    body = {
+        "model": args.model,
+        "promptText": args.prompt,
+        "ratio": ratio,
+    }
+
+    if args.reference_images:
+        refs = []
+        for pair in args.reference_images:
+            if "=" not in pair:
+                print(
+                    f"Error: Reference image must be Tag=URL, got: {pair}",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+            tag, source = pair.split("=", 1)
+            refs.append({"tag": tag, "uri": ensure_url(source, api_key)})
+        body["referenceImages"] = refs
+    elif args.model == "gen4_image_turbo":
+        print("Error: gen4_image_turbo requires --reference-images.", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Generating image with {args.model}...", file=sys.stderr)
+    task = api_post(api_key, "/v1/text_to_image", body)
+    task_id = task.get("id")
+    print(f"Task created: {task_id}", file=sys.stderr)
+
+    result = poll_task(api_key, task_id)
+    urls = result.get("output", [])
+
+    if not urls:
+        print("Error: No output URLs in result.", file=sys.stderr)
+        sys.exit(1)
+
+    for i, url in enumerate(urls):
+        if len(urls) == 1:
+            out = output_path(args.filename, args.output_dir)
+        else:
+            base, ext = os.path.splitext(args.filename)
+            out = output_path(f"{base}-{i + 1}{ext}", args.output_dir)
+        path = download_file(url, out)
+        print(path)
+        print(f"Saved: {path}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/plugins/runway-api/scripts/generate_video.py b/plugins/runway-api/scripts/generate_video.py
new file mode 100644
index 00000000..fbffa5a4
--- /dev/null
+++ b/plugins/runway-api/scripts/generate_video.py
@@ -0,0 +1,117 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["requests"]
+# ///
+
+"""Generate videos using the Runway API."""
+
+import argparse
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from runway_helpers import (
+    get_api_key,
+    api_post,
+    poll_task,
+    download_file,
+    ensure_url,
+    output_path,
+    VIDEO_MODELS,
+)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate videos with the Runway API")
+    parser.add_argument("--prompt", required=True, help="Text description of the video")
+    parser.add_argument("--filename", required=True, help="Output filename (e.g. output.mp4)")
+    parser.add_argument(
+        "--model",
+        default="gen4.5",
+        choices=list(VIDEO_MODELS.keys()),
+        help="Video model (default: gen4.5)",
+    )
+    parser.add_argument("--ratio", default="1280:720", help="Aspect ratio (default: 1280:720). All models use pixel-based ratios.")
+    parser.add_argument("--duration", type=int, default=5, help="Duration in seconds (default: 5)")
+    parser.add_argument("--image-url", help="Input image URL or local path for image-to-video")
+    parser.add_argument("--video-url", help="Input video URL or local path for video-to-video (gen4_aleph, seedance2)")
+    parser.add_argument("--output-dir", help="Output directory (default: cwd)")
+    args = parser.parse_args()
+
+    api_key = get_api_key()
+    model_info = VIDEO_MODELS[args.model]
+
+    valid_durations = model_info.get("durations")
+    duration = args.duration
+    if valid_durations and duration not in valid_durations:
+        closest = min(valid_durations, key=lambda d: abs(d - duration))
+        print(f"  Note: {args.model} supports durations {valid_durations}, using {closest}s instead of {duration}s.", file=sys.stderr)
+        duration = closest
+
+    if args.video_url:
+        if "video_to_video" not in model_info["endpoints"]:
+            print(f"Error: {args.model} does not support video-to-video.", file=sys.stderr)
+            sys.exit(1)
+        endpoint = "/v1/video_to_video"
+        video_uri = ensure_url(args.video_url, api_key)
+        if args.model == "seedance2":
+            body = {
+                "model": args.model,
+                "promptVideo": video_uri,
+                "promptText": args.prompt,
+            }
+        else:
+            body = {
+                "model": args.model,
+                "videoUri": video_uri,
+                "promptText": args.prompt,
+            }
+    elif args.image_url:
+        if "image_to_video" not in model_info["endpoints"]:
+            print(f"Error: {args.model} does not support image-to-video.", file=sys.stderr)
+            sys.exit(1)
+        endpoint = "/v1/image_to_video"
+        image_uri = ensure_url(args.image_url, api_key)
+        body = {
+            "model": args.model,
+            "promptImage": image_uri,
+            "promptText": args.prompt,
+            "ratio": args.ratio,
+        }
+        body["duration"] = duration
+    else:
+        if "text_to_video" not in model_info["endpoints"]:
+            print(
+                f"Error: {args.model} requires an input image (--image-url). "
+                "It does not support text-only generation.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        endpoint = "/v1/text_to_video"
+        body = {
+            "model": args.model,
+            "promptText": args.prompt,
+            "ratio": args.ratio,
+            "duration": duration,
+        }
+
+    print(f"Generating video with {args.model} ({args.duration}s, {args.ratio})...", file=sys.stderr)
+    task = api_post(api_key, endpoint, body)
+    task_id = task.get("id")
+    print(f"Task created: {task_id}", file=sys.stderr)
+
+    result = poll_task(api_key, task_id)
+    urls = result.get("output", [])
+
+    if not urls:
+        print("Error: No output URLs in result.", file=sys.stderr)
+        sys.exit(1)
+
+    out = output_path(args.filename, args.output_dir)
+    path = download_file(urls[0], out)
+    print(path)
+    print(f"Saved: {path}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/plugins/runway-api/scripts/get_task.py b/plugins/runway-api/scripts/get_task.py
new file mode 100644
index 00000000..2b8635b7
--- /dev/null
+++ b/plugins/runway-api/scripts/get_task.py
@@ -0,0 +1,35 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["requests"]
+# ///
+
+"""Check the status of a Runway API task."""
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from runway_helpers import get_api_key, api_get
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Check Runway task status")
+    parser.add_argument("--task-id", required=True, help="Task ID to check")
+    parser.add_argument("--wait", action="store_true", help="Poll until the task completes")
+    args = parser.parse_args()
+
+    api_key = get_api_key()
+
+    if args.wait:
+        from runway_helpers import poll_task
+        result = poll_task(api_key, args.task_id)
+        print(json.dumps(result, indent=2))
+    else:
+        task = api_get(api_key, f"/v1/tasks/{args.task_id}")
+        print(json.dumps(task, indent=2))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/plugins/runway-api/scripts/list_models.py b/plugins/runway-api/scripts/list_models.py
new file mode 100644
index 00000000..fc6537ab
--- /dev/null
+++ b/plugins/runway-api/scripts/list_models.py
@@ -0,0 +1,55 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["requests"]
+# ///
+
+"""List available Runway API models and their costs."""
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from runway_helpers import VIDEO_MODELS, IMAGE_MODELS, AUDIO_MODELS
+
+
+def print_table(title, models, extra_cols=None):
+    print(f"\n{'=' * 60}")
+    print(f"  {title}")
+    print(f"{'=' * 60}")
+    for name, info in models.items():
+        desc = info.get("description", "")
+        cost = info.get("cost", "")
+        print(f"  {name:<30} {cost:<20} {desc}")
+    print()
+
+
+def main():
+    parser = argparse.ArgumentParser(description="List available Runway API models")
+    parser.add_argument("--type", choices=["video", "image", "audio", "all"], default="all", help="Model type to list")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    args = parser.parse_args()
+
+    data = {}
+    if args.type in ("video", "all"):
+        data["video"] = VIDEO_MODELS
+    if args.type in ("image", "all"):
+        data["image"] = IMAGE_MODELS
+    if args.type in ("audio", "all"):
+        data["audio"] = AUDIO_MODELS
+
+    if args.json:
+        print(json.dumps(data, indent=2))
+        return
+
+    if "video" in data:
+        print_table("Video Models", VIDEO_MODELS)
+    if "image" in data:
+        print_table("Image Models", IMAGE_MODELS)
+    if "audio" in data:
+        print_table("Audio Models", AUDIO_MODELS)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/plugins/runway-api/scripts/runway_helpers.py b/plugins/runway-api/scripts/runway_helpers.py
new file mode 100644
index 00000000..36646314
--- /dev/null
+++ b/plugins/runway-api/scripts/runway_helpers.py
@@ -0,0 +1,396 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["requests"]
+# ///
+
+"""Shared helpers for Runway API scripts: API calls, task polling, retry, download, error handling."""
+
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import time
+import mimetypes
+from urllib.parse import urlparse
+import requests
+
+API_BASE = "https://api.dev.runwayml.com"
+API_VERSION = "2024-11-06"
+
+# - Models registry -
+
+VIDEO_MODELS = {
+    "seedance2": {
+        "endpoints": ["text_to_video", "image_to_video", "video_to_video"],
+        "cost": "36 credits/sec",
+        "description": "Reference image and video, long duration (up to 15s)",
+        "input": "Text, Image, and/or Video",
+    },
+    "gen4.5": {
+        "endpoints": ["text_to_video", "image_to_video"],
+        "cost": "12 credits/sec",
+        "description": "High quality, general purpose",
+        "input": "Text and/or Image",
+    },
+    "gen4_turbo": {
+        "endpoints": ["image_to_video"],
+        "cost": "5 credits/sec",
+        "description": "Fast, image-driven (image required)",
+        "input": "Image required",
+    },
+    "gen4_aleph": {
+        "endpoints": ["video_to_video"],
+        "cost": "15 credits/sec",
+        "description": "Video editing/transformation",
+        "input": "Video + Text/Image",
+    },
+    "veo3": {
+        "endpoints": ["text_to_video", "image_to_video"],
+        "cost": "40 credits/sec",
+        "description": "Premium quality",
+        "input": "Text/Image",
+        "durations": [8],
+    },
+    "veo3.1": {
+        "endpoints": ["text_to_video", "image_to_video"],
+        "cost": "20-40 credits/sec",
+        "description": "High quality Google model",
+        "input": "Text/Image",
+        "durations": [4, 6, 8],
+    },
+    "veo3.1_fast": {
+        "endpoints": ["text_to_video", "image_to_video"],
+        "cost": "10-15 credits/sec",
+        "description": "Fast Google model",
+        "input": "Text/Image",
+        "durations": [4, 6, 8],
+    },
+}
+
+IMAGE_MODELS = {
+    "gen4_image": {
+        "endpoint": "text_to_image",
+        "cost": "5-8 credits",
+        "description": "Highest quality",
+    },
+    "gen4_image_turbo": {
+        "endpoint": "text_to_image",
+        "cost": "2 credits",
+        "description": "Fast and cheap",
+    },
+    "gemini_2.5_flash": {
+        "endpoint": "text_to_image",
+        "cost": "5 credits",
+        "description": "Google Gemini model",
+    },
+}
+
+AUDIO_MODELS = {
+    "eleven_multilingual_v2": {
+        "endpoint": "text_to_speech",
+        "cost": "1 credit/50 chars",
+        "description": "Text to speech",
+    },
+    "eleven_text_to_sound_v2": {
+        "endpoint": "sound_effect",
+        "cost": "1-2 credits",
+        "description": "Sound effect generation",
+    },
+    "eleven_voice_isolation": {
+        "endpoint": "voice_isolation",
+        "cost": "1 credit/6 sec",
+        "description": "Isolate voice from audio",
+    },
+    "eleven_voice_dubbing": {
+        "endpoint": "voice_dubbing",
+        "cost": "1 credit/2 sec",
+        "description": "Dub to other languages",
+    },
+    "eleven_multilingual_sts_v2": {
+        "endpoint": "speech_to_speech",
+        "cost": "1 credit/3 sec",
+        "description": "Voice conversion",
+    },
+}
+
+# - API key -
+
+def get_api_key():
+    """Read the API key from RUNWAYML_API_SECRET. CLI flags are not supported to avoid exposing
+    the secret in shell history or process lists."""
+    key = os.environ.get("RUNWAYML_API_SECRET")
+    if not key:
+        print(
+            "Error: RUNWAYML_API_SECRET is not set.\n"
+            "Export it in your shell (e.g. `export RUNWAYML_API_SECRET=...`) - do not pass keys as CLI flags.\n"
+            "Get your key at https://dev.runwayml.com/",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    return key
+
+
+def _headers(api_key):
+    return {
+        "Authorization": f"Bearer {api_key}",
+        "X-Runway-Version": API_VERSION,
+        "Content-Type": "application/json",
+    }
+
+# - Error formatting -
+
+def format_api_error(status_code, response_text):
+    msg = f"API error {status_code}"
+    try:
+        data = json.loads(response_text)
+        error = data.get("error", data.get("message", ""))
+        issues = data.get("issues", [])
+    except (json.JSONDecodeError, TypeError):
+        error = response_text[:500] if response_text else ""
+        issues = []
+
+    if status_code == 400:
+        detail = error
+        if issues:
+            parts = [f"{i.get('path', ['?'])[-1]}: {i.get('message', '')}" for i in issues]
+            detail = f"{error} [{'; '.join(parts)}]"
+        return f"{msg}: Invalid input - {detail}"
+    elif status_code == 401:
+        return f"{msg}: Authentication failed. Check RUNWAYML_API_SECRET."
+    elif status_code == 429:
+        return f"{msg}: Rate limited. Will retry..."
+    elif status_code in (502, 503, 504):
+        return f"{msg}: Server overload. Will retry..."
+    return f"{msg}: {error}"
+
+# - API calls with retry -
+
+def api_post(api_key, endpoint, body, max_retries=3):
+    """POST to the Runway API with automatic retry on 429/5xx."""
+    headers = _headers(api_key)
+    delays = [5, 15, 45]
+
+    for attempt in range(max_retries + 1):
+        r = requests.post(f"{API_BASE}{endpoint}", headers=headers, json=body)
+        if r.ok:
+            return r.json()
+        if r.status_code in (429, 502, 503, 504) and attempt < max_retries:
+            delay = delays[min(attempt, len(delays) - 1)]
+            print(
+                f"  {format_api_error(r.status_code, r.text)}\n"
+                f"  Retrying in {delay}s (attempt {attempt + 1}/{max_retries})...",
+                file=sys.stderr,
+            )
+            time.sleep(delay)
+            continue
+        msg = format_api_error(r.status_code, r.text)
+        print(f"Error: {msg}", file=sys.stderr)
+        sys.exit(1)
+
+
+def api_get(api_key, path, max_retries=3):
+    """GET from the Runway API with automatic retry on 429/5xx."""
+    headers = _headers(api_key)
+    delays = [5, 15, 45]
+
+    for attempt in range(max_retries + 1):
+        r = requests.get(f"{API_BASE}{path}", headers=headers)
+        if r.ok:
+            return r.json()
+        if r.status_code in (429, 502, 503, 504) and attempt < max_retries:
+            delay = delays[min(attempt, len(delays) - 1)]
+            print(f"  Retrying in {delay}s...", file=sys.stderr)
+            time.sleep(delay)
+            continue
+        msg = format_api_error(r.status_code, r.text)
+        print(f"Error: {msg}", file=sys.stderr)
+        sys.exit(1)
+
+# - Task polling -
+
+def poll_task(api_key, task_id, interval=5, timeout=600):
+    """Poll a Runway task until it reaches a terminal state."""
+    start = time.time()
+    while time.time() - start < timeout:
+        task = api_get(api_key, f"/v1/tasks/{task_id}")
+        status = task.get("status", "")
+
+        if status == "SUCCEEDED":
+            return task
+        if status == "FAILED":
+            failure = task.get("failure", "Unknown error")
+            failure_code = task.get("failureCode", "")
+            detail = f"{failure_code}: {failure}" if failure_code else str(failure)
+            print(f"Error: Task failed - {detail}", file=sys.stderr)
+            sys.exit(1)
+        if status == "CANCELLED":
+            print("Error: Task was cancelled.", file=sys.stderr)
+            sys.exit(1)
+
+        elapsed = int(time.time() - start)
+        print(f"  [{task_id[:12]}] {status} ({elapsed}s)...", file=sys.stderr)
+        time.sleep(interval)
+
+    print(f"Error: Task timed out after {timeout}s.", file=sys.stderr)
+    sys.exit(1)
+
+# - File download -
+
+def download_file(url, filename):
+    """Download a URL to a local file."""
+    parent = os.path.dirname(filename)
+    if parent:
+        os.makedirs(parent, exist_ok=True)
+    r = requests.get(url, stream=True)
+    r.raise_for_status()
+    with open(filename, "wb") as f:
+        for chunk in r.iter_content(chunk_size=8192):
+            f.write(chunk)
+    return os.path.abspath(filename)
+
+# - Upload helper -
+
+def upload_file(api_key, local_path):
+    """Upload a local file to Runway and return the runway:// URI.
+
+    Two-step process:
+    1. POST /v1/uploads with filename to get a presigned uploadUrl + fields + runwayUri
+    2. POST the file to uploadUrl with the returned fields as multipart form data
+    """
+    if not os.path.isfile(local_path):
+        print(f"Error: File not found: {local_path}", file=sys.stderr)
+        sys.exit(1)
+
+    filename = os.path.basename(local_path)
+
+    r = requests.post(
+        f"{API_BASE}/v1/uploads",
+        headers=_headers(api_key),
+        json={"filename": filename, "type": "ephemeral"},
+    )
+    if not r.ok:
+        msg = format_api_error(r.status_code, r.text)
+        print(f"Error creating upload: {msg}", file=sys.stderr)
+        sys.exit(1)
+
+    data = r.json()
+    upload_url = data.get("uploadUrl")
+    fields = data.get("fields", {})
+    runway_uri = data.get("runwayUri")
+
+    if not upload_url or not runway_uri:
+        print(f"Error: Upload response missing uploadUrl or runwayUri: {json.dumps(data)}", file=sys.stderr)
+        sys.exit(1)
+
+    mime_type = mimetypes.guess_type(local_path)[0] or "application/octet-stream"
+    with open(local_path, "rb") as f:
+        r2 = requests.post(
+            upload_url,
+            data=fields,
+            files={"file": (filename, f, mime_type)},
+        )
+
+    if not r2.ok:
+        print(f"Error uploading file: {r2.status_code} {r2.text[:500]}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"  Uploaded: {runway_uri}", file=sys.stderr)
+    return runway_uri
+
+
+def _assert_safe_media_url(url):
+    """Validate an external media URL before sending it to the Runway API.
+
+    Rejects non-http(s) schemes (e.g. file://, data:) and, when
+    RUNWAY_ALLOWED_MEDIA_HOSTS is set, enforces a comma-separated host allowlist.
+    Prefer uploading local files (which produce runway:// URIs) over passing
+    arbitrary external URLs - see the `rw-integrate-uploads` skill.
+    """
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        print(
+            f"Error: Unsupported URL scheme '{parsed.scheme}://'. "
+            "Only http(s) URLs or runway:// URIs from uploads are allowed.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    if not parsed.netloc:
+        print(f"Error: URL has no host: {url}", file=sys.stderr)
+        sys.exit(1)
+
+    allowlist = os.environ.get("RUNWAY_ALLOWED_MEDIA_HOSTS", "").strip()
+    if allowlist:
+        allowed = {h.strip().lower() for h in allowlist.split(",") if h.strip()}
+        host = parsed.hostname.lower() if parsed.hostname else ""
+        if host not in allowed:
+            print(
+                f"Error: Host '{host}' is not in RUNWAY_ALLOWED_MEDIA_HOSTS.\n"
+                f"Allowed: {', '.join(sorted(allowed))}",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+    if parsed.scheme == "http":
+        print(
+            f"  Warning: Using insecure http:// URL ({parsed.hostname}). Prefer https or upload the file.",
+            file=sys.stderr,
+        )
+
+
+def ensure_url(path_or_url, api_key):
+    """Resolve a user-supplied input to a URI the API can fetch.
+
+    - runway:// URIs pass through.
+    - http(s) URLs are validated (see `_assert_safe_media_url`) then passed through.
+    - Anything else is treated as a local file path and uploaded.
+    """
+    if path_or_url.startswith("runway://"):
+        return path_or_url
+    if path_or_url.startswith("http://") or path_or_url.startswith("https://"):
+        _assert_safe_media_url(path_or_url)
+        return path_or_url
+    return upload_file(api_key, path_or_url)
+
+# - Output path helper -
+
+def output_path(filename, output_dir=None):
+    if output_dir:
+        os.makedirs(output_dir, exist_ok=True)
+        return os.path.join(output_dir, os.path.basename(filename))
+    return filename
+
+# - Cost estimation -
+
+def estimate_video_credits(model, duration):
+    """Rough credit estimate for a video generation."""
+    cost_str = VIDEO_MODELS.get(model, {}).get("cost", "")
+    try:
+        per_sec = int(cost_str.split()[0].replace("-", "").strip("~"))
+    except (ValueError, IndexError):
+        return None
+    return per_sec * duration
+
+
+def estimate_image_credits(model):
+    cost_str = IMAGE_MODELS.get(model, {}).get("cost", "")
+    try:
+        return int(cost_str.split()[0].replace("-", "").strip("~"))
+    except (ValueError, IndexError):
+        return None
+
+# - Desktop notification -
+
+def send_notification(title, message):
+    try:
+        system = platform.system()
+        if system == "Linux" and shutil.which("notify-send"):
+            subprocess.run(["notify-send", title, message], timeout=5)
+        elif system == "Darwin":
+            script = f'display notification "{message}" with title "{title}"'
+            subprocess.run(["osascript", "-e", script], timeout=5)
+        else:
+            print("\a", end="", file=sys.stderr)
+    except Exception:
+        pass
diff --git a/plugins/runway-api/skills/rw-api-reference/SKILL.md b/plugins/runway-api/skills/rw-api-reference/SKILL.md
new file mode 100644
index 00000000..cd101f8a
--- /dev/null
+++ b/plugins/runway-api/skills/rw-api-reference/SKILL.md
@@ -0,0 +1,423 @@
+---
+name: rw-api-reference
+description: "Complete reference for Runway's public API: models, endpoints, costs, limits, and types"
+user-invocable: false
+---
+
+# Runway Public API Reference
+
+> PREREQUISITE: Run `rw-check-compatibility` first to ensure the project has server-side capability.
+
+Base URL: `https://api.dev.runwayml.com`
+
+All requests require these headers:
+```
+Authorization: Bearer <RUNWAYML_API_SECRET>
+X-Runway-Version: 2024-11-06
+```
+
+---
+
+## Models & Endpoints
+
+### Video Generation
+
+| Model | Endpoint | Input | Cost (credits/sec) |
+|-------|----------|-------|---------------------|
+| `gen4.5` | `POST /v1/image_to_video` or `POST /v1/text_to_video` | Text and/or Image | 12 |
+| `gen4_turbo` | `POST /v1/image_to_video` | Image required | 5 |
+| `gen4_aleph` | `POST /v1/video_to_video` | Video + Text/Image | 15 |
+| `act_two` | `POST /v1/character_performance` | Image/Video | 5 |
+| `veo3` | `POST /v1/image_to_video` or `POST /v1/text_to_video` | Text/Image | 40 |
+| `veo3.1` | `POST /v1/image_to_video` or `POST /v1/text_to_video` | Text/Image | 20-40 |
+| `veo3.1_fast` | `POST /v1/image_to_video` or `POST /v1/text_to_video` | Text/Image | 10-15 |
+| `seedance2` | `POST /v1/text_to_video`, `POST /v1/image_to_video`, or `POST /v1/video_to_video` | Text, Image, and/or Video | 36 |
+
+Video duration: 2-15 seconds (model-dependent). Aspect ratios are pixel-based: `1280:720`, `720:1280`, `1104:832`, `960:960`, `832:1104`, `1584:672`, etc.
+
+Seedance 2 specifics:
+- Modes: text-to-video, image-to-video (first/last frame or image reference), video-to-video
+- Duration: required for TTV and ITV (in seconds)
+- Aspect ratios (pixel-based): `1280:720`, `720:1280`, `960:960`, `1112:834`, `834:1112`, `1470:630`, `992:432`, `864:496`, `752:560`, `640:640`, `560:752`, `496:864`
+- ITV supports two mutually exclusive modes: first/last frame (`promptImage` array with `position`) or image reference (`references` array)
+- VTV input requirements: max 15 seconds, max 32 MB, min 720p resolution, MP4 recommended
+
+### Image Generation
+
+| Model | Endpoint | Cost (credits) |
+|-------|----------|----------------|
+| `gen4_image` | `POST /v1/text_to_image` | 5 (720p), 8 (1080p) |
+| `gen4_image_turbo` | `POST /v1/text_to_image` | 2 |
+| `gemini_2.5_flash` | `POST /v1/text_to_image` | 5 |
+
+### Audio Generation
+
+| Model | Endpoint | Use Case | Cost |
+|-------|----------|----------|------|
+| `eleven_multilingual_v2` | `POST /v1/text_to_speech` | Text to speech | 1 credit/50 chars |
+| `eleven_text_to_sound_v2` | `POST /v1/sound_effect` | Sound effects | 1-2 credits |
+| `eleven_voice_isolation` | `POST /v1/voice_isolation` | Isolate voice from audio | 1 credit/6 sec |
+| `eleven_voice_dubbing` | `POST /v1/voice_dubbing` | Dub audio to other languages | 1 credit/2 sec |
+| `eleven_multilingual_sts_v2` | `POST /v1/speech_to_speech` | Voice conversion | 1 credit/3 sec |
+
+### Characters (Real-Time Avatars)
+
+| Model | Description | Session Max Duration |
+|-------|-------------|----------------------|
+| `gwm1_avatars` | Real-time conversational avatars powered by GWM-1 | 5 minutes |
+
+Endpoints:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/v1/avatars` | Create a new Avatar |
+| `GET` | `/v1/avatars/{id}` | Retrieve an Avatar |
+| `PATCH` | `/v1/avatars/{id}` | Update an Avatar (name, voice, personality, documentIds) |
+| `DELETE` | `/v1/avatars/{id}` | Delete an Avatar |
+| `POST` | `/v1/realtime_sessions` | Create a new real-time session |
+| `GET` | `/v1/realtime_sessions/{id}` | Retrieve session status (poll until `READY`) |
+| `POST` | `/v1/realtime_sessions/{id}/consume` | Consume session credentials for WebRTC (one-time use) |
+
+Avatar creation parameters:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | string | Display name for the avatar |
+| `referenceImage` | string | URL or `runway://` URI of the character image |
+| `voice` | object | `{ type: 'runway-live-preset', presetId: 'clara' }` |
+| `personality` | string | System prompt / personality instructions |
+| `documentIds` | string[] | Optional. IDs of knowledge base documents to attach |
+
+Voice presets: `clara` (soft), `victoria` (firm), `vincent` (authoritative). Preview all at [dev.runwayml.com](https://dev.runwayml.com/).
+
+Session statuses: `NOT_READY` -> `READY` -> `RUNNING` -> `COMPLETED` (or `FAILED` / `CANCELLED`)
+
+### Documents (Knowledge Base)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/v1/documents` | Create a document (plain text or Markdown) |
+| `GET` | `/v1/documents/{id}` | Retrieve a document |
+| `DELETE` | `/v1/documents/{id}` | Delete a document |
+
+Each Avatar supports up to 50,000 tokens of knowledge. Link documents to an Avatar via `client.avatars.update(id, { documentIds: [...] })`.
+
+---
+
+## Request Body Reference (raw JSON)
+
+Use these when calling the API directly (e.g. through `use-runway-api`'s `request` command) rather than via an SDK. Only required + common fields shown - consult `rw-fetch-api-reference` for the full schema.
+
+### `POST /v1/text_to_image`
+
+```json
+{
+  "model": "gen4_image",
+  "promptText": "A serene Japanese garden with cherry blossoms",
+  "ratio": "1920:1080"
+}
+```
+
+- `model`: `gen4_image` | `gen4_image_turbo` | `gemini_2.5_flash` (required)
+- `promptText`: string, up to ~1000 chars (required)
+- `ratio`: one of `1920:1080`, `1080:1920`, `1024:1024`, `1360:768`, `1080:1080`, `1168:880`, `1440:1080`, `1080:1440`, `1808:768`, `2112:912` (required; 720p or 1080p variants depending on model)
+- `referenceImages`: optional `[{ "uri": "https://...", "tag": "MyTag" }]` - reference by `@MyTag` in `promptText`
+- `seed`: optional integer for reproducibility
+
+### `POST /v1/text_to_video`
+
+```json
+{
+  "model": "gen4.5",
+  "promptText": "A golden retriever running through wildflowers at sunset",
+  "ratio": "1280:720",
+  "duration": 5
+}
+```
+
+- `model`: `gen4.5` | `veo3` | `veo3.1` | `veo3.1_fast` | `seedance2` (required)
+- `duration`: integer seconds, 2-10 (required; model-specific valid values - e.g. veo3 only accepts 8)
+- `ratio`: e.g. `1280:720`, `720:1280`, `1104:832`, `832:1104`, `960:960` (required)
+
+### `POST /v1/image_to_video`
+
+```json
+{
+  "model": "gen4.5",
+  "promptImage": "https://example.com/cover.jpg",
+  "promptText": "A slow dolly-in shot",
+  "ratio": "1280:720",
+  "duration": 5
+}
+```
+
+- `model`: `gen4.5` | `gen4_turbo` | `veo3` | `veo3.1` | `veo3.1_fast` | `seedance2` (required)
+- `promptImage`: HTTPS URL, data URI, or `runway://` URI (required). Can also be `[{ "uri": "...", "position": "first" | "last" }]` for keyframes.
+- `promptText`: optional for most models, required for `gen4_turbo` when no image motion is obvious
+
+### `POST /v1/video_to_video`
+
+```json
+{
+  "model": "gen4_aleph",
+  "videoUri": "https://example.com/source.mp4",
+  "promptText": "Change the season to winter with snowfall",
+  "ratio": "1280:720"
+}
+```
+
+### `POST /v1/text_to_speech`
+
+```json
+{
+  "model": "eleven_multilingual_v2",
+  "promptText": "Hello, welcome to Runway.",
+  "voice": { "type": "runway-preset", "presetId": "Maya" }
+}
+```
+
+- `voice`: `{ type: "runway-preset", presetId: "Maya" | "Noah" | "Leslie" | ... }` or a provider-specific voice object
+- `languageCode`: optional ISO code (auto-detected by default)
+
+### `POST /v1/sound_effect`
+
+```json
+{
+  "model": "eleven_text_to_sound_v2",
+  "promptText": "Thunderclap followed by heavy rain",
+  "duration": 5
+}
+```
+
+### `POST /v1/voice_isolation`
+
+```json
+{
+  "model": "eleven_voice_isolation",
+  "audioUri": "https://example.com/noisy.mp3"
+}
+```
+
+### `POST /v1/voice_dubbing`
+
+```json
+{
+  "model": "eleven_voice_dubbing",
+  "audioUri": "https://example.com/english.mp3",
+  "targetLang": "es"
+}
+```
+
+### `POST /v1/speech_to_speech`
+
+```json
+{
+  "model": "eleven_multilingual_sts_v2",
+  "media": { "type": "audio", "uri": "https://example.com/source.mp3" },
+  "voice": { "type": "runway-preset", "presetId": "Maya" }
+}
+```
+
+### `POST /v1/avatars`
+
+```json
+{
+  "name": "Support Agent",
+  "referenceImage": "https://example.com/portrait.jpg",
+  "voice": { "type": "runway-live-preset", "presetId": "clara" },
+  "personality": "You are a friendly support agent.",
+  "documentIds": []
+}
+```
+
+### `POST /v1/documents`
+
+```json
+{
+  "avatarId": "<avatar-id>",
+  "name": "FAQ",
+  "content": "Q: What is your return policy?\nA: 30 days, no questions asked."
+}
+```
+
+### `POST /v1/realtime_sessions`
+
+```json
+{
+  "avatarId": "<avatar-id>"
+}
+```
+
+---
+
+### Management Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/v1/tasks/{id}` | Get task status and output |
+| `DELETE` | `/v1/tasks/{id}` | Cancel/delete a task |
+| `POST` | `/v1/uploads` | Create ephemeral upload |
+| `GET` | `/v1/organization` | Organization info & credit balance |
+| `POST` | `/v1/organization/usage` | Credit usage history (up to 90 days) |
+
+---
+
+## Task Lifecycle
+
+All generation endpoints return a task object. The flow is:
+
+1. Submit - `POST /v1/<endpoint>` -> returns `{ "id": "task_xxx" }`
+2. Poll - `GET /v1/tasks/{id}` -> returns task with `status`
+3. Retrieve output - When `status === "SUCCEEDED"`, the `output` array contains signed URLs
+
+### Task Statuses
+
+| Status | Meaning |
+|--------|---------|
+| `PENDING` | Queued, waiting to start |
+| `RUNNING` | Currently generating |
+| `SUCCEEDED` | Complete - output URLs available |
+| `FAILED` | Generation failed - check `failure` field |
+| `THROTTLED` | Concurrency limit hit - auto-queued |
+
+### SDK Polling (Recommended)
+
+The SDKs provide a `waitForTaskOutput()` method that handles polling automatically:
+
+```javascript
+// Node.js - polls until complete (default 10 min timeout)
+const task = await client.imageToVideo.create({
+  model: 'gen4.5',
+  promptImage: 'https://example.com/image.jpg',
+  promptText: 'A sunset timelapse',
+  ratio: '1280:720',
+  duration: 5
+}).waitForTaskOutput();
+
+console.log(task.output); // Array of signed URLs
+```
+
+```python
+# Python
+task = client.image_to_video.create(
+    model='gen4.5',
+    prompt_image='https://example.com/image.jpg',
+    prompt_text='A sunset timelapse',
+    ratio='1280:720',
+    duration=5
+).wait_for_task_output()
+
+print(task.output)
+```
+
+### Manual Polling (REST)
+
+```javascript
+async function pollTask(taskId) {
+  while (true) {
+    const response = await fetch(`https://api.dev.runwayml.com/v1/tasks/${taskId}`, {
+      headers: {
+        'Authorization': `Bearer ${process.env.RUNWAYML_API_SECRET}`,
+        'X-Runway-Version': '2024-11-06'
+      }
+    });
+    const task = await response.json();
+
+    if (task.status === 'SUCCEEDED') return task;
+    if (task.status === 'FAILED') throw new Error(task.failure);
+
+    await new Promise(r => setTimeout(r, 5000)); // poll every 5 seconds
+  }
+}
+```
+
+---
+
+## Output Handling
+
+- Successful tasks return an `output` array with signed URLs to generated content
+- Output URLs expire within 24-48 hours
+- Download and store outputs in your own storage - do not serve signed URLs to end users
+- Video outputs are MP4, image outputs are PNG/JPEG
+
+---
+
+## Input Requirements
+
+### Size Limits
+
+| Type | Via URL | Via Data URI | Via Upload |
+|------|---------|-------------|------------|
+| Image | 16 MB | 5 MB | 200 MB |
+| Video | 32 MB | 16 MB | 200 MB |
+| Audio | 32 MB | 16 MB | 200 MB |
+
+### Supported Formats
+
+- Images: JPEG, PNG, WebP (no GIF)
+- Video codecs: H.264, H.265/HEVC, AV1, VP8/VP9, Apple ProRes, Theora
+- Audio: MP3, AAC, FLAC, PCM, ALAC
+
+### URL Requirements
+
+If providing assets via URL:
+- HTTPS only (no HTTP)
+- Domain names only (no IP addresses)
+- No redirects
+- Must support HTTP HEAD requests
+- Must return valid `Content-Type` and `Content-Length` headers
+- Max URL length: 2,048 characters
+
+---
+
+## Rate Limits & Tiers
+
+| Tier | Concurrency | Daily Gens | Monthly Cap | Unlock |
+|------|-------------|------------|-------------|--------|
+| 1 (default) | 1-2 | 50-200 | $100 | - |
+| 2 | 3 | 500-1,000 | $500 | 1 day + $50 |
+| 3 | 5 | 1,000-2,000 | $2,000 | 7 days + $100 |
+| 4 | 10 | 5,000-10,000 | $20,000 | 14 days + $1,000 |
+| 5 | 20 | 25,000-30,000 | $100,000 | 7 days + $5,000 |
+
+- No requests-per-minute limit - only daily generation quotas
+- Exceeding concurrency -> `THROTTLED` status (auto-queued, not rejected)
+- Exceeding daily limit -> `429 Too Many Requests`
+- Daily limits use a rolling 24-hour window
+
+---
+
+## Error Handling
+
+### HTTP Errors
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| 400 | Input validation failure | Fix input, do not retry |
+| 401 | Invalid API key | Check key, do not retry |
+| 429 | Rate limited | Retry with exponential backoff + jitter |
+| 502/503/504 | Server overload | Retry with exponential backoff + jitter |
+
+### Task Failure Codes
+
+| Code | Meaning | Retry? |
+|------|---------|--------|
+| `SAFETY.INPUT.*` | Input content moderation | No - not refundable |
+| `SAFETY.OUTPUT.*` | Output content moderation | Yes - try different prompt |
+| `INTERNAL.BAD_OUTPUT` | Quality issue | Yes |
+| `ASSET.INVALID` | Bad input format | Fix input |
+| `INTERNAL` | Server error | Yes |
+
+The SDKs handle retries for transient errors automatically.
+
+---
+
+## Data URI Support
+
+Base64-encoded images can be passed instead of URLs:
+
+```
+data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
+```
+
+Useful for small images or when you don't want to host the file. Subject to the data URI size limits above.
diff --git a/plugins/runway-api/skills/rw-check-compatibility/SKILL.md b/plugins/runway-api/skills/rw-check-compatibility/SKILL.md
new file mode 100644
index 00000000..a613c4e0
--- /dev/null
+++ b/plugins/runway-api/skills/rw-check-compatibility/SKILL.md
@@ -0,0 +1,116 @@
+---
+name: rw-check-compatibility
+description: "Analyze a user's codebase to verify it can use Runway's public API (server-side requirement)"
+user-invocable: false
+---
+
+# Check Compatibility
+
+Analyze the user's project to determine whether it is compatible with Runway's public API.
+
+## Why This Matters
+
+Runway's public API requires server-side invocation. The API key must never be exposed in client-side code. Projects that are purely frontend (static HTML/JS, client-only SPAs without a backend) cannot safely call the API.
+
+## Analysis Steps
+
+### Step 1: Identify the Project Type
+
+Search the project root for these files to determine the stack:
+
+| File | Indicates |
+|------|-----------|
+| `package.json` | Node.js project |
+| `requirements.txt`, `pyproject.toml`, `Pipfile`, `setup.py` | Python project |
+| `go.mod` | Go project |
+| `Cargo.toml` | Rust project |
+| `pom.xml`, `build.gradle` | Java/Kotlin project |
+| `Gemfile` | Ruby project |
+| `composer.json` | PHP project |
+
+If none of these exist, flag the project as unknown and ask the user what language/runtime they're using.
+
+### Step 2: Check for Server-Side Capability
+
+Look for indicators of a server/backend:
+
+Node.js projects - check `package.json` dependencies for:
+- `express`, `fastify`, `koa`, `hapi`, `nest`, `hono` -> HTTP server framework
+- `next` -> Next.js (has API routes - compatible)
+- `nuxt` -> Nuxt.js (has server routes - compatible)
+- `remix` -> Remix (has loaders/actions - compatible)
+- `@sveltejs/kit` -> SvelteKit (has server routes - compatible)
+- `astro` -> Astro (has API endpoints if SSR enabled)
+
+Python projects - check for:
+- `flask`, `django`, `fastapi`, `starlette`, `tornado`, `aiohttp`, `sanic` -> web server framework
+- `streamlit`, `gradio` -> can make server-side calls
+
+Red flags (frontend-only):
+- `package.json` with only `react`, `vue`, `svelte`, `angular` and NO server framework
+- `vite.config.ts` or `webpack.config.js` with no server/SSR configuration
+- Static site generators without server routes (e.g., plain Gatsby, plain Eleventy)
+- `index.html` as the only entry point with inline `<script>` tags
+
+### Step 3: Check for Existing Runway SDK
+
+Search for existing Runway SDK installations:
+
+Node.js:
+- Check `package.json` for `@runwayml/sdk`
+- Search for `import RunwayML` or `require('@runwayml/sdk')` in source files
+
+Python:
+- Check `requirements.txt` / `pyproject.toml` for `runwayml`
+- Search for `from runwayml import RunwayML` or `import runwayml` in source files
+
+### Step 4: Check Runtime Version
+
+Node.js: Must be version 18 or higher (`node --version`)
+Python: Must be version 3.8 or higher (`python3 --version`)
+
+### Step 5: Check for Environment Variable Support
+
+Look for `.env` file, `.env.example`, `.env.local`, or dotenv configuration:
+- Node.js: `dotenv` in dependencies, or framework-native env support (Next.js, etc.)
+- Python: `python-dotenv` in dependencies, or framework-native support
+
+## Report Format
+
+After analysis, provide a clear report:
+
+```
+## Runway API Compatibility Report
+
+Project type: [Node.js / Python / etc.]
+Server-side capable: [Yes / No / Partial]
+Runtime version: [version] - [Compatible / Needs upgrade]
+Runway SDK installed: [Yes / No]
+Environment variable support: [Yes / No / Needs setup]
+
+### Verdict: [COMPATIBLE / NEEDS CHANGES / INCOMPATIBLE]
+
+[If COMPATIBLE]
+Your project is ready for Runway API integration. Proceed with API key setup.
+
+[If NEEDS CHANGES]
+Your project needs the following changes:
+1. [List specific changes needed]
+
+[If INCOMPATIBLE]
+Your project is frontend-only and cannot safely call Runway's API. Options:
+1. Add a backend - Add an Express/FastAPI server or use a framework with server routes (Next.js, SvelteKit, etc.)
+2. Use a serverless function - Add API routes via Vercel Functions, AWS Lambda, Cloudflare Workers, etc.
+3. Create a separate backend - Build a thin API proxy that your frontend calls
+```
+
+## Important Notes
+
+- Never suggest embedding the API key in client-side code. This is a security risk.
+- If the project uses Next.js, Remix, SvelteKit, Nuxt, or Astro with SSR, it IS compatible - the server-side route handlers can call the API.
+- Serverless platforms (Vercel, Netlify, AWS Lambda, Cloudflare Workers) are compatible.
+- Docker/containerized apps are compatible if they run a server process.
+
+## After Compatibility Check
+
+If the project is compatible, suggest the user proceed with `rw-setup-api-key` to configure their API credentials.
diff --git a/plugins/runway-api/skills/rw-check-org-details/SKILL.md b/plugins/runway-api/skills/rw-check-org-details/SKILL.md
new file mode 100644
index 00000000..4c2de91b
--- /dev/null
+++ b/plugins/runway-api/skills/rw-check-org-details/SKILL.md
@@ -0,0 +1,206 @@
+---
+name: rw-check-org-details
+description: "Query the Runway API for organization details: rate limits, credit balance, usage tier, and daily generation counts"
+user-invocable: true
+---
+
+# Check Organization Details
+
+> PREREQUISITE: Run `rw-setup-api-key` first to ensure the API key is configured.
+
+Query the Runway API to retrieve the user's organization details - credit balance, usage tier, rate limits, current daily generation counts, and historical credit usage.
+
+## Step 1: Verify API Key Is Available
+
+Before making any requests, confirm the API key is accessible:
+
+1. Check for a `.env` file containing `RUNWAYML_API_SECRET`
+2. Or quietly check whether the environment variable exists: `test -n "${RUNWAYML_API_SECRET:-}"`
+
+If the key is not found, tell the user to run `rw-setup-api-key` first and stop.
+
+## Step 2: Query Organization Info
+
+Call `GET /v1/organization` to retrieve the org's tier, credit balance, and current usage.
+
+### Node.js
+
+```javascript
+import RunwayML from '@runwayml/sdk';
+
+const client = new RunwayML();
+const details = await client.organization.retrieve();
+console.log(JSON.stringify(details, null, 2));
+```
+
+### Python
+
+```python
+from runwayml import RunwayML
+
+client = RunwayML()
+details = client.organization.retrieve()
+print(details)
+```
+
+### Node.js fetch (no SDK)
+
+```bash
+node <<'NODE'
+const apiKey = process.env.RUNWAYML_API_SECRET ?? process.env.RUNWAY_SKILLS_API_SECRET;
+if (!apiKey) throw new Error("RUNWAYML_API_SECRET is not set");
+const response = await fetch("https://api.dev.runwayml.com/v1/organization", {
+  headers: {
+    Authorization: `Bearer ${apiKey}`,
+    "X-Runway-Version": "2024-11-06",
+  },
+});
+console.log(JSON.stringify(await response.json(), null, 2));
+NODE
+```
+
+### Response Shape
+
+```json
+{
+  "tier": {
+    "maxMonthlyCreditSpend": 10000,
+    "models": {
+      "gen4.5": {
+        "maxConcurrentGenerations": 2,
+        "maxDailyGenerations": 200
+      }
+    }
+  },
+  "creditBalance": 5000,
+  "usage": {
+    "models": {
+      "gen4.5": {
+        "dailyGenerations": 12
+      }
+    }
+  }
+}
+```
+
+## Step 3: Present the Results
+
+Format the output as a clear summary for the user:
+
+```
+## Organization Overview
+
+Credit Balance: X credits ($X.XX at $0.01/credit)
+Monthly Spend Cap: X credits
+
+### Rate Limits (by model)
+
+| Model | Concurrency | Daily Limit | Used Today | Remaining |
+|-------|-------------|-------------|------------|-----------|
+| gen4.5 | 2 | 200 | 12 | 188 |
+| veo3.1 | 2 | 100 | 5 | 95 |
+| ... | ... | ... | ... | ... |
+```
+
+Key things to highlight:
+- Credit balance - convert to dollar value (`credits x $0.01`)
+- Per-model daily limits - show how many generations remain today (rolling 24-hour window)
+- Concurrency - how many tasks can run simultaneously per model
+- Monthly cap - the max credit spend per month for their tier
+
+## Step 4 (Optional): Query Credit Usage History
+
+If the user wants to see historical usage, call `POST /v1/organization/usage`.
+
+### Node.js
+
+```javascript
+const usage = await client.organization.retrieveUsage({
+  startDate: '2026-02-15',   // ISO-8601, up to 90 days back
+  beforeDate: '2026-03-17'   // exclusive end date
+});
+console.log(JSON.stringify(usage, null, 2));
+```
+
+### Python
+
+```python
+usage = client.organization.retrieve_usage(
+    start_date="2026-02-15",
+    before_date="2026-03-17"
+)
+print(usage)
+```
+
+### Node.js fetch (no SDK)
+
+```bash
+node <<'NODE'
+const apiKey = process.env.RUNWAYML_API_SECRET ?? process.env.RUNWAY_SKILLS_API_SECRET;
+if (!apiKey) throw new Error("RUNWAYML_API_SECRET is not set");
+const response = await fetch("https://api.dev.runwayml.com/v1/organization/usage", {
+  method: "POST",
+  headers: {
+    Authorization: `Bearer ${apiKey}`,
+    "X-Runway-Version": "2024-11-06",
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({ startDate: "2026-02-15", beforeDate: "2026-03-17" }),
+});
+console.log(JSON.stringify(await response.json(), null, 2));
+NODE
+```
+
+### Response Shape
+
+```json
+{
+  "results": [
+    {
+      "date": "2026-03-16",
+      "usedCredits": [
+        { "model": "gen4.5", "amount": 120 },
+        { "model": "veo3.1", "amount": 400 }
+      ]
+    }
+  ],
+  "models": ["gen4.5", "veo3.1"]
+}
+```
+
+Present this as a usage breakdown:
+
+```
+### Credit Usage (Feb 15 - Mar 17)
+
+| Date | Model | Credits Used |
+|------|-------|-------------|
+| 2026-03-16 | gen4.5 | 120 |
+| 2026-03-16 | veo3.1 | 400 |
+| ... | ... | ... |
+
+Total: X credits
+```
+
+## Tier Reference
+
+If the user asks about upgrading, share the tier breakdown:
+
+| Tier | Concurrency | Daily Gens | Monthly Cap | Unlock Requirement |
+|------|-------------|------------|-------------|---------------------|
+| 1 (default) | 1-2 | 50-200 | $100 | - |
+| 2 | 3 | 500-1,000 | $500 | 1 day + $50 spent |
+| 3 | 5 | 1,000-2,000 | $2,000 | 7 days + $100 spent |
+| 4 | 10 | 5,000-10,000 | $20,000 | 14 days + $1,000 spent |
+| 5 | 20 | 25,000-30,000 | $100,000 | 7 days + $5,000 spent |
+
+Tiers upgrade automatically once the spend and time requirements are met.
+
+## Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| `401 Unauthorized` | Invalid or missing API key | Re-run `rw-setup-api-key` |
+| `creditBalance` is 0 | No credits purchased | Purchase at https://dev.runwayml.com/ -> Billing (min $10) |
+| Daily limit reached | Rolling 24-hour quota exhausted | Wait for the window to reset, or upgrade tier |
+| All models show 0 daily limit | Tier 1 restrictions | Check that credits have been purchased |
diff --git a/plugins/runway-api/skills/rw-fetch-api-reference/SKILL.md b/plugins/runway-api/skills/rw-fetch-api-reference/SKILL.md
new file mode 100644
index 00000000..ab8bd00a
--- /dev/null
+++ b/plugins/runway-api/skills/rw-fetch-api-reference/SKILL.md
@@ -0,0 +1,44 @@
+---
+name: rw-fetch-api-reference
+description: "Retrieve the latest Runway API reference from docs.dev.runwayml.com and use it as the authoritative source before any integration work"
+user-invocable: false
+---
+
+# Fetch Latest API Reference
+
+Before guiding or implementing any Runway API integration, retrieve the current API reference and use it as the source of truth.
+
+## Why This Matters
+
+The [Runway API](https://docs.dev.runwayml.com/api/) is the official reference. Models, endpoints, request/response shapes, and versioning can change. Using the live docs ensures integration guidance and code match the latest API.
+
+## Steps
+
+### 1. Fetch the API Reference
+
+Retrieve the contents of:
+
+https://docs.dev.runwayml.com/api/
+
+Use your available fetch tool (e.g. `mcp_web_fetch` or equivalent) to load this URL. The page contains the full API reference: endpoints, request bodies, accepted values, and examples.
+
+### 2. Use It Before Integrating
+
+- Before writing or suggesting integration code for video, image, audio, uploads, characters, documents, or any other Runway API feature, use the fetched content as the authoritative reference.
+- Prefer exact endpoint paths, model IDs, parameter names, and header values from the fetched reference over any cached or local documentation.
+- If the fetched content conflicts with text in other skills (e.g. `rw-api-reference` or an integrate skill), the fetched docs take precedence for that session.
+
+### 3. When to Re-Fetch
+
+- Re-fetch when the user asks to integrate a new capability or when you are unsure about an endpoint or parameter.
+- Re-fetch when the user reports errors that might be due to API changes (e.g. invalid model name, changed request shape).
+
+## After Fetching
+
+Proceed with the relevant integrate skill (`rw-integrate-video`, `rw-integrate-image`, `rw-integrate-audio`, `rw-integrate-uploads`, `rw-integrate-characters`, `rw-integrate-documents`, `rw-integrate-character-embed`) using the retrieved reference to guide implementation.
+
+## Important Notes
+
+- Base URL for the API is `https://api.dev.runwayml.com`.
+- All requests require `Authorization: Bearer <RUNWAYML_API_SECRET>` and `X-Runway-Version: 2024-11-06` (or the version stated in the fetched docs).
+- Do not rely solely on bundled or in-repo API summaries when the user is integrating; the live docs are the source of truth.
diff --git a/plugins/runway-api/skills/rw-generate-audio/SKILL.md b/plugins/runway-api/skills/rw-generate-audio/SKILL.md
new file mode 100644
index 00000000..1262fe82
--- /dev/null
+++ b/plugins/runway-api/skills/rw-generate-audio/SKILL.md
@@ -0,0 +1,78 @@
+---
+name: rw-generate-audio
+description: "Generate audio using the Runway API via runnable scripts. Supports TTS, sound effects, voice isolation, dubbing, and voice conversion."
+user-invocable: true
+---
+
+# Generate Audio
+
+Generate audio directly using the Runway API. Supports text-to-speech, sound effects, voice isolation, dubbing, and speech-to-speech voice conversion.
+
+IMPORTANT: Run scripts from the user's working directory so output files are saved where the user expects.
+
+Resolve `<plugin-dir>` before running examples below. From this skill's directory, it is two directories up from `SKILL.md`; for an installed plugin, it is the `runway-api` plugin directory under `~/.cline/plugins/_installed/`.
+
+## Usage
+
+```bash
+uv run <plugin-dir>/scripts/generate_audio.py --type tts --text "Hello world" --filename "greeting.mp3" [--voice-id ID]
+```
+
+## Preflight
+
+1. `command -v uv` must succeed
+2. `RUNWAYML_API_SECRET` must be set in the environment. Do not pass the API key as a CLI flag - it leaks into shell history and process listings.
+
+## Audio Types
+
+| Type | Description | Required Args |
+|------|-------------|---------------|
+| `tts` | Text to speech | `--text` |
+| `sfx` | Sound effect generation | `--text` |
+| `isolate` | Isolate voice from audio | `--audio-url` |
+| `dub` | Dub to another language | `--audio-url`, `--target-language` |
+| `sts` | Voice conversion | `--audio-url` |
+
+## Parameters
+
+| Param | Description | Default |
+|-------|-------------|---------|
+| `--type` | Audio type (required): tts, sfx, isolate, dub, sts | -- |
+| `--filename` | Output filename (required) | -- |
+| `--text` | Text input (for tts and sfx) | -- |
+| `--audio-url` | Audio URL or local path (for isolate, dub, sts) | -- |
+| `--voice-id` | Voice preset (for tts and sts, e.g. Maya, Noah, Leslie) | Maya |
+| `--target-language` | Language code (for dub, e.g. "es") | -- |
+| `--output-dir` | Output directory | cwd |
+
+## Examples
+
+Text-to-speech:
+```bash
+uv run <plugin-dir>/scripts/generate_audio.py --type tts --text "Welcome to our product showcase" --filename "voiceover.mp3"
+```
+
+Sound effect:
+```bash
+uv run <plugin-dir>/scripts/generate_audio.py --type sfx --text "Thunder rolling across a stormy sky" --filename "thunder.mp3"
+```
+
+Voice isolation:
+```bash
+uv run <plugin-dir>/scripts/generate_audio.py --type isolate --audio-url "noisy-recording.mp3" --filename "clean-voice.mp3"
+```
+
+Speech-to-speech (voice conversion):
+```bash
+uv run <plugin-dir>/scripts/generate_audio.py --type sts --audio-url "recording.mp3" --voice-id Noah --filename "converted.mp3"
+```
+
+Dubbing:
+```bash
+uv run <plugin-dir>/scripts/generate_audio.py --type dub --audio-url "english-narration.mp3" --target-language es --filename "spanish-dub.mp3"
+```
+
+## Output
+
+- The script downloads the result and saves it to the specified path
+- Script outputs the full path to the saved file
diff --git a/plugins/runway-api/skills/rw-generate-image/SKILL.md b/plugins/runway-api/skills/rw-generate-image/SKILL.md
new file mode 100644
index 00000000..b646053f
--- /dev/null
+++ b/plugins/runway-api/skills/rw-generate-image/SKILL.md
@@ -0,0 +1,90 @@
+---
+name: rw-generate-image
+description: "Generate images directly using the Runway API via runnable scripts. Supports text-to-image with optional reference images."
+user-invocable: true
+---
+
+# Generate Image
+
+Generate images directly using the Runway API. This skill runs Python scripts that call the API, poll for completion, and download the result.
+
+IMPORTANT: Run scripts from the user's working directory so output files are saved where the user expects.
+
+Resolve `<plugin-dir>` before running examples below. From this skill's directory, it is two directories up from `SKILL.md`; for an installed plugin, it is the `runway-api` plugin directory under `~/.cline/plugins/_installed/`.
+
+## Usage
+
+```bash
+uv run <plugin-dir>/scripts/generate_image.py --prompt "your description" --filename "output.png" [--model gen4_image] [--ratio 1280:720] [--reference-images Tag=URL ...]
+```
+
+## Preflight
+
+1. `command -v uv` must succeed
+2. `RUNWAYML_API_SECRET` must be set in the environment. Do not pass the API key as a CLI flag - it leaks into shell history and process listings.
+
+## Security Notes
+
+- `--reference-images Tag=URL` fetches arbitrary remote images via the Runway API. Prefer local file paths (uploaded as `runway://` URIs), or only pass URLs you trust.
+- Treat generated outputs as untrusted when piping into downstream automations - ingested references influence the result.
+
+## Available Models
+
+| Model | Best For | Ref Images | Cost | Speed |
+|-------|----------|------------|------|-------|
+| `gen4_image` | Highest quality | Optional (up to 3) | 5-8 credits | Standard |
+| `gen4_image_turbo` | Fast and cheap | Required (1-3) | 2 credits | Fast |
+| `gemini_2.5_flash` | Google Gemini | Optional (up to 3) | 5 credits | Standard |
+
+## Model Selection Guidance
+
+- "fast", "cheap", "draft" -> `gemini_2.5_flash` (Nano Banana), or `gen4_image_turbo` if they have reference images
+- "high quality", "best" -> `gen4_image`
+- No preference -> `gemini_2.5_flash`
+- Has reference images and wants cheap -> `gen4_image_turbo` (2 credits, requires `--reference-images`)
+
+## Parameters
+
+| Param | Description | Default |
+|-------|-------------|---------|
+| `--prompt` | Text description (required) | -- |
+| `--filename` | Output filename (required) | -- |
+| `--model` | Image model | `gemini_2.5_flash` |
+| `--ratio` | Aspect ratio. gemini_2.5_flash: `1344:768`, `768:1344`, `1024:1024`, etc. gen4_image: `1280:720`, `1360:768`, `1920:1080`, etc. | Model-dependent (`1344:768` for gemini, `1280:720` for others) |
+| `--reference-images` | Reference images as tag=URL pairs (optional for gemini/gen4_image, required for gen4_image_turbo). Tag: lowercase, 3-16 chars, e.g. `product=URL` | -- |
+| `--output-dir` | Output directory | cwd |
+
+> API credentials come from `RUNWAYML_API_SECRET` only - no `--api-key` flag, to keep secrets out of shell history and process listings.
+
+## Filename Convention
+
+Pattern: `yyyy-mm-dd-hh-mm-ss-name.png`
+
+## Examples
+
+Basic image:
+```bash
+uv run <plugin-dir>/scripts/generate_image.py --prompt "A serene Japanese garden with cherry blossoms" --filename "2026-04-14-japanese-garden.png"
+```
+
+With a local reference image (gen4_image):
+```bash
+uv run <plugin-dir>/scripts/generate_image.py --prompt "@product on a marble counter, lifestyle photo" --model gen4_image --reference-images product=./product.jpg --filename "2026-04-14-product-lifestyle.png"
+```
+
+With a reference image from a trusted origin (gen4_image_turbo - requires reference images):
+```bash
+uv run <plugin-dir>/scripts/generate_image.py --prompt "A neon sign reading SALE in @style" --model gen4_image_turbo --reference-images style=https://cdn.yourapp.com/style.jpg --filename "draft.png"
+```
+
+## Output
+
+- The script downloads the result and saves it to the specified path
+- Script outputs the full path to the saved file
+- Do not read the image file back -- just inform the user of the saved path
+
+## Common Failures
+
+- `Error: No API key` -> set `RUNWAYML_API_SECRET` in the environment (e.g. `export RUNWAYML_API_SECRET=...` or a `.env` file).
+- `Error: Task failed -- SAFETY.INPUT.*` -> content moderation, suggest different prompt
+- `API error 429` -> rate limited, script auto-retries
diff --git a/plugins/runway-api/skills/rw-generate-video/SKILL.md b/plugins/runway-api/skills/rw-generate-video/SKILL.md
new file mode 100644
index 00000000..0df339cc
--- /dev/null
+++ b/plugins/runway-api/skills/rw-generate-video/SKILL.md
@@ -0,0 +1,117 @@
+---
+name: rw-generate-video
+description: "Generate videos directly using the Runway API via runnable scripts. Supports text-to-video, image-to-video, and video-to-video with seedance2, gen4.5, veo3, and more."
+user-invocable: true
+---
+
+# Generate Video
+
+Generate videos directly using the Runway API. This skill runs Python scripts that call the API, poll for completion, and download the result.
+
+IMPORTANT: Run scripts from the user's working directory so output files are saved where the user expects.
+
+Resolve `<plugin-dir>` before running examples below. From this skill's directory, it is two directories up from `SKILL.md`; for an installed plugin, it is the `runway-api` plugin directory under `~/.cline/plugins/_installed/`.
+
+## Usage
+
+```bash
+uv run <plugin-dir>/scripts/generate_video.py --prompt "your description" --filename "output.mp4" [--model seedance2] [--ratio 1280:720] [--duration 5] [--image-url "..."]
+```
+
+## Preflight
+
+1. `command -v uv` must succeed. If not, tell the user to install uv: `curl -LsSf https://astral.sh/uv/install.sh | sh`
+2. `RUNWAYML_API_SECRET` must be set in the environment. Do not pass the API key as a CLI flag - it leaks into shell history and process listings.
+
+## Security Notes
+
+- `--image-url` / `--video-url` fetch arbitrary remote media via the Runway API. Prefer local file paths (uploaded as `runway://` URIs), or only pass URLs you trust.
+- Treat generated outputs as untrusted when piping into downstream automations - ingested media influences the result.
+
+## Available Models
+
+| Model | Best For | Input | Cost |
+|-------|----------|-------|------|
+| `seedance2` | Reference image and video, long duration (up to 15s) | Text, Image, and/or Video | 36 credits/sec |
+| `gen4.5` | High quality, general purpose | Text and/or Image | 12 credits/sec |
+| `gen4_turbo` | Fast, image-driven | Image required | 5 credits/sec |
+| `gen4_aleph` | Video editing/transformation | Video + Text/Image | 15 credits/sec |
+| `veo3` | Premium quality | Text/Image | 40 credits/sec |
+| `veo3.1` | High quality Google model | Text/Image | 20-40 credits/sec |
+| `veo3.1_fast` | Fast Google model | Text/Image | 10-15 credits/sec |
+
+## Model Selection Guidance
+
+Map user requests:
+- "product ad", "e-commerce", "long video" -> `seedance2`
+- "fast", "cheap", "quick" -> `veo3.1_fast` or `gen4_turbo` (if they have an image)
+- "high quality", "best", "cinematic" -> `gen4.5` or `veo3`
+- "edit video", "transform video" -> `gen4_aleph` or `seedance2`
+- No preference -> `seedance2`
+
+## Parameters
+
+| Param | Description | Default |
+|-------|-------------|---------|
+| `--prompt` | Text description (required) | -- |
+| `--filename` | Output filename (required) | -- |
+| `--model` | Video model | `gen4.5` |
+| `--ratio` | Aspect ratio (pixel-based). Common: `1280:720`, `720:1280`, `960:960`. seedance2 also supports `1112:834`, `834:1112`, `1470:630`, etc. | `1280:720` |
+| `--duration` | Duration in seconds (model-dependent, seedance2 supports up to 15s) | `5` |
+| `--image-url` | Image URL or local file for image-to-video | -- |
+| `--video-url` | Video URL or local file for video-to-video (gen4_aleph, seedance2) | -- |
+| `--output-dir` | Output directory | cwd |
+
+> API credentials come from `RUNWAYML_API_SECRET` only - no `--api-key` flag, to keep secrets out of shell history and process listings.
+
+## Filename Convention
+
+Generate filenames with the pattern: `yyyy-mm-dd-hh-mm-ss-name.mp4`
+
+Examples:
+- "A cyberpunk city" -> `2026-04-14-14-23-05-cyberpunk-city.mp4`
+- "Waves on a beach" -> `2026-04-14-15-30-12-beach-waves.mp4`
+
+## Examples
+
+Text-to-video (seedance2):
+```bash
+uv run <plugin-dir>/scripts/generate_video.py --prompt "A serene mountain landscape at sunrise with mist" --filename "2026-04-14-mountain-sunrise.mp4" --model seedance2 --ratio 1280:720
+```
+
+Image-to-video (animate a local product photo):
+```bash
+uv run <plugin-dir>/scripts/generate_video.py --prompt "Camera slowly zooms out, product sparkles" --image-url "./product.jpg" --filename "2026-04-14-product-reveal.mp4" --model seedance2 --ratio 720:1280
+```
+
+Video-to-video from a local file (seedance2):
+```bash
+uv run <plugin-dir>/scripts/generate_video.py --prompt "Transform into a warm golden sunset scene" --video-url "./input.mp4" --filename "2026-04-14-sunset-transform.mp4" --model seedance2
+```
+
+Fast draft:
+```bash
+uv run <plugin-dir>/scripts/generate_video.py --prompt "A cat playing piano" --filename "draft.mp4" --model veo3.1_fast --ratio 1280:720 --duration 4
+```
+
+Premium quality:
+```bash
+uv run <plugin-dir>/scripts/generate_video.py --prompt "Cinematic drone shot over Tokyo at night" --filename "tokyo.mp4" --model veo3 --ratio 1280:720 --duration 8
+```
+
+## Output
+
+- The script downloads the result and saves it to the specified path
+- Script outputs the full path to the saved file
+- Do not read the video file back -- just inform the user of the saved path
+
+## Common Failures
+
+- `Error: No API key` -> set `RUNWAYML_API_SECRET` in the environment (e.g. `export RUNWAYML_API_SECRET=...` or a `.env` file).
+- `Error: Task failed -- SAFETY.INPUT.*` -> content moderation, suggest different prompt
+- `Error: Task failed -- ASSET.INVALID` -> bad input file format, check image/video format
+- `API error 429` -> rate limited, script auto-retries
+
+## For Batch Generation
+
+To generate many videos at once, run this script in a loop - the agent can orchestrate multiple calls with different prompts, images, or parameters to produce campaigns, localized variants, or creative iterations at scale.
diff --git a/plugins/runway-api/skills/rw-integrate-audio/SKILL.md b/plugins/runway-api/skills/rw-integrate-audio/SKILL.md
new file mode 100644
index 00000000..0f528e46
--- /dev/null
+++ b/plugins/runway-api/skills/rw-integrate-audio/SKILL.md
@@ -0,0 +1,177 @@
+---
+name: rw-integrate-audio
+description: "Help users integrate Runway audio APIs (TTS, sound effects, voice isolation, dubbing)"
+user-invocable: false
+---
+
+# Integrate Audio Generation
+
+> PREREQUISITE: Run `rw-check-compatibility` first. Run `rw-fetch-api-reference` to load the latest API reference before integrating. Requires `rw-setup-api-key` for API credentials. Requires `rw-integrate-uploads` for local audio/video files.
+
+Help users add Runway audio generation to their server-side code.
+
+## Available Models
+
+| Model | Endpoint | Use Case | Cost |
+|-------|----------|----------|------|
+| `eleven_multilingual_v2` | `POST /v1/text_to_speech` | Text to speech | 1 credit/50 chars |
+| `eleven_text_to_sound_v2` | `POST /v1/sound_effect` | Sound effect generation | 1-2 credits |
+| `eleven_voice_isolation` | `POST /v1/voice_isolation` | Isolate voice from audio | 1 credit/6 sec |
+| `eleven_voice_dubbing` | `POST /v1/voice_dubbing` | Dub audio to other languages | 1 credit/2 sec |
+| `eleven_multilingual_sts_v2` | `POST /v1/speech_to_speech` | Voice conversion | 1 credit/3 sec |
+
+## Text-to-Speech
+
+Generate speech from text using the ElevenLabs multilingual model.
+
+### Node.js SDK
+
+```javascript
+import RunwayML from '@runwayml/sdk';
+
+const client = new RunwayML();
+
+const task = await client.textToSpeech.create({
+  model: 'eleven_multilingual_v2',
+  promptText: 'Hello, welcome to our application!',
+  voice: { type: 'runway-preset', presetId: 'Maya' }
+}).waitForTaskOutput();
+
+const audioUrl = task.output[0];
+```
+
+### Python SDK
+
+```python
+from runwayml import RunwayML
+
+client = RunwayML()
+
+task = client.text_to_speech.create(
+    model='eleven_multilingual_v2',
+    prompt_text='Hello, welcome to our application!',
+    voice={ 'type': 'runway-preset', 'presetId': 'Maya' }
+).wait_for_task_output()
+
+audio_url = task.output[0]
+```
+
+## Sound Effects
+
+Generate sound effects from text descriptions.
+
+```javascript
+const task = await client.soundEffect.create({
+  model: 'eleven_text_to_sound_v2',
+  promptText: 'Thunder rolling across a stormy sky'
+}).waitForTaskOutput();
+```
+
+```python
+task = client.sound_effect.create(
+    model='eleven_text_to_sound_v2',
+    prompt_text='Thunder rolling across a stormy sky'
+).wait_for_task_output()
+```
+
+## Voice Isolation
+
+Extract voice from audio with background noise.
+
+```javascript
+// If using a local file, upload first
+const upload = await client.uploads.createEphemeral(
+  fs.createReadStream('/path/to/noisy-audio.mp3')
+);
+
+const task = await client.voiceIsolation.create({
+  model: 'eleven_voice_isolation',
+  audioUri: upload.runwayUri
+}).waitForTaskOutput();
+```
+
+## Voice Dubbing
+
+Dub audio/video into other languages.
+
+```javascript
+const task = await client.voiceDubbing.create({
+  model: 'eleven_voice_dubbing',
+  audioUri: 'https://example.com/speech.mp3',
+  targetLang: 'es'  // Spanish
+}).waitForTaskOutput();
+```
+
+## Speech-to-Speech
+
+Convert one voice to another.
+
+```javascript
+const task = await client.speechToSpeech.create({
+  model: 'eleven_multilingual_sts_v2',
+  media: { type: 'audio', uri: 'https://example.com/original-speech.mp3' },
+  voice: { type: 'runway-preset', presetId: 'Noah' }
+}).waitForTaskOutput();
+```
+
+## Integration Pattern
+
+### Express.js - Text-to-Speech Endpoint
+
+```javascript
+import RunwayML from '@runwayml/sdk';
+import express from 'express';
+
+const client = new RunwayML();
+const app = express();
+app.use(express.json());
+
+app.post('/api/text-to-speech', async (req, res) => {
+  try {
+    const { text, voiceId } = req.body;
+
+    const task = await client.textToSpeech.create({
+      model: 'eleven_multilingual_v2',
+      promptText: text,
+      voice: { type: 'runway-preset', presetId: voiceId || 'Maya' }
+    }).waitForTaskOutput();
+
+    res.json({ audioUrl: task.output[0] });
+  } catch (error) {
+    console.error('TTS failed:', error);
+    res.status(500).json({ error: error.message });
+  }
+});
+```
+
+### FastAPI - Sound Effects
+
+```python
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from runwayml import RunwayML
+
+app = FastAPI()
+client = RunwayML()
+
+class SoundRequest(BaseModel):
+    prompt: str
+
+@app.post("/api/sound-effect")
+async def generate_sound(req: SoundRequest):
+    try:
+        task = client.sound_effect.create(
+            model='eleven_text_to_sound_v2',
+            prompt_text=req.prompt
+        ).wait_for_task_output()
+        return {"audio_url": task.output[0]}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+```
+
+## Tips
+
+- Output URLs expire in 24-48 hours. Download audio files to your own storage.
+- For local audio files (voice isolation, dubbing, speech-to-speech), upload via `rw-integrate-uploads` first.
+- Voice IDs can be listed via the voices endpoint - see `rw-api-reference` for details.
+- Text-to-speech cost scales with text length: 1 credit per 50 characters.
diff --git a/plugins/runway-api/skills/rw-integrate-character-embed/SKILL.md b/plugins/runway-api/skills/rw-integrate-character-embed/SKILL.md
new file mode 100644
index 00000000..e3ab5b5d
--- /dev/null
+++ b/plugins/runway-api/skills/rw-integrate-character-embed/SKILL.md
@@ -0,0 +1,294 @@
+---
+name: rw-integrate-character-embed
+description: "Help users embed Runway Character avatar calls in React apps using the @runwayml/avatars-react SDK"
+user-invocable: false
+---
+
+# Embed Characters in React (Avatars React SDK)
+
+> PREREQUISITES:
+> - `rw-check-compatibility` - Project must have server-side capability (API key must never be exposed to the client)
+> - `rw-fetch-api-reference` - Load the latest API reference from https://docs.dev.runwayml.com/api/ before integrating
+> - `rw-integrate-characters` - Character (Avatar) must be created and session endpoint must exist
+> - Project must use React (Next.js, Vite+React, Remix, etc.)
+>
+> OPTIONAL:
+> - `rw-integrate-documents` - Add knowledge base before embedding
+
+Embed real-time avatar video calls in React applications using the `@runwayml/avatars-react` SDK.
+
+## Installation
+
+```bash
+npm install @runwayml/avatars-react
+```
+
+This is a client-side package. The server-side `@runwayml/sdk` should already be installed from `rw-integrate-characters`.
+
+## Option A: Simple - `AvatarCall` Component
+
+The fastest way to embed a character. Handles WebRTC connection and renders a default UI automatically.
+
+```tsx
+'use client';
+
+import { AvatarCall } from '@runwayml/avatars-react';
+import '@runwayml/avatars-react/styles.css';
+
+export default function CharacterPage() {
+  return (
+    <AvatarCall
+      avatarId="your-avatar-id-here"
+      connectUrl="/api/avatar/session"
+      onEnd={() => console.log('Call ended')}
+      onError={(error) => console.error('Error:', error)}
+    />
+  );
+}
+```
+
+### `AvatarCall` Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `avatarId` | `string` | The Avatar UUID from the Developer Portal or API |
+| `connectUrl` | `string` | Your server-side session endpoint (e.g., `/api/avatar/session`) |
+| `onEnd` | `() => void` | Called when the call ends normally |
+| `onError` | `(error: Error) => void` | Called on connection or runtime errors |
+
+For custom avatars created in the Developer Portal, use the Avatar UUID as `avatarId`.
+
+## Option B: Fully Custom - Hooks
+
+For full control over the UI, use `AvatarSession` with hooks.
+
+### Components & Hooks
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `AvatarSession` | Component | Provider that manages the WebRTC session |
+| `AvatarVideo` | Component | Renders the avatar's video stream |
+| `UserVideo` | Component | Renders the user's camera feed |
+| `useAvatarSession` | Hook | Access session state: `state`, `sessionId`, `error`, `end()` |
+| `useLocalMedia` | Hook | Control user's media: `isMicEnabled`, `toggleMic()` |
+
+### Custom UI Example
+
+```tsx
+'use client';
+
+import {
+  AvatarSession,
+  AvatarVideo,
+  UserVideo,
+  useAvatarSession,
+  useLocalMedia,
+} from '@runwayml/avatars-react';
+import type { SessionCredentials } from '@runwayml/avatars-react';
+
+function CallUI() {
+  const { state, end } = useAvatarSession();
+  const { isMicEnabled, toggleMic } = useLocalMedia();
+
+  return (
+    <div className="relative w-full h-screen">
+      {/* Avatar video takes full screen */}
+      <AvatarVideo className="w-full h-full object-cover" />
+
+      {/* User's camera in a small overlay */}
+      <UserVideo className="absolute bottom-4 right-4 w-48 rounded-lg" />
+
+      {/* Controls */}
+      <div className="absolute bottom-4 left-4 flex gap-2">
+        <button onClick={toggleMic}>
+          {isMicEnabled ? 'Mute' : 'Unmute'}
+        </button>
+        <button onClick={end}>End Call</button>
+      </div>
+
+      {/* Connection state */}
+      {state === 'connecting' && (
+        <div className="absolute inset-0 flex items-center justify-center bg-black/50">
+          Connecting...
+        </div>
+      )}
+    </div>
+  );
+}
+
+export function CustomAvatar({ credentials }: { credentials: SessionCredentials }) {
+  return (
+    <AvatarSession credentials={credentials} audio video>
+      <CallUI />
+    </AvatarSession>
+  );
+}
+```
+
+### Fetching Credentials for Custom UI
+
+When using the hooks approach, you need to fetch credentials from your server endpoint and pass them to `AvatarSession`:
+
+```tsx
+'use client';
+
+import { useState, useCallback } from 'react';
+import type { SessionCredentials } from '@runwayml/avatars-react';
+import { CustomAvatar } from './CustomAvatar';
+
+export default function CharacterPage() {
+  const [credentials, setCredentials] = useState<SessionCredentials | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  const startCall = useCallback(async () => {
+    setLoading(true);
+    try {
+      const res = await fetch('/api/avatar/session', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ avatarId: 'your-avatar-id-here' }),
+      });
+      const data = await res.json();
+      setCredentials(data);
+    } catch (error) {
+      console.error('Failed to connect:', error);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  if (credentials) {
+    return <CustomAvatar credentials={credentials} />;
+  }
+
+  return (
+    <button onClick={startCall} disabled={loading}>
+      {loading ? 'Connecting...' : 'Start Conversation'}
+    </button>
+  );
+}
+```
+
+## Integration Patterns
+
+### Next.js App Router (Full Example)
+
+Server route (`app/api/avatar/session/route.ts`):
+See `rw-integrate-characters` for the complete server-side session creation code.
+
+Client page (`app/character/page.tsx`):
+
+```tsx
+'use client';
+
+import { AvatarCall } from '@runwayml/avatars-react';
+import '@runwayml/avatars-react/styles.css';
+
+const AVATAR_ID = process.env.NEXT_PUBLIC_AVATAR_ID || 'your-avatar-id';
+
+export default function CharacterPage() {
+  return (
+    <div className="flex items-center justify-center min-h-screen">
+      <AvatarCall
+        avatarId={AVATAR_ID}
+        connectUrl="/api/avatar/session"
+        onEnd={() => window.location.reload()}
+        onError={(error) => {
+          console.error('Avatar error:', error);
+          alert('Connection failed. Please try again.');
+        }}
+      />
+    </div>
+  );
+}
+```
+
+### Conditional Rendering (Show/Hide)
+
+```tsx
+'use client';
+
+import { useState } from 'react';
+import { AvatarCall } from '@runwayml/avatars-react';
+import '@runwayml/avatars-react/styles.css';
+
+export default function SupportPage() {
+  const [showAvatar, setShowAvatar] = useState(false);
+
+  return (
+    <div>
+      <h1>Customer Support</h1>
+
+      {!showAvatar ? (
+        <button onClick={() => setShowAvatar(true)}>
+          Talk to an Agent
+        </button>
+      ) : (
+        <AvatarCall
+          avatarId="support-agent-id"
+          connectUrl="/api/avatar/session"
+          onEnd={() => setShowAvatar(false)}
+          onError={(error) => {
+            console.error(error);
+            setShowAvatar(false);
+          }}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+## Error Handling
+
+### Verbose Error Logging
+
+```tsx
+<AvatarCall
+  avatarId="your-avatar-id"
+  connectUrl="/api/avatar/session"
+  onError={(error) => {
+    console.error('Avatar error:', error);
+    console.error('Error name:', error.name);
+    console.error('Error message:', error.message);
+    if (error.cause) {
+      console.error('Cause:', error.cause);
+    }
+  }}
+/>
+```
+
+### Debug Session State
+
+```tsx
+import { useAvatarSession } from '@runwayml/avatars-react';
+
+function DebugPanel() {
+  const { state, sessionId, error } = useAvatarSession();
+
+  return (
+    <pre style={{ fontSize: 12, position: 'fixed', top: 0, right: 0 }}>
+      {JSON.stringify({ state, sessionId, error: error?.message }, null, 2)}
+    </pre>
+  );
+}
+```
+
+## Browser Support
+
+| Browser | Minimum Version |
+|---------|-----------------|
+| Chrome | 74+ |
+| Firefox | 78+ |
+| Safari | 14.1+ |
+| Edge | 79+ |
+
+Users must grant microphone permissions when prompted. Camera permissions are needed if user video is enabled.
+
+## Tips
+
+- Always import the styles: `import '@runwayml/avatars-react/styles.css'` when using `AvatarCall`
+- `'use client'` directive is required in Next.js App Router for all components using the React SDK
+- Session max duration is 5 minutes - handle the `onEnd` callback to show a reconnect option
+- Credentials are one-time use - if connection fails, fetch new credentials (create a new session)
+- For the full SDK source, examples, and issue tracking: [github.com/runwayml/avatars-sdk-react](https://github.com/runwayml/avatars-sdk-react)
diff --git a/plugins/runway-api/skills/rw-integrate-characters/SKILL.md b/plugins/runway-api/skills/rw-integrate-characters/SKILL.md
new file mode 100644
index 00000000..502fd090
--- /dev/null
+++ b/plugins/runway-api/skills/rw-integrate-characters/SKILL.md
@@ -0,0 +1,466 @@
+---
+name: rw-integrate-characters
+description: "Help users create Runway Characters (GWM-1 avatars) and integrate real-time conversational sessions into their apps"
+user-invocable: false
+---
+
+# Integrate Characters (GWM-1 Avatars)
+
+> PREREQUISITES:
+> - `rw-check-compatibility` - Project must have a server-side component (API key must NEVER be exposed to the client)
+> - `rw-fetch-api-reference` - Load the latest API reference from https://docs.dev.runwayml.com/api/ before integrating
+> - `rw-setup-api-key` - API credentials must be configured
+>
+> OPTIONAL DEPENDENCIES:
+> - `rw-integrate-documents` - Add a knowledge base to your character
+> - `rw-integrate-character-embed` - Use the React SDK to embed the avatar call UI
+
+Help users create Runway Characters - real-time conversational AI avatars powered by GWM-1.
+
+Use this only when modifying a user's codebase. For direct avatar management or other one-off Runway account actions from the agent, use `use-runway-api` instead.
+
+Characters are generated from a single image (any visual style - photorealistic, animated, non-human) with full control over voice, personality, knowledge, and actions. No fine-tuning or training required.
+
+## Key Concepts
+
+### Avatars vs Sessions
+
+| Concept | Description |
+|---------|-------------|
+| Avatar | A persistent persona with a defined appearance, voice, and personality. Created once, used many times. |
+| Session | A live WebRTC connection for real-time conversation. Connects one user to one avatar. Max duration: 5 minutes. |
+
+### Session Lifecycle
+
+```
+                    - - 
+         - -  NOT_READY - - 
+         -           - -           - 
+         -                 -                 - 
+         -                  -                  -  
+     CANCELLED          READY           FAILED
+                       - - - 
+                       -      - 
+                       -       -  
+                    RUNNING FAILED
+                    - - - 
+                    -      - 
+                    -       -  
+                COMPLETED CANCELLED
+```
+
+| Status | Description |
+|--------|-------------|
+| `NOT_READY` | Session is being provisioned. Poll until ready. |
+| `READY` | Session is ready. The `sessionKey` is available. |
+| `RUNNING` | WebRTC connection is active. Conversation in progress. |
+| `COMPLETED` | Session ended normally. |
+| `FAILED` | Error occurred. Check the `failure` field. |
+| `CANCELLED` | Explicitly cancelled before completion. |
+
+> Important: Session credentials can only be consumed once. If the WebRTC connection fails after credentials are consumed, you must create a new Session.
+
+### Architecture
+
+The API key must stay server-side. The flow is:
+
+```
+Client (React)  ->  Your Server  ->  Runway API
+                                      -  
+Client (React)  <-- WebRTC -<- Runway (realtime)
+```
+
+1. Client requests a session from your server
+2. Your server calls Runway API to create a session (`POST /v1/realtime_sessions`)
+3. Your server polls until session is `READY` (`GET /v1/realtime_sessions/:id`)
+4. Your server consumes credentials (`POST /v1/realtime_sessions/:id/consume`)
+5. Your server returns credentials to the client
+6. Client establishes a direct WebRTC connection to Runway
+
+## Step 1: Install Dependencies
+
+```bash
+npm install @runwayml/sdk @runwayml/avatars-react
+```
+
+- `@runwayml/sdk` - Server-side SDK (session creation, avatar management)
+- `@runwayml/avatars-react` - Client-side React components (WebRTC, UI)
+
+## Step 2: Create an Avatar
+
+Avatars can be created via the Developer Portal (UI) or the API (programmatic).
+
+### Option A: Developer Portal (Recommended for first time)
+
+1. Go to https://dev.runwayml.com/ -> Characters tab
+2. Click Create a Character
+3. Upload a reference image (tips below)
+4. Choose a voice preset
+5. Write personality instructions (e.g., "You are a helpful customer support agent for Acme Corp...")
+6. Optionally add a starting script (what the character says first)
+7. Optionally upload knowledge documents (`.txt` files)
+8. Click Create Character
+9. Copy the Avatar ID (a UUID like `8be4df61-93ca-11d2-aa0d-00e098032b8c`)
+
+### Option B: API (Programmatic)
+
+```javascript
+// Node.js
+import RunwayML from '@runwayml/sdk';
+
+const client = new RunwayML();
+
+const avatar = await client.avatars.create({
+  name: 'Support Agent',
+  referenceImage: 'https://example.com/avatar.png',
+  voice: {
+    type: 'runway-live-preset',
+    presetId: 'clara',
+  },
+  personality: 'You are a helpful customer support agent for Acme Corp. You help users with billing questions and technical issues.',
+});
+
+console.log('Avatar ID:', avatar.id);
+```
+
+```python
+# Python
+from runwayml import RunwayML
+
+client = RunwayML()
+
+avatar = client.avatars.create(
+    name='Support Agent',
+    reference_image='https://example.com/avatar.png',
+    voice={
+        'type': 'runway-live-preset',
+        'preset_id': 'clara',
+    },
+    personality='You are a helpful customer support agent for Acme Corp.',
+)
+
+print('Avatar ID:', avatar.id)
+```
+
+If the reference image is a local file, upload it first using `rw-integrate-uploads`:
+
+```javascript
+import fs from 'fs';
+
+const upload = await client.uploads.createEphemeral(
+  fs.createReadStream('/path/to/avatar-image.png')
+);
+
+const avatar = await client.avatars.create({
+  name: 'Support Agent',
+  referenceImage: upload.runwayUri,
+  voice: { type: 'runway-live-preset', presetId: 'clara' },
+  personality: 'You are a helpful customer support agent...',
+});
+```
+
+### Reference Image (Required)
+
+`referenceImage` is required when creating an avatar. It accepts three formats:
+
+| Format | Limit | When to use |
+|--------|-------|-------------|
+| `https://...` URL | 2048 chars | Image already hosted publicly |
+| `data:image/...;base64,...` | 5 MB (characters) | Small-to-medium local files (~3.5 MB raw max) |
+| `runway://...` URI | 5000 chars | Large files uploaded via `/v1/uploads` first |
+
+For local files over ~3.5 MB, use the upload flow (`rw-integrate-uploads`) to get a `runway://` URI instead of a data URI.
+
+### Reference Image Guidelines
+
+- Any visual style works: photorealistic humans, animated mascots, stylized brand characters
+- Use high-quality images with good lighting
+- Face must be clearly visible and centered - images without a recognizable face will fail processing
+- Avoid images with multiple people or obstructions
+- Recommended aspect ratio: 1088x704
+
+### Voice Presets
+
+| Preset ID | Name | Style |
+|-----------|------|-------|
+| `clara` | Clara | Soft, approachable |
+| `victoria` | Victoria | Firm, professional |
+| `vincent` | Vincent | Knowledgeable, authoritative |
+
+Preview all voices in the [Developer Portal](https://dev.runwayml.com/).
+
+## Step 3: Create a Session (Server-Side)
+
+This is the server-side API route that your client will call. It creates a session, polls until ready, consumes credentials, and returns them.
+
+### Next.js App Router
+
+```typescript
+// app/api/avatar/session/route.ts
+import RunwayML from '@runwayml/sdk';
+
+const client = new RunwayML();
+
+export async function POST(request: Request) {
+  const { avatarId } = await request.json();
+
+  // 1. Create session
+  const { id: sessionId } = await client.realtimeSessions.create({
+    model: 'gwm1_avatars',
+    avatar: { type: 'custom', avatarId },
+  });
+
+  // 2. Poll until ready
+  let sessionKey: string | undefined;
+  for (let i = 0; i < 60; i++) {
+    const session = await client.realtimeSessions.retrieve(sessionId);
+
+    if (session.status === 'READY') {
+      sessionKey = session.sessionKey;
+      break;
+    }
+    if (session.status === 'FAILED') {
+      return Response.json({ error: session.failure }, { status: 500 });
+    }
+
+    await new Promise(r => setTimeout(r, 1000));
+  }
+
+  if (!sessionKey) {
+    return Response.json({ error: 'Session timed out' }, { status: 504 });
+  }
+
+  // 3. Consume session to get WebRTC credentials
+  const consumeResponse = await fetch(
+    `${client.baseURL}/v1/realtime_sessions/${sessionId}/consume`,
+    {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${sessionKey}`,
+        'X-Runway-Version': '2024-11-06',
+      },
+    }
+  );
+  const credentials = await consumeResponse.json();
+
+  return Response.json({
+    sessionId,
+    serverUrl: credentials.url,
+    token: credentials.token,
+    roomName: credentials.roomName,
+  });
+}
+```
+
+### Express.js
+
+```typescript
+import RunwayML from '@runwayml/sdk';
+import express from 'express';
+
+const client = new RunwayML();
+const app = express();
+app.use(express.json());
+
+app.post('/api/avatar/session', async (req, res) => {
+  const { avatarId } = req.body;
+
+  try {
+    // 1. Create session
+    const { id: sessionId } = await client.realtimeSessions.create({
+      model: 'gwm1_avatars',
+      avatar: { type: 'custom', avatarId },
+    });
+
+    // 2. Poll until ready
+    let sessionKey: string | undefined;
+    for (let i = 0; i < 60; i++) {
+      const session = await client.realtimeSessions.retrieve(sessionId);
+
+      if (session.status === 'READY') {
+        sessionKey = session.sessionKey;
+        break;
+      }
+      if (session.status === 'FAILED') {
+        return res.status(500).json({ error: session.failure });
+      }
+
+      await new Promise(r => setTimeout(r, 1000));
+    }
+
+    if (!sessionKey) {
+      return res.status(504).json({ error: 'Session timed out' });
+    }
+
+    // 3. Consume credentials
+    const consumeResponse = await fetch(
+      `${client.baseURL}/v1/realtime_sessions/${sessionId}/consume`,
+      {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${sessionKey}`,
+          'X-Runway-Version': '2024-11-06',
+        },
+      }
+    );
+    const credentials = await consumeResponse.json();
+
+    res.json({
+      sessionId,
+      serverUrl: credentials.url,
+      token: credentials.token,
+      roomName: credentials.roomName,
+    });
+  } catch (error) {
+    console.error('Session creation failed:', error);
+    res.status(500).json({ error: error instanceof Error ? error.message : 'Unknown error' });
+  }
+});
+```
+
+### FastAPI (Python)
+
+```python
+import time
+import httpx
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from runwayml import RunwayML
+
+app = FastAPI()
+client = RunwayML()
+
+class SessionRequest(BaseModel):
+    avatar_id: str
+
+@app.post("/api/avatar/session")
+async def create_session(req: SessionRequest):
+    # 1. Create session
+    result = client.realtime_sessions.create(
+        model='gwm1_avatars',
+        avatar={'type': 'custom', 'avatar_id': req.avatar_id},
+    )
+    session_id = result.id
+
+    # 2. Poll until ready
+    session_key = None
+    for _ in range(60):
+        session = client.realtime_sessions.retrieve(session_id)
+
+        if session.status == 'READY':
+            session_key = session.session_key
+            break
+        if session.status == 'FAILED':
+            raise HTTPException(status_code=500, detail=str(session.failure))
+
+        time.sleep(1)
+
+    if not session_key:
+        raise HTTPException(status_code=504, detail='Session timed out')
+
+    # 3. Consume credentials
+    async with httpx.AsyncClient() as http:
+        resp = await http.post(
+            f"{client.base_url}/v1/realtime_sessions/{session_id}/consume",
+            headers={
+                "Authorization": f"Bearer {session_key}",
+                "X-Runway-Version": "2024-11-06",
+            },
+        )
+    credentials = resp.json()
+
+    return {
+        "session_id": session_id,
+        "server_url": credentials["url"],
+        "token": credentials["token"],
+        "room_name": credentials["roomName"],
+    }
+```
+
+## Step 4: Connect from the Client
+
+See `rw-integrate-character-embed` for the React SDK components that handle WebRTC connection and rendering. The simplest approach:
+
+```tsx
+'use client';
+import { AvatarCall } from '@runwayml/avatars-react';
+import '@runwayml/avatars-react/styles.css';
+
+export default function CharacterPage() {
+  return (
+    <AvatarCall
+      avatarId="your-avatar-id"
+      connectUrl="/api/avatar/session"
+      onEnd={() => console.log('Call ended')}
+      onError={(error) => console.error('Error:', error)}
+    />
+  );
+}
+```
+
+## Troubleshooting
+
+- API key errors: Key starts with `key_` followed by 128 hex chars. Ensure it's active.
+- No credits: Account must have prepaid credits before starting a call.
+- Session timeout: The 60-iteration poll loop waits ~60 seconds. If sessions consistently time out, check your tier's concurrency limits.
+- Credentials already consumed: Session credentials are one-time use. If WebRTC fails after consume, create a new session.
+
+### Debug logging
+
+```tsx
+<AvatarCall
+  avatarId="your-avatar-id"
+  connectUrl="/api/avatar/session"
+  onError={(error) => {
+    console.error('Avatar error:', error);
+    console.error('Error name:', error.name);
+    console.error('Error message:', error.message);
+    if (error.cause) console.error('Cause:', error.cause);
+  }}
+/>
+```
+
+### Monitor session state
+
+```tsx
+import { useAvatarSession } from '@runwayml/avatars-react';
+
+function DebugInfo() {
+  const { state, sessionId, error } = useAvatarSession();
+  return (
+    <pre>
+      {JSON.stringify({ state, sessionId, error: error?.message }, null, 2)}
+    </pre>
+  );
+}
+```
+
+### Test with minimal setup
+
+```bash
+npx degit runwayml/avatars-sdk-react/examples/nextjs-simple test-app
+cd test-app
+npm install
+# Add your API key to .env.local
+npm run dev
+```
+
+## Browser Support
+
+| Browser | Minimum Version |
+|---------|-----------------|
+| Chrome | 74+ |
+| Firefox | 78+ |
+| Safari | 14.1+ |
+| Edge | 79+ |
+
+Users must grant microphone permissions. Camera permissions needed if user video is enabled.
+
+## Getting Help
+
+| Resource | Description |
+|----------|-------------|
+| [Developer Portal](https://dev.runwayml.com/) | Manage avatars, view logs, access dashboard |
+| [SDK Repository](https://github.com/runwayml/avatars-sdk-react) | Report bugs, view examples, check releases |
+
+When reporting issues, include: browser/version, SDK version (`npm list @runwayml/avatars-react`), error messages, session ID, and steps to reproduce.
diff --git a/plugins/runway-api/skills/rw-integrate-documents/SKILL.md b/plugins/runway-api/skills/rw-integrate-documents/SKILL.md
new file mode 100644
index 00000000..b1f9f21c
--- /dev/null
+++ b/plugins/runway-api/skills/rw-integrate-documents/SKILL.md
@@ -0,0 +1,220 @@
+---
+name: rw-integrate-documents
+description: "Help users add knowledge base documents to Runway Characters for domain-specific conversations"
+user-invocable: false
+---
+
+# Integrate Documents (Knowledge Base)
+
+> PREREQUISITE: Run `rw-check-compatibility` first. Run `rw-fetch-api-reference` to load the latest API reference before integrating. `rw-setup-api-key` - API credentials must be configured
+>
+> USED BY: `rw-integrate-characters` - Documents are linked to Avatars to give them domain-specific knowledge
+
+Give your Characters access to domain-specific knowledge. Upload content that your Avatar can reference during conversations for accurate, contextual responses.
+
+## When to Use Documents
+
+| Use Case | Example Content |
+|----------|----------------|
+| Customer support | FAQs, product info, company policies, return procedures |
+| Quizzes & games | Question banks, correct answers, scoring rules |
+| Education | Course material, reference content, learning objectives |
+| Brand experiences | Brand guidelines, messaging, product catalogs |
+
+## Constraints
+
+- Each Avatar supports up to 50,000 tokens of knowledge
+- Supported formats: plain text and Markdown
+- More formats planned for future releases
+
+## Flow
+
+The flow is: Create a Document -> Link it to an Avatar
+
+## Step 1: Create a Document
+
+### Node.js
+
+```javascript
+import RunwayML from '@runwayml/sdk';
+
+const client = new RunwayML();
+
+const document = await client.documents.create({
+  name: 'Product FAQ',
+  content: `# Product FAQ
+
+## What is your return policy?
+We offer a 30-day return policy for all unused items in original packaging.
+
+## How do I track my order?
+Log in to your account and visit the Orders page. You'll find tracking information for all shipped orders.
+
+## Do you offer international shipping?
+Yes, we ship to over 50 countries. Shipping costs and delivery times vary by destination.`,
+});
+
+console.log('Document created:', document.id);
+```
+
+### Python
+
+```python
+from runwayml import RunwayML
+
+client = RunwayML()
+
+document = client.documents.create(
+    name='Product FAQ',
+    content="""# Product FAQ
+
+## What is your return policy?
+We offer a 30-day return policy for all unused items in original packaging.
+
+## How do I track my order?
+Log in to your account and visit the Orders page.
+
+## Do you offer international shipping?
+Yes, we ship to over 50 countries.""",
+)
+
+print('Document created:', document.id)
+```
+
+## Step 2: Link the Document to an Avatar
+
+Update your Avatar to attach the document. This replaces any existing document attachments - pass all document IDs you want linked.
+
+### Node.js
+
+```javascript
+await client.avatars.update(avatarId, {
+  documentIds: [document.id],
+});
+```
+
+### Python
+
+```python
+client.avatars.update(
+    avatar_id,
+    document_ids=[document.id],
+)
+```
+
+### Multiple Documents
+
+You can link multiple documents to a single avatar (total must stay under 50,000 tokens):
+
+```javascript
+const faq = await client.documents.create({
+  name: 'FAQ',
+  content: '...',
+});
+
+const policies = await client.documents.create({
+  name: 'Company Policies',
+  content: '...',
+});
+
+await client.avatars.update(avatarId, {
+  documentIds: [faq.id, policies.id],
+});
+```
+
+## Step 3: Start a Session
+
+Once documents are linked, the Avatar automatically has access to the knowledge during conversations. Start a session as usual - no additional configuration needed:
+
+```javascript
+const session = await client.realtimeSessions.create({
+  model: 'gwm1_avatars',
+  avatar: {
+    type: 'custom',
+    avatarId: avatarId,
+  },
+});
+```
+
+```python
+session = client.realtime_sessions.create(
+    model='gwm1_avatars',
+    avatar={
+        'type': 'custom',
+        'avatar_id': avatar_id,
+    },
+)
+```
+
+See `rw-integrate-characters` for the full session creation, polling, and WebRTC flow.
+
+## Integration Patterns
+
+### Load Documents from Files
+
+Read content from local files and create documents:
+
+```javascript
+import fs from 'fs';
+import RunwayML from '@runwayml/sdk';
+
+const client = new RunwayML();
+
+// Read a local markdown file
+const content = fs.readFileSync('./knowledge/product-faq.md', 'utf-8');
+
+const document = await client.documents.create({
+  name: 'Product FAQ',
+  content,
+});
+```
+
+```python
+from pathlib import Path
+from runwayml import RunwayML
+
+client = RunwayML()
+
+content = Path('./knowledge/product-faq.md').read_text()
+
+document = client.documents.create(
+    name='Product FAQ',
+    content=content,
+)
+```
+
+### Dynamic Knowledge Updates
+
+Update documents programmatically - useful for syncing with a CMS or database:
+
+```javascript
+// Example: API endpoint to update character knowledge
+app.post('/api/avatar/update-knowledge', async (req, res) => {
+  const { avatarId, documents } = req.body;
+
+  // Create new documents
+  const docIds = [];
+  for (const doc of documents) {
+    const created = await client.documents.create({
+      name: doc.name,
+      content: doc.content,
+    });
+    docIds.push(created.id);
+  }
+
+  // Link all documents to the avatar (replaces existing)
+  await client.avatars.update(avatarId, {
+    documentIds: docIds,
+  });
+
+  res.json({ success: true, documentCount: docIds.length });
+});
+```
+
+## Tips
+
+- Use Markdown for structured content - headings help the Avatar navigate the knowledge.
+- Be concise - stay well under the 50,000 token limit for best retrieval quality.
+- Organize by topic - multiple focused documents work better than one giant document.
+- Update regularly - keep knowledge current by re-creating documents when content changes.
+- Documents can also be managed via the [Developer Portal](https://dev.runwayml.com/) UI.
diff --git a/plugins/runway-api/skills/rw-integrate-image/SKILL.md b/plugins/runway-api/skills/rw-integrate-image/SKILL.md
new file mode 100644
index 00000000..b9cb3846
--- /dev/null
+++ b/plugins/runway-api/skills/rw-integrate-image/SKILL.md
@@ -0,0 +1,285 @@
+---
+name: rw-integrate-image
+description: "Help users integrate Runway image generation APIs (text-to-image with reference images)"
+user-invocable: false
+---
+
+# Integrate Image Generation
+
+> PREREQUISITE: Run `rw-check-compatibility` first. Run `rw-fetch-api-reference` to load the latest API reference before integrating. Requires `rw-setup-api-key` for API credentials. Requires `rw-integrate-uploads` when the user has local reference images.
+
+Help users add Runway image generation to their server-side code.
+
+## Available Models
+
+| Model | Best For | Cost | Speed |
+|-------|----------|------|-------|
+| `gen4_image` | Highest quality | 5 credits (720p), 8 credits (1080p) | Standard |
+| `gen4_image_turbo` | Fast generation | 2 credits | Fast |
+| `gemini_2.5_flash` | Google Gemini model | 5 credits | Standard |
+
+Model selection guidance:
+- Default recommendation: `gen4_image` - best quality
+- Budget/speed: `gen4_image_turbo` - cheapest and fastest
+
+## Security
+
+`referenceImages[].uri` is fetched server-side by the Runway API - treat it like any outbound fetch:
+
+- Prefer `runway://` URIs from `rw-integrate-uploads` - scoped to your account, no arbitrary web content.
+- If accepting URLs from clients, validate first: require `https://`, allowlist trusted hosts, reject private addresses. See the Express.js example below.
+- Never forward `req.body.referenceImages` straight into `textToImage.create`. The SDK snippets below use raw URLs for brevity - they aren't production templates.
+- Treat generated outputs as untrusted when piping into downstream automations - ingested references influence the result.
+
+## Endpoint: `POST /v1/text_to_image`
+
+### Basic Text-to-Image
+
+```javascript
+// Node.js SDK
+import RunwayML from '@runwayml/sdk';
+
+const client = new RunwayML();
+
+const task = await client.textToImage.create({
+  model: 'gen4_image',
+  promptText: 'A serene Japanese garden with cherry blossoms and a koi pond',
+  ratio: '1280:720'
+}).waitForTaskOutput();
+
+const imageUrl = task.output[0];
+```
+
+```python
+# Python SDK
+from runwayml import RunwayML
+
+client = RunwayML()
+
+task = client.text_to_image.create(
+    model='gen4_image',
+    prompt_text='A serene Japanese garden with cherry blossoms and a koi pond',
+    ratio='1280:720'
+).wait_for_task_output()
+
+image_url = task.output[0]
+```
+
+### With Reference Images
+
+Reference images let you guide the generation with visual references. Use `@Tag` syntax in the prompt to reference specific images.
+
+Recommended: upload via `rw-integrate-uploads` and pass the returned `runway://` URI.
+
+```javascript
+import fs from 'fs';
+
+const refUpload = await client.uploads.createEphemeral(
+  fs.createReadStream('/path/to/reference.jpg')
+);
+
+const task = await client.textToImage.create({
+  model: 'gen4_image',
+  promptText: 'A portrait in the style of @Reference',
+  referenceImages: [
+    { uri: refUpload.runwayUri, tag: 'Reference' }
+  ],
+  ratio: '1280:720'
+}).waitForTaskOutput();
+```
+
+External URLs also work - only pass origins you control (see Security):
+
+```javascript
+const task = await client.textToImage.create({
+  model: 'gen4_image',
+  promptText: '@EiffelTower painted in the style of @StarryNight',
+  referenceImages: [
+    { uri: 'https://cdn.yourapp.com/eiffel-tower.jpg', tag: 'EiffelTower' },
+    { uri: 'https://cdn.yourapp.com/starry-night.jpg', tag: 'StarryNight' }
+  ],
+  ratio: '1280:720'
+}).waitForTaskOutput();
+```
+
+```python
+task = client.text_to_image.create(
+    model='gen4_image',
+    prompt_text='@EiffelTower painted in the style of @StarryNight',
+    reference_images=[
+        {"uri": "https://cdn.yourapp.com/eiffel-tower.jpg", "tag": "EiffelTower"},
+        {"uri": "https://cdn.yourapp.com/starry-night.jpg", "tag": "StarryNight"}
+    ],
+    ratio='1280:720'
+).wait_for_task_output()
+```
+
+## Common Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `model` | string | Model ID (required) |
+| `promptText` | string | Text description of the image (required) |
+| `ratio` | string | Aspect ratio, e.g. `'1280:720'`, `'720:1280'`, `'1080:1080'` |
+| `referenceImages` | array | Optional. Array of `{ uri, tag }` objects for visual guidance |
+
+## Integration Pattern
+
+1. Prefer uploads over URLs - Default to `rw-integrate-uploads` so inputs are `runway://` URIs. External URLs only from origins you control (see Security).
+2. Write the server-side handler - Create an API route or server function.
+3. Handle the output - Download and store the image, don't serve signed URLs to clients.
+4. Add error handling - Wrap in try/catch.
+
+### Example: Express.js API Route
+
+```javascript
+import RunwayML from '@runwayml/sdk';
+import express from 'express';
+
+const client = new RunwayML();
+const app = express();
+app.use(express.json());
+
+// `runway://` URIs bypass this check; external URLs must match the allowlist.
+const ALLOWED_MEDIA_HOSTS = new Set(['cdn.yourapp.com', 'uploads.yourapp.com']);
+
+function validateReferenceImages(refs) {
+  if (!Array.isArray(refs)) throw new Error('referenceImages must be an array');
+  return refs.map(({ uri, tag }) => {
+    if (typeof uri !== 'string' || typeof tag !== 'string') {
+      throw new Error('each reference needs a uri and tag');
+    }
+    if (uri.startsWith('runway://')) return { uri, tag };
+    const u = new URL(uri);
+    if (u.protocol !== 'https:') throw new Error('https required');
+    if (!ALLOWED_MEDIA_HOSTS.has(u.hostname)) throw new Error('untrusted media host');
+    return { uri: u.toString(), tag };
+  });
+}
+
+app.post('/api/generate-image', async (req, res) => {
+  try {
+    const { prompt, model = 'gen4_image', ratio = '1280:720', referenceImages } = req.body;
+
+    const task = await client.textToImage.create({
+      model,
+      promptText: prompt,
+      ratio,
+      ...(referenceImages && { referenceImages: validateReferenceImages(referenceImages) })
+    }).waitForTaskOutput();
+
+    res.json({ imageUrl: task.output[0] });
+  } catch (error) {
+    console.error('Image generation failed:', error);
+    res.status(400).json({ error: error.message });
+  }
+});
+```
+
+> For browser uploads: POST files to your server, upload via `rw-integrate-uploads`, and pass the `runway://` URI. Don't accept raw URLs from the browser.
+
+### Example: Next.js API Route
+
+```typescript
+// app/api/generate-image/route.ts
+import RunwayML from '@runwayml/sdk';
+import { NextRequest, NextResponse } from 'next/server';
+
+const client = new RunwayML();
+const ALLOWED_MEDIA_HOSTS = new Set(['cdn.yourapp.com', 'uploads.yourapp.com']);
+
+function trustedReferenceImages(referenceImages?: Array<{ uri: string; tag: string }>) {
+  return referenceImages?.map((ref) => {
+    if (ref.uri.startsWith('runway://')) return ref;
+    const url = new URL(ref.uri);
+    if (url.protocol !== 'https:') throw new Error('https required');
+    if (!ALLOWED_MEDIA_HOSTS.has(url.hostname)) throw new Error('untrusted media host');
+    return { ...ref, uri: url.toString() };
+  });
+}
+
+export async function POST(request: NextRequest) {
+  const { prompt, referenceImages } = await request.json();
+
+  try {
+    const task = await client.textToImage.create({
+      model: 'gen4_image',
+      promptText: prompt,
+      ratio: '1280:720',
+      ...(referenceImages && { referenceImages: trustedReferenceImages(referenceImages) })
+    }).waitForTaskOutput();
+
+    return NextResponse.json({ imageUrl: task.output[0] });
+  } catch (error) {
+    return NextResponse.json(
+      { error: error instanceof Error ? error.message : 'Generation failed' },
+      { status: 500 }
+    );
+  }
+}
+```
+
+### Example: FastAPI Route
+
+```python
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from urllib.parse import urlparse
+from runwayml import RunwayML
+
+app = FastAPI()
+client = RunwayML()
+ALLOWED_MEDIA_HOSTS = {"cdn.yourapp.com", "uploads.yourapp.com"}
+
+def trusted_reference_images(reference_images: list[dict] | None) -> list[dict] | None:
+    if not reference_images:
+        return None
+    safe = []
+    for ref in reference_images:
+        uri = ref["uri"]
+        if uri.startswith("runway://"):
+            safe.append(ref)
+            continue
+        parsed = urlparse(uri)
+        if parsed.scheme != "https" or parsed.hostname not in ALLOWED_MEDIA_HOSTS:
+            raise ValueError("untrusted reference image URL")
+        safe_ref = ref.copy()
+        safe_ref["uri"] = uri
+        safe.append(safe_ref)
+    return safe
+
+class ImageRequest(BaseModel):
+    prompt: str
+    model: str = "gen4_image"
+    ratio: str = "1280:720"
+    reference_images: list[dict] | None = None
+
+@app.post("/api/generate-image")
+async def generate_image(req: ImageRequest):
+    try:
+        params = {
+            "model": req.model,
+            "prompt_text": req.prompt,
+            "ratio": req.ratio,
+        }
+        reference_images = trusted_reference_images(req.reference_images)
+        if reference_images:
+            params["reference_images"] = reference_images
+
+        task = client.text_to_image.create(
+            model=params["model"],
+            prompt_text=params["prompt_text"],
+            ratio=params["ratio"],
+            reference_images=params.get("reference_images"),
+        ).wait_for_task_output()
+        return {"image_url": task.output[0]}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+```
+
+## Tips
+
+- Output URLs expire in 24-48 hours. Download images to your own storage immediately.
+- Reference images use `@Tag` syntax in the prompt - the tag must match the `tag` field in the `referenceImages` array.
+- For local files, always upload via `rw-integrate-uploads` first, then use the `runway://` URI.
+- `gen4_image_turbo` is the cheapest option at 2 credits per image - good for prototyping.
diff --git a/plugins/runway-api/skills/rw-integrate-uploads/SKILL.md b/plugins/runway-api/skills/rw-integrate-uploads/SKILL.md
new file mode 100644
index 00000000..98687166
--- /dev/null
+++ b/plugins/runway-api/skills/rw-integrate-uploads/SKILL.md
@@ -0,0 +1,299 @@
+---
+name: rw-integrate-uploads
+description: "Help users upload local files to Runway for use as inputs to generation models"
+user-invocable: false
+---
+
+# Integrate Uploads
+
+> PREREQUISITE: Run `rw-check-compatibility` first. Run `rw-fetch-api-reference` to load the latest API reference before integrating. Requires `rw-setup-api-key` for API credentials.
+
+Help users upload local files (images, videos, audio) to Runway's ephemeral storage for use as inputs to generation models.
+
+## When to Use Uploads
+
+Use the Uploads API when:
+- The user has a local file (not a public URL) they want to use as input
+- The file exceeds data URI size limits (5 MB for images, 16 MB for video/audio)
+- The file's URL doesn't meet Runway's URL requirements (HTTPS, proper headers, no redirects)
+
+You do NOT need uploads when:
+- The asset is already at a public HTTPS URL with proper headers
+- The asset is small enough for a data URI (< 5 MB image, < 16 MB video)
+
+## How It Works
+
+1. Request an ephemeral upload slot -> get a presigned upload URL and form fields
+2. Upload the file to the presigned URL
+3. Use the returned `runway://` URI as input to any generation endpoint
+
+`runway://` URIs are valid for 24 hours.
+
+## SDK Upload (Recommended)
+
+### Node.js
+
+```javascript
+import RunwayML from '@runwayml/sdk';
+import fs from 'fs';
+
+const client = new RunwayML();
+
+// Upload from a file stream
+const upload = await client.uploads.createEphemeral(
+  fs.createReadStream('/path/to/image.jpg')
+);
+
+// Use the runway:// URI in any generation call
+const task = await client.imageToVideo.create({
+  model: 'gen4.5',
+  promptImage: upload.runwayUri,
+  promptText: 'The scene comes to life',
+  ratio: '1280:720',
+  duration: 5
+}).waitForTaskOutput();
+```
+
+The Node.js SDK accepts:
+- `fs.ReadStream` - file streams
+- `File` objects - from web APIs
+- `Blob` objects
+- `Buffer` / `ArrayBuffer` / typed arrays
+- `Response` objects - from `fetch()`
+- Async iterables
+
+### Python
+
+```python
+from runwayml import RunwayML
+from pathlib import Path
+
+client = RunwayML()
+
+# Upload from a file path
+upload = client.uploads.create_ephemeral(
+    Path('/path/to/image.jpg')
+)
+
+# Use the runway:// URI
+task = client.image_to_video.create(
+    model='gen4.5',
+    prompt_image=upload.runway_uri,
+    prompt_text='The scene comes to life',
+    ratio='1280:720',
+    duration=5
+).wait_for_task_output()
+```
+
+The Python SDK accepts:
+- `pathlib.Path` objects
+- `IOBase` objects (file-like objects)
+- Two-tuples of `(filename, content)`
+
+## REST API Upload (Manual)
+
+If not using the SDK, the upload flow has three steps:
+
+### Step 1: Create an upload slot
+
+```javascript
+const response = await fetch('https://api.dev.runwayml.com/v1/uploads', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${process.env.RUNWAYML_API_SECRET}`,
+    'X-Runway-Version': '2024-11-06',
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    filename: 'image.jpg',
+    type: 'ephemeral'
+  })
+});
+
+const { uploadUrl, fields, runwayUri } = await response.json();
+```
+
+### Step 2: Upload the file using the presigned URL
+
+```javascript
+const formData = new FormData();
+
+// Add all presigned form fields first
+for (const [key, value] of Object.entries(fields)) {
+  formData.append(key, value);
+}
+
+// Add the file last
+formData.append('file', fileBuffer, 'image.jpg');
+
+await fetch(uploadUrl, {
+  method: 'POST',
+  body: formData
+});
+```
+
+### Step 3: Use the `runway://` URI
+
+```javascript
+const task = await fetch('https://api.dev.runwayml.com/v1/image_to_video', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${process.env.RUNWAYML_API_SECRET}`,
+    'X-Runway-Version': '2024-11-06',
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    model: 'gen4.5',
+    promptImage: runwayUri,
+    promptText: 'Animate this scene',
+    ratio: '1280:720',
+    duration: 5
+  })
+});
+```
+
+## Upload Constraints
+
+| Constraint | Value |
+|-----------|-------|
+| Minimum file size | 512 bytes |
+| Maximum file size | 200 MB |
+| URI validity | 24 hours |
+| Requires credits | Yes (must have purchased credits) |
+
+## Integration Pattern
+
+### Express.js - Upload Endpoint with File Generation
+
+```javascript
+import RunwayML from '@runwayml/sdk';
+import express from 'express';
+import multer from 'multer';
+
+const client = new RunwayML();
+const app = express();
+const upload = multer({
+  storage: multer.memoryStorage(),
+  limits: { fileSize: 200 * 1024 * 1024 },
+  fileFilter: (_req, file, cb) => {
+    const ok = file.mimetype.startsWith('image/') ||
+      file.mimetype.startsWith('video/') ||
+      file.mimetype.startsWith('audio/');
+    cb(ok ? null : new Error('unsupported media type'), ok);
+  }
+});
+
+app.post('/api/image-to-video', upload.single('image'), async (req, res) => {
+  try {
+    if (!req.file) return res.status(400).json({ error: 'image file is required' });
+
+    // Upload the user's file to Runway
+    const runwayUpload = await client.uploads.createEphemeral(req.file.buffer);
+
+    // Use the uploaded file for video generation
+    const task = await client.imageToVideo.create({
+      model: 'gen4.5',
+      promptImage: runwayUpload.runwayUri,
+      promptText: req.body.prompt || 'Animate this image',
+      ratio: '1280:720',
+      duration: 5
+    }).waitForTaskOutput();
+
+    res.json({ videoUrl: task.output[0] });
+  } catch (error) {
+    console.error('Generation failed:', error);
+    res.status(500).json({ error: error.message });
+  }
+});
+```
+
+### Next.js - Upload + Generate
+
+```typescript
+// app/api/image-to-video/route.ts
+import RunwayML from '@runwayml/sdk';
+import { NextRequest, NextResponse } from 'next/server';
+
+const client = new RunwayML();
+const MAX_UPLOAD_BYTES = 200 * 1024 * 1024;
+const ALLOWED_MIME_PREFIXES = ['image/', 'video/', 'audio/'];
+
+export async function POST(request: NextRequest) {
+  const formData = await request.formData();
+  const imageFile = formData.get('image') as File;
+  const prompt = formData.get('prompt') as string;
+
+  try {
+    if (!imageFile) throw new Error('image file is required');
+    if (imageFile.size > MAX_UPLOAD_BYTES) throw new Error('file is too large');
+    if (!ALLOWED_MIME_PREFIXES.some((prefix) => imageFile.type.startsWith(prefix))) {
+      throw new Error('unsupported media type');
+    }
+
+    // Upload file to Runway
+    const upload = await client.uploads.createEphemeral(imageFile);
+
+    // Generate video from the uploaded image
+    const task = await client.imageToVideo.create({
+      model: 'gen4.5',
+      promptImage: upload.runwayUri,
+      promptText: prompt || 'Animate this image',
+      ratio: '1280:720',
+      duration: 5
+    }).waitForTaskOutput();
+
+    return NextResponse.json({ videoUrl: task.output[0] });
+  } catch (error) {
+    return NextResponse.json(
+      { error: error instanceof Error ? error.message : 'Failed' },
+      { status: 500 }
+    );
+  }
+}
+```
+
+### FastAPI - Upload + Generate
+
+```python
+from fastapi import FastAPI, UploadFile, Form, HTTPException
+from runwayml import RunwayML
+
+app = FastAPI()
+client = RunwayML()
+MAX_UPLOAD_BYTES = 200 * 1024 * 1024
+ALLOWED_MIME_PREFIXES = ("image/", "video/", "audio/")
+
+@app.post("/api/image-to-video")
+async def image_to_video(image: UploadFile, prompt: str = Form("Animate this image")):
+    try:
+        if not image.content_type or not image.content_type.startswith(ALLOWED_MIME_PREFIXES):
+            raise HTTPException(status_code=400, detail="unsupported media type")
+
+        # Upload to Runway
+        content = await image.read()
+        if len(content) > MAX_UPLOAD_BYTES:
+            raise HTTPException(status_code=400, detail="file is too large")
+
+        upload = client.uploads.create_ephemeral((image.filename, content))
+
+        # Generate video
+        task = client.image_to_video.create(
+            model="gen4.5",
+            prompt_image=upload.runway_uri,
+            prompt_text=prompt,
+            ratio="1280:720",
+            duration=5
+        ).wait_for_task_output()
+
+        return {"video_url": task.output[0]}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+```
+
+## Tips
+
+- Always upload local files before passing them to generation endpoints. Don't try to pass local file paths - they won't work.
+- `runway://` URIs expire after 24 hours. If you need to re-use an asset, upload it again.
+- The SDK handles the presigned URL flow automatically - prefer the SDK over manual REST calls.
+- For models requiring image/video input (image-to-video, video-to-video, character performance), upload the asset first, then pass the `runway://` URI.
+- Maximum 200 MB per file via uploads - larger than URL (16 MB) or data URI (5 MB) limits.
diff --git a/plugins/runway-api/skills/rw-integrate-video/SKILL.md b/plugins/runway-api/skills/rw-integrate-video/SKILL.md
new file mode 100644
index 00000000..608dfd15
--- /dev/null
+++ b/plugins/runway-api/skills/rw-integrate-video/SKILL.md
@@ -0,0 +1,430 @@
+---
+name: rw-integrate-video
+description: "Help users integrate Runway video generation APIs (text-to-video, image-to-video, video-to-video)"
+user-invocable: false
+---
+
+# Integrate Video Generation
+
+> PREREQUISITE: Run `rw-check-compatibility` first. Run `rw-fetch-api-reference` to load the latest API reference before integrating. Requires `rw-setup-api-key` for API credentials. Requires `rw-integrate-uploads` when the user has local files to use as input.
+
+Help users add Runway video generation to their server-side code.
+
+## Available Models
+
+| Model | Best For | Input | Cost | Speed |
+|-------|----------|-------|------|-------|
+| `seedance2` | Reference image and video, long duration | Text, Image, and/or Video | 36 credits/sec | Standard |
+| `gen4.5` | High quality, general purpose | Text and/or Image | 12 credits/sec | Standard |
+| `gen4_turbo` | Fast, image-driven | Image required | 5 credits/sec | Fast |
+| `gen4_aleph` | Video editing/transformation | Video + Text/Image | 15 credits/sec | Standard |
+| `veo3` | Premium Google model | Text/Image | 40 credits/sec | Standard |
+| `veo3.1` | High quality Google model | Text/Image | 20-40 credits/sec | Standard |
+| `veo3.1_fast` | Fast Google model | Text/Image | 10-15 credits/sec | Fast |
+
+Model selection guidance:
+- Default recommendation: `gen4.5` - best balance of quality and cost
+- Product ads / e-commerce: `seedance2` - up to 15s, supports reference image and video
+- Budget-conscious: `gen4_turbo` (requires image) or `veo3.1_fast`
+- Highest quality: `veo3` (most expensive)
+- Video-to-video editing: `gen4_aleph` or `seedance2`
+
+## Security
+
+`promptImage`, `promptVideo`, `videoUri`, and `references[].uri` are fetched server-side by the Runway API - treat them like any outbound fetch:
+
+- Prefer `runway://` URIs from `rw-integrate-uploads` - scoped to your account, no arbitrary web content.
+- If accepting URLs from clients, validate first: require `https://`, allowlist trusted hosts, reject private addresses. See the Express.js example below.
+- Never forward `req.body.imageUrl` (or similar) straight into `promptImage` / `promptVideo`. The SDK snippets below use raw URLs for brevity - they aren't production templates.
+- Treat generated outputs as untrusted when piping into downstream automations - ingested media influences the result.
+
+## Endpoints
+
+### Text-to-Video: `POST /v1/text_to_video`
+
+Generate video from a text prompt only.
+
+Compatible models: `seedance2`, `gen4.5`, `veo3`, `veo3.1`, `veo3.1_fast`
+
+```javascript
+// Node.js SDK
+import RunwayML from '@runwayml/sdk';
+
+const client = new RunwayML();
+
+const task = await client.textToVideo.create({
+  model: 'gen4.5',
+  promptText: 'A golden retriever running through a field of wildflowers at sunset',
+  ratio: '1280:720',
+  duration: 5
+}).waitForTaskOutput();
+
+// task.output is an array of signed URLs
+const videoUrl = task.output[0];
+```
+
+```python
+# Python SDK
+from runwayml import RunwayML
+
+client = RunwayML()
+
+task = client.text_to_video.create(
+    model='gen4.5',
+    prompt_text='A golden retriever running through a field of wildflowers at sunset',
+    ratio='1280:720',
+    duration=5
+).wait_for_task_output()
+
+video_url = task.output[0]
+```
+
+### Image-to-Video: `POST /v1/image_to_video`
+
+Animate a still image into a video.
+
+Compatible models: `seedance2`, `gen4.5`, `gen4_turbo`, `veo3`, `veo3.1`, `veo3.1_fast`
+
+Recommended: upload via `rw-integrate-uploads` and pass the returned `runway://` URI.
+
+```javascript
+// Node.js SDK - preferred flow
+import fs from 'fs';
+
+const upload = await client.uploads.createEphemeral(
+  fs.createReadStream('/path/to/image.jpg')
+);
+
+const task = await client.imageToVideo.create({
+  model: 'gen4.5',
+  promptImage: upload.runwayUri,
+  promptText: 'The scene comes to life with gentle wind',
+  ratio: '1280:720',
+  duration: 5
+}).waitForTaskOutput();
+```
+
+External URLs also work - only pass origins you control (see Security):
+
+```javascript
+const task = await client.imageToVideo.create({
+  model: 'gen4.5',
+  promptImage: 'https://cdn.yourapp.com/landscape.jpg',
+  promptText: 'Camera slowly pans right revealing a mountain range',
+  ratio: '1280:720',
+  duration: 5
+}).waitForTaskOutput();
+```
+
+```python
+# Python SDK
+task = client.image_to_video.create(
+    model='gen4.5',
+    prompt_image='https://cdn.yourapp.com/landscape.jpg',
+    prompt_text='Camera slowly pans right revealing a mountain range',
+    ratio='1280:720',
+    duration=5
+).wait_for_task_output()
+```
+
+### Video-to-Video: `POST /v1/video_to_video`
+
+Transform an existing video with a text prompt and/or reference image.
+
+Compatible models: `gen4_aleph`, `seedance2`
+
+```javascript
+// Node.js SDK - gen4_aleph
+const task = await client.videoToVideo.create({
+  model: 'gen4_aleph',
+  videoUri: 'https://cdn.yourapp.com/source.mp4',
+  promptText: 'Transform into an animated cartoon style',
+}).waitForTaskOutput();
+```
+
+```javascript
+// Node.js SDK - seedance2 video-to-video (with optional image reference)
+const task = await client.videoToVideo.create({
+  model: 'seedance2',
+  promptVideo: 'https://cdn.yourapp.com/input.mp4',
+  promptText: 'Transform into a warm golden sunset scene',
+  references: [{ type: 'image', uri: 'https://cdn.yourapp.com/style_ref.jpg' }]
+}).waitForTaskOutput();
+```
+
+> seedance2 VTV input requirements: max 15 seconds, max 32 MB, min 720p resolution, MP4 recommended.
+
+### Seedance 2
+
+Seedance 2 supports text-to-video, image-to-video (two modes), and video-to-video. It uses pixel-based ratios: `1280:720`, `720:1280`, `960:960`, `1112:834`, `834:1112`, `1470:630`, `992:432`, `864:496`, `752:560`, `640:640`, `560:752`, `496:864`.
+
+#### Text-to-Video
+
+```javascript
+const task = await client.textToVideo.create({
+  model: 'seedance2',
+  promptText: 'A calm ocean wave gently crashing on a sandy beach at sunset',
+  duration: 5,
+  ratio: '1280:720'
+}).waitForTaskOutput();
+```
+
+#### Image-to-Video - Mode 1: First / Last Frame
+
+Use a specific image as the first and/or last frame. The `references` field cannot be used in this mode.
+
+```javascript
+const task = await client.imageToVideo.create({
+  model: 'seedance2',
+  promptText: 'Smooth transition from day to night in a cozy mountain cabin',
+  promptImage: [
+    { uri: 'https://cdn.yourapp.com/image.jpg', position: 'first' },
+    { uri: 'https://cdn.yourapp.com/image2.jpg', position: 'last' }
+  ],
+  duration: 4,
+  ratio: '1280:720'
+}).waitForTaskOutput();
+```
+
+`promptImage` is an array of objects with `uri` (required) and `position` (`"first"` or `"last"`, defaults to first).
+
+#### Image-to-Video - Mode 2: Image Reference
+
+Use an image as a stylistic/content reference rather than a literal frame. `promptImage` is still required (as a URI string or single-item array).
+
+```javascript
+const task = await client.imageToVideo.create({
+  model: 'seedance2',
+  promptText: 'Smooth transition from day to night in a cozy mountain cabin',
+  promptImage: 'https://cdn.yourapp.com/image.jpg',
+  references: [{ type: 'image', uri: 'https://cdn.yourapp.com/reference.jpg' }],
+  duration: 4,
+  ratio: '1280:720'
+}).waitForTaskOutput();
+```
+
+> These two ITV modes are mutually exclusive - you cannot use `position` in `promptImage` and `references` in the same request.
+
+#### Video-to-Video
+
+Transform an existing video guided by a text prompt, optionally with an image reference.
+
+```python
+task = client.video_to_video.create(
+    model='seedance2',
+    prompt_video='https://cdn.yourapp.com/input.mp4',
+    prompt_text='Transform into a warm golden sunset scene',
+    references=[{'type': 'image', 'uri': 'https://cdn.yourapp.com/style_ref.jpg'}]
+).wait_for_task_output()
+```
+
+> VTV input requirements: max 15 seconds, max 32 MB, min 720p resolution, MP4 recommended.
+
+#### Seedance 2 Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `model` | string | Yes | Must be `"seedance2"` |
+| `promptText` | string | Yes | Text description of the desired video |
+| `duration` | number | Yes (TTV/ITV) | Duration in seconds |
+| `ratio` | string | Yes (TTV/ITV) | `1280:720`, `720:1280`, `960:960`, `1112:834`, `834:1112`, `1470:630` |
+| `promptImage` | string or array | Yes (ITV) | URI string or array of `{ uri, position? }` objects |
+| `promptVideo` | string | Yes (seedance2 VTV) | Input video URI (seedance2 only) |
+| `videoUri` | string | Yes (gen4_aleph VTV) | Input video URI (gen4_aleph only) |
+| `references` | array | No | Image references - `[{ type: "image", uri: "..." }]` (ITV Mode 2 and VTV only) |
+
+### Character Performance: `POST /v1/character_performance`
+
+Animate a character with facial/body performance.
+
+Compatible models: `act_two`
+
+```javascript
+const task = await client.characterPerformance.create({
+  model: 'act_two',
+  promptImage: 'https://cdn.yourapp.com/character.jpg',
+  promptPerformance: 'https://cdn.yourapp.com/performance.mp4',
+  ratio: '1280:720',
+  duration: 5
+}).waitForTaskOutput();
+```
+
+## Common Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `model` | string | Model ID (required) |
+| `promptText` | string | Text prompt describing the video |
+| `promptImage` | string | URL, data URI, or `runway://` URI of input image |
+| `ratio` | string | Aspect ratio, e.g. `'1280:720'`, `'720:1280'` |
+| `duration` | number | Video length in seconds (2-15, model-dependent) |
+
+## Integration Pattern
+
+When helping the user integrate, follow this pattern:
+
+1. Determine the use case - What type of video generation? (text-to-video, image-to-video, etc.)
+2. Prefer uploads over URLs - Default to `rw-integrate-uploads` so inputs are `runway://` URIs. External URLs only from origins you control (see Security).
+3. Select the model - Recommend based on quality/cost/speed needs
+4. Write the server-side handler - Create an API route or server function
+5. Handle the output - Download and store the video, don't serve signed URLs to clients
+6. Add error handling - Wrap in try/catch, handle `TaskFailedError`
+
+### Example: Express.js API Route
+
+```javascript
+import RunwayML from '@runwayml/sdk';
+import express from 'express';
+
+const client = new RunwayML();
+const app = express();
+app.use(express.json());
+
+// `runway://` URIs bypass this check; external URLs must match the allowlist.
+const ALLOWED_MEDIA_HOSTS = new Set(['cdn.yourapp.com', 'uploads.yourapp.com']);
+
+function assertTrustedMediaUrl(raw) {
+  const u = new URL(raw);
+  if (u.protocol !== 'https:') throw new Error('https required');
+  if (!ALLOWED_MEDIA_HOSTS.has(u.hostname)) throw new Error('untrusted media host');
+  return u.toString();
+}
+
+app.post('/api/generate-video', async (req, res) => {
+  try {
+    const { prompt, imageUrl, model = 'gen4.5', duration = 5 } = req.body;
+
+    const params = {
+      model,
+      promptText: prompt,
+      ratio: '1280:720',
+      duration
+    };
+
+    let task;
+    if (imageUrl) {
+      task = await client.imageToVideo.create({
+        ...params,
+        promptImage: assertTrustedMediaUrl(imageUrl)
+      }).waitForTaskOutput();
+    } else {
+      task = await client.textToVideo.create(params).waitForTaskOutput();
+    }
+
+    res.json({ videoUrl: task.output[0] });
+  } catch (error) {
+    console.error('Video generation failed:', error);
+    res.status(400).json({ error: error.message });
+  }
+});
+```
+
+> For browser uploads: POST files to your server, upload via `rw-integrate-uploads`, and pass the `runway://` URI. Don't accept raw URLs from the browser.
+
+### Example: Next.js API Route
+
+```typescript
+// app/api/generate-video/route.ts
+import RunwayML from '@runwayml/sdk';
+import { NextRequest, NextResponse } from 'next/server';
+
+const client = new RunwayML();
+const ALLOWED_MEDIA_HOSTS = new Set(['cdn.yourapp.com', 'uploads.yourapp.com']);
+
+function trustedMediaUri(raw: string): string {
+  if (raw.startsWith('runway://')) return raw;
+  const url = new URL(raw);
+  if (url.protocol !== 'https:') throw new Error('https required');
+  if (!ALLOWED_MEDIA_HOSTS.has(url.hostname)) throw new Error('untrusted media host');
+  return url.toString();
+}
+
+export async function POST(request: NextRequest) {
+  const { prompt, imageUrl } = await request.json();
+
+  try {
+    const task = imageUrl
+      ? await client.imageToVideo.create({
+          model: 'gen4.5',
+          promptImage: trustedMediaUri(imageUrl),
+          promptText: prompt,
+          ratio: '1280:720',
+          duration: 5
+        }).waitForTaskOutput()
+      : await client.textToVideo.create({
+          model: 'gen4.5',
+          promptText: prompt,
+          ratio: '1280:720',
+          duration: 5
+        }).waitForTaskOutput();
+
+    return NextResponse.json({ videoUrl: task.output[0] });
+  } catch (error) {
+    return NextResponse.json(
+      { error: error instanceof Error ? error.message : 'Generation failed' },
+      { status: 500 }
+    );
+  }
+}
+```
+
+### Example: FastAPI Route
+
+```python
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from urllib.parse import urlparse
+from runwayml import RunwayML
+
+app = FastAPI()
+client = RunwayML()
+ALLOWED_MEDIA_HOSTS = {"cdn.yourapp.com", "uploads.yourapp.com"}
+
+def trusted_media_uri(raw: str) -> str:
+    if raw.startswith("runway://"):
+        return raw
+    parsed = urlparse(raw)
+    if parsed.scheme != "https":
+        raise ValueError("https required")
+    if parsed.hostname not in ALLOWED_MEDIA_HOSTS:
+        raise ValueError("untrusted media host")
+    return raw
+
+class VideoRequest(BaseModel):
+    prompt: str
+    image_url: str | None = None
+    model: str = "gen4.5"
+    duration: int = 5
+
+@app.post("/api/generate-video")
+async def generate_video(req: VideoRequest):
+    try:
+        if req.image_url:
+            task = client.image_to_video.create(
+                model=req.model,
+                prompt_image=trusted_media_uri(req.image_url),
+                prompt_text=req.prompt,
+                ratio="1280:720",
+                duration=req.duration
+            ).wait_for_task_output()
+        else:
+            task = client.text_to_video.create(
+                model=req.model,
+                prompt_text=req.prompt,
+                ratio="1280:720",
+                duration=req.duration
+            ).wait_for_task_output()
+
+        return {"video_url": task.output[0]}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+```
+
+## Tips
+
+- Output URLs expire in 24-48 hours. Download videos to your own storage (S3, GCS, local filesystem) immediately after generation.
+- `gen4_turbo` requires an image - it cannot do text-only generation.
+- Video-to-video models: `gen4_aleph` and `seedance2` - use for editing/transforming existing videos.
+- Duration varies by model. Most models support 2-10 seconds; seedance2 supports up to 15 seconds.
+- `waitForTaskOutput()` has a default 10-minute timeout. For long-running generations, you may want to implement your own polling loop or increase the timeout.
+- For local files, always use `rw-integrate-uploads` to upload first, then pass the `runway://` URI.
diff --git a/plugins/runway-api/skills/rw-recipe-full-setup/SKILL.md b/plugins/runway-api/skills/rw-recipe-full-setup/SKILL.md
new file mode 100644
index 00000000..d1157d9e
--- /dev/null
+++ b/plugins/runway-api/skills/rw-recipe-full-setup/SKILL.md
@@ -0,0 +1,103 @@
+---
+name: rw-recipe-full-setup
+description: "Complete Runway API setup: check compatibility, configure API key, and integrate generation endpoints"
+user-invocable: true
+---
+
+# Full Runway API Setup
+
+> PREREQUISITE: Run `rw-check-compatibility` first to ensure the project has server-side capability.
+
+This recipe guides a user through the complete process of integrating Runway's public API into their project. It chains together the compatibility check, API key setup, and API integration skills.
+
+## Workflow
+
+### Phase 1: Compatibility Check
+
+Use `rw-check-compatibility` to analyze the user's project.
+
+1. Identify the project type (Node.js, Python, etc.)
+2. Verify server-side capability
+3. Check runtime version compatibility
+4. Look for existing Runway SDK installation
+
+If the project is INCOMPATIBLE, stop and explain the options:
+
+- Add a backend (Express, FastAPI, etc.)
+- Use a fullstack framework (Next.js, SvelteKit, Nuxt, Remix)
+- Add serverless functions (Vercel Functions, AWS Lambda)
+- Create a separate backend service
+
+If NEEDS CHANGES, help the user make the required changes before proceeding.
+
+If COMPATIBLE, proceed to Phase 2.
+
+### Phase 2: API Key Setup
+
+Use `rw-setup-api-key` to configure credentials.
+
+1. Direct the user to https://dev.runwayml.com/ to create an account and API key
+2. Install the appropriate SDK (`@runwayml/sdk` for Node.js, `runwayml` for Python)
+3. Configure the `RUNWAYML_API_SECRET` environment variable
+4. Update `.gitignore` to exclude `.env`
+5. Remind about credit purchase requirement ($10 minimum)
+
+Wait for the user to confirm they have their API key before proceeding.
+
+### Phase 3: Determine What to Integrate
+
+Ask the user what they want to build. Based on their response, use the appropriate integration skill:
+
+| User wants...                   | Skill to use                                                                    |
+| ------------------------------- | ------------------------------------------------------------------------------- |
+| Generate videos from text       | `rw-integrate-video` (text-to-video)                                              |
+| Animate images into video       | `rw-integrate-video` (image-to-video) + `rw-integrate-uploads` if local files       |
+| Edit/transform existing videos  | `rw-integrate-video` (video-to-video) + `rw-integrate-uploads`                      |
+| Generate images from text       | `rw-integrate-image`                                                              |
+| Generate images with references | `rw-integrate-image` + `rw-integrate-uploads` if local refs                         |
+| Text-to-speech                  | `rw-integrate-audio`                                                              |
+| Sound effects                   | `rw-integrate-audio`                                                              |
+| Voice isolation/dubbing         | `rw-integrate-audio` + `rw-integrate-uploads`                                       |
+| Real-time conversational avatar | `rw-integrate-characters` + `rw-integrate-character-embed` (React UI)               |
+| Avatar with domain knowledge    | `rw-integrate-characters` + `rw-integrate-documents` + `rw-integrate-character-embed` |
+| Multiple capabilities           | Integrate each one, sharing the same client instance                            |
+
+### Phase 4: Write the Integration Code
+
+Based on the user's framework and needs:
+
+1. Create the API route/handler - server-side endpoint that calls Runway
+2. Add upload handling if the user needs to accept files from their users
+3. Add error handling - catch and handle task failures
+4. Handle output storage - remind user that output URLs expire in 24-48 hours
+
+### Phase 5: Test and Verify
+
+Help the user:
+
+1. Run a test generation to verify everything works
+2. Check for common issues (missing env var, insufficient credits, wrong model)
+3. Confirm output is accessible
+
+## Decision Tree for Upload Requirements
+
+When the user's workflow involves images or videos as input:
+
+```
+Does the input come from a public HTTPS URL?
+- - YES -> Pass the URL directly to the API
+- NO -> Is it a local file or user-uploaded file?
+    - - YES -> Use rw-integrate-uploads to upload first, then pass runway:// URI
+    - NO -> Is it small enough for a data URI? (< 5MB image, < 16MB video)
+        - - YES -> Convert to base64 data URI
+        - NO -> Use rw-integrate-uploads
+```
+
+## Important Reminders
+
+- Never expose the API key in client-side code. All API calls must happen server-side.
+- Output URLs expire. Always download and store generated content.
+- Credits are required. The API won't work without prepaid credits.
+- Rate limits exist. Rate limits exist. You should always check what is the rate limit before attempting concurrent generations.
+- Content moderation applies to both inputs and outputs. Safety-flagged inputs are non-refundable.
+- Be cost-conscious. Help users pick the right model for their budget. Credit cost can be found on https://docs.dev.runwayml.com/guides/pricing/
diff --git a/plugins/runway-api/skills/rw-setup-api-key/SKILL.md b/plugins/runway-api/skills/rw-setup-api-key/SKILL.md
new file mode 100644
index 00000000..a722aadc
--- /dev/null
+++ b/plugins/runway-api/skills/rw-setup-api-key/SKILL.md
@@ -0,0 +1,153 @@
+---
+name: rw-setup-api-key
+description: "Guide users through obtaining and configuring a Runway API key"
+user-invocable: false
+---
+
+# Setup API Key
+
+Guide the user through obtaining a Runway API key, installing the SDK, and configuring their project for API access.
+
+> PREREQUISITE: Run `rw-check-compatibility` first to ensure the project has server-side capability.
+
+## Step 1: Create a Runway Developer Account
+
+Direct the user to:
+
+1. Go to https://dev.runwayml.com/
+2. Create an organization (or use an existing one)
+3. Navigate to Organization Settings -> API Keys
+4. Click Create API Key
+5. Copy the key immediately - it is only shown once and cannot be recovered
+
+Important warnings to tell the user:
+- Lost keys cannot be retrieved. If lost, disable the old key and create a new one.
+- API keys are organization-scoped, not user-scoped.
+- You must prepay for credits before the API will work. Minimum purchase is $10 (1,000 credits at $0.01/credit). Do this at https://dev.runwayml.com/ under billing.
+
+## Step 2: Install the SDK
+
+### Node.js
+```bash
+npm install @runwayml/sdk
+```
+Requires Node.js 18+. The SDK includes TypeScript type definitions.
+
+### Python
+```bash
+pip install runwayml
+```
+Requires Python 3.8+. Includes MyPy type annotations.
+
+## Step 3: Configure the Environment Variable
+
+The SDK automatically reads the API key from the `RUNWAYML_API_SECRET` environment variable.
+
+### Option A: `.env` file (recommended for development)
+
+Check if the project already has a `.env` file. If so, ask the user to add the variable locally. If not, ask before creating one.
+
+```
+RUNWAYML_API_SECRET=your_api_key_here
+```
+
+For Node.js projects: Ensure the project loads `.env` files:
+- Next.js, Remix, Vite - built-in `.env` support, no extra setup needed
+- Express/Fastify/plain Node - install `dotenv`:
+  ```bash
+  npm install dotenv
+  ```
+  Add to the entry point:
+  ```javascript
+  import 'dotenv/config';
+  ```
+
+For Python projects: Ensure `python-dotenv` is installed if not using a framework with built-in support:
+```bash
+pip install python-dotenv
+```
+Add to the entry point:
+```python
+from dotenv import load_dotenv
+load_dotenv()
+```
+
+### Option B: System environment variable
+
+```bash
+export RUNWAYML_API_SECRET=your_api_key_here
+```
+
+### Option C: Pass directly to the client (not recommended)
+
+Avoid this for generated project code. Use environment variables, deployment secrets, or a secrets manager instead. If a one-off local script needs an explicit key for debugging, the user should type it into their own terminal or secure prompt, not chat.
+
+## Step 4: Update .gitignore
+
+Ensure `.env` is in `.gitignore` to prevent accidentally committing the API key:
+
+```
+.env
+.env.local
+.env.*.local
+```
+
+Check the existing `.gitignore` and ask before adding the entry if it's missing.
+
+## Step 5: Verify the Setup
+
+Suggest the user run a quick verification:
+
+### Node.js
+```javascript
+import RunwayML from '@runwayml/sdk';
+
+const client = new RunwayML();
+// If no error is thrown, the API key is configured correctly
+console.log('Runway SDK initialized successfully');
+```
+
+### Python
+```python
+from runwayml import RunwayML
+
+client = RunwayML()
+# If no error is thrown, the API key is configured correctly
+print('Runway SDK initialized successfully')
+```
+
+## Step 6: Confirm Credit Balance
+
+Remind the user:
+- The API requires prepaid credits to function
+- Minimum purchase: $10 (1,000 credits)
+- Purchase at: https://dev.runwayml.com/ -> Billing
+- They can check their balance via the API:
+
+```javascript
+// Node.js - check organization info
+const response = await fetch('https://api.dev.runwayml.com/v1/organization', {
+  headers: {
+    'Authorization': `Bearer ${process.env.RUNWAYML_API_SECRET}`,
+    'X-Runway-Version': '2024-11-06'
+  }
+});
+const org = await response.json();
+console.log('Credits:', org.creditBalance);
+```
+
+## Security Checklist
+
+Before moving on, verify:
+- [ ] API key is stored in an environment variable, not hardcoded
+- [ ] `.env` file is in `.gitignore`
+- [ ] API calls will only happen server-side (not in browser-executed code)
+- [ ] User has purchased credits
+
+## Next Steps
+
+Once the API key is configured, the user can proceed with integration:
+- `rw-integrate-video` - Video generation (text-to-video, image-to-video)
+- `rw-integrate-image` - Image generation
+- `rw-integrate-audio` - Audio generation (TTS, sound effects, voice)
+- `rw-integrate-uploads` - File upload for models that require image/video input
diff --git a/plugins/runway-api/skills/use-runway-api/AUTH.md b/plugins/runway-api/skills/use-runway-api/AUTH.md
new file mode 100644
index 00000000..f7f4e46c
--- /dev/null
+++ b/plugins/runway-api/skills/use-runway-api/AUTH.md
@@ -0,0 +1,46 @@
+# Auth Setup
+
+Use environment variables for direct Runway API actions. The API key must never appear in the chat.
+
+## Default setup
+
+1. Open the API keys page: `https://dev.runwayml.com/settings/api-keys`
+2. Create or copy an API key
+3. Set it in the environment that launches Cline, or in a user-created local env file that is ignored by git
+
+Current shell before launching Cline:
+
+```bash
+export RUNWAYML_API_SECRET=YOUR_KEY_HERE
+```
+
+For a persistent setup, ask the user to edit their shell profile or secret manager locally. Do not write API keys into shell profiles automatically.
+
+Replace `YOUR_KEY_HERE` locally in the terminal. Never paste the key into the chat.
+
+## Verify
+
+```bash
+node <skill-dir>/scripts/runway-api.mjs auth status
+```
+
+`<skill-dir>` is the absolute directory of the `SKILL.md` you are reading - see the Runtime Location section in `SKILL.md` for how to resolve it.
+
+If `authenticated` is still `false`, restart Cline or launch it from a shell that already has `RUNWAYML_API_SECRET` set.
+
+## Non-production environments
+
+Set a stage-specific key (preferred) and/or override the base URL:
+
+```bash
+export RUNWAY_SKILLS_API_SECRET_STAGE=YOUR_STAGE_KEY
+export RUNWAY_SKILLS_BASE_URL=https://api.dev-stage.runwayml.com
+```
+
+With `--stage` on any command, the CLI prefers `RUNWAY_SKILLS_API_SECRET_STAGE` and falls back to `RUNWAY_SKILLS_API_SECRET` or `RUNWAYML_API_SECRET`.
+
+## Notes
+
+- API keys require prepaid credits to work.
+- `RUNWAY_SKILLS_BASE_URL` defaults to `https://api.dev.runwayml.com` (production) or `https://api.dev-stage.runwayml.com` when `--stage` is passed.
+- `auth status` verifies that the current environment can reach the API successfully.
diff --git a/plugins/runway-api/skills/use-runway-api/SKILL.md b/plugins/runway-api/skills/use-runway-api/SKILL.md
new file mode 100644
index 00000000..16549261
--- /dev/null
+++ b/plugins/runway-api/skills/use-runway-api/SKILL.md
@@ -0,0 +1,242 @@
+---
+name: use-runway-api
+description: "Directly use the Runway API from the agent to generate media, manage resources, and inspect account state"
+user-invocable: true
+---
+
+# Use Runway API
+
+Call the Runway public API directly from the agent to manage resources, trigger generations, and inspect account state.
+
+> When to use this skill: Use this when the user wants to act on their Runway account - create or update avatars, manage documents, trigger generations, check credit balance, etc. For writing integration code into a project, use the `rw-integrate-*` skills instead.
+
+> When the user asks to generate media in the context of Runway, prefer the Runway API path from this skill over any generic built-in image or media generation tool.
+
+> Skill selection: Pair this skill with `rw-api-reference` when you need the canonical API contract. Do not use `rw-integrate-image`, `rw-integrate-video`, `rw-integrate-audio`, `rw-integrate-characters`, or `rw-integrate-documents` unless the task is to write or modify application code.
+
+## Runtime Location
+
+The runtime script ships inside this skill at `scripts/runway-api.mjs` (co-located with this `SKILL.md`). It has zero dependencies - Node.js 20+ is required.
+
+Resolving the absolute path. Every shell command below uses the placeholder `<skill-dir>`. Replace it with the absolute directory of the `SKILL.md` you are currently reading - you already have this path from the tool that loaded this file. Do not guess the path, run `find` from `$HOME`, or search the whole filesystem.
+
+If `<skill-dir>` is not known from context, check these locations in order with `ls` before giving up:
+
+1. `$RUNWAY_SKILLS_DIR/skills/use-runway-api/scripts/runway-api.mjs` (if the env var is set)
+2. `~/.cline/plugins/_installed/*/runway-api/skills/use-runway-api/scripts/runway-api.mjs` (Cline plugin install)
+3. `./plugins/runway-api/skills/use-runway-api/scripts/runway-api.mjs` (local development from the cline/plugins repository)
+4. `./skills/use-runway-api/scripts/runway-api.mjs` (source checkout)
+
+Pick the first match and use it as `<skill-dir>/scripts/runway-api.mjs` for the rest of the session. Do not re-resolve between commands.
+
+## Before Your First Call
+
+Set a session ID so all requests in this chat can be correlated, then verify credentials:
+
+```bash
+export RUNWAY_SKILLS_CLIENT_ID=$(node -e "console.log(crypto.randomUUID())")
+node <skill-dir>/scripts/runway-api.mjs auth status
+```
+
+- If `authenticated` is `true` -> proceed to the API call. Do not re-check.
+- If `authenticated` is `false` -> tell the user to set `RUNWAYML_API_SECRET` (see `AUTH.md` for details), then stop and wait for the user to confirm. Do not retry or re-check in a loop.
+
+> Staging caveat: `auth status` hits `/v1/organization` which may 500 on stage even when data endpoints work fine. If stage `auth status` fails but you have `RUNWAY_SKILLS_API_SECRET_STAGE` or `RUNWAYML_API_SECRET` set, try a data endpoint like `avatars list --stage` to confirm the key works before giving up.
+
+## Fast Paths
+
+For plain list requests, use the compact list commands first instead of the generic `request` command:
+
+- list avatars -> `node <skill-dir>/scripts/runway-api.mjs avatars list`
+- list voices -> `node <skill-dir>/scripts/runway-api.mjs voices list`
+- list documents -> `node <skill-dir>/scripts/runway-api.mjs documents list [--avatar-id <id>]`
+
+These commands return smaller, list-friendly JSON on purpose. After a successful list command, answer once. Do not re-run the command, do not read back the same output, and do not render the same table twice.
+
+## Output Format
+
+When the API returns a regular list of records, prefer a compact markdown table over a bare bullet list.
+
+Good defaults:
+- avatars: `Name`, `Status`, `Voice`, `Docs`, `Created`
+- documents: `Name`, `Avatar`, `Created`
+- voices: `Name`, `Provider`, `Preview`
+
+After the table, add one short summary line only if something notable stands out. Do not repeat the table in a second block.
+
+## Generic Request
+
+Call any public API endpoint:
+
+```bash
+node <skill-dir>/scripts/runway-api.mjs request <METHOD> <path> [--body '<json>'] [--stdin] [--dry-run]
+```
+
+All output is JSON. Errors go to stderr with a non-zero exit code and include an `example` field with a correctable invocation.
+
+Flags:
+- `--body <json>` - inline JSON request body
+- `--stdin` - read JSON body from stdin (useful for large or multi-line payloads)
+- `--dry-run` - print the full request (method, URL, headers, body) without executing it
+- `--help` - show usage and examples for any command
+
+Use `rw-api-reference` as the canonical source for:
+- model choices
+- endpoint details
+- exact POST/PATCH body shapes
+- required and optional fields
+
+Do not duplicate or invent request schemas in this skill. For simple GET/DELETE calls and the list fast paths above, you do not need to load `rw-api-reference`.
+
+### Examples
+
+Get organization info:
+```bash
+node <skill-dir>/scripts/runway-api.mjs request GET /v1/organization
+```
+
+List avatars:
+```bash
+node <skill-dir>/scripts/runway-api.mjs avatars list
+```
+
+Get a specific avatar:
+```bash
+node <skill-dir>/scripts/runway-api.mjs request GET /v1/avatars/<id>
+```
+
+Update an avatar:
+```bash
+node <skill-dir>/scripts/runway-api.mjs request PATCH /v1/avatars/<id> --body '{
+  "personality": "Updated personality text"
+}'
+```
+
+Delete an avatar (preview first):
+```bash
+node <skill-dir>/scripts/runway-api.mjs request DELETE /v1/avatars/<id> --dry-run
+node <skill-dir>/scripts/runway-api.mjs request DELETE /v1/avatars/<id>
+```
+
+List knowledge documents for an avatar:
+```bash
+node <skill-dir>/scripts/runway-api.mjs documents list --avatar-id <avatar-id>
+```
+
+Create a knowledge document:
+```bash
+node <skill-dir>/scripts/runway-api.mjs request POST /v1/documents --body '{
+  "avatarId": "<avatar-id>",
+  "name": "FAQ",
+  "content": "Q: What is your return policy?\nA: 30 days, no questions asked."
+}'
+```
+
+List voices:
+```bash
+node <skill-dir>/scripts/runway-api.mjs voices list
+```
+
+## Waiting for Tasks
+
+Generation endpoints return a task ID. Always run `wait` immediately after a generation call - do not ask the user whether to wait.
+
+```bash
+node <skill-dir>/scripts/runway-api.mjs wait <task-id>
+```
+
+## Generation Requests
+
+When the user asks to generate an image, video, or audio:
+
+1. Read `rw-api-reference` once before the first generation POST. It is the canonical source for model options, request body shapes, and valid field values.
+2. Choose the model from `rw-api-reference` and tell the user which one you picked, briefly.
+3. Build the request body from `rw-api-reference`. Do not guess field names.
+4. Call the generation endpoint once with that body.
+5. Run `wait` automatically.
+6. Present the result following the rules in Presenting Generation Output below.
+
+For generation requests, never skip the `rw-api-reference` read. For simple list/get/delete requests, do not load it unless needed.
+
+If the user says only "generate an image" but the surrounding context is clearly about Runway account actions or this skill, still use the Runway API rather than a generic built-in image tool.
+
+## Presenting Generation Output
+
+The `wait` command returns a task with an `output` array of signed URLs. These URLs expire in 24-48 hours and are long signed JWT blobs that are awkward to read inline.
+
+After a successful generation, do all of the following:
+
+1. Lead with what was generated - one short line stating the model and cost, e.g.
+   `Generated with gen4_image (1080p, 8 credits).`
+2. Embed images inline as Markdown so the user can see them without clicking:
+   ```markdown
+   ![Fox in a snowy forest](https://storage.runway.../signed-url)
+   ```
+   For videos, link them as plain Markdown links (`[fox.mp4](...)`) since inline video does not render in most chat UIs.
+3. Offer to save a local copy in the same message, proactively. Suggest a predictable path (`./generated/` or `./runway-outputs/`) and infer a filename from the prompt when possible. Example:
+   > Want me to save it to `./generated/fox.png`? The signed URL expires in ~24-48h.
+4. Do not paste the full signed URL as raw text unless the user asks for it. The Markdown image/link already contains it.
+
+If the user confirms a download, fetch with `curl -L -o <path> '<url>'` (quote the URL - it contains `&`).
+
+## API Reference
+
+Use `rw-api-reference` for the canonical API contract. Use `rw-fetch-api-reference` only when you specifically need the latest docs content from `docs.dev.runwayml.com`.
+
+## Staging (--stage)
+
+Add `--stage` to any command to target the staging API:
+
+```bash
+node <skill-dir>/scripts/runway-api.mjs --stage avatars list
+node <skill-dir>/scripts/runway-api.mjs --stage request GET /v1/avatars
+```
+
+With `--stage`, the CLI checks `RUNWAY_SKILLS_API_SECRET_STAGE` first, then falls back to `RUNWAY_SKILLS_API_SECRET` and `RUNWAYML_API_SECRET`. The base URL defaults to `https://api.dev-stage.runwayml.com`.
+
+## Large Payloads (--stdin)
+
+When creating resources with data URIs (e.g. base64-encoded images for avatar `referenceImage`), the body can exceed shell argument limits. Use `--stdin` to pipe the body:
+
+```bash
+python3 -c "
+import json, base64
+with open('image.png', 'rb') as f:
+    b64 = base64.b64encode(f.read()).decode()
+body = json.dumps({'name': 'My Avatar', 'referenceImage': f'data:image/png;base64,{b64}', ...})
+with open('/tmp/body.json', 'w') as f:
+    f.write(body)
+" && cat /tmp/body.json | node <skill-dir>/scripts/runway-api.mjs request POST /v1/avatars --stdin
+```
+
+Alternatively, write the JSON to a file and use `curl -d @file` directly. The `--body` flag is fine for small JSON payloads but will hit `argument list too long` for data URIs of images over ~200KB.
+
+## Environment Variables
+
+The runtime reads credentials from the process environment:
+
+| Variable | Description |
+|----------|-------------|
+| `RUNWAYML_API_SECRET` | Production API key |
+| `RUNWAY_SKILLS_API_SECRET` | Optional alias for the direct helper |
+| `RUNWAY_SKILLS_API_SECRET_STAGE` | Stage API key (used with `--stage`) |
+| `RUNWAY_SKILLS_BASE_URL` | Override the base URL for any environment |
+| `RUNWAY_SKILLS_DIR` | Optional. Absolute path to this plugin or source checkout - used by the agent as a fallback when resolving `<skill-dir>`. |
+
+If the agent cannot see `RUNWAYML_API_SECRET`, Cline likely needs to be restarted after the variable is set.
+
+## Related Files
+
+- `AUTH.md` - auth setup and troubleshooting for this skill
+
+## Related Skills
+
+| Skill | When to use |
+|-------|-------------|
+| `rw-api-reference` | Full API reference - models, endpoints, costs, rate limits |
+| `rw-fetch-api-reference` | Fetch latest docs from docs.dev.runwayml.com |
+| `rw-integrate-video` | Write video generation code into a project |
+| `rw-integrate-image` | Write image generation code into a project |
+| `rw-integrate-audio` | Write audio generation code into a project |
+| `rw-integrate-characters` | Write avatar session code into a project |
+| `rw-integrate-documents` | Write knowledge document code into a project |
diff --git a/plugins/runway-api/skills/use-runway-api/scripts/runway-api.mjs b/plugins/runway-api/skills/use-runway-api/scripts/runway-api.mjs
new file mode 100644
index 00000000..8e98cb14
--- /dev/null
+++ b/plugins/runway-api/skills/use-runway-api/scripts/runway-api.mjs
@@ -0,0 +1,663 @@
+#!/usr/bin/env node
+
+import { randomUUID } from "node:crypto";
+
+const VERSION = "1.0.1";
+const DEFAULT_BASE_URL = "https://api.dev.runwayml.com";
+const STAGE_BASE_URL = "https://api.dev-stage.runwayml.com";
+const API_VERSION = "2024-11-06";
+const BIN = "runway-api.mjs";
+const CLIENT_ID = process.env.RUNWAY_SKILLS_CLIENT_ID || randomUUID();
+
+const useStage = process.argv.includes("--stage");
+
+function hasFlag(args, ...flags) {
+  return flags.some((f) => args.includes(f));
+}
+
+function stripFlag(args, flag) {
+  return args.filter((a) => a !== flag);
+}
+
+// ---------------------------------------------------------------------------
+// Auth resolution
+// ---------------------------------------------------------------------------
+
+async function resolveAuth() {
+  const envKey = useStage
+    ? process.env.RUNWAY_SKILLS_API_SECRET_STAGE ?? process.env.RUNWAY_SKILLS_API_SECRET ?? process.env.RUNWAYML_API_SECRET
+    : process.env.RUNWAYML_API_SECRET ?? process.env.RUNWAY_SKILLS_API_SECRET;
+  const envUrl = useStage
+    ? process.env.RUNWAY_SKILLS_BASE_URL ?? STAGE_BASE_URL
+    : process.env.RUNWAY_SKILLS_BASE_URL;
+
+  if (!envKey) return null;
+
+  return {
+    apiKey: envKey,
+    baseUrl: envUrl || DEFAULT_BASE_URL,
+    source: useStage ? "environment (stage)" : "environment",
+  };
+}
+
+async function requireAuth() {
+  const auth = await resolveAuth();
+  if (!auth) {
+    printError(
+      "Not authenticated. Set RUNWAYML_API_SECRET in the environment that launches your editor or shell.",
+    );
+    process.exit(1);
+  }
+  return auth;
+}
+
+// ---------------------------------------------------------------------------
+// HTTP client
+// ---------------------------------------------------------------------------
+
+const MAX_RETRIES = 2;
+const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+
+async function apiFetch(method, path, { body, auth } = {}) {
+  const resolvedAuth = auth ?? (await requireAuth());
+  const url = `${resolvedAuth.baseUrl}${path}`;
+
+  const headers = {
+    Authorization: `Bearer ${resolvedAuth.apiKey}`,
+    "X-Runway-Version": API_VERSION,
+    "X-Runway-Client-Id": CLIENT_ID,
+    "X-Runway-Source-Application": "skills",
+    "X-Runway-Source-Application-Version": VERSION,
+    "User-Agent": `runway-skills/${VERSION}`,
+    Accept: "application/json",
+  };
+  if (body !== undefined) {
+    headers["Content-Type"] = "application/json";
+  }
+
+  const fetchOptions = {
+    method,
+    headers,
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  };
+
+  let lastError;
+
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    if (attempt > 0) {
+      const delay = Math.min(1000 * 2 ** (attempt - 1), 4000);
+      await new Promise((r) => setTimeout(r, delay));
+    }
+
+    try {
+      const response = await fetch(url, fetchOptions);
+
+      if (RETRYABLE_STATUSES.has(response.status) && attempt < MAX_RETRIES) {
+        lastError = { status: response.status, message: `HTTP ${response.status}` };
+        continue;
+      }
+
+      if (!response.ok) {
+        let errorBody;
+        try {
+          errorBody = await response.json();
+        } catch {
+          errorBody = { message: await response.text() };
+        }
+        const error = new Error(errorBody.message || errorBody.error || `HTTP ${response.status}`);
+        error.status = response.status;
+        if (errorBody.code) error.code = errorBody.code;
+        if (errorBody.issues) error.issues = errorBody.issues;
+        if (errorBody.docUrl) error.docUrl = errorBody.docUrl;
+        throw error;
+      }
+
+      if (response.status === 204) return {};
+
+      return await response.json();
+    } catch (error) {
+      if (error.status && !RETRYABLE_STATUSES.has(error.status)) throw error;
+      lastError = error;
+      if (attempt === MAX_RETRIES) throw lastError;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Output helpers
+// ---------------------------------------------------------------------------
+
+function printJson(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+function printError(message, { example, details } = {}) {
+  const payload = { error: message };
+  if (example) payload.example = example;
+  if (details) payload.details = details;
+  console.error(JSON.stringify(payload, null, 2));
+}
+
+function printHelp(text) {
+  console.log(text.trimStart());
+}
+
+function printApiError(error) {
+  const payload = { error: error.message };
+  if (error.status) payload.status = error.status;
+  if (error.code) payload.code = error.code;
+  if (error.issues) payload.issues = summarizeIssues(error.issues);
+  if (error.docUrl) payload.docUrl = error.docUrl;
+  console.error(JSON.stringify(payload, null, 2));
+}
+
+function summarizeIssues(issues) {
+  return issues.map((issue) => {
+    const field = Array.isArray(issue.path) ? issue.path.join(".") : undefined;
+    const messages = [];
+    if (issue.message && issue.message !== "Invalid input") messages.push(issue.message);
+    if (Array.isArray(issue.errors)) {
+      for (const branch of issue.errors) {
+        const branchMsgs = (Array.isArray(branch) ? branch : [branch])
+          .map((e) => e.message)
+          .filter(Boolean);
+        if (branchMsgs.length) messages.push(...branchMsgs);
+      }
+    }
+    const unique = [...new Set(messages)];
+    return { field, messages: unique.length ? unique : [issue.message ?? issue.code] };
+  });
+}
+
+function compactIsoDate(value) {
+  if (!value) return null;
+  const parsedDate = new Date(value);
+  if (Number.isNaN(parsedDate.getTime())) return value;
+  return parsedDate.toISOString();
+}
+
+function describeVoice(voice) {
+  if (!voice) return null;
+  if (typeof voice === "string") return voice;
+
+  const voiceName = voice.name ?? voice.id ?? "Unknown";
+  if (voice.type === "custom") return `${voiceName} (custom)`;
+  if (voice.type === "preset") return `${voiceName} (preset)`;
+  return voiceName;
+}
+
+function pickArray(result) {
+  if (Array.isArray(result)) return result;
+  if (Array.isArray(result.data)) return result.data;
+  return [];
+}
+
+async function readStdin() {
+  if (process.stdin.isTTY) {
+    printError("--stdin requires piped input, but stdin is a terminal.", {
+      example: `echo '{"name":"test"}' | ${BIN} request POST /v1/avatars --stdin`,
+    });
+    process.exit(1);
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// Commands: auth
+// ---------------------------------------------------------------------------
+
+async function authLogin(args) {
+  void args;
+  printError(
+    "Persisted auth is disabled. Set RUNWAYML_API_SECRET in your environment instead.",
+  );
+  process.exit(1);
+}
+
+async function authStatus() {
+  const auth = await resolveAuth();
+  if (!auth) {
+    printJson({
+      authenticated: false,
+      source: "environment",
+      baseUrl: process.env.RUNWAY_SKILLS_BASE_URL || DEFAULT_BASE_URL,
+    });
+    return;
+  }
+
+  try {
+    const organization = await apiFetch("GET", "/v1/organization", { auth });
+    printJson({
+      authenticated: true,
+      source: auth.source,
+      baseUrl: auth.baseUrl,
+      keyPrefix: auth.apiKey.slice(0, 8) + "...",
+      organization: organization.name ?? null,
+    });
+  } catch (primaryError) {
+    try {
+      await apiFetch("GET", "/v1/avatars", { auth });
+      printJson({
+        authenticated: true,
+        source: auth.source,
+        baseUrl: auth.baseUrl,
+        keyPrefix: auth.apiKey.slice(0, 8) + "...",
+        organization: null,
+        note: "/v1/organization unavailable; verified via /v1/avatars",
+      });
+    } catch {
+      printJson({
+        authenticated: false,
+        source: auth.source,
+        baseUrl: auth.baseUrl,
+        keyPrefix: auth.apiKey.slice(0, 8) + "...",
+        error: primaryError.message,
+      });
+      process.exit(1);
+    }
+  }
+}
+
+async function authLogout() {
+  printError(
+    "Persisted auth is disabled. Unset RUNWAYML_API_SECRET or RUNWAY_SKILLS_API_SECRET in your shell or editor environment to log out.",
+  );
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Commands: request
+// ---------------------------------------------------------------------------
+
+async function request(args) {
+  if (hasFlag(args, "--help", "-h")) {
+    printHelp(`
+Usage: ${BIN} request <METHOD> <path> [options]
+
+Options:
+  --body <json>   JSON request body
+  --stdin         Read JSON body from stdin
+  --dry-run       Print request details without executing
+  --help          Show this help
+
+Examples:
+  ${BIN} request GET /v1/avatars
+  ${BIN} request POST /v1/documents --body '{"avatarId":"abc","name":"FAQ","content":"..."}'
+  ${BIN} request DELETE /v1/avatars/abc123 --dry-run
+  echo '{"name":"test"}' | ${BIN} request POST /v1/avatars --stdin
+`);
+    return;
+  }
+
+  const method = args[0]?.toUpperCase();
+  const path = args[1];
+
+  if (!method || !path) {
+    printError("Missing required arguments: METHOD and path.", {
+      example: `${BIN} request GET /v1/avatars`,
+    });
+    process.exit(1);
+  }
+
+  const supportedMethods = new Set(["GET", "POST", "PATCH", "PUT", "DELETE"]);
+  if (!supportedMethods.has(method)) {
+    printError(`Unsupported HTTP method: ${method}. Use one of: GET, POST, PATCH, PUT, DELETE.`, {
+      example: `${BIN} request GET /v1/avatars`,
+    });
+    process.exit(1);
+  }
+
+  let body;
+
+  if (hasFlag(args, "--stdin")) {
+    const raw = await readStdin();
+    try {
+      body = JSON.parse(raw);
+    } catch {
+      printError("Invalid JSON from stdin.", {
+        example: `echo '{"name":"test"}' | ${BIN} request POST /v1/avatars --stdin`,
+      });
+      process.exit(1);
+    }
+  } else {
+    const bodyIdx = args.indexOf("--body");
+    if (bodyIdx !== -1 && args[bodyIdx + 1]) {
+      try {
+        body = JSON.parse(args[bodyIdx + 1]);
+      } catch {
+        printError("Invalid JSON in --body argument.", {
+          example: `${BIN} request POST /v1/documents --body '{"avatarId":"abc","name":"FAQ"}'`,
+        });
+        process.exit(1);
+      }
+    }
+  }
+
+  if (hasFlag(args, "--dry-run")) {
+    const auth = await requireAuth();
+    printJson({
+      dry_run: true,
+      method,
+      url: `${auth.baseUrl}${path}`,
+      headers: {
+        Authorization: "Bearer ***",
+        "X-Runway-Version": API_VERSION,
+        "X-Runway-Client-Id": CLIENT_ID,
+        "X-Runway-Source-Application": "skills",
+        "X-Runway-Source-Application-Version": VERSION,
+        "User-Agent": `runway-skills/${VERSION}`,
+        Accept: "application/json",
+        ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+      },
+      body: body ?? null,
+    });
+    return;
+  }
+
+  try {
+    const result = await apiFetch(method, path, { body });
+    printJson(result);
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Commands: compact lists
+// ---------------------------------------------------------------------------
+
+async function listAvatars() {
+  try {
+    const result = await apiFetch("GET", "/v1/avatars");
+    const items = pickArray(result).map((avatar) => ({
+      id: avatar.id,
+      name: avatar.name ?? null,
+      status: avatar.status ?? null,
+      voice: describeVoice(avatar.voice),
+      documents: Array.isArray(avatar.documentIds) ? avatar.documentIds.length : 0,
+      createdAt: compactIsoDate(avatar.createdAt),
+    }));
+
+    printJson({ data: items });
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+}
+
+async function listVoices() {
+  try {
+    const result = await apiFetch("GET", "/v1/voices");
+    const items = pickArray(result).map((voice) => ({
+      id: voice.id,
+      name: voice.name ?? null,
+      provider: voice.provider ?? voice.type ?? null,
+      preview: voice.previewAudioUri ?? voice.previewUri ?? null,
+    }));
+
+    printJson({ data: items });
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+}
+
+async function listDocuments(args) {
+  if (hasFlag(args, "--help", "-h")) {
+    printHelp(`
+Usage: ${BIN} documents list [options]
+
+Options:
+  --avatar-id <id>   Filter documents by avatar
+  --help             Show this help
+
+Examples:
+  ${BIN} documents list
+  ${BIN} documents list --avatar-id abc123
+`);
+    return;
+  }
+
+  const avatarIdIndex = args.indexOf("--avatar-id");
+  const avatarId =
+    avatarIdIndex !== -1 && args[avatarIdIndex + 1]
+      ? args[avatarIdIndex + 1]
+      : null;
+
+  const queryString = avatarId ? `?avatarId=${encodeURIComponent(avatarId)}` : "";
+
+  try {
+    const result = await apiFetch("GET", `/v1/documents${queryString}`);
+    const items = pickArray(result).map((document) => ({
+      id: document.id,
+      name: document.name ?? null,
+      avatarId: document.avatarId ?? null,
+      createdAt: compactIsoDate(document.createdAt),
+    }));
+
+    printJson({ data: items });
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Commands: wait
+// ---------------------------------------------------------------------------
+
+const POLL_INTERVAL_MS = 5_000;
+const TERMINAL_STATUSES = new Set(["SUCCEEDED", "FAILED", "CANCELLED"]);
+
+async function waitForTask(args) {
+  if (hasFlag(args, "--help", "-h")) {
+    printHelp(`
+Usage: ${BIN} wait <task-id>
+
+Poll a generation task until it reaches a terminal status.
+Prints status updates to stderr during polling.
+
+Examples:
+  ${BIN} wait task_abc123
+`);
+    return;
+  }
+
+  const taskId = args[0];
+  if (!taskId) {
+    printError("Missing required argument: task-id.", {
+      example: `${BIN} wait task_abc123`,
+    });
+    process.exit(1);
+  }
+
+  try {
+    let task = await apiFetch("GET", `/v1/tasks/${taskId}`);
+
+    while (!TERMINAL_STATUSES.has(task.status)) {
+      await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+      task = await apiFetch("GET", `/v1/tasks/${taskId}`);
+      process.stderr.write(`status: ${task.status}\n`);
+    }
+
+    printJson(task);
+
+    if (task.status !== "SUCCEEDED") {
+      process.exit(1);
+    }
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Help text
+// ---------------------------------------------------------------------------
+
+function printRootHelp() {
+  printHelp(`
+Usage: ${BIN} <command> [options]
+
+Commands:
+  auth            Manage authentication
+  request         Call any public API endpoint
+  avatars list    List avatars (compact)
+  voices list     List voices (compact)
+  documents list  List documents (compact)
+  wait            Poll a task until completion
+
+Options:
+  --stage         Target the staging API (uses RUNWAY_SKILLS_API_SECRET_STAGE)
+  --help          Show help for a command
+  --version       Show version
+
+Examples:
+  ${BIN} auth status
+  ${BIN} request GET /v1/avatars
+  ${BIN} request POST /v1/documents --body '{"avatarId":"abc","name":"FAQ","content":"..."}'
+  ${BIN} avatars list
+  ${BIN} documents list --avatar-id abc123
+  ${BIN} wait task_abc123
+`);
+}
+
+function printAuthHelp() {
+  printHelp(`
+Usage: ${BIN} auth <subcommand>
+
+Subcommands:
+  status    Verify current environment auth
+  login     Show env-based auth guidance
+  logout    Show env-based logout guidance
+
+Examples:
+  ${BIN} auth status
+`);
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const allArgs = stripFlag(process.argv.slice(2), "--stage");
+
+if (hasFlag(allArgs, "--version", "-v") && !allArgs.some((a) => !a.startsWith("-"))) {
+  console.log(VERSION);
+  process.exit(0);
+}
+
+if (allArgs.length === 0 || (hasFlag(allArgs, "--help", "-h") && !allArgs.some((a) => !a.startsWith("-")))) {
+  printRootHelp();
+  process.exit(0);
+}
+
+const [command, subcommand, ...rest] = allArgs;
+
+try {
+  switch (command) {
+    case "auth":
+      if (hasFlag([subcommand, ...rest], "--help", "-h") || !subcommand) {
+        printAuthHelp();
+        break;
+      }
+      switch (subcommand) {
+        case "login":
+          await authLogin(rest);
+          break;
+        case "status":
+          await authStatus();
+          break;
+        case "logout":
+          await authLogout();
+          break;
+        default:
+          printError(`Unknown auth subcommand: ${subcommand}.`, {
+            example: `${BIN} auth status`,
+          });
+          process.exit(1);
+      }
+      break;
+
+    case "request":
+      await request([subcommand, ...rest].filter(Boolean));
+      break;
+
+    case "avatars":
+      if (hasFlag([subcommand, ...rest], "--help", "-h")) {
+        printHelp(`
+Usage: ${BIN} avatars list
+
+List all avatars with compact fields (id, name, status, voice, documents, createdAt).
+
+Examples:
+  ${BIN} avatars list
+`);
+        break;
+      }
+      if (subcommand === "list") {
+        await listAvatars();
+        break;
+      }
+      printError(`Unknown avatars subcommand: ${subcommand ?? "(none)"}.`, {
+        example: `${BIN} avatars list`,
+      });
+      process.exit(1);
+      break;
+
+    case "voices":
+      if (hasFlag([subcommand, ...rest], "--help", "-h")) {
+        printHelp(`
+Usage: ${BIN} voices list
+
+List all voices with compact fields (id, name, provider, preview).
+
+Examples:
+  ${BIN} voices list
+`);
+        break;
+      }
+      if (subcommand === "list") {
+        await listVoices();
+        break;
+      }
+      printError(`Unknown voices subcommand: ${subcommand ?? "(none)"}.`, {
+        example: `${BIN} voices list`,
+      });
+      process.exit(1);
+      break;
+
+    case "documents":
+      if (hasFlag([subcommand, ...rest], "--help", "-h")) {
+        await listDocuments(["--help"]);
+        break;
+      }
+      if (subcommand === "list") {
+        await listDocuments(rest);
+        break;
+      }
+      printError(`Unknown documents subcommand: ${subcommand ?? "(none)"}.`, {
+        example: `${BIN} documents list`,
+      });
+      process.exit(1);
+      break;
+
+    case "wait":
+      await waitForTask([subcommand, ...rest].filter(Boolean));
+      break;
+
+    default:
+      printError(`Unknown command: ${command}.`, {
+        example: `${BIN} --help`,
+      });
+      process.exit(1);
+  }
+} catch (error) {
+  printApiError(error);
+  process.exit(1);
+}