Skip to main content
skill CX Codex

runway-dev-characters — Claude Code skill

runway-dev-characters — a skill for building Runway Characters integrations. Manage avatars, set up realtime Sessions, handle knowledge documents, and work with the Characters SDK and MCP tools.

MIT 162 installs ★ 76 updated 2026-10-20

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add runwayml/skills --skill runway-dev-characters -a claude-code
Open on GitHub

What runway-dev-characters does

This skill guides developers integrating Runway Characters (called Avatars in the SDK) into applications. It covers the full workflow: selecting or creating an avatar, managing live Sessions, configuring knowledge, and handling connection states in the UI.

The skill points to current integration docs and SDK references, helps structure the server architecture correctly (create Sessions server-side with @runwayml/sdk, store the API Secret on the backend), and selects the right client library (@runwayml/avatars-react for React or @runwayml/avatars for plain web). MCP tools let you inspect available avatars and their readiness state, manage knowledge documents, and create custom avatars.

The skill does not cover avatar video generation from text or audio—use other Runway tools for that. If MCP is unavailable, you can continue with code that follows the docs and known avatar IDs, but live account verification steps pause until MCP reconnects.

What it helps with

  • Choose or create an avatar for an application
  • Set up Session credentials on the backend and securely pass them to the browser
  • Handle connection states (permission, connecting, active, failed, ended) in UI
  • Add or update knowledge documents attached to an avatar
  • Verify avatar readiness and reconnect if session credentials are consumed

Example prompts for the agent

  • Integrate a Runway avatar into a React app using components from @runwayml/avatars-react
  • Check available avatars and their state via MCP tools
  • Create a knowledge document for an avatar and ensure the Session is ready to connect

How to install runway-dev-characters

1Skills CLI (Vercel)

npx skills add runwayml/skills --skill runway-dev-characters -a claude-code

2Manually: put the files in place

~/.claude/skills/runway-dev-characters/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/runway-dev-characters/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about runway-dev-characters

How do I install runway-dev-characters in Claude Code?

Run npx skills add runwayml/skills --skill runway-dev-characters -a claude-code, then open ~/.claude/skills/runway-dev-characters/SKILL.md.

What does this skill do?

The skill guides development of Runway Characters integrations: selecting or creating avatars, setting up realtime Sessions, managing knowledge, and handling connection states in your app UI.

When should I use this skill instead of the SDK directly?

The skill connects documentation, UI state patterns, security practices (keeping the API Secret on the backend), and MCP tools for live avatar inspection in one place. Without it, you'd coordinate these separately.

Source text

SKILL.md · MIT
---
name: runway-dev-characters
description: "Use when building or maintaining a Runway Characters integration, including avatar discovery or management, realtime Sessions, knowledge, and the call interface. Follow current Characters and SDK docs. Do not use for generating avatar videos from text or audio."
user-invocable: true
---

# 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](https://docs.dev.runwayml.com/characters/integration/) and [SDK documentation](https://docs.dev.runwayml.com/_llms-txt/characters.txt). 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

- [Characters overview](https://docs.dev.runwayml.com/characters/)
- [Build an integration](https://docs.dev.runwayml.com/characters/integration/)
- [Session concepts and lifecycle](https://docs.dev.runwayml.com/characters/concepts/)
- [Characters documentation set](https://docs.dev.runwayml.com/_llms-txt/characters.txt)
- [React SDK](https://github.com/runwayml/avatar-sdk-react)

© runwayml · MIT · runwayml/skills

Similar skills

All skills for AI and ML →

From the same set7

Project sponsors

Companies that keep this analytics open