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
npx skills add runwayml/skills --skill runway-dev-characters -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/runway-dev-characters/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/runway-dev-characters/
1Skills CLI (Vercel)
npx skills add runwayml/skills --skill runway-dev-characters -a codex2Manually: put the files in place
.agents/skills/runway-dev-characters/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add runwayml/skills --skill runway-dev-characters -a cursor2Manually: put the files in place
.cursor/skills/runway-dev-characters/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install runwayml/skills skills/runway-dev-characters2Manually: put the files in place
.github/skills/runway-dev-characters/SKILL.md1Skills CLI (Vercel)
npx skills add runwayml/skills --skill runway-dev-characters -a gemini-cli2Platform CLI
gemini skills install https://github.com/runwayml/skills --path skills/runway-dev-charactersManually: put the files in place
.devin/skills/runway-dev-characters/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add runwayml/skills --skill runway-dev-characters -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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