企业官网建设流程全解析

如何让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-video

claude-video（/watch）是一款为 Claude Code 赋予"看视频"能力的技能插件：粘贴一个视频链接或本地文件路径，它会自动下载视频、抽取关键帧、提取字幕文本，最终让 Claude 基于"亲眼所见"的画面回答你的问题。本文从 Claude Code 技能系统的工作机制出发，带你拆解这套集成背后的完整原理，无需编程基础也能看懂。

先看结果：一个命令的完整旅程 🎬

整个体验浓缩成一行命令：

/watch https://youtu.be/xxxxx 这个视频在第30秒发生了什么？

Claude 收到指令后，背后实际发生了一串"接力"动作，这也是理解集成原理的最佳切入点：

关键洞察：claude-video 本身并不"看"视频。它只负责把视频拆解成 Claude 能处理的两种形态——图片帧和带时间戳的文字——然后交给 Claude 的多模态 Read 工具完成真正的"观看"。这正是它作为技能系统的精妙之处。

技能系统三要素：claude-video 如何用文件"教"Claude

Claude 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）：

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）。

这套机制形成了一个清晰的分层架构：

1. 契约层（SKILL.md + commands/）—— 定义"做什么、何时做"，被框架和 AI 共同消费；
2. 执行层（scripts/）—— 干脏活累活，对 AI 而言只是"一条 Bash 命令"；
3. 钩子层（hooks/）—— 在会话生命周期节点自动运行，提供环境保障。

AI 负责"决策"（解析用户问题、选择参数、读取结果），脚本负责"执行"（下载、抽帧、转录）。双方通过stdout 文本报告交换信息：入口脚本 scripts/watch.py 结束时会打印一份 Markdown 报告，列出所有帧文件路径（带t=MM:SS时间戳标记）和完整字幕文本（见 watch.py#L185-L224）——Claude 读到的就是这份报告，再据此并行 Read 每帧图片。

一次调用的编排细节 🔍

以入口脚本 scripts/watch.py 为主线，看技能系统如何被"编排"起来：

1. 建工作目录：默认在系统临时目录创建watch-xxxx，所有产物集中于此，用完即删；
2. 下载：scripts/download.py 封装 yt-dlp，本地文件则跳过下载直接探测（0.1.3 版本还加固了防参数注入，见 CHANGELOG.md#L11-L12）；
3. 抽帧：scripts/frames.py 用 ffprobe 探测时长后，按"帧预算"而非固定帧率抽帧——短视频更密集，长视频封顶 100 帧、2 fps（硬上限），核心逻辑在auto_fps函数（frames.py#L21-L24）。用户用--start/--end聚焦片段时，切换为更密集的"聚焦模式"预算；
4. 转录：scripts/transcribe.py 优先解析 yt-dlp 抓到的原生字幕（免费、零成本）；失败时才由 scripts/whisper.py 调用 Groq（首选）或 OpenAI 的 Whisper API 兜底；
5. 汇报：打印帧路径列表 + 带时间戳字幕，等待 Claude 接管。

💡Token 经济学：图片帧是 token 消耗大头（约 50-80k 图像 token / 80 帧 @512px），字幕则很便宜。所以技能内置"按时长自适应抽帧 + 聚焦模式 + 追问不重跑"三重省 token 设计，这些策略都写在 SKILL.md 的正文里，由 Claude 自觉遵守。

首次运行向导：让技能"自我安装"

技能系统的另一个亮点是零配置启动：首次调用/watch时，SKILL.md 的 Step 0 会静默运行预检（setup.py 的--check模式），按退出码分派修复动作：

安装器是幂等的——可安全重复运行，且绝不在未征得用户同意时写入任何密钥（见 setup.py#L9-L18 的设计注释）。密钥文件以0600权限存放于~/.config/watch/.env，会话钩子还会定期检查权限是否过松。

多端集成：同一套文件，三种装法 📦

由于能力全部沉淀在"SKILL.md + 脚本"这一套文件里，claude-video 能同时适配多个宿主，差异仅在加载方式：

这种"一份契约、多端加载"的能力，正是 Claude Code 技能系统设计上的通用性红利：SKILL.md 的 frontmatter 是标准格式，脚本是平台无关的 Python，因此换个宿主只需换"外壳"。

给技能开发者的 5 个可复用模式 🧩

claude-video 值得作为 Claude Code 技能系统的参考实现，它示范了 5 个最佳实践：

1. 契约与执行分离：SKILL.md 只写流程决策，重活全部交给 scripts/，保持契约文件可读、可移植；
2. 静默成功原则：预检就绪时零输出，避免每轮对话刷屏"setup complete"这类噪音；
3. 结构化状态输出：setup.py --json提供{status, first_run, ...}机器可读状态，让 AI 能精确分支决策（见 SKILL.md#L47）；
4. 失败模式显式化：SKILL.md 专设 "Failure modes and handling" 一节，把每种失败路径的应对方式写成表格，AI 照表处理，不会瞎试；
5. 安全边界声明：明确列出"技能做什么 / 不做什么"——只上传提取的音频而非视频本体、不登录任何平台、密钥不出对应域名（见 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