前言¶

用 React 写视频，听起来很酷：时间轴变成帧号，动画变成 interpolate()，最终渲染成 MP4。Remotion 把这套流程跑通了，但 AI 编程助手在生成 Remotion 代码时，经常会踩一些「看起来像前端、实际渲染不对」的坑——比如用 CSS transition 做动画、资产路径写错、媒体组件选错包。

remotion-best-practices 就是 Remotion 官方为这类场景准备的 Agent Skill。它把「怎么正确写 Remotion」拆成可路由的知识库，让 Cursor、Claude Code、Codex 等工具在改视频相关代码时，先按官方约定行事，而不是凭通用 React 经验瞎猜。

这是什么¶

remotion-best-practices 由 Remotion 官方维护（仓库：remotion-dev/skills），在 Agent Skills 标准下以 SKILL.md 形式分发。官方文档称它是总入口 Skill：不确定该用哪条子技能时，优先用它；它会按任务把代理路由到创建项目、写 Markup、地图、字幕、渲染、升级等更细的参考文档。

当前仓库中标注的版本为 4.0.509。skills.sh 上的摘要把它定位为：面向 Remotion + React 的领域知识库，覆盖动画、音频、资产、字幕、地图、渲染与组合管理等实践。

核心能力¶

从官方 SKILL.md 与文档目录看，它主要做三件事：

1. 按场景路由
   用户说「做个新视频」「写 Remotion 组件」「加字幕」「开 Studio」「渲染」「查文档」「升级」时，入口 Skill 会指向对应的子技能，例如：
   - remotion-create：脚手架与新建 composition
   - remotion-markup：动画、布局、媒体、特效、字体等 Markup 规范
   - remotion-maps：静态地图、路线、Mapbox / MapLibre / MapTiler、GeoJSON、三维飞越等
   - remotion-multimedia：浏览器内裁剪、元数据等多媒体任务
   - remotion-captions：字幕相关
   - remotion-studio / remotion-render：预览与渲染
   - remotion-saas：基于 Remotion 的 SaaS / 自动化架构（含 Lambda、Vercel、Cloudflare、客户端渲染等方向）
   - remotion-interactivity：让 Studio 里可交互编辑并写回代码
   - remotion-docs / remotion-upgrade：查官方文档、升级依赖与已安装 Skills

2. 把「帧驱动」写成硬规则
   Markup 子技能明确要求：动画用 useCurrentFrame() + interpolate()；CSS transition / animation 以及 Tailwind 动画类在 Remotion 渲染里不可靠，需要改掉。媒体优先用 @remotion/media 的 <Video> / <Audio>，静态资源放 public/，用 staticFile() 引用。

3. 保留用户手改
   入口与多条子技能都写了同一条原则：如果发现对话外有意外改动，不要直接覆盖，默认当作有意修改或先向用户确认。这对「人和 AI 一起改同一份 composition」很实用。

安装与启用¶

官方文档给出的安装方式是一次性拉取 Remotion 维护的 Skills 包（其中包含 remotion-best-practices 等）：

npx skills add remotion-dev/skills

若只要单独安装这一条，skills.sh 上的命令是：

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

新建 Remotion 项目时也可以顺带安装。官方文档示例：

bun create video

创建流程里会提示是否添加这些 Skills。

该 Skill 基于通用 SKILL.md 格式。Remotion 官方文档写明适用于 Claude Code、Codex、Kimi Code、Cursor 等 AI 代理；具体落到哪个工具目录，以 npx skills 安装时的选择为准（例如 Cursor 常见为项目内的 skills 目录）。核实到的信息止于此，各工具细目录差异以本机安装输出为准。

典型用法¶

1. 从零搭一个空白视频项目¶

子技能 remotion-create 要求：当前目录还没有 Remotion 项目时，用官方脚手架（需已安装 Node.js 与 Git）：

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

把 my-video 换成合适的项目名。之后在组件里写 React Markup，而不是先手搓一套目录。

2. 按规范写一帧驱动的淡入标题¶

remotion-markup 给出的核心模式是：帧号进 interpolate()，缓动用 Easing.bezier() / Easing.spring()，尽量把插值写在 style 里（方便 Studio 编辑）。示意如下（来自官方 REFERENCE 思路）：

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>
  );
};

媒体资源示例：

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")} />
  </>
);

需要加 @remotion/* 等包时，Skill 建议用：

npx remotion add @remotion/media

以保证版本与 Remotion 主版本匹配。

3. 预览与抽帧自检¶

预览 Studio：

npx remotion studio --no-open

命令会打印本地预览地址；已有服务在跑时也会打印 URL。可按 composition id 访问，例如 http://localhost:3000/MapAnimation。

可选：渲染单帧做布局/配色 sanity check（官方建议非必要可跳过）：

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

在 30 fps 下，--frame=30 约等于第 1 秒（帧号从 0 起）。完整成片仅在用户明确要求时再执行 npx remotion render。

4. 对代理怎么说¶

安装后，直接用自然语言即可，例如：

• 「用 Remotion 做一个产品宣传片 composition」
• 「给这段视频加字幕」
• 「开 Studio 预览并检查标题动画」
• 「按官方规范升级 Remotion 相关包」

入口 Skill 的默认提示示例是：Make a promo video for my product。不确定子技能时，也可以显式点名 /remotion-best-practices，让代理从总路由开始加载。

适用场景与注意点¶

比较适合：

• 已经或准备用 Remotion 做程序化视频（宣传片、数据可视化视频、模板化短视频、地图讲解等）
• 希望 AI 助手少写「能预览但渲染错」的 CSS 动画，多写帧驱动代码
• 需要字幕、地图、SaaS 渲染、Studio 可编辑结构等进阶能力，又不想自己把文档翻一遍

使用时注意：

• 这是领域知识 Skill，不是视频剪辑软件；最终仍要有可用的 Remotion 工程与渲染环境。
• CSS / Tailwind 动画类在 Remotion 里不可靠，应改成 useCurrentFrame() + interpolate()。
• 资产放 public/，媒体组件优先走 @remotion/media；加包尽量用 npx remotion add。
• 渲染成片前先用 Studio 或 still 抽帧确认；不要默认自动全量 render。
• 人和 AI 共编辑时，Skill 要求尊重对话外的手改，避免无覆盖。

小结¶

程序化视频把「剪辑」变成了「写组件」。remotion-best-practices 的价值，在于把 Remotion 官方那一套帧驱动、资源引用、Studio/渲染约定，装进 AI 代理可加载的 Skill 里，并按任务路由到更细的子文档。若你已经用 Cursor / Claude Code / Codex 写 Remotion，装上它通常比反复纠正「别用 CSS transition」更省时间。

官方地址：

• Skill 目录：https://github.com/remotion-dev/skills/tree/main/skills/remotion-best-practices
• 官方文档：https://www.remotion.dev/docs/ai/skills
• skills.sh：https://skills.sh/remotion-dev/skills/remotion-best-practices