把 AI 生成视频转场特效封装成一个 Skill是短视频创作者和 AI 工程实践者都应该掌握的用法。所谓 Skill简单说就是给 AI 助手准备的一套能力包用户描述“我要让两段视频之间做一个 1 秒的交叉溶解”时AI 不再靠泛泛的对话猜测转场参数而是读取目录里写好的 SKILL.md按固定步骤调用脚本最终生成可验证的 FFmpeg 命令或直接产出视频。下面从 Skill 概念讲起逐步搭建一个名为video-transition-skill的最小能力包并给出运行验证、常见问题排查和扩展建议。我会按“理解 Skill 机制 - 准备环境 - 编写 Skill - 运行验证 - 排错 - 最佳实践”的顺序展开。如果你已经写过 Agent 插件可以重点看第 3 章和第 4 章的脚本实现如果你刚接触 Skill建议从第 1 章开始读避免后面配置失败时不知道问题出在哪一层。1. 先搞清楚 Skill 到底是什么再决定要不要自己写1.1 Skill 解决的是“让 AI 按固定套路干活”的问题大模型本身能聊天但没法可靠地执行“读取视频时长、计算转场偏移、生成 FFmpeg 命令”这套固定流程。普通提示词可以让模型“大概知道”要做什么却无法保证每次都能按同一套参数规范操作。Skill 的作用是把这套流程变成 AI 可读取、可调用、可校验的能力包。一个 Skill 通常是一个目录里面至少包含一份说明文件和一些可执行资源。说明文件告诉 AI这个技能在什么场景下使用有哪些输入参数应该按什么顺序执行最后输出什么结果。AI 收到用户请求后先判断当前任务是否匹配某个 Skill如果匹配就按照说明调用脚本、读取示例或运行命令。在视频转场场景里Skill 的核心价值是稳定。跨场转场涉及xfade、zoompan、fade等滤镜参数稍有偏差就会得到黑屏、闪帧或偏移错误。把参数说明和生成逻辑写进 SkillAI 就不需要回忆“上个视频是怎么做的”而是直接查找能力包里的模板。1.2 Skill、Agent、插件和普通脚本的边界这几个概念经常混在一起。先看它们的分工概念核心作用在视频转场场景中的例子Skill给 AI 提供一套可复用的操作流程和工具说明video-transition-skill包含 SKILL.md 和生成 FFmpeg 命令的脚本Agent负责拆解任务、调用多个工具、根据结果决定下一步用户说“生成转场并发送到工作群”Agent 先调用 Skill 生成视频再调用上传脚本插件通常指扩展 IDE 或 CLI 功能的程序模块编辑器中集成视频预览面板不属于 AI 能力包普通脚本能独立完成一个具体操作但 AI 不知道它存在单独运行的make_transition.py只能由人手动执行Skill 和 Agent 的关系可以理解为“职业手册”和“管理层”的关系。Agent 负责决策和编排Skill 负责提供标准作业程序。如果只有脚本AI 不知道该怎么用如果只有提示词执行结果不够稳定。Skill 正好把两者结合起来。1.3 视频转场特效为什么适合封装成 Skill视频转场是典型的高重复、高参数化任务。每一次转场都需要指定输入文件、转场类型、持续时间、开始时间和输出路径。参数组合很多但规律固定。用户往往不会说“用 xfade 滤镜transitionfadeduration1.0offset3.2”而是说“在第二个片段开始前做一个柔和过渡”。封装成 Skill 后AI 能完成一次“自然语言转结构化参数”的转换。它先把用户描述映射成 JSON 配置再调用脚本生成命令最后执行并反馈结果。这样用户不需要记住 FFmpeg 滤镜语法AI 也不需要依赖记忆生成命令整个链路更接近工程化。2. 环境准备一个能跑通的最小组合2.1 需要准备哪些工具要复现下面的示例建议准备一个最小环境工具用途最低建议Python 3运行脚本解析 JSON 配置3.8 及以上FFmpeg执行视频滤镜和编码支持xfade滤镜的版本ffprobe读取视频时长等元数据随 FFmpeg 安装支持 Skill 机制的 AI 编程助手让模型能读取 SKILL.md 并调用脚本任选你已使用的工具这里不绑定某一个具体平台。常见的编程助手对 Skill 的目录约定可能略有差异有的放在项目.agents/skills下有的放在用户级~/.claude/skills或~/.codex/skills下。落地前先查一下当前工具的文档确认它读取的是哪个目录。2.2 确认 Skill 目录约定如果你的 AI 助手已经支持 Skill 机制通常会有一个约定的查找路径。比如项目根目录/ .agents/ skills/ video-transition-skill/ SKILL.md scripts/ make_transition.py有些平台使用.claude/skills、.codex/skills或~/.codex/skills。还有的会把 Skill 放在用户级目录方便所有项目共用。为了不对版本下结论建议你按当前工具的文档确认关键词SKILL.md、skills 目录、是否支持项目级配置。确认目录时可以做一次最简测试在候选目录下新建一个hello-skill/SKILL.md写入“当用户说 hello 时回复 skill ok”然后让 AI 触发。如果助手能引用这个文件说明目录路径正确。2.3 准备测试视频片段示例脚本需要两段输入视频。为了快速验证可以用 FFmpeg 生成两个带颜色的测试片段ffmpeg -f lavfi -i colorcred:size640x360:duration5 -c:v libx264 -pix_fmt yuv420p clip1.mp4 ffmpeg -f lavfi -i colorcblue:size640x360:duration5 -c:v libx264 -pix_fmt yuv420p clip2.mp4执行完后检查ffprobe -v error -show_entries formatduration -of defaultnoprint_wrappers1:nokey1 clip1.mp4如果能看到类似5.000000的输出说明测试片段可用。注意生成测试片段时建议指定-pix_fmt yuv420p否则后续视频拼接可能因为像素格式不一致报错。3. 创建 video-transition-skill目录结构与核心文件3.1 目录结构先定下来一个最小的 Skill 可以只有SKILL.md但做视频转场建议把“说明”和“可执行脚本”分开video-transition-skill/ SKILL.md scripts/ make_transition.py examples/ crossfade.json fadeblack.json每个文件的作用SKILL.md给 AI 看的说明书描述技能用途、参数、执行步骤和注意事项。scripts/make_transition.py读取 JSON 配置自动计算转场偏移输出 FFmpeg 命令。examples/存放不同转场类型的示例配置方便 AI 快速复制。目录结构不要写成多级嵌套。Skill 本身应该是独立、单一职责的能力包目录越简单越容易被读取。3.2 编写 SKILL.md告诉 AI 什么时候用、怎么用下面是一份可用的 SKILL.md 示例你需要根据自己平台的 frontmatter 要求做调整# video-transition-skill 为两段视频生成转场特效。支持 crossfade、fadeblack、wipeleft、 slideleft、circleopen 等基于 xfade 滤镜的转场。 ## 适用场景 用户提供两段视频路径并希望合成一个带转场效果的新视频时 使用本技能。 ## 使用步骤 1. 确认两个输入视频文件存在且可以被 ffprobe 读取。 2. 将用户需求整理成 JSON 配置写入临时文件或直接作为命令行参数。 3. 先执行 dry-run 生成命令并展示给用户确认。 4. 用户确认后使用 --run 执行生成。 ## 命令示例 python scripts/make_transition.py --config examples/crossfade.json --dry-run python scripts/make_transition.py --config examples/crossfade.json --run ## 配置字段 - input1: 第一段视频路径。 - input2: 第二段视频路径。 - transition: 转场类型默认 crossfade。 - duration: 转场时长单位秒默认 1.0。 - offset: 可选转场开始时间。不填时脚本会尝试自动计算。 - output: 输出视频路径默认 output.mp4。 ## 注意事项 - duration 必须小于第一段视频的时长。 - 不要覆盖输入文件。 - 执行前先 dry-run避免 ffmpeg 参数错误导致输出文件损坏。关键点在于“适用场景”要具体。AI 判断是否调用 Skill 时依赖这份描述来判断匹配度。如果写得太宽泛AI 可能在不合适的时候调用写得太窄又会漏掉真实需求。最好在真实助手环境中测试几轮再补充边界情况。3.3 编写 make_transition.py把转场参数变成 FFmpeg 命令脚本不需要处理像素级算法FFmpeg 已经帮我们做好了。脚本的职责是把 JSON 配置转换成合理的 FFmpeg 命令并在执行前校验参数。先创建一个scripts/make_transition.py#!/usr/bin/env python3 import argparse import json import subprocess import sys from pathlib import Path TRANSITIONS { crossfade: fade, fadeblack: fadeblack, wipeleft: wipeleft, slideleft: slideleft, circleopen: circleopen, } def get_duration(path: str) - float: cmd [ ffprobe, -v, error, -show_entries, formatduration, -of, defaultnoprint_wrappers1:nokey1, str(path), ] result subprocess.run(cmd, capture_outputTrue, textTrue) if result.returncode ! 0: raise RuntimeError(f无法读取视频时长: {path} - {result.stderr}) return float(result.stdout.strip()) def build_command(config: dict): input1 config.get(input1) input2 config.get(input2) if not input1 or not input2: raise ValueError(配置中必须包含 input1 和 input2) transition config.get(transition, crossfade) if transition not in TRANSITIONS: raise ValueError(f不支持的转场类型: {transition}) duration float(config.get(duration, 1.0)) output config.get(output, output.mp4) duration1 None try: duration1 get_duration(input1) except RuntimeError: print(警告无法读取第一段视频时长将依赖配置中的 offset。, filesys.stderr) if duration1 and duration duration1: raise ValueError(转场时长必须小于第一段视频时长) offset config.get(offset) if offset is None: if duration1: offset max(duration1 - duration, 0) else: raise ValueError(无法自动计算 offset请在配置中提供 offset) else: offset float(offset) filter_complex ( f[0:v][1:v]xfadetransition{TRANSITIONS[transition]} f:duration{duration}:offset{offset}[v] ) return [ ffmpeg, -i, input1, -i, input2, -filter_complex, filter_complex, -map, [v], -c:v, libx264, -pix_fmt, yuv420p, -y, output, ] def main(): parser argparse.ArgumentParser(description生成视频转场 FFmpeg 命令) parser.add_argument(--config, requiredTrue, helpJSON 配置文件路径) parser.add_argument(--dry-run, actionstore_true, help只打印命令不执行) args parser.parse_args() config json.loads(Path(args.config).read_text(encodingutf-8)) cmd build_command(config) print(生成的命令) print( .join(cmd)) if args.dry_run: return print(开始执行……) subprocess.run(cmd, checkTrue) print(转场视频已生成:, config.get(output, output.mp4)) if __name__ __main__: main()这段脚本有几个设计点。get_duration用 ffprobe 获取第一段视频时长目的是自动计算offset。在xfade滤镜中offset表示转场开始的时间点通常等于第一段视频时长减去转场时长。例如第一段视频 5 秒转场 1 秒offset 应为 4 秒这样第二段视频从第 4 秒开始混合进入。build_command返回的是字符串列表而不是直接拼成 shell 字符串。这样执行时不需要经过 shell可以减少特殊字符带来的问题。FFmpeg 命令中可能包含中文路径、空格、括号使用参数列表更安全。--dry-run是安全边界。脚本默认行为只打印命令用户确认后再通过--run实际执行。如果 AI 直接执行未经确认的命令一旦输出路径写错或参数异常可能会覆盖已有文件。4. 用 JSON 配置驱动转场生成4.1 配置字段说明为了让 AI 能稳定生成配置建议在SKILL.md和示例文件里把字段写仔细。以一个交叉溶解示例为例创建examples/crossfade.json{ input1: clip1.mp4, input2: clip2.mp4, transition: crossfade, duration: 1.0, output: output_crossfade.mp4 }字段含义如下表字段是否必填默认值说明input1是无第一段视频路径input2是无第二段视频路径transition否crossfade转场类型duration否1.0转场时长单位秒offset否自动计算转场开始时间单位秒output否output.mp4输出视频路径4.2 自动计算 offset 的原理xfade滤镜要求两个输入视频在时间轴上重叠。它的时间轴逻辑是第二段视频从offset秒处开始与第一段视频混合混合持续duration秒。如果第一段视频总长为 5 秒duration 为 1 秒offset 应该是 4 秒。如果 offset 设置过小转场会在第一段视频还很亮时就开始出现第二段画面如果 offset 过大转场结束后第一段可能已经结束画面会黑场。更严重的是offset 加 duration 超过第一段视频总时长时FFmpeg 会报错或输出异常。因此代码优先用 ffprobe 读取真实时长再自动计算 offset。只有在读取失败时才要求用户在配置中手动填写 offset。实际项目中如果输入视频来自剪辑软件时长信息通常可靠如果来自网络下载或录屏最好保留手动 offset 覆盖能力。4.3 从用户一句话到 Skill 执行的完整链路当 AI 支持 Skill 机制后完整链路可以这样理解用户说“把 clip1.mp4 和 clip2.mp4 拼起来中间用一个 1 秒的淡入淡出转场。”AI 识别到“两段视频”“转场”等关键词判定匹配video-transition-skill。AI 读取 SKILL.md看到使用步骤和参数说明。AI 把用户描述整理成 JSON 配置甚至可以自动创建临时配置也可以参考examples/crossfade.json。AI 先执行 dry-run得到 FFmpeg 命令并展示。用户确认后AI 去掉--dry-run执行脚本。这个链路的关键是“结构化参数”。如果 AI 没有把用户描述转换成 JSON而是直接生成 FFmpeg 命令就不能复用脚本的校验和 offset 计算逻辑。Skill 的价值不是替代 FFmpeg而是让 AI 的每一步都可复现、可校验。5. 运行与验证不能只看命令输出了5.1 先跑 dry-run在 AI 助手环境中建议先运行cd video-transition-skill python scripts/make_transition.py --config examples/crossfade.json --dry-run预期输出类似生成的命令 ffmpeg -i clip1.mp4 -i clip2.mp4 -filter_complex [0:v][1:v]xfadetransitionfade:duration1.0:offset4.0[v] -map [v] -c:v libx264 -pix_fmt yuv420p -y output_crossfade.mp4这里offset4.0是脚本自动计算出来的。如果 clip1 的时长不是 5 秒这里会显示实际计算值。看到这段输出后不要急着执行先确认三件事路径是否正确。转场类型是否匹配用户描述。offset 是否大于 0 且小于第一段视频时长。5.2 实际执行生成视频dry-run 确认无误后执行python scripts/make_transition.py --config examples/crossfade.json --run执行过程中会看到 FFmpeg 的日志。如果正常结束命令行最后会显示转场视频已生成: output_crossfade.mp4此时先检查文件是否存在ls -lh output_crossfade.mp4文件大小不能是 0。如果文件非常小很可能是 FFmpeg 阶段失败或者输出为空。5.3 验证输出视频验证不能只看文件存在。建议用 ffprobe 检查输出文件ffprobe -v error -show_entries formatduration,size:streamcodec_name,width,height -of defaultnoprint_wrappers1 output_crossfade.mp4正常情况下能看到duration9.000000 size... codec_nameh264 width640 height360两个 5 秒视频通过 1 秒交叉溶解合成总时长约为 9 秒。如果是 10 秒可能没有真正实现转场而是把两个视频直接拼接了。常见问题里会提到这个判断方法。如果条件允许再用播放器打开输出文件肉眼确认画面过渡是否平滑。颜色测试片段比较适合验证红蓝两个片段交叉溶解时中间会出现红蓝色混合的紫色过渡说明转场生效。6. 常见问题排查从现象倒推根因6.1 SKILL.md 没有被 AI 识别现象是用户触发了转场需求但 AI 不读取 SKILL.md也没有调用脚本。排查顺序确认 Skill 放在 AI 助手要求的目录下。不同的工具可能读取.agents/skills、.claude/skills或.codex/skills。确认文件名严格为SKILL.md大小写不能错。确认 SKILL.md 里的描述足够清晰。如果“适用场景”太模糊AI 可能不会匹配。确认工具是否开启了 Skill 权限。有些 CLI 工具有自动批准或手动确认的权限模型。可以先做一个最小 hello-skill 测试。如果最小用例能跑通问题往往出在描述文本或路径上。6.2 FFmpeg 报 No such filter执行命令后出现No such filter: xfade原因是 FFmpeg 版本太旧。xfade滤镜在 FFmpeg 4.3 之后才提供。你的机器上可能使用系统软件源安装的旧版本。处理方式ffmpeg -version查看版本号。如果版本过低需要更新 FFmpeg 或下载新版静态构建包。如果无法更新最简单的方式是换用fade滤镜实现简单的淡入淡出但两段视频拼接的逻辑会变复杂建议优先升级 FFmpeg。6.3 输出视频总时长等于两个片段时长之和如果 output 总时长是 10 秒而不是约 9 秒通常说明xfade没有真正生效或者命令被 Fallback 成了 concat。检查点命令中是否包含-filter_complex和xfade字样。是否能看到转场过程。颜色片段中是否有混合色。如果 AI 工具没有调用脚本而是自己拼了命令可以用 dry-run 输出的命令手动执行对比。这个问题的根源是 AI 绕过了 Skill 脚本。遇到时不要继续调整 FFmpeg先回到“有没有走 Skill 脚本”这条路径排查。6.4 JSON 解析失败或 offset 报错现象是脚本执行后报ValueError: 不支持的转场类型: crossfade或ValueError: 无法自动计算 offset请在配置中提供 offset前者通常说明输入配置里写了不支持的类型检查TRANSITIONS字典和 JSON 拼写。后者说明 ffprobe 无法读取第一段视频时长可能输入文件路径错误、文件损坏或 ffprobe 未安装。先手动运行ffprobe -v error -show_entries formatduration -of defaultnoprint_wrappers1:nokey1 clip1.mp4如果没有任何输出且返回值非 0说明文件读不了换一下输入视频或在 config 中手写offset绕过自动计算。6.5 输出画面花屏或绿屏可能是像素格式问题。FFmpeg 某些滤镜链输出可能是 yuv420p也可能是其他格式。脚本里已经加了-pix_fmt yuv420p但如果手动执行命令时漏掉播放兼容性会变差。另外输入视频尺寸不一致时也容易出现异常。建议先把输入视频统一为相同分辨率再合成。7. 最佳实践与扩展方向7.1 编写 Skill 时的可复用清单不要只把上面的例子复制到项目里就结束建议按这份清单检查是否有独立的 SKILL.md且文件名为全大写。描述里是否说明了适用场景和禁用场景。是否有明确的参数表包含默认值。是否区分 dry-run 和实际执行。是否有示例配置方便 AI 复制。脚本是否使用参数列表调用子进程而不是拼 shell 字符串。输入输出路径是否做了校验。是否检查了错误码并给出人可读的提示。是否有针对输出文件的长度或内容验证方法。这份清单可以复用到图片合成、音频处理、字幕生成等类似 Skill 开发中。Skill 越规范AI 越不容易误用。7.2 生产环境使用建议在本地试验可以直接运行脚本但进入生产或半自动流程时要注意加入日志记录输入配置、生成的命令、执行结果、耗时和错误信息。加入并发控制FFmpeg 是大资源任务多个任务同时执行会抢占 CPU。对视频大小和时长做限制防止输出巨大文件。输出文件不要覆盖原片建议写入独立输出目录并带时间戳。对 AI 调用设置权限边界不要让模型随意执行任意命令。脚本内部只暴露白名单参数不要透传成 shell。如果要在服务器上提供接口供前端调用建议把 Skill 脚本封装成 REST API而不是让前端直接触发命令行。这样既能做参数校验也能统一记录操作日志。7.3 扩展更多转场、批量处理和其他 Agent 平台当前脚本只支持xfade滤镜的几种转场。实际可扩展方向包括增加xfade支持的其他转场名比如fadewhite、slideup、smoothup、dissolve。增加对单视频内部镜头的zoompan推进效果适合 vlog 节奏感。增加批量处理遍历一个目录下所有片段两两拼接。增加音频交叉淡化使用acrossfade滤镜。把 Skill 迁移到支持相似机制的其他 AI 平台只需保留脚本调整 SKILL.md 的约定格式。对于刚入门的读者建议先不做太多转场类型而是把“配置 - dry-run - 执行 - 验证”这条链路跑熟。视频处理最容易出现的问题不是滤镜不会写而是参数上下文没有对齐时长、分辨率、帧率、像素格式都可能影响最终结果。把 Skill 当成一个受约束的工程组件来对待AI 生成视频转场特效这条路就能走得更稳。