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完成视频理解的流程和工具集。你把视频路径交给AgentAgent看到当前任务命中claude-video的描述就会按Skill里的管线去处理先混流拆解再抽帧和转写最后把视觉素材与文字素材按时间轴合并生成结构化的视频分析结果。之所以强调这个区别是因为实际使用中经常有人困惑为什么装了SkillAgent还是直接说“我无法处理视频”多半是因为视频没有落到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 ffmpegLinux用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的能力边界又往前拱了一大块。