Remotion Best Practices: 30 Rules That Teach AI Agents How to Build Videos in React

Install an agent skill, then write a video.

That is what remotion-best-practices from the remotion-dev/skills repository does. Over 350,000 installs on skills.sh. 3500 GitHub stars since it appeared in January 2024. And unlike most Remotion agent skills you have seen about this project (like the ones inside Remotion’s own monorepo), this one is for developers building with Remotion, not contributing code to it.

The Problem It Solves

Remotion runs on three things most web developers have never touched before: a frame-based animation system, WebGL shader compilation, and FFmpeg rendering pipelines. Write useCurrentFrame() wrong by one index and your entire composition desynchronizes. Export a video with the wrong codec parameters and FFmpeg silently produces garbled output. Use <audio> instead of AudioSprite and your browser will refuse to render at all.

The learning curve is steep because the mental model is completely different from normal web development. Time doesn’t flow. Frames pass one by one. Animations don’t use CSS keyframes or GSAP — they use interpolate() with explicit frame ranges and easing curves. Audio isn’t played through the Web Audio API — it’s embedded at the binary level via FFmpeg during render time.

This skill compresses years of community experience into 30+ rule files that an AI coding agent reads before writing any Remotion code. The goal isn’t to teach every concept. It’s to prevent the mistakes that waste hours finding and fixing.

What Is Inside

The skill decomposes Remotion development into discrete domains, each with its own rule file in the skills/remotion/rules/ directory:

Animation primitives (timing.md, 3d.md): How timing actually works in Remotion. useCurrentFrame(), useVideoContext(), interpolate(). Easing function selection. Frame interpolation boundaries. When to use useTransform() versus manual interpolation. This is where most beginners go wrong trying to force CSS animation patterns onto a frame-driven system.

Media types (videos.md, images.md, gifs.md): Each media type has different insertion methods, codec requirements, and performance implications. Videos require Sequence components for multi-segment handling. GIFs can exceed upload limits in Vercel deployments if uncompressed. Images need proper aspect ratio declarations or FFmpeg will stretch them during output.

Audio ecosystem (audio.md, audio-visualization.md, sfx.md, get-audio-duration.md, silence-detection.md): Audio is probably the most complex domain because Remotion separates playback concerns entirely from rendering concerns. The skill covers getAudioDurationForFrame, silence detection for auto-cropping long tracks, sound effects integration via sfx.json, audio visualization using canvas-based spectrogram generation, and converting between frame counts and audio timestamps.

Text and typography (measuring-text.md, google-fonts.md, local-fonts.md): Measuring text is non-trivial in a Canvas environment. You can’t just use getComputedStyle(). The skill documents how to use textBlockLayout for layout measurements, preload fonts with FontFaceObserver, handle font fallbacks, and load custom fonts from local bundles when Google Fonts aren’t available.

Captions and subtitles (display-captions.md, import-srt-captions.md, transcribe-captions.md, subtitles.md): SRT caption import, transcription workflows, runtime caption display, and subtitle styling. Captions are tricky because they operate on time coordinates (milliseconds) while Remotion operates on frames (at your configured FPS). Conversion math matters.

Transitions and visual effects (transitions.md, light-leaks.md, lottie.md): Transition compositions, keyframe sequencing for multi-element crossfades, light leak overlay blending techniques, and Lottie JSON animation integration. These rules include specific BlendMode configurations and opacity curves that produce professional results without trial-and-error.

Advanced integrations (maplibre.md, tailwind.md, html-in-canvas.md): Mapbox/MapLibre map rendering for animated location videos. TailwindCSS setup quirks specific to Remotion’s webpack config. HTML content rendered inside Canvas elements via OffscreenCanvas transfer.

Metadata and inspection (calculate-metadata.md, get-video-dimensions.md, get-video-duration.md): Calculating total duration from parameterized compositions, extracting media dimensions, frame extraction for thumbnails, and dynamic metadata computation across multi-scene projects.

Core mechanics (compositions.md, parameters.md, sequencing.md, trimming.md, ffmpeg.md, transparent-videos.md): Composition architecture, parameter passing between compositions, sequencing multiple compositions, trimming audio/video segments, direct FFmpeg command access, and transparent alpha channel export with the correct codec settings.

How It Actually Works

You don’t configure this skill manually. On skills.sh, installation is one command:

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

Your agent (Claude Code, Cursor, Codex, Windsurf, etc.) reads the SKILL.md file first, which tells it two things:

1. When to apply: Only when dealing with Remotion-related code
2. Project setup helper: If starting from zero, scaffold with npx create-video@latest --yes --blank my-video

Then as you begin coding, the agent pulls relevant rules contextually. Writing an animation? It references timing.md. Adding SRT captions? It reads import-srt-captions.md. Generating a spectrogram visualization? It follows audio-visualization.md.

The new project setup instruction alone saves significant time. Without it, agents try npm init + manual @remotion/cli installation. With it, they get a working project structure immediately.

Real Patterns Worth Stealing

Timing fundamentals: Every Remotion animation starts with the same pattern:

const frame = useCurrentFrame();
const duration = 60; // frames
const scale = interpolate(frame, [0, duration], [0, 1], {
  extrapolateRight: ' clamp',
});

The skill teaches agents to always declare duration explicitly rather than hardcoding numbers scattered across a component. This makes reusability trivial.

Composition parameters: Rather than embedding values directly, use CompositionProps’s props parameter:

<Sequence from={20} durationInFrames={30}>
  <Intro title={props.title} />
</Sequence>

This lets you render variations of the same composition with different data — critical for batch-producing social media videos where only the headline changes but the entire video template stays identical.

Sequencing multiple scenes: Most real Remotion projects need more than one scene. The sequencing.md rule documents the pattern of chaining sequences with precise from offsets:

<Sequence from={0} durationInFrames={videoLength}>
  <SceneOne />
</Sequence>
<Sequence from={30} durationInFrames={20}>
  <SceneTwo />
</Sequence>

Without knowing about from offset overlap behavior, developers accidentally create black gap frames or overlapping renders.

Where It Falls Short

No interactive preview feedback. The skill teaches you to write correct Remotion code, but it can’t show you whether the output looks right. Remotion’s built-in dev server preview already handles this. The skill fills the gap between “it compiles” and “this is how professionals do it.”

Maps rules are heavy. The Mapbox/MapLibre integration documentation is over 12kb (the largest rule file in the set). If you’re not animating maps, those instructions sit idle in context. Rule-level caching means you typically only pay for what you read, but it still adds to initial load overhead.

Doesn’t replace the docs. For deep API questions — like the exact signature of useVideoContext() or all available BlendMode values — the Remotion reference docs are still the source of truth. This skill provides conventions and patterns between docs pages, not replacements for them.

Why Official Team Skills Matter

Most open-source Agent Skills come from individual developers sharing their workflow tricks. They work great until the underlying API changes. Remotion’s remotion-dev/skills repo is maintained by the official team building the product. Rules ship alongside framework releases. Breaking API changes arrive with updated rule files.

A 356K-install count suggests either massive adoption or aggressive download behavior. But the star count relative to install count (3500 vs 350,000+) indicates most users consume these skills silently during agent sessions — they don’t need to star something they’re actively using.

The real signal is simpler than metrics: this skill exists because an entire team decided that documenting how to build with their tool should be machine-readable first. Not a secondary concern. A first-class citizen.

Try It

If you’re building anything with Remotion — a YouTube intro, automated TikTok clips, data-driven report videos — adding this skill to your agent configuration prevents the kind of mistakes that cost more time than writing the code itself.

Installation:

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

Repository: https://github.com/remotion-dev/skills