skills

让 AI 真正学会「用 React 写视频」：Remotion 官方 Agent Skills 深拆

一、从一个真实的翻车现场说起

设想一个场景：产品经理让你用 Remotion 做一条 30 秒的产品宣传片。你打开 Claude Code 说「帮我写个动画视频」，AI 很快交出一份看起来很像样的 Composition.tsx——<div> 套 <div>，用 CSS transition 做淡入淡出，<img> 直接塞本地文件，音频用 <audio autoplay> 叠在上面。 然后你执行 npx remotion render，报错、渲染卡死、字体不对、帧率抖动、画面撕裂，最后发现所有问题都出在同一个根因：AI 根本不知道 Remotion 的规矩。Remotion 是一个把 React 组件按帧确定性渲染成视频的框架，它的整个世界观建立在「每一帧都是纯函数」之上——不能用 Math.random()、不能用 Date.now()、不能用浏览器动画 API、不能用 setTimeout。而通用大模型对这套约束一无所知，写出来的代码天然违反 Remotion 的核心假设。 remotion-dev/skills 这个仓库，就是为解决这个断层而生的。它是 Remotion 官方维护的 Agent Skills 集合，用 178 个 Markdown 文件把「在 Remotion 项目里该怎么干活」写成 AI 能读懂、且能按需加载的规范。截至 2026 年 11 月，它在 GitHub 上收获 6420 星、696 个 fork，单个贡献者（创始人 Jonny Burger）提交了 95 次，是 Remotion monorepo 中 packages/skills 子包独立出来的产物。

二、背景科普：Remotion 与 Agent Skills 规范

先说 Remotion 本身。它出自一位独立开发者 Jonny Burger之手，核心思路是把「视频」当作 React 组件树：你在浏览器里写组件、实时预览在 Studio 里，最终由 headless Chrome 逐帧截图再交给 FFmpeg 合成。这个架构让前端工程师第一次可以像写网页一样写视频，也让它天然适合被 AI 改造——因为 React 代码对大模型来说是最熟悉的语言。 但也正因为如此，Remotion 的「隐式知识」特别多。这些知识分散在官方文档站的几十个页面里：怎么用 useCurrentFrame() 驱动动画、怎么用 interpolate() 做缓动、Sequence 的 from/durationInFrames 怎么算、音频和视频元素为什么必须放在 Sequence 里、音量曲线怎么写、字体为什么要 @remotion/google-fonts 而不是本地 <link>。文档写给人看，AI 不会主动去读，于是就成了典型的「知识鸿沟」。 而 Agent Skills（agentskills.io 规范）正是 Anthropic 等厂商推动的一种 Agent 上下文组织方式：把领域知识拆成带 YAML frontmatter 的 SKILL.md，放进 .agents/skills/ 目录（Claude Code 通过 .claude/skills 符号链接兼容），模型在需要时按 description 匹配并加载。Remotion 是较早把这一机制做成产品化分发的开源项目之一。

三、类比：把它想成「AI 编程时的领域教练

如果把写 Remotion 视频比作拍一部电影，那么这个技能包相当于一位坐在监视器旁边的场记兼摄影指导。它不会替你按快门（npx remotion render 仍要你自己触发），但它会拍掉那些「业余」的镜头：告诉你灯光要从第 30 帧开始渐亮而不是靠 CSS 过渡，告诉你素材要放进 public/ 而不能引用外部 URL，告诉你旁白轨道要用 staticFile() 加载本地音频。 更妙的是它的「路由式」设计。remotion-best-practices 是总纲，本身就是一份「问题 → 该读哪份文档」的路由表：想做新项目读 remotion-create，要写动画读 remotion-markup，要做字幕读 remotion-captions，要做地图动画读 remotion-maps，要做 SaaS 集成读 remotion-saas，要查 API 读 remotion-docs。模型只需要加载最相关的那一两个分支，不必把 178 个文件全部塞进上下文。

四、核心功能与技能矩阵

仓库根目录只有 README.md、package.json、tsconfig.json、scripts/ 和 skills/，结构极度克制。skills/ 下 13 个技能目录，按 Markdown 文档数计：

• remotion-best-practices（89 篇）——总纲与路由，外加动画、时序、转场、字体等细则的完整索引；
• remotion-markup（49 篇）——写 React 标记的核心规范，覆盖合成、动画、布局、排版、媒体元素、特效、音频、字体、时序、转场、3D、HTML-in-Canvas、Lottie、语音旁白、阿拉伯语排版等；
• remotion-maps（15 篇）——Mapbox / MapLibre / MapTiler / GeoJSON 静态地图与路线动画、CesiumJS 三维地理漫游；
• 其余 captions、multimedia、saas、create、interactivity、render、docs、license、studio、upgrade 各 1-4 篇；
• 每个技能还额外带一个 agents/openai.yaml，声明 display_name、品牌色 #0B84F3、默认提示词等元信息，让 Codex 等非 Claude 系客户端也能正确呈现技能。 值得一提的三个设计细节。第一是**「先预览、后渲染」的强约束**：remotion-best-practices 明确要求除非用户显式要求，否则不主动渲染，先启动 Studio 让用户看着进度实时指挥，这在人机协作里极大降低了「渲染完才发现方向错了」的返工成本。第二是**「保护用户改动」原则写在总纲最前面——检测到对话期间代码被外部修改时，不覆盖、假定有意为之或先询问。第三是内容与代码分离**：仓库只有 5 个 TypeScript 脚本（sync-readme.ts、validate-links.ts 等），负责同步 README、校验文档内链、嵌入技能进 SDK，而不是承载业务逻辑。

五、上手门槛：几乎为零，但有两个坑

安装本身是两条命令之一：

npx skills add remotion-dev/skills   # 通用 skills CLI
gh skill install remotion-dev/skills # GitHub CLI

也可以在 bun create video 新建项目时被官方提示顺带安装，或用 npx remotion skills add / update 走 Remotion 自己的 CLI（技能装到 .agents/skills，Claude Code 通过符号链接兼容）。第三方统计（skills.sh）显示这套技能累计安装量超过 370 万次，其中 remotion-best-practices 独占 75 万——它是事实上的入口技能。 坑有两个。其一是技能本身不解决环境问题：它能教 AI 写对代码，但 Remotion 渲染仍需要 Chromium、Node 环境以及一份可能需要付费的公司许可证（个人和 3 人以下小公司免费商用）。其二是许可证的双轨制：remotion-dev/skills 仓库本身没有独立的 LICENSE 文件，它继承 monorepo 根目录的 Remotion License——允许免费使用与修改，但明确禁止「复制 Remotion 源码做成竞品」。这正是 PIFS 库里 license 字段标为 Other 而不是 MIT 的原因，也提醒使用者：技能文档可自由取用，但拿它去造一个替代 Remotion 的产品并不被允许。

六、争议与局限

第一，这类「官方喂给 AI 的规范库」本质上是把文档成本转移给模型厂商。Remotion 通过维护这套技能，等于用一次性的文档整理换取长期的模型调用质量，思路聪明，但也意味着 Remotion 团队要持续承担「AI 生成的代码更复杂、更难排错」的间接成本。 第二，技能内容与官方文档版本必须强绑定。仓库版本号 4.0.541 与 Remotion SDK 版本严格一致，还有专门的 remotion-upgrade 技能负责同步 SDK、Mediabunny 与已安装技能。这套「同步」机制做得好，但也暴露一个事实：用户装到的技能随时可能落后于实际依赖的 SDK 版本，而 95 次提交几乎全是「Update template」这类自动同步提交，仓库的人工增量其实很少。 第三，remotion-docs 技能本质上是一个「文档抓取器」——搜索文档站并把页面转成 Markdown 取回。AI 生成的代码若引用了不存在的 API，仍然要靠人兜底，技能并不提供编译期校验。

七、行业意义：一个更大的信号

Remotion Skills 的 6420 星，在开源「Skills 类仓库」这个 2026 年才成型的新物种里相当突出——同类还有 mattpocock/skills、obra/superpowers 等。作为对比，一个普通工具库要拿到 6400 星需要数年，而 Remotion Skills 从 2026 年 1 月 19 日创建到 2026 年 11 月仅用约十个月。 这背后是一条清晰的主线：框架厂商正在把「如何正确使用我」编码成 AI 可消费的资产。过去文档是给人读的、搜索是关键词匹配、模型是随机采样上下文；现在文档被重组成可路由、可按需加载、可版本锁定的技能包，直接参与代码生成。对框架方而言，这是把「用户踩坑 → 提 issue → 官方改文档」的慢循环，压缩成「用户踩坑 → AI 读技能 → 直接写对」。对使用者而言，竞争正在从「哪个框架我更熟」转向「哪个框架的技能包更好」——这会实质性地重排前端与 AI 工具链的生态位。 如果你正在用 AI 做视频自动化，这条路径值得优先试：让 AI 先读 /remotion-best-practices，再让它开 Studio 给你看，最后才渲染——把「导演」和「剪辑」这两个角色分开，正好是这套技能设计时预设的工作流。