前言¶

用 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