1. 先想一个问题：Agent为什么练不出“看视频”这门手艺
开门见山，聊个很多搞Agent的朋友都会卡住的场景。
我在做一个会议纪要Agent的时候，用户提了一个需求：能不能直接把发布会录像丢进来，把画面里出现的PPT重点、演示操作、实物展示一并总结出来？
当时我第一反应是：这有什么难的，把音轨抽出来转文字，整段丢给大模型，三分钟出纪要。结果一跑就露馅了。PPT上的关键数据在口播里根本不会完整念出来，产品实物展示的细节、画面中的操作步骤、字幕里一闪而过的型号参数，全丢了。转录文本做得再好，视频里大约三分之一到一半的信息量是纯视觉的，文字根本承载不了。
这不是工具链的缺失，而是Agent能力边界的问题。过去两年，Agent能读文本、能看图、能听音频，但视频一直是个僵局。因为视频本质上不是一种“数据”，而是一个“时序容器”：它同时包含画面流、音频流、字幕轨道、时间轴信息，四个维度叠加在一起才构成完整的语义。直接把视频“喂”给模型，既不是现有多模态模型的输入格式，也没有哪个Agent通道愿意背动辄几百MB的载荷。所以多数团队的解决方案是放弃，手动让人去扒信息，或者只做音频转写——都在将就。
claude-video这个Skill，就是冲着这个僵局来的。它让运行在Claude生态里的Agent具备了一条完整的视频处理管线：能拆流、能抽帧、能转写、能对齐时间轴，最后把这些素材组装成多模态大模型能消费的“结构化视频摘要”。说人话就是：你的Agent从此能像一个人一样，把一段视频“看”一遍，而不是只能“听”一遍。
这篇文章会把这套东西从头到尾拆开，包括Skill本身的机制、管线设计、部署步骤，以及我在实际测试里踩过的坑和调优经验。后面会花不少篇幅在“为什么要这么做”上，因为只照着抄步骤，换个视频你就不会玩了。
如果你正在做Agent开发，或者被“视频理解”这个问题卡过，这篇文章应该能帮你省下几天的调研时间。
2. Skill不是插件也不是函数，Claude生态里它有自己的生态位
先把Skill这个概念说清楚。最近“Skill”在Agent圈子里热度很高，搜一下能看到一堆相关词：Codex Skill、WorkBuddy Skill、Spring AI Skill、AI Agent Skill……但不少人还是分不清Skill和Agent的区别，甚至有人以为Skill就是一段提示词模板。这个误解会让后面所有操作都变拧巴。
我的理解是：Agent是决策者，Skill是执行者。Agent负责理解用户的意图、拆解任务、决定下一步要调用什么工具或技能；Skill则是一套封装好的“能力单元”，它告诉Agent“在什么场景下、用什么样的步骤、调用哪些脚本或资源，来把某一类任务干完”。
以Claude生态为例，Skill落地为一个SKILL.md文件加配套资源目录。SKILL.md用自然语言描述这个Skill的触发场景、工作流程、输出格式、注意事项，里面也可以引用同目录下的脚本、模板、参考文档。当Agent在对话里判断当前任务命中某个Skill的描述时，它就会读取这个文件，按里面的指令一步步执行。
这里有个关键点：Skill不是把现成的答案硬编码进去，而是给Agent一套“做事情的SOP”。Agent仍然负责过程中所有的分析和判断，Skill只负责提供领域知识、操作步骤和工具接口。这个设计比单纯堆提示词要优雅得多——提示词长到一定程度就会互相污染，而Skill按场景天然隔离，Agent按需加载，不用的能力不占用上下文。
claude-video就是按照这个规范做出来的一个Skill。它不是一个能直接“看懂视频”的模型，而是一套能指挥Agent完成视频理解的流程和工具集。你把视频路径交给Agent，Agent看到当前任务命中claude-video的描述，就会按Skill里的管线去处理：先混流拆解，再抽帧和转写，最后把视觉素材与文字素材按时间轴合并，生成结构化的视频分析结果。
之所以强调这个区别，是因为实际使用中经常有人困惑：为什么装了Skill，Agent还是直接说“我无法处理视频”？多半是因为视频没有落到Skill能访问的本地路径，或者Agent没有把当前任务与这个Skill匹配起来。先用Agent的思维去理解Skill，而不是把它当魔法，这类问题就能少一半。
3. 视频处理管线的三个关键动作：拆流、抽帧、转写
claude-video的核心，是把“看视频”这个大问题拆成三个小动作，然后再把结果组装起来。搞清楚这三个动作为什么这么设计，你才能理解后面所有的配置项。
先说拆流。一个MP4文件在容器层面同时封装了视频轨道和音频轨道。Skill的第一步通常是用FFmpeg把这两条轨道剥离开，视频轨道用于后续抽帧，音频轨道送去转写。这一步很多人觉得没必要，直接喂音频转写不就行了？没必要的前提是你不在乎画面信息。但只要是产品演示、教学录屏、发布会的场景，画面里的信息量占比通常超乎你的想象。
然后是抽帧。为什么非要抽帧而不是把整个视频流喂给视觉模型？两个原因：一是上下文窗口装不下，一个小时的视频按30fps算有十万多帧，没有哪个模型能一口吞；二是连续帧之间的信息冗余度极高，相邻几帧的画面差异微乎其微，全量处理纯粹浪费计算资源。所以Skill会根据你设定的抽帧间隔（比如每秒一帧、每五秒一帧），从视频轨道里均匀采样出关键帧，再把这些帧压缩到合适的尺寸，批量交给多模态模型做画面分析。
这里有一个很常见的设计分歧：抽帧是均匀采样还是智能选帧？均匀采样实现简单，但对静态画面多的视频会浪费额度；智能选帧（检测场景切换再抽关键帧）效果好，但实现复杂度高。claude-video在默认配置里用的还是均匀采样，把间隔参数开放出来让使用者按视频类型调整——会议视频间隔可以拉大，动作演示类视频需要缩小区间。够用优先，稳定优先，这个取舍很务实。
最后是转写。音频轨道交给ASR模型转成带时间戳的文字稿。这一步的产物在后面的时序分析里非常关键：文字稿不只是拿来读的，而是用来和抽帧结果“对齐”的。一段画面里的PPT翻页、操作演示、界面跳转，如果能在时间轴上找到对应的口播内容，整个视频的逻辑就能像看书一样一页一页还原出来。
这三步做完，Skill手上就有了三批素材：一批关键帧画面、一份带时间戳的文本转写、一个时间轴。接下来才是真正的重头戏——把这些素材组装成多模态大模型能下咽的结构化输入。
4. 组装与消费：让多模态模型真正“看懂”视频的输入模式
素材有了，不代表Agent就能直接看懂了。怎么把画面和文字这些异构素材组织成上下文，直接决定了输出质量。
claude-video的做法，我总结下来是一个三步组装策略。
第一步，把关键帧批量压成“剧情卡片”。每张卡片包含帧编号、时间戳、画面里提取到的核心信息（比如屏幕上的大字、人物动作、界面状态）。这一步通常由视觉模型逐帧或小批次分析完成，输出的不是“这张图里有个人”这种废话，而是能传递信息量的结构化描述。
第二步，把转写文本按时间段切块，与相邻的关键帧描述配对。比如第2分钟到第3分钟的文字内容，和这个时间段内抽到的帧描述放在同一个上下文块里。这样视觉信息和语言信息在时间上形成一一对应的关系，模型读起来就像在看一段带有旁白的连环画，而不是两张互不相干的名单。
第三步，把整条时间轴的故事线交给主模型，让它以“视频分析师”的身份产出最终结论。它可以看到完整的时间线、每个阶段的关键画面描述、对应的文字稿，然后在一次长上下文推理里完成综述、提炼、答疑。这个阶段最重要的产出一是分段摘要，二是全局结论，三是按用户指令定制的细节提取。
之所以这么费劲地组装，是因为直接抽帧然后让模型“看图写话”、或者只拿文本转写做分析，都会丢失关键维度。只有把视觉与文本在时间线上对齐，模型才能理解“在什么画面下说了什么话”这种视频独有的表达方式。
这一步也解释了为什么claude-video这类Skill要用Agent来跑，而不是写个一次性脚本。因为Agent可以在组装后主动跟用户确认需求：你是要一分钟速览，还是要完整的逐帧讲解？你是只关心产品参数的表述，还是想看操作流程的细节？这种交互式分析的能力，是固定脚本给不了的。
我在实际测试里发现，组装顺序对结果的影响非常大。如果把所有画面描述堆在前面、所有文字稿堆在后面，模型会明显更偏向后期文字内容，前期的画面细节容易被忽略。把时间相近的画面和文字放在同一个上下文块里，输出质量立刻上了一个档次。这也是为什么Skill文档会把组装格式写成强约束而不是给个可选建议——格式就是能力的一部分。
5. 实操部署：把claude-video装进你自己的Agent环境
理论聊完，上实操。以Claude Code环境为例，一次完整的部署大概需要下面几个步骤。我尽量把每个操作背后的原因也交代清楚，方便你做判断。
第一步，确认环境基础。claude-video依赖FFmpeg做音视频拆流，需要确保本机已安装。macOS上可以用brew install ffmpeg，Linux用apt或对应包管理器。装完执行ffmpeg -version确认。这一步卡住的话后面都不用谈，Skill脚本本身不会帮你装系统依赖，它不是安装器，只是执行SOP。
第二步，把Skill放进Claude的skills目录。按Claude生态的约定，自定义Skill放在~/.claude/skills/ /目录下，里面至少要有一个SKILL.md文件。我把claude-video的目录结构列一下：
~/.claude/skills/claude-video/ ├── SKILL.md ├── scripts/ │ ├── extract_frames.py │ ├── transcribe_audio.py │ └── assemble_context.py └── resources/ ├── frame_prompt.md └── output_template.mdSKILL.md是Agent真正读取的总索引，scripts目录里放的是被SKILL.md调用的Python脚本，resources里放的是各个阶段的提示词模板和输出格式模板。之所以拆这么细，是为了让Agent在执行时能按需读取——它不用一次性把这些文件全部载入上下文，而是读SKILL.md，知道“第一步要用哪个脚本、第二步要读哪个模板”，做到哪里读到哪，省上下文。
第三步，核对SKILL.md里的环境变量和路径配置。视频文件路径建议用绝对路径，相对路径在Agent的工作目录漂移时容易踩坑。输出目录也提前建好，脚本默认不会自动递归创建目录这个坑我踩过一次，后面会细说。
第四步，启动Claude Code，用自己的话发起任务。比如：“帮我看一下/tmp/demo.mp4这个视频，我要一份5分钟的产品演示摘要。”Agent识别到视频文件路径后，会去skills目录里检索匹配的Skill，如果claude-video的描述与任务吻合，它就会开始按SKILL.md的流程执行。
第五步，观察执行日志，确认管线各环节是否跑通。正常的执行序列是：拆流、抽帧、音频转写、画面描述、时间轴组装、最终分析。哪一步卡住，日志里一般会给出脚本的具体报错。
整个部署过程，说实话不复杂。真正考验人的是后面那些“看起来能用但实际不好用”的细节——这些放在下一节展开。
6. 实测记录：三段视频从翻车到稳定的完整过程
理论说得再好看，不拿真视频跑一遍都是空的。我在自己的机器上做了三轮测试，前两轮都翻车了，但也正因为翻了车，才把Skill的各个参数到底影响什么摸清楚了。
第一轮测试用的是一个人工智能发布会录像，时长约45分钟，画面里有大量PPT和大屏演示。我第一次跑用的是默认参数，抽帧间隔设的每秒一帧，音频转写用默认解析器。结果呢，抽出了两千多张帧，上下文开销巨大，多模态分析阶段直接把额度打爆了，最终输出的摘要极其泛泛，几乎没有提到PPT上的具体数据。
这一轮暴露的问题很典型：抽帧不是越密越好，而是要根据内容密度来调。发布会这种画面信息变化不频繁的场景，每5秒甚至每10秒抽一帧完全够用。我后来把抽帧间隔调到5秒，帧数量降到原来的五分之一，再配合按时间段分批做画面描述，输出质量立刻上来了，PPT上的几个关键数据也被正确提取了出来。
第二轮测试换成了双人访谈类视频，时长30分钟，画面几乎不变，主要是两个人对话。我原本以为这种视频极端好处理，因为信息全在语音里，画面描述可有可无。但实际跑下来发现了一个时序对齐的坑：ASR转写出来的文字稿有延迟匹配问题，人物说到某个话题的时候，对应的画面其实还停留在上一段的PPT上。如果机械地把“帧描述+该时间段文字”绑在一起，模型就会以为演讲者在聊画面里的内容，造成事实性错乱。
解决办法是在组装阶段引入一个容错机制：让时间相近但不必严格一致的帧描述和文本块配对，同时把帧描述里的时间戳和文本块的起止时间都保留下来，让模型自己判断“眼”和“耳”到底谁先谁后。这个方式有效地缓解了延迟问题，也让我意识到，视频理解不光是技术栈的问题，还涉及信息融合的策略。
第三轮测试是纯画面视频，一段没有配音、没有字幕的Vlog，靠画面和背景音乐叙事。这种视频对Skill来说是最难的，因为音频转写几乎产不出有效文本，整个分析任务全部压在视觉通道上。跑下来之后，我发现关键帧描述的质量直接决定最终输出。之前用的Frame Prompt比较笼统，生成的描述大多是“画面中出现一台笔记本电脑和一杯咖啡”这类表面信息。后来把Frame Prompt改成了分层描述结构——先描述主体元素，再描述界面/文字/操作细节，再描述画面氛围与镜头变化。经过这个调整，纯画面视频也能产出相当可读的场景叙事了。
三轮测试跑完，我对这个Skill的适用边界有了清晰的判断：它最擅长的是有人声讲解、有画面变化的教学/发布/录屏类视频；其次是有人声的访谈；最薄弱的是无声纯视觉叙事。所以我现在用它的策略也很明确，拿它处理“有讲解的镜头内容”是效率最高的场景，纯画面类需求得配合更细致的提示词工程才行。
7. 避坑清单：那些文档里不会写、但一定会踩的问题
部署和测试过程中攒了不少经验，专门列一个踩坑清单，都是我在实际运行中遇到过的，按影响程度排序。
第一个坑，也是最大的坑：临时文件不收拾。视频处理管线跑下来会生成大量中间文件，抽帧图片、音频轨道临时文件、ASR中间结果，加起来很容易占掉几个GB。如果输出目录规划得不好，放在/tmp下，系统一清理就没了，想排查问题都没法查。我的习惯是建一个单独的工作目录，按视频名建子目录，跑完清理中间产物，只保留最终结果和日志。这个习惯在批量处理视频时尤其重要。
第二个坑：FFmpeg版本过低导致的兼容性问题。有些老版本FFmpeg对特定编码格式（比如某些手机直出的HEVC视频）支持不完整，会出现抽帧失败或者音轨提取为空但毫无报错信息的诡异情况。所以不光是确认安装了FFmpeg，还建议确认版本不要过于老旧。我遇到过音轨提取空了但主流程还在继续跑的情况，要不是对比了输出文件大小根本发现不了。
第三个坑：ASR模型的选型和语种匹配。Skill的音频转写默认接的语音识别引擎，对英语支持通常比较好，中文识别速度、准确率和口音适应性会有差异。如果你处理的视频主要是中文，建议在Skill配置里显式指定语言模型和热词列表，尤其是产品名、人名这些专有名词，热词能极大提升识别准确度。没有这一步，后面所有的文本分析都是在垃圾进垃圾出。
第四个坑：上下文长度和费用管理。视频处理涉及长上下文，输出质量虽然上去，成本和延迟也会同步上升。如果只是自己小范围用，建议在SKILL.md里约束输出格式：默认只产出分段摘要和结论，不产出逐帧详细描述；只有在用户明确要求时才输出精细分析。这个约束文档里写清楚，Agent执行时会严格遵守，能帮你省下不少token。
第五个坑：多视频批量处理时的并发问题。抽帧和转写都是计算密集操作，如果同一时间把多个视频塞给Agent并行处理，很容易把CPU打满或者触发API限流。我在实测中就遇到过一次同时处理三个视频时，ASR服务返回的大量超时错误。现在我的策略是一次只让Agent处理一个视频，或者明确指定一个队列顺序，宁可慢一点也不要中途崩。
8. 从claude-video延伸出去：一套你自己的Agent视频能力模板
如果你能完整跑通claude-video，接下来自然会有个想法：我想让Agent处理其他格式、其他场景，怎么改？
这类自定义Skill的开发，我总结出的套路是四步。
第一步，确定能力边界。先想清楚这个Skill到底解决哪一类任务的哪一段流程。不是“让Agent更聪明”这种目标，而是“让Agent能把一个20分钟内的产品发布会视频，输出为按产品模块组织的要点清单”这种具体到可检验的边界。
第二步，设计SOP。把你希望Agent执行的流程拆成3到5个步骤，每个步骤尽量有独立的输入输出。写得好的SKILL.md，是Agent照着做就能稳定产出结果的“操作手册”，不是讲道理的文章。要写清楚“如果……那么……”的判断分支，比如音频转写结果为空时应该怎么办。
第三步，沉淀模板。每个领域都有自己的好提示词。把每次测试里效果最好的提示词固化到resources目录里，形成模板。我自己的体会是，模板的质量决定了Skill的上限，因为Agent的自由发挥在不确定的任务里差距非常大，有模板兜底，输出基本就能稳定在可用水平。
第四步，反复用真实材料做回归。Skill的迭代不是靠改提示词，而是靠建立你自己的测试集。找三五段典型的视频，每次改动后都跑一遍，看输出有没有劣化。这个习惯在Agent开发里尤其重要，因为同样的Skill在不同版本的主模型上表现可能有波动，没有回归测试就没法放心往上叠新功能。
按这个思路，其实热点讨论的Skill生态里那些更宽的东西，比如Spring AI Skill、Codex Skill，本质上都是一样逻辑：把领域知识沉淀成Agent可读的SOP，把能力拆成可按需加载的单元。claude-video只是把这个逻辑用在了视频理解上而已。
就拿我的个人体验举个例子：我在公司内部做完会议纪要Agent之后，发现同样的Skill模板稍微改一下，就可以处理录屏软件的教学流程整理、供应链视频质检报告的摘要生成，甚至可以把视频逐段拆开做一个可以直接检索的视频知识库。核心管线没换，换的只是提示词和输出模板。这说明这类方案的可复用性相当强，学会一个，基本上就学会了一整类。
最后再分享一个我的真实使用体会：不要把视频理解交给Agent以后就完全放手。视频是语义密度极高的信息载体，Agent给出的摘要里偶尔会出现编造细节的幻觉，尤其是画面中一闪而过的小字、背景音里的关键数字。所以我现在的工作流，仍然是Agent产出初稿，人工做一轮关键信息核对，然后再进入正式交付。工具用了，但人没有完全退场，这一点在视频这种高密度信息场景里尤其要守住。
如果你也正在给Agent加“眼睛”，希望claude-video这条路线能给你一个相对低成本的起点。跑通一个Skill并不难，难的是把管线、模板、验收标准都打磨成你自己团队能稳定复用的东西。但一旦这层做扎实了，你会发现，Agent的能力边界又往前拱了一大块。
 超时排查与修复)
