如何让Claude“看懂“视频：claude-video与Claude Code技能系统的深度集成原理

如何让Claude看懂视频claude-video与Claude Code技能系统的深度集成原理【免费下载链接】claude-videoGive Claude the ability to watch any video. /watch downloads, extracts frames, transcribes, hands it all to Claude.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-videoclaude-video/watch是一款为 Claude Code 赋予看视频能力的技能插件粘贴一个视频链接或本地文件路径它会自动下载视频、抽取关键帧、提取字幕文本最终让 Claude 基于亲眼所见的画面回答你的问题。本文从 Claude Code 技能系统的工作机制出发带你拆解这套集成背后的完整原理无需编程基础也能看懂。先看结果一个命令的完整旅程 整个体验浓缩成一行命令/watch https://youtu.be/xxxxx 这个视频在第30秒发生了什么Claude 收到指令后背后实际发生了一串接力动作这也是理解集成原理的最佳切入点阶段执行者做了什么对应模块① 命令解析Claude Code 框架把/watch识别为斜杠命令并转发参数commands/watch.md② 环境预检预检脚本毫秒级检查依赖是否齐全scripts/setup.py③ 下载视频yt-dlp抓取视频 原生字幕scripts/download.py④ 抽帧ffmpeg按时长自适应速率导出 JPEG 帧scripts/frames.py⑤ 转录字幕/Whisper API优先用免费字幕无字幕时调 Whisperscripts/transcribe.py、scripts/whisper.py⑥ 看图作答Claude 的 Read 工具并行读取所有帧图片 对照字幕作答无Claude 原生能力关键洞察claude-video 本身并不看视频。它只负责把视频拆解成 Claude 能处理的两种形态——图片帧和带时间戳的文字——然后交给 Claude 的多模态 Read 工具完成真正的观看。这正是它作为技能系统的精妙之处。技能系统三要素claude-video 如何用文件教ClaudeClaude Code 技能系统的核心思想是用一组约定好的文件向 AI 描述一项新能力。claude-video 的目录结构恰好是这套思想的教科书式示范claude-video/ ├── SKILL.md # 技能契约告诉 Claude 何时、如何执行 ├── commands/ # 斜杠命令入口/watch 的来源 ├── scripts/ # 6 个 Python 脚本真正的体力活 └── hooks/ # 会话启动钩子环境状态提示1. SKILL.md —— 写给 AI 的操作手册SKILL.md 是整个技能的灵魂。它由两部分组成YAML 元信息frontmatter技能的身份证框架据此加载技能。Markdown 正文写给 Claude 的步骤指南包括何时使用、如何调用脚本、遇到失败怎么办、如何节省 token 等。frontmatter 中的几个字段各司其职见 SKILL.md#L1-L11字段作用对集成的意义name: watch技能名称安装后以watch标识注册description能力描述Claude 据此判断该不该用这个技能argument-hint参数提示用户输入时给出格式提示allowed-tools: Bash, Read, AskUserQuestion工具白名单明确技能被允许动用的能力边界user-invocable: true用户可手动调用用户可直接敲/watch触发2. commands/watch.md —— 斜杠命令的接线员commands/watch.md 文件很短却解决了一个关键问题让技能暴露成斜杠命令。它把用户输入的$ARGUMENTS原样转发给 SKILL.md 定义的完整流水线预检 → 下载 → 抽帧 → 转录 → 读帧 → 作答。没有它插件即使安装成功/watch也无法被调用——这正是 CHANGELOG.md 中 0.1.1 版本修复的问题。3. hooks/ —— 会话启动时的哨兵hooks/hooks.json 注册了一个SessionStart钩子每次 Claude Code 会话开始时自动运行 hooks/scripts/check-setup.sh静默检查 ffmpeg、yt-dlp 和 API 密钥状态。设计很克制——一切就绪时保持沉默不刷屏只有缺依赖时才输出一行提示告诉用户运行安装器。集成桥梁环境变量如何让文档层驱动脚本层SKILL.md 是纯文本如何驱动 scripts/ 里的 Python 代码桥梁是框架注入的环境变量CLAUDE_SKILL_DIR/CLAUDE_PLUGIN_ROOT指向技能自身目录。SKILL.md 中的命令写作python3 ${CLAUDE_SKILL_DIR}/scripts/watch.py见 SKILL.md#L74-L76这样技能无论被安装到哪个用户目录都能找到自己的脚本钩子脚本中同样用${CLAUDE_PLUGIN_ROOT}定位安装器见 hooks/hooks.json#L9。这套机制形成了一个清晰的分层架构契约层SKILL.md commands/—— 定义做什么、何时做被框架和 AI 共同消费执行层scripts/—— 干脏活累活对 AI 而言只是一条 Bash 命令钩子层hooks/—— 在会话生命周期节点自动运行提供环境保障。AI 负责决策解析用户问题、选择参数、读取结果脚本负责执行下载、抽帧、转录。双方通过stdout 文本报告交换信息入口脚本 scripts/watch.py 结束时会打印一份 Markdown 报告列出所有帧文件路径带tMM:SS时间戳标记和完整字幕文本见 watch.py#L185-L224——Claude 读到的就是这份报告再据此并行 Read 每帧图片。一次调用的编排细节 以入口脚本 scripts/watch.py 为主线看技能系统如何被编排起来建工作目录默认在系统临时目录创建watch-xxxx所有产物集中于此用完即删下载scripts/download.py 封装 yt-dlp本地文件则跳过下载直接探测0.1.3 版本还加固了防参数注入见 CHANGELOG.md#L11-L12抽帧scripts/frames.py 用 ffprobe 探测时长后按帧预算而非固定帧率抽帧——短视频更密集长视频封顶 100 帧、2 fps硬上限核心逻辑在auto_fps函数frames.py#L21-L24。用户用--start/--end聚焦片段时切换为更密集的聚焦模式预算转录scripts/transcribe.py 优先解析 yt-dlp 抓到的原生字幕免费、零成本失败时才由 scripts/whisper.py 调用 Groq首选或 OpenAI 的 Whisper API 兜底汇报打印帧路径列表 带时间戳字幕等待 Claude 接管。Token 经济学图片帧是 token 消耗大头约 50-80k 图像 token / 80 帧 512px字幕则很便宜。所以技能内置按时长自适应抽帧 聚焦模式 追问不重跑三重省 token 设计这些策略都写在 SKILL.md 的正文里由 Claude 自觉遵守。首次运行向导让技能自我安装技能系统的另一个亮点是零配置启动首次调用/watch时SKILL.md 的 Step 0 会静默运行预检setup.py 的--check模式按退出码分派修复动作退出码含义自动动作0一切就绪静默继续不打扰用户2缺 ffmpeg / yt-dlpmacOS 自动brew installLinux/Windows 打印精确命令3缺 Whisper API 密钥生成~/.config/watch/.env模板询问用户密钥4两者皆缺先装依赖再问密钥安装器是幂等的——可安全重复运行且绝不在未征得用户同意时写入任何密钥见 setup.py#L9-L18 的设计注释。密钥文件以0600权限存放于~/.config/watch/.env会话钩子还会定期检查权限是否过松。多端集成同一套文件三种装法 由于能力全部沉淀在SKILL.md 脚本这一套文件里claude-video 能同时适配多个宿主差异仅在加载方式宿主集成方式说明Claude Code插件市场安装/plugin命令完整体验技能 斜杠命令 SessionStart 钩子claude.ai 网页版上传打包后的watch.skill文件打包脚本会剥离hooks/、commands/等非网页端组件Codex / 通用技能目录克隆到~/.codex/skills/watch仅依赖 SKILL.md 契约 脚本手动/开发克隆到~/.claude/skills/watch开发者调试用这种一份契约、多端加载的能力正是 Claude Code 技能系统设计上的通用性红利SKILL.md 的 frontmatter 是标准格式脚本是平台无关的 Python因此换个宿主只需换外壳。给技能开发者的 5 个可复用模式 claude-video 值得作为 Claude Code 技能系统的参考实现它示范了 5 个最佳实践契约与执行分离SKILL.md 只写流程决策重活全部交给 scripts/保持契约文件可读、可移植静默成功原则预检就绪时零输出避免每轮对话刷屏setup complete这类噪音结构化状态输出setup.py --json提供{status, first_run, ...}机器可读状态让 AI 能精确分支决策见 SKILL.md#L47失败模式显式化SKILL.md 专设 Failure modes and handling 一节把每种失败路径的应对方式写成表格AI 照表处理不会瞎试安全边界声明明确列出技能做什么 / 不做什么——只上传提取的音频而非视频本体、不登录任何平台、密钥不出对应域名见 SKILL.md#L154-L169。总结技能系统集成的本质回头看claude-video 与 Claude Code 技能系统的集成原理可以浓缩为一句话用 SKILL.md 这份AI 可读的操作手册声明能力用 commands/ 把它接上斜杠命令入口用 scripts/ 承载具体执行用 hooks/ 守护会话环境——四个文件目录协作就把看视频变成了一项 Claude 的一等能力。对普通用户你只需要一条/watch命令对开发者这个项目则是理解 Claude Code 技能机制frontmatter 契约、斜杠命令注册、SessionStart 钩子、环境变量定位、多端打包的最佳入门样本。想深入了解某一步的实现建议从 SKILL.md 读起再顺藤摸瓜到 scripts/watch.py 的编排逻辑——整条链路只有几百行代码全部可读懂。更多版本演进细节可查看 CHANGELOG.md完整功能说明见 README.md。【免费下载链接】claude-videoGive Claude the ability to watch any video. /watch downloads, extracts frames, transcribes, hands it all to Claude.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-video创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考