Agent开发做到一定程度，都会遇到同一个坎：你的Agent什么都能聊，却连一段视频都“看”不懂。文本、代码、JSON它可以处理得飞快，但你丢给它一个MP4，它就卡住了。这不是模型不够聪明，而是Agent天生没有视觉通道。claude-video这个Skill就是在这个背景下出现的——它的核心目标一句话就能说清：让Agent拥有看视频的能力，能抽帧、能读音频、能理解画面内容，然后基于视频内容完成总结、问答、检索和结构化输出。

这篇文章我会从Agent为什么需要“看视频”说起，把Skill的定位、安装接入过程、底层实现原理、真实场景实测，再到如何自己动手写一个视频Skill完整过一遍。不管你是刚入门的AI应用开发者，还是在做Agent平台、做内容工具、做自动化的朋友，这篇应该都能给你一些能直接落地的经验。

1. Agent的感官短板：为什么“能读”不等于“会看”

1.1 文本Agent的边界在哪里

先聊一个基础问题：现在市面上主流的Agent，本质上是“文本交互+工具调用”的产物。它们能读懂你的提示词，能调用搜索引擎、能操作数据库、能写代码，但这一切都建立在“信息已经被转成文本”的前提上。

遇到视频，这个前提就塌了。视频是一个多模态复合体——画面是图像序列、声音是音频流、剧情或讲解内容要靠时间轴把两者对齐。Agent如果只能处理文本，它就相当于一个只能靠文字描述来“脑补”内容的读者，视频里的很多关键信息它根本获取不到。

我见过不少团队在Agent项目里硬编码视频处理逻辑，比如直接调某个第三方API传视频。这样做不是不行，但每个视频都要等整个文件上传、转码、返回结果，流程冗长、费时费钱，而且API返回的结果往往只是“一段摘要”，没法支持后续的追问和多轮交互。真正的痛点在于：Agent缺少一套把视频“翻译”成自己可理解内容的中间能力，而这个能力放在Agent自己的Skill体系里，才是最自然、最可扩展的解法。

1.2 视频理解的四个真难点

视频理解不是一个单一任务，它至少包含四个层面的问题，哪一个没处理好，最终结果都会变味。

第一是画面信息获取。视频一秒钟有24到30帧，不可能全送进模型，需要抽帧。但抽帧抽多少、隔几秒抽、按什么策略抽，直接影响理解质量。按固定间隔抽可能漏掉关键画面，按场景切换抽又需要额外的检测算法，这里面的取舍很考验经验。

第二是音频信息获取。对话、旁白、背景音乐里的信息，画面里根本没有，要单独提取并转写成文字。转写的准确性、说话人区分、专有名词的识别，都是容易出现问题的环节。

第三是时间对齐。抽出来的帧和转写出来的文字，必须对应到同一时间轴，否则Agent会张冠李戴——明明第3秒说的话，配上了第80秒的画面，整个理解就全乱了。

第四是上下文整合。一个10分钟的视频可能产生几百张帧和上万字转写，怎么在有限的上下文窗口里总结出有价值的信息，本身就是个工程问题。直接把所有内容塞给模型，大多数模型会直接报上下文超限。

claude-video把这些问题打包处理，作为一个可复用的Skill提供给Agent调用。Agent不用每次纠结“我该抽几帧、怎么转写、怎么对齐”，调一个技能，就能拿到结构化结果。

1.3 claude-video在能力矩阵里的位置

如果给Agent的能力画一张能力矩阵，大多数Agent天生具备的是“读文本”和“调工具”，claude-video补上的是“看视频”这一格。它不替代多模态模型，而是把视频处理成多模态模型能消化的输入；它也不替代向量数据库，而是提供“看完之后”的结构化结果。

我习惯把这类Skill叫“感知型Skill”，它们做的是把物理世界的复杂信号转成Agent能理解的结构化信息。和“搜索型Skill”“代码执行型Skill”不一样，感知型Skill有一个明显特征：转换过程不可逆——视频一旦被压缩成抽帧和转写，原始信息就损失了一部分。所以好的感知型Skill必须在转换时尽可能保留关键信息，这也是claude-video设计时最花心思的地方。

2. Skill到底是什么：Agent能力扩展的关键机制

2.1 Skill、工具、工作流三者的区别

很多刚接触Agent开发的人会混淆Skill和工具。我打个比方：工具是“锤子”，Skill是“会使用锤子的老师傅”。

工具是一个单一功能点，比如“运行一段Python代码”“发一个HTTP请求”。Skill则是一整套完成某个任务的流程，它告诉Agent“遇到视频类任务时，应该按什么步骤处理、调用哪些工具、每一步的参数怎么定”。同一个工具可以被不同Skill复用，而一个Skill内部往往串联了多个工具调用。

工作流则是更偏“固定流程”的东西。工作流是提前把步骤写死的流水线，Agent没有太多决策空间；Skill是给Agent一套“操作说明和可选动作”，由Agent自己根据任务动态决定怎么组合。对于“看视频”这种输入形态非常多样、任务目标五花八门的场景，Skill的灵活性远高于固定工作流。

2.2 Skill的核心组成与运行机制

现在主流的Skill规范，核心是一个目录，里面通常包含四类内容。

SKILL.md是给Agent读的说明文件，包含技能名称、能力描述、使用场景、参数定义、注意事项。脚本文件是实际执行逻辑的入口，抽帧、转写、分析都可能在这里完成，常见语言是Python或Bash。另外还有辅助资源，比如提示词模板、依赖清单、默认配置文件，以及测试用例。

Agent在运行时会先读SKILL.md，判断当前任务是否匹配这个技能。匹配了，就按说明调用脚本、传入参数、接收输出，再结合输出内容继续推理。这套机制有点像给Agent发了一本“使用手册”，Agent翻到对应章节，照着手册干活。

2.3 为什么“看视频”特别适合做成Skill

视频处理任务最大的特点是没有标准答案。用户说“帮我总结一下这个视频”，和用户说“找出视频里第三个出现的人”是完全不同的任务，但在同一个视频上。如果做成固定工具，你得为每种需求写一个接口。做成Skill，Agent可以基于同样的底层处理结果，针对不同指令做不同的推理延伸。

所以claude-video把视频处理拆成了“基础处理”和“智能分析”两层：基础处理负责抽帧、转写、对齐，这部分是确定性的工程逻辑；智能分析完全交给Agent在拿到基础数据后自主完成，这部分是灵活的模型推理。这个分层设计很聪明，既保证了底层处理的稳定性，又保留了上层分析的灵活性，是我认为这类Skill最值得参考的架构思路。

3. 从零跑通：claude-video 安装与接入实录

3.1 环境准备清单

在开始之前，先确认几件事。claude-video依赖ffmpeg来抽帧、抽取音频，所以机器上必须装好ffmpeg。检查方法是终端里执行：

ffmpeg -version

如果没有输出，根据你的系统安装。macOS可以直接用Homebrew执行“brew install ffmpeg”，Ubuntu/Debian用“apt install ffmpeg”，Windows建议用包管理器或直接下载编译好的二进制。另外，如果Skill里的音频转写用的是whisper类方案，还要确认本地有可用的whisper环境，或者能调用在线的转写服务。

再说一下Python版本。Skill里如果附带了Python脚本，建议用Python 3.10以上，因为有些依赖包对旧版本支持不好。我的建议是直接用虚拟环境装，避免污染全局环境，尤其是你机器上已经有多个Python项目的时候。

3.2 获取Skill并安装

以常见的Claude Agent项目为例，Skill的安装路径一般是两个位置：全局目录和项目目录。全局目录通常对应所有Agent会话，项目目录只对当前项目生效。

安装步骤不复杂，核心是把skill目录放到正确位置。比如在终端里把claude-video的目录复制到Agent的skills目录下：

# 假设你的Agent配置目录在 ~/.claude
mkdir -p ~/.claude/skills
cp -r claude-video ~/.claude/skills/

如果你用的是项目级配置，则复制到项目目录下的“.claude/skills/”里。放好后重启Agent会话，让Skill被重新扫描加载。这一步经常有人漏掉，结果放完Skill发现Agent没反应，其实只是没重启。

3.3 Skill注册与触发

加载成功后，Agent会在遇到视频相关任务时自动匹配这个Skill。触发词通常包括“视频”“mp4”“总结这个片子”“这个视频讲了什么”等，具体要看SKILL.md里写的description和trigger条件。

我实测下来的经验是：显式触发比隐式触发更可靠。比如直接说“用claude-video分析一下demo.mp4”，比只说“看看这个视频”更容易让Agent准确调用Skill。因为这本质上是一个意图识别问题，明确提到技能名，Agent几乎不会判断错。

另外要注意，视频文件路径必须让Agent能访问到。如果视频在本地，建议用绝对路径；如果视频在远端，先下载到本地或使用可访问的HTTP地址。经常有人卡在这一步，视频路径写错了，Agent去读文件读到一半报错。

4. 视频到底是怎么被“看”懂的：核心原理拆解

4.1 前置处理：从MP4到可读素材

视频想被模型理解，第一步必须转成模型能接受的输入。当前主流的做法是两种素材：画面帧和音频转写文本。

画面帧用ffmpeg抽。最基本的命令是按固定间隔抽帧：

ffmpeg -i input.mp4 -vf "fps=1/5" -q:v 2 frame_%04d.jpg

这个命令的意思是每5秒抽一帧并保存为jpg。间隔越短，帧数越多，信息越全，但后续处理压力越大。进阶玩法是根据场景切换抽帧，先跑场景检测，在每个镜头变化点抽帧，能显著减少重复帧。

音频转写一般用whisper类的模型完成。把视频里的音轨提取出来，然后转成带时间戳的文本。命令大致是：

ffmpeg -i input.mp4 -vn audio.wav
whisper audio.wav --output_format json --output_dir ./transcript

转写结果会包含每句话的起止时间，这部分时间戳是后续对齐的关键依据。

4.2 多模态模型如何理解画面

抽出来的帧只是一堆图片，要成为Agent能推理的信息，还需要多模态模型“看”一遍。当前主流的多模态模型会把图片切成若干视觉token，和文本token一起送入Transformer结构计算。模型能识别出画面里有什么物体、什么人物、什么文字、什么场景，并把这些视觉信息转成语言描述。

这里有一个容易被忽略的问题：单帧图像的信息密度远低于一段视频。一帧只能看到某一个瞬间，如果关键动作发生在两帧之间，或者视频里大量信息依赖前后连续画面，只靠单帧是理解不了的。所以部分实现会采用“多帧并排”方案，把同一时间段的几帧拼成一张图送给模型，让模型同时看到前后文关系。

4.3 时间轴组织与上下文拼接

抽帧有了，转写也有了，接下来最关键的一步是让Agent在回答时知道“哪段画面对应哪段声音”。这靠的是时间轴。

实现上通常是把帧按时间编号，把转写文本按时间戳分段，然后交错组织成一种“时间线”格式。比如第0秒画面文字描述后面跟着第0秒的对话内容，接下来是第5秒的画面描述和对话内容。这样模型读到的是一串按时间排序的多模态信息流，就能回答“第几分钟发生了什么”这类问题。

上下文管理也需要控制。一个60分钟的视频全部按抽帧转写组织起来，内容量可能超过模型上下文窗口。常用的策略是分段摘要：先把视频按每5分钟切成一段，分别生成小摘要，再让小摘要汇总成完整摘要。这属于经典的分治思路，实测效果比一口气看完要好得多。

5. 真实场景实测：拿三段视频跑一遍

5.1 场景一：产品发布会视频，10分钟内容摘要

我拿了一个10分钟的产品发布会视频做测试。视频里有演讲者、PPT画面、演示操作，信息来源混杂。用claude-video跑完之后，Agent给出的摘要不仅包含了发布的新品名称和核心特性，还把演示过程中出现的具体参数（续航数字、价格区间）从PPT画面上准确识别出来了。

这个场景里最亮眼的点是画面和语音的信息互补。演讲者口头没提到的一个价格数字，在PPT上以表格形式出现了不到3秒，但抽帧刚好抓到了那一帧。这说明抽帧间隔的选择很关键，10分钟视频我用的是每3秒抽一帧，一共抽了200帧，没有漏掉关键画面。如果间隔太长，这种一闪而过的信息大概率就丢了。

5.2 场景二：教程视频，提取操作步骤

第二个测试是一段Unity操作教程，大概15分钟，全程有屏幕录制和旁白。我让Agent帮我提取完整的操作步骤清单。结果Agent输出了一份带步骤编号的清单，每一步都标注了出现在视频的哪个时间点，后续如果想回看，可以直接跳到对应时间点。

这个场景的难点在于操作的准确性。有些操作是鼠标点击、有些是快捷键、有些是菜单选择，旁白经常与画面不同步。实测下来，音画结合的方式比较稳：Agent会先看帧画面里的鼠标位置和菜单状态，再读一段旁白，两个信息互相验证，比单纯看画面或单纯听旁白都准确。

5.3 场景三：长访谈视频，按人名检索观点

第三个场景我用了一段40分钟的多人访谈，任务是找出某位嘉宾针对“开源许可证”问题说过的所有观点。这个任务的难点有两个：一是嘉宾有多人，需要分辨谁说了什么；二是观点分散在视频不同时间段。

claude-video处理的方式是先把转写文本按说话人分段（社区里有专门的说话人分离工具），然后Agent再基于带说话人标签的转写结论进行检索。最终输出时，每一条观点后面都列出了视频时间戳。这里有个实战教训：说话人分离模型的准确率不是100%，人名标签偶尔会出错，所以回答里我建议Agent注明“根据说话人识别结果”，避免把错误归因当成事实。

5.4 实测参数与效果对照

我整理了三次实测的关键参数和效果，供你参考：

视频类型	时长	抽帧间隔	转写模型	摘要效果
发布会	10分钟	3秒	本地whisper base	关键参数全部捕获
教程录屏	15分钟	2秒	本地whisper small	步骤提取完整，含时间戳
多人访谈	40分钟	5秒	在线转写服务	观点定位准确，说话人偶有误差

抽帧间隔不是越短越好，要根据视频类型调整。信息密度高的屏幕录制建议2到3秒一帧，信息密度低的人物访谈5秒一帧也够，这样做能明显降低后续处理成本。

6. 自己动手写一个视频Skill：从SKILL.md到脚本

6.1 Skill目录规范与命名

如果你看完前面的内容，也想给自己项目的Agent写一个类似的视频Skill，我建议直接从目录规范开始。一个标准的Skill目录长这样：

claude-video/
├── SKILL.md
├── scripts/
│   ├── extract_frames.py
│   ├── transcribe.py
│   └── analyze.py
├── assets/
│   └── prompt_templates/
└── requirements.txt

目录命名建议用短横线分隔的小写单词，避免空格和中文。SKILL.md放最外层，这是Agent第一个读的文件。scripts目录放可执行脚本，assets放辅助资源。

6.2 SKILL.md的写作要点

SKILL.md的核心目标不是给人看，而是给Agent“看”的，所以它的写法跟普通README完全不一样。要写明技能名称、触发条件、输入输出格式、调用步骤、注意事项，语言尽量明确，避免歧义。

我建议的模板大致是这样：

---
name: claude-video
description: 分析本地视频文件，提取关键画面帧和音频转写，支持视频摘要、内容问答、时间点检索。当用户提到视频分析、视频总结时使用。
---

# claude-video

## 能力范围
- 从mp4/mov等视频文件中抽取关键帧
- 从视频中提取音频并转写为带时间戳文本
- 将画面和文本按时间线组织，供多模态模型分析

## 输入要求
- 视频文件路径（本地绝对路径或可访问URL）
- 可选参数：抽帧间隔（秒）

## 调用步骤
1. 用extract_frames.py按间隔抽帧
2. 用transcribe.py转写音频
3. 按时间轴合并结果，输出JSON

## 注意事项
- 视频文件过大时先截取分段处理
- 转写结果需保留原始时间戳

description部分用什么词会直接影响Agent能不能在正确时机触发它，所以一定要把用户可能说的自然语言说法写进去。

6.3 核心脚本设计：抽帧与转写

抽帧脚本用Python配合subprocess调ffmpeg，是最稳妥的方式。核心逻辑不复杂：

import subprocess
import os

def extract_frames(video_path, output_dir, interval=3):
    os.makedirs(output_dir, exist_ok=True)
    cmd = [
        "ffmpeg", "-i", video_path,
        "-vf", f"fps=1/{interval}",
        "-q:v", "2",
        os.path.join(output_dir, "frame_%04d.jpg")
    ]
    subprocess.run(cmd, check=True)

转写脚本可以封装whisper调用，输出带时间戳的JSON。这里有一个我自己踩过坑之后总结的经验：转写结果一定要保留每个segment的start和end字段，不要只留纯文本。后面做时间对齐、按时间点检索全部要靠这些字段，少一个都难受。

6.4 调试技巧与常见坑

自己写Skill，调试比写代码花的时间更多。我的经验是先准备一个20秒左右的短视频作为固定测试素材，每次改完代码都用它跑一遍，验证整体流程没坏，再拿长视频测试效果。

常见坑有三个：一是路径问题，Agent调用脚本时的工作目录可能跟脚本所在目录不一致，建议在脚本开头用“os.path.dirname(os.path.abspath( file ))”定位素材目录；二是临时文件清理，抽出来的帧如果不删，跑几次之后磁盘会被占满，建议脚本结束时自动清理；三是依赖缺失，在requirements.txt里写清楚依赖，并在Skill说明里写上安装命令，否则换台机器就废了。

7. 高频踩坑与排查速查表

7.1 抽帧失败或全是黑帧

抽帧失败最常见的原因是视频编码格式问题。有些视频文件虽然是mp4后缀，但内部用的编码ffmpeg不支持。解决办法是在命令里加“-c:v libx264”强制转码，或者先跑一遍“ffprobe”查看编码格式。

全黑帧一般发生在视频有加密保护、或者部分DRM录屏的场景。如果确认不是视频本身的问题，可以尝试调整抽帧时“-q:v”的压缩质量参数，把画质拉高再试。设置一个黑帧检测函数，把亮度均值低于阈值的帧过滤掉，也是一个必备的兜底方案。

7.2 上下文窗口被撑爆

这是长视频最容易遇到的问题。30分钟的视频抽帧可能产生几百张图片，转写文本也可能几万字，直接全部塞进上下文，大多数模型都会超限。

我建议的处理顺序是：先看视频时长，超过15分钟就强制启用分段摘要；每段生成独立摘要后，再把各段摘要汇总。不要贪心一次处理完整视频，分段处理虽然多跑几轮，但结果稳定性高得多。

7.3 时间戳对不上

画面和声音各说各话，基本是时间戳没对齐。排查方向有两个：一是确认帧文件名里的时间是不是实际播放时间，有的抽帧命令从0开始编号，要换算成真实秒数；二是确认转写文本的时间戳是相对视频开始时间，而不是相对某个片段。

一个简单的校验方法是：随机抽一个时间点，手动跳到视频该位置，看画面对应的转写文本是不是同一句话。如果差几秒，在做时间轴组织时做一次偏移修正即可。

7.4 多轮对话状态丢失

很多Agent框架的多轮对话不会主动保留上一轮视频处理的结果。用户第一轮问了“这个视频讲了什么”，第二轮问“第3分钟那个人是谁”，结果Agent已经把第一轮的帧和转写删了，只能重新处理一遍。

解决办法是在Skill里设计缓存机制：按视频文件的哈希值做缓存目录，处理结果以JSON格式存下来。第二次遇到同一个视频，直接读缓存，处理速度能快一个数量级。

7.5 资源占用过高

抽帧和转写在CPU上跑会很慢，特别大视频可能几分钟到十几分钟。转写阶段有GPU就用GPU，没有GPU就选用small/tiny级别的模型，优先保证响应速度。

另外一个容易忽略的点是磁盘IO。抽帧会产生大量小文件，如果输出目录在机械硬盘上，写入速度会拖慢整个过程。建议把临时目录设在SSD上，跑完再转移到低速存储。

我个人在实际操作中最大的体会是：视频Skill的价值不在于“技术多复杂”，而在于它真正补齐了Agent的感知短板。以前Agent只能处理“别人总结好的”信息，现在它可以自己直接面对一段原始视频，这个转变对很多自动化场景来说是质变。最后再分享一个小组件级别的建议：如果你准备写自己的视频Skill，不要一上来就追求功能全，先把“抽帧+转写+时间轴输出”这一条最小链路跑通，再逐步加分段摘要、说话人分离、关键帧去重这些进阶能力。视频理解是典型的水桶工程，底层链路不稳，上层功能越多越容易翻车。