Remotion 官方 Agent Skill：30 条规则教会 AI 用 React 写视频

安装一个 agent skill，然后开始写视频。

这就是 remotion-dev/skills 仓库中的 remotion-best-practices 做的事情。skills.sh 上超过 35 万次安装，2024 年 1 月上线至今拿到了 3500 个 GitHub star。和之前介绍过的 Remotion 内部贡献 skill（存放在主仓库 .agents/ 下的那些）不同，这一个面向的是在 Remotion 之上做开发的开发者，而非参与框架本身贡献的贡献者。

它解决什么问题

Remotion 的运行依赖三个大多数前端开发者没碰过的东西：基于帧的动画系统、WebGL Shader 编译、以及 FFmpeg 渲染管线。useCurrentFrame() 的帧索引写错一位，整个合成轨道就会错位；用了错误的 codec 参数导出视频，FFmpeg 会静默产出损坏的文件；在页面里直接用 <audio> 标签而不是 AudioSprite ，浏览器直接拒绝渲染。

学习曲线陡峭的原因是心智模型和常规 Web 开发完全不同。时间不是流逝的，是一帧一帧推进的。动画不用 CSS keyframe 或 GSAP，而是用 interpolate() 配合明确的帧范围和缓动曲线。音频不是通过 Web Audio API 播放的——而是在渲染时通过 FFmpeg 嵌入到二进制流中。

这个 skill 把社区多年的经验压缩成了 30 多条规则文件，AI 编码代理在写任何 Remotion 代码之前先读它们。目标不是教会所有概念，而是防止那些浪费数小时排查的错误。

里面有什么

skill 将 Remotion 开发拆成了独立的领域，每个领域对应 skills/remotion/rules/ 下的一条规则文件：

动画基础 (timing.md, 3d.md)： Remotion 中时间的真实运作方式。useCurrentFrame()、useVideoContext()、interpolate()。缓动函数的选择。帧插值的边界处理。何时用 useTransform() 还是手动插值。这是新手最容易出错的地方——他们总试图把 CSS 动画的模式套到帧驱动的系统上。

媒体类型 (videos.md, images.md, gifs.md)： 每种媒体类型的插入方法、编解码器要求和性能影响都不同。视频需要 Sequence 组件来处理多段素材。GIF 如果不压缩，Vercel 部署时会超过上传限制。图片不声明正确的比例，FFmpeg 输出时会拉伸变形。

音频体系 (audio.md, audio-visualization.md, sfx.md, get-audio-duration.md, silence-detection.md)： 音频可能是最复杂的领域，因为 Remotion 把播放和渲染完全分离了。skill 覆盖了：用 getAudioDurationForFrame 获取音频时长、自动裁剪超长音轨的静音检测、通过 sfx.json 集成音效、用 Canvas 实现频谱可视化、以及在帧数和音频时间戳之间做转换的方法。

文字和排版 (measuring-text.md, google-fonts.md, local-fonts.md)： Canvas 环境中测量文字并不简单。你不能用 getComputedStyle()。skill 记录了如何用 textBlockLayout 进行布局测量、用 FontFaceObserver 预加载字体、处理字体降级方案、以及在 Google Fonts 不可用时从本地包加载自定义字体。

字幕和标题 (display-captions.md, import-srt-captions.md, transcribe-captions.md, subtitles.md)： SRT 字幕导入、语音转写工作流、运行时字幕显示和样式定制。字幕比较棘手，因为它们基于时间坐标（毫秒），而 Remotion 基于帧数（根据配置的 FPS）。单位换算的数学公式必须写对。

转场和视觉特效 (transitions.md, light-leaks.md, lottie.md)： 转场合成、多元素淡入淡出的关键帧序列、光效叠加混合技法、以及 Lottie JSON 动画集成。这些规则提供了具体的 BlendMode 配置和透明度曲线参数，无需反复调试就能达到专业效果。

高级集成 (maplibre.md, tailwind.md, html-in-canvas.md)： Mapbox/MapLibre 地图渲染用于动态位置视频。TailwindCSS 接入 Remotion webpack 配置的注意事项。通过 OffscreenCanvas 传输在 Canvas 中渲染 HTML 内容。

元数据和媒体测量 (calculate-metadata.md, get-video-dimensions.md, get-video-duration.md)： 计算参数化合成的总时长、提取媒体维度、帧级缩略图提取、以及多场景项目的动态元数据计算。

核心机制 (compositions.md, parameters.md, sequencing.md, trimming.md, ffmpeg.md, transparent-videos.md)： 合成架构、跨组件的参数传递、多合成链式编排、音视频片段裁剪、底层 FFmpeg 命令行访问、以及带透明通道的 alpha channel 导出与编码器设置。

实际是怎么工作的

不需要手动配置。在 skills.sh 上只需要一条命令：

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

你的 agent（Claude Code、Cursor、Codex、Windsurf 等）会先读取 SKILL.md 文件，告诉它两件事：

1. 何时生效： 只有在处理 Remotion 相关代码时才应用规则
2. 项目初始化助手： 如果从零开始，执行 npx create-video@latest --yes --blank my-video 搭建结构

随着代码编写展开，agent 会按需拉取相关规则上下文。写动画？引用 timing.md。添加 SRT 字幕？读 import-srt-captions.md。生成频谱可视化？跟着 audio-visualization.md 走。

项目初始化那条指令本身就省了很多时间。没有它的话，agent 会尝试 npm init + 手动装 @remotion/cli。有了它就立刻拿到可运行的项目结构。

值得借鉴的实用模式

动画基础写法： 所有 Remotion 动画都始于同一个模式：

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

skill 教 agent 始终显式声明 duration，而不是把数字散落在组件各处。这让复用变得异常简单。

合成参数传递： 不要硬编码值，使用 CompositionProps 的 props 参数：

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

这样你可以用同一个模板渲染不同数据的组合——为批量生产社交媒体视频的关键场景，唯一的变量是标题文字，但整张视频模板保持不变。

多场景链式编排： 多数实际项目不止一个场景。sequencing.md 规则文档化了带精确 from 偏移量的 sequence 链式编排模式：

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

不了解 from 偏移量重叠行为的话，开发者会不知不觉中制造黑帧间隙或者重叠渲染。

它的局限性

没有交互预览反馈。 这个 skill 教你写正确的 Remotion 代码，但它无法告诉你输出的效果是否正确。Remotion 自带的 dev server preview 已经能解决这步。skill 填补的是「能编译」和「这样做才专业」之间的空白。

地图规则文件很重。 Mapbox/MapLibre 集成的文档超过了 12kb（全篇最大的规则文件）。如果你不做地图动画，这些指令只是在上下文中占着位置。虽然 rule 级缓存意味着你通常只为实际读取的部分付费，但仍然会增加初始加载开销。

不能替代官网 doc。 关于详细 API 问题——比如 useVideoContext() 的完整签名、所有可用的 BlendMode 值——Remotion 的参考文档仍然是权威来源。这个 skill 提供的是文档页与文档页之间的模式和约定，不是替代品。

为什么官方团队的 skill 很重要

大多数开源 Agent Skill 来自个人开发者分享自己的工作流技巧。它们能用，直到底层 API 发生了 breaking change。Remotion 的 remotion-dev/skills 仓库由官方产品构建团队维护。规则和框架版本同步发布。API 变更会带来配套更新的规则文件。

35 万次安装量和 3500 星数之间的差距（100:1），说明大部分用户是在 agent 会话中静默消费的——不需要给正在使用的工具打 star。

更简单的信号是：整个团队做出了一个决定，就是把工具的用法文档做成机器可读的形式。不是第二优先级。是第一位的。

试试

如果你在用 Remotion 做任何东西——YouTube 片头、自动化的 TikTok 短视频、数据驱动的汇报视频——把这个 skill 加到你的 agent 配置中，能省下不少排查错误的时间。

安装：

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

仓库：https://github.com/remotion-dev/skills