mcpField
R
runway-dev-characters

runway-dev-characters

github.com/runwaymlDevelopment74129 installsUpdated 2d ago
Repository

About runway-dev-characters

A development skill for integrating Runway Characters into applications, from choosing an Avatar to creating realtime Sessions and handling client states. It combines current integration guidance with live Avatar and knowledge-document operations through Dev MCP, while keeping API secrets on the server.

Key features

  1. 01Inspect and select a Character or Avatar
  2. 02Check Avatar state through Dev MCP
  3. 03Create server-side Sessions with the SDK
  4. 04Handle connection and Session lifecycle states
  5. 05Manage Avatars and knowledge documents

Use cases

  1. 01Integrate realtime conversations into an app
  2. 02Build against live account Avatar state
  3. 03Manage knowledge documents for a custom Avatar

MCP support

Uses Dev MCP to inspect Avatars and knowledge documents, and to create, update, or delete them. When live account information is needed, it requires checking current records and tool contracts first.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/runwayml/skills --skill runway-dev-characters

After installing, type/runway-dev-charactersin Claude Code to confirm it loaded.

Details

From the project README

Runway Characters

The Developer Portal calls these Characters; the API and SDK use Avatars. A realtime Session is one live conversation. Consult runway-dev for account setup and shared credential guidance when installed.

Workflow

  1. Inspect the app's call experience and server architecture. Ask whether it should use an existing Character, a documented preset, or a newly created custom Avatar only when that choice is not already clear.
  2. When live account state or a user's Character matters, use Dev MCP to inspect the available Avatars and their state. Do not substitute a different Avatar or guess a preset ID. If a custom Avatar is requested, use its reference image and current API/MCP schema.
  3. Follow the current Characters integration guide and SDK documentation. Check the @runwayml/avatars-react README for current React components, hooks, and styles; use @runwayml/avatars for a non-React web client.
  4. Create Sessions server-side with @runwayml/sdk. Keep RUNWAYML_API_SECRET on the server. Follow the current Session readiness and credential-consumption flow; expose only the one-time connection fields the browser SDK needs. Never send the API secret to the browser.
  5. Handle permission, connecting, active, failed, and ended states in the app UI. End or cancel a Session during teardown according to the current SDK/API guidance. If single-use credentials have already been consumed and connection fails, create a new Session rather than reusing them.
  6. Run local checks. A live Session may incur usage; only open one for verification when requested or approved.

Live data and knowledge

Use the available MCP tools to inspect live Avatars with list_avatars and get_avatar, and knowledge documents with list_avatar_knowledge_documents and get_avatar_knowledge_document. create_avatar, update_avatar, and delete_avatar manage Avatars; the corresponding *_avatar_knowledge_document tools manage knowledge documents. After creating an Avatar, check it with get_avatar until its state is READY or FAILED. Read the existing record and current tool contract before changing it, and confirm destructive deletes with the user. If MCP is unavailable, continue app code that can be implemented from docs and existing IDs, and pause only the step that requires live account state.

Current docs

Comments

Markdown supported