Preface

Building videos with React sounds amazing: timelines become frame numbers, animations become interpolate(), and the final output is an MP4. Remotion has made this workflow possible, but AI coding assistants often stumble into pitfalls that “look like frontend code but render incorrectly” when generating Remotion code—such as using CSS transition for animations, incorrect asset paths, or choosing the wrong media component packages.

remotion-best-practices is the official Remotion Agent Skill designed for these scenarios. It breaks down “how to write Remotion correctly” into a routable knowledge base, ensuring tools like Cursor, Claude Code, and Codex follow official conventions when modifying video-related code, instead of guessing based on generic React experience.

What Is It

remotion-best-practices is maintained by the official Remotion team (repository: remotion-dev/skills) and distributed as a SKILL.md file under the Agent Skills standard. The official documentation calls it the master entry Skill: when you are unsure which sub-skill to use, start with this one first. It will route your agent to more detailed reference documents for tasks like project creation, writing markup, maps, captions, rendering, and upgrades.

The version tagged in the current repository is 4.0.509. The summary on skills.sh positions it as a domain-specific knowledge base for Remotion + React, covering practices for animations, audio, assets, captions, maps, rendering, and composition management.

Core Capabilities

Based on the official SKILL.md and documentation directory, it mainly does three things:

  1. Route by Scenario
    When a user says “make a new video”, “write a Remotion component”, “add captions”, “open Studio”, “render”, “look up documentation”, or “upgrade”, the entry Skill will point to the corresponding sub-skill, for example:

    • remotion-create: Scaffolding and new composition creation
    • remotion-markup: Markup specifications for animations, layouts, media, effects, fonts, etc.
    • remotion-maps: Static maps, routes, Mapbox / MapLibre / MapTiler, GeoJSON, 3D flyovers, etc.
    • remotion-multimedia: Multimedia tasks such as in-browser cropping and metadata
    • remotion-captions: Caption-related features
    • remotion-studio / remotion-render: Preview and rendering
    • remotion-saas: SaaS/automated architectures based on Remotion (including Lambda, Vercel, Cloudflare, client-side rendering, etc.)
    • remotion-interactivity: Enabling interactive editing in Studio and writing back to code
    • remotion-docs / remotion-upgrade: Looking up official documentation, upgrading dependencies, and installed Skills

  2. Enforce “Frame-Driven” Development as a Hard Rule
    The remotion-markup sub-skill clearly mandates: use useCurrentFrame() + interpolate() for animations. CSS transition / animation and Tailwind animation classes are unreliable in Remotion rendering and must be replaced. Prefer using <Video> / <Audio> from @remotion/media for media, place static assets in the public/ folder, and reference them with staticFile().

  3. Preserve Manual User Changes
    Both the entry Skill and multiple sub-skills share the same principle: if unexpected changes outside the conversation are detected, do not overwrite them directly. Treat them as intentional modifications by default or confirm with the user first. This is very practical for “collaborative editing of the same composition between humans and AI”.

Installation and Activation

The official installation method is to pull the Remotion-maintained Skills package (which includes remotion-best-practices and others) in one go:

npx skills add remotion-dev/skills

If you only want to install this single Skill, the command on skills.sh is:

npx skills add https://github.com/remotion-dev/skills --skill remotion-best-practices

You can also install it during the process of creating a new Remotion project. An official documentation example:

bun create video

The creation wizard will prompt you whether to add these Skills.

This Skill follows the generic SKILL.md format. The official Remotion documentation states that it is compatible with Claude Code, Codex, Kimi Code, Cursor and other AI agents. The specific directory where it is installed depends on your selection during npx skills install (for example, the skills directory within the project is common for Cursor). The verified information ends here, and differences in tool-specific directories are subject to the output of your local installation.

Typical Usage

1. Build a blank video project from scratch

The remotion-create sub-skill requires: when there is no Remotion project in the current directory, use the official scaffolding (Node.js and Git must be installed first):

npx create-video@latest --yes --blank --no-tailwind my-video
cd my-video
npm i

Replace my-video with your preferred project name. Afterwards, write React Markup directly in your components instead of manually setting up a directory structure first.

2. Write a frame-driven fade-in title according to specifications

The core pattern from remotion-markup is: pass the frame number into interpolate(), use Easing.bezier() / Easing.spring() for easing functions, and write interpolations into the style prop as much as possible (to enable editing in Studio). A demonstration is as follows (from the official REFERENCE concept):

import {
  AbsoluteFill,
  Easing,
  Interactive,
  interpolate,
  useCurrentFrame,
  useVideoConfig,
} from "remotion";

export const TitleScene = () => {
  const { fps } = useVideoConfig();
  const frame = useCurrentFrame();

  return (
    <AbsoluteFill
      style={{
        display: "flex",
        justifyContent: "center",
        alignItems: "center",
        backgroundColor: "white",
      }}
    >
      <Interactive.Div
        name="Title"
        style={{
          opacity: interpolate(frame, [1 * fps, 2 * fps], [0, 1], {
            extrapolateLeft: "clamp",
            extrapolateRight: "clamp",
            easing: Easing.bezier(0.16, 1, 0.3, 1),
          }),
          fontSize: 88,
        }}
      >
        Title
      </Interactive.Div>
    </AbsoluteFill>
  );
};

Media asset example:

import { Audio, Video } from "@remotion/media";
import { staticFile } from "remotion";

export const MediaLayer = () => (
  <>
    <Video src={staticFile("video.mp4")} style={{ opacity: 0.5 }} />
    <Audio src={staticFile("audio.mp3")} />
  </>
);

When you need to add packages like @remotion/*, the Skill recommends using:

npx remotion add @remotion/media

This ensures the version matches the main Remotion version.

3. Preview and do frame-by-frame self-checks

Preview in Studio:

npx remotion studio --no-open

The command will print the local preview address; it will also print the URL if a service is already running. You can access it via the composition id, for example http://localhost:3000/MapAnimation.

Optional: Render a single frame to sanity-check your layout/color scheme (official recommendation: skip this if not necessary):

npx remotion still [composition-id] --scale=0.25 --frame=30

At 30 fps, --frame=30 is approximately the 1st second (frame numbers start at 0). Only run npx remotion render for the final full-length video when explicitly requested by the user.

4. How to speak to the agent

After installation, you can use natural language directly, for example:
- “Make a product promo composition with Remotion”
- “Add captions to this video”
- “Open Studio to preview and check the title animation”
- “Upgrade Remotion-related packages according to official specifications”

The default prompt example for the entry Skill is: Make a promo video for my product. If you are unsure which sub-skill to use, you can also explicitly call /remotion-best-practices to have the agent load from the master routing.

Applicable Scenarios and Notes

Best for:
- Users who are already using or planning to use Remotion for programmatic videos (promo videos, data visualization videos, templated short videos, map explainers, etc.)
- Users who want their AI assistant to stop writing CSS animations that “preview correctly but render wrong” and instead write frame-driven code
- Users who need advanced features like captions, maps, SaaS rendering, Studio-editable structures, and do not want to read through the documentation themselves

Important notes during use:
- This is a domain knowledge Skill, not a video editing software. You still need a working Remotion project and rendering environment in the end.
- CSS / Tailwind animation classes are unreliable in Remotion; replace them with useCurrentFrame() + interpolate().
- Place assets in the public/ folder, prefer @remotion/media for media components; use npx remotion add when installing packages.
- Always preview in Studio or render a single frame for confirmation before rendering the final video; do not automatically run a full render by default.
- When collaborating with AI on edits, the Skill requires respecting manual changes outside the conversation and avoiding overwriting without confirmation.

Summary

Programmatic video turns “editing” into “writing components”. The value of remotion-best-practices lies in packaging Remotion’s official frame-driven development, resource referencing, Studio/rendering conventions into an AI agent-loadable Skill, and routing to more detailed sub-documents based on tasks. If you already use Cursor / Claude Code / Codex to write Remotion code, installing this Skill will usually save you more time than repeatedly correcting “don’t use CSS transition”.

Official links:
- Skill directory: https://github.com/remotion-dev/skills/tree/main/skills/remotion-best-practices
- Official documentation: https://www.remotion.dev/docs/ai/skills
- skills.sh: https://skills.sh/remotion-dev/skills/remotion-best-practices