Communitygithub.com

/watch – 视频观看与理解技能

观看视频(URL 或本地路径),使用 yt-dlp 下载,通过 ffmpeg 提取自动缩放的帧,从字幕(或使用 Whisper API 作为备选)提取文字记录,并将结果提供给 Claude,以便它可以回答关于视频内容的提问。

watch – 视频观看与理解技能 是什么?

该技能为 AI 助手(如 Claude Code、Cursor、Codex 等)提供了全面的视频理解能力。它集成了多个命令行工具(yt-dlp、ffmpeg)和可选的 Whisper API,以处理来自 URL(如 YouTube、Vimeo)或本地文件的视频。工作流程包括自动下载、基于内容的智能截图(场景感知或关键帧)、获取带时间戳的文字记录(优先使用原生字幕,失败时回退到 Whisper),最后将帧路径和文字记录交给 AI。用户可以通过 `/watch <source> [question]` 命令询问视频中的细节。技能支持 macOS、Linux 和 Windows,并包含自动安装脚本,可处理首次使用时的设置、环境变量和配置首选项。其独特优势在于将多模态信息(帧和文字)无缝融合,使 AI 能够回答关于视频内容的复杂问题,并引用具体时间点。

兼容平台✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI
npx skills add https://github.com/Jo5i4swastaken/Skills-Locker/tree/HEAD/skills/watch

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

/watch

你原本没有视频输入能力,这个技能为你提供了。一个 Python 脚本首先获取字幕,可选地下载视频,将帧提取为 JPEG 格式(场景感知模式,或 efficient 模式下的快速关键帧),获取带时间戳的文字记录(优先原生字幕,回退到 Whisper API),并打印帧路径。然后你 Read 每个帧路径以查看图像,并将它们与文字记录结合以回答用户的问题。

解析 SKILL_DIR(在任何命令之前执行)

下面的每个 python3 ... 命令都运行 SKILL_DIR/scripts/ 下的捆绑脚本。将 SKILL_DIR 设置为 包含此 SKILL.md 文件的目录的绝对路径——你的运行环境在 Read 结果中已告知你该路径。脚本始终与这个文件直接同级(SKILL_DIR/scripts/watch.py),在所有安装布局中都是如此:

Read ~/.claude/plugins/cache/claude-video/watch/<ver>/skills/watch/SKILL.md → SKILL_DIR=…/skills/watch
Read ~/.codex/skills/watch/SKILL.md                                          → SKILL_DIR=~/.codex/skills/watch
Read ~/.agents/skills/watch/SKILL.md                                         → SKILL_DIR=~/.agents/skills/watch

在每条命令中将 ${SKILL_DIR} 替换为该文字路径。这种方式适用于所有运行环境(Claude Code、Codex、Cursor、Gemini CLI 等),而无需依赖任何特定于运行环境的环境变量。在运行开始时进行一次验证:

SKILL_DIR="<你所 Read 的 SKILL.md 所在目录的绝对路径>"
if [ ! -f "$SKILL_DIR/scripts/watch.py" ]; then
  echo "错误:在 SKILL_DIR=$SKILL_DIR 下未找到 scripts/watch.py" >&2
  echo "请重新检查你所 Read 的 SKILL.md 所在目录,并将 SKILL_DIR 替换为该路径。" >&2
  exit 1
fi

步骤 0 — 设置预检(每次调用 /watch 时运行,成功时静默)

Python 解释器: 此技能中所有 python3 ... 命令均适用于 macOS/Linux。在 Windows 上,请替换为 python——Windows 上的 python3 命令是 Microsoft Store 存根,无法运行脚本。

在会话中首次调用 /watch 时,使用结构化预检以便检测首次运行设置:

python3 "${SKILL_DIR}/scripts/setup.py" --json

根据两个字段进行分支处理:

  • can_proceed: true 且 first_run: false → 设置已完成(用户可能有意跳过了 Whisper 密钥——这是允许的)。直接进入步骤 1,无需评论。
  • first_run: true → 真正的首次设置。按以下顺序执行:
    1. 如果 missing_binaries 非空,则首先运行安装程序(它在 macOS 上自动安装/在其他系统上打印命令——见下文)并确认二进制文件已就位。不要跳过此步骤直接进入偏好设置。
    2. 如有必要,再运行一次安装程序,以便创建 ~/.config/watch/.env 文件(它仅在文件不存在时写入模板,因此请先让它创建文件之后你再向其中写入任何值)。
    3. 鼓励用户提供 Whisper API 密钥并询问下面的观看偏好问题,然后将所选值写入 ~/.config/watch/.env 并设置 SETUP_COMPLETE=true。
  • can_proceed: false 且 first_run: false → 之前已完成设置,但环境退化了(例如操作系统更改后出现 missing_binaries)。运行安装程序进行修复,然后继续。不要重新询问偏好。

缺少 Whisper 密钥是鼓励修复,但非必须:在真正的首次运行时,即使二进制文件存在,status 也会显示为 needs_key——这是你鼓励提供密钥的提示,而不是障碍。

在同一会话的后续 /watch 调用中,使用静默检查:

python3 "${SKILL_DIR}/scripts/setup.py" --check

这是一个小于 100ms 的查找操作。退出码 0 表示可以运行 /watch——这包括已完成设置但没有 Whisper 密钥的用户(无密钥是允许的)。退出码 0 时脚本不输出任何内容——直接进入步骤 1 而不评论。不要向用户宣布“设置已完成”——他们不需要在每次交互时都看到状态消息。步骤 0 唯一可接受的对用户可见的输出是当需要修复时。

在非零退出时,按照下表处理:

退出码含义操作
2缺少二进制文件(ffmpeg / ffprobe / yt-dlp)运行安装程序
3真正的首次运行且没有 Whisper API 密钥运行安装程序以创建 .env 文件,然后鼓励提供密钥(用户可能拒绝——使用 --no-whisper 继续)
4两者都缺失运行安装程序,然后鼓励提供密钥

退出码 3 仅在用户尚未完成设置时触发。一旦写入 SETUP_COMPLETE=true,无密钥的安装返回退出码 0 并且永远不会再次提示。

安装程序是幂等的——可以安全地重新运行:

python3 "${SKILL_DIR}/scripts/setup.py"

在 macOS(带有 Homebrew)上,它会自动安装 ffmpeg 和 yt-dlp。在 Linux/Windows 上,它会打印出确切的安装命令供用户运行。它以 0600 权限创建带有注释占位符和默认观看设置的 ~/.config/watch/.env 文件。

如果安装后 API 密钥仍然缺失: 使用 AskUserQuestion 询问用户是否有 Groq API 密钥(首选——更便宜、更快)或 OpenAI 密钥。然后将其写入 ~/.config/watch/.env——设置匹配的 GROQ_API_KEY=... 或 OPENAI_API_KEY=... 行。如果他们不想设置 Whisper,则使用 --no-whisper 继续,并告诉他们没有原生字幕的视频将以仅帧的形式返回。

首次运行的观看偏好: 在安装程序创建 ~/.config/watch/.env 后,使用 AskUserQuestion 询问一个问题:

  • 默认细节(单次选择)。以以下确切顺序将选项呈现为 AskUserQuestion 选项——从最轻到最重——并保留 balanced 上的 (recommended) 标记,即使它不是第一个选项(不要重新排序将推荐选项放在首位):
    • transcript — 无帧,仅文字记录(存在字幕时跳过视频下载)。
    • efficient — 快速关键帧传递(上限 50)。
    • balanced(推荐)— 场景感知帧(上限 100,默认)。
    • token-burner — 场景感知,无上限(最高保真度;高令牌成本)。

直接将答案写入 ~/.config/watch/.env,设置裸键在其单独的行上——没有尾随内联注释(值后的 # 注释 可能会破坏解析):

WATCH_DETAIL=balanced

使用用户选择的值。如果他们跳过问题,则保留推荐的默认值。一旦处理完依赖项、API 密钥选择和此偏好,在同一个文件中写入或更新 SETUP_COMPLETE=true。当 SETUP_COMPLETE=true 时,不要再问此偏好的问题。

结构化模式(可选): python3 "${SKILL_DIR}/scripts/setup.py" --json 输出 {status, can_proceed, first_run, setup_complete, missing_binaries, whisper_backend, has_api_key, config_file, watch_detail, platform},其中 status 为 ready | needs_install | needs_key | needs_install_and_key 之一。status 描述理想状态(鼓励使用密钥,因此无密钥的首次运行显示为 needs_key);can_proceed 是操作门控(二进制文件存在 AND 密钥已设置 OR 设置已完成)。根据 can_proceed/first_run 决定是否运行;使用 status 决定鼓励什么。

在同一个会话中,你可以在后续的 /watch 调用中跳过步骤 0——一旦 --check 返回 0,环境在两次交互之间不会发生变化。

何时使用

  • 用户粘贴视频 URL(YouTube、Vimeo、X、TikTok、Twitch 片段、大多数 yt-dlp 支持的站点)并询问相关内容。
  • 用户指向本地视频文件(.mp4、.mov、.mkv、.webm 等)并询问相关内容。
  • 用户输入 /watch <url-or-path> [question]。

推荐限制

  • 最佳准确度:10 分钟以下的视频。 帧覆盖范围与时长成反比。
  • 通用速率限制:2 fps。 即使预算或 --fps 暗示更多,脚本采样速度也永远不会超过 2 fps。
  • 帧上限由细节模式决定(~/.config/watch/.env 中的 WATCH_DETAIL,或 --detail),而不是单个全局上限:
    • transcript → 无帧
    • efficient → 最多 50(关键帧)
    • balanced(默认)→ 最多 100(场景感知)
    • token-burner → 无上限(场景感知;超过 250 帧时会打印一个软警告)
    • --max-frames N 覆盖模式原本使用的任何上限。
  • 按时长划分的全视频帧预算。 令牌成本随帧数增长,因此脚本按时长设定预算。此预算设置 fps 和均匀采样回退方案;场景感知选择可以填充到上述细节上限,以较低者为准:
    • ≤30秒 → 约12-30帧
    • 30秒-1分钟 → 约40帧
    • 1-3分钟 → 约60帧
    • 3-10分钟 → 约80帧
    • 10分钟 → 最高到细节上限,稀疏分布(会打印警告)

  • 如果用户给你一个长视频,考虑询问他们是否想要特定分段,然后再在稀疏扫描上消耗令牌。

如何调用

步骤 1 — 解析用户输入。 将视频源(URL 或路径)与用户提出的任何问题分开。示例:/watch https://youtu.be/abc 这个视频是什么语言的? → 源 = https://youtu.be/abc,问题 = 这个视频是什么语言的?。

步骤 2 — 运行观看脚本。 直接传递源字符串。除了正常引用外,不要自己进行 shell 转义:

python3 "${SKILL_DIR}/scripts/watch.py" "<source>"

可选标志:

  • --detail transcript|efficient|balanced|token-burner — 保真度/速度调节。transcript = 无帧(仅文字记录,存在字幕时跳过视频下载);efficient = 快速关键帧(上限 50);balanced = 场景感知帧(上限 100);token-burner = 场景感知,无上限。
  • --start T / --end T — 聚焦于某个片段。接受 SS、MM:SS 或 HH:MM:SS 格式。当设置了其中任一时,fps 会自动缩放得更密集(见下文“聚焦于某个片段”)。
  • --timestamps T1,T2,… — 在这些绝对时间戳(SS、MM:SS 或 HH:MM:SS)处各抓取一帧。在阅读文字记录后使用此功能,以捕获演示者强调的指示性时刻(“看这里”、“正如你所见”、“注意这个”),这些时刻单靠视觉选择可能错过。见下面的“文字记录提示帧”。
  • --max-frames N — 覆盖预设上限以获得更紧凑的令牌预算(例如 --max-frames 40)
  • --resolution W — 更改帧宽度(像素,默认为 512;仅当用户需要阅读屏幕上的文本时才增加到 1024)
  • --fps F — 覆盖自动 fps(上限为 2 fps)
  • --out-dir DIR — 将工作文件保留在特定位置(默认:自动生成的临时目录)
  • --whisper groq|openai — 强制使用特定的 Whisper 后端(默认:如果两个密钥都存在,则优先使用 Groq)
  • --no-whisper — 完全禁用 Whisper 回退(如果没有字幕,则仅返回帧)
  • --no-dedup — 保留近乎重复的帧。默认情况下,帧差异传递会删除与前一个保留帧视觉上近乎相同的帧(如静态幻灯片、屏幕录制、暂停的视频),以便帧预算用于不同的内容;报告的 Frames 行会注明丢弃了多少帧。仅在用户需要每个采样帧时才传递此标志(例如,判断细微的帧间运动)。

聚焦于某个片段(更高的帧率)

当用户询问特定时刻时——“2 分钟处发生了什么?”、“集中看 0:45 到 1:00”、“前 10 秒”——传递 --start 和/或 --end。脚本切换到聚焦模式预算,这比全视频预算更密集(仍然上限为 2 fps,并且仍受细节模式上限的约束——以下计数假设默认的 balanced 上限为 100;efficient 上限为 50):

  • ≤5秒 → 2 fps(最多 10 帧)
  • 5-15秒 → 2 fps(最多 30 帧)
  • 15-30秒 → 约2 fps(最多 60 帧)
  • 30-60秒 → 约1.3 fps(最多 80 帧)
  • 60-180秒 → 约0.6 fps(100 帧,上限)

聚焦模式适用于以下情况:

  • 用户明确命名的任何时刻/范围(“大约 2:30”、“开头”、“最后 30 秒”)。
  • 任何时长超过约 10 分钟且用户的问题针对特定部分的视频——对相关片段运行聚焦模式比对整个视频进行稀疏扫描有用得多。
  • 在全扫描后发现某个区域细节不足时重新运行。

文字记录会自动过滤到相同范围。帧时间戳是绝对的(视频的真实时间线,不是从开始算起的偏移量)。

示例:

# 1 分钟视频的最后 10 秒
python3 "${SKILL_DIR}/scripts/watch.py" video.mp4 --start 50 --end 60

# 聚焦 2:15 → 2:45,2 fps(60 帧)
python3 "${SKILL_DIR}/scripts/watch.py" "$URL" --start 2:15 --end 2:45 --fps 2

# 从 1h12m 到视频结束
python3 "${SKILL_DIR}/scripts/watch.py" "$URL" --start 1:12:00

步骤 3 — Read 脚本列出的每个帧路径。 Read 工具将 JPEG 直接渲染为图像供你查看。在单条消息中(并行工具调用)Read 所有帧,以便你一起看到它们。帧按时间顺序排列,带有 t=MM:SS 时间戳,方便你将其与文字记录对齐。

步骤 4 — 回答用户。 你现在有两方面的证据:

  • 帧 — 每个时间戳屏幕上的内容
  • 文字记录 — 每个时间戳所说的内容。报告的头部显示来源(captions = yt-dlp 拉取的原生字幕;whisper (groq) 或 whisper (openai) = 由 API 转录)。

如果用户问了具体问题,直接回答并引用时间戳。如果他们什么都没问,则总结视频中发生的事情——结构、关键时刻、显著的视觉内容、口语内容。

这也适用于 transcript 细节模式:即使没有帧,也要像其他模式一样生成一个摘要——不要将完整文字记录粘贴到聊天中。综合结构、关键时刻和口语内容并附上时间戳;只引用关键语句。仅当用户明确要求时才提供原始文字记录。

步骤 5 — 清理。 脚本会在末尾打印工作目录。如果用户不会就此视频提出后续问题,请使用 rm -rf <dir> 删除它。如果他们可能会问,则将其保留在原处。

细节和帧

默认行为来自 ~/.config/watch/.env:

  • WATCH_DETAIL=transcript|efficient|balanced|token-burner(默认:balanced)

在

…

[翻译截断]

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

Jo5i4swastaken/Skills-Locker

Implements the "100% Retrieval Strategy" by Vercel. Injects a compressed docs index into AGENTS.md/CLAUDE.md to guarantee the agent always uses your global skills and best practices.

Jo5i4swastaken/Skills-Locker

Premium brand-kit image generation skill for creating high-end brand-guidelines boards, logo systems, identity decks, and visual-world presentations. Trained for minimalist, cinematic, editorial, dark-tech, luxury, cultural, security, gaming, developer-tool, and consumer-app brand systems. Optimized for intentional logo concepting, refined composition, sparse typography, strong symbolic meaning, premium mockups, art-directed imagery, and flexible grid layouts.

Jo5i4swastaken/Skills-Locker

Rewrite text to make ideas and sentences clearer and easier to understand. Use when the user wants to simplify prose, untangle a tangled sentence, reduce jargon, sharpen vague claims, or make writing accessible to a wider audience. Works on any text: docs, emails, blog posts, reports, marketing copy, slide bullets, academic prose. TRIGGER on phrases like: "make this clearer", "clarify this", "simplify this", "rewrite for clarity", "plain language", "reduce jargon", "make it easier to understand", "untangle this", "explain this simply", "tighten this up", "make this readable". Returns the rewritten text only — no diff, no commentary.

Jo5i4swastaken/Skills-Locker

Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.

Jo5i4swastaken/Skills-Locker

Elite UX/UI & Advanced GSAP Motion Engineer. Enforces Python-driven true randomization for layout variance, strict AIDA page structure, wide editorial typography (bans 6-line wraps), gapless bento grids, strict GSAP ScrollTriggers (pinning, stacking, scrubbing), inline micro-images, and massive section spacing.

Jo5i4swastaken/Skills-Locker

Remove signs of AI-generated writing from text. Use when editing or reviewing text to make it sound more natural and human-written. Based on Wikipedia's comprehensive "Signs of AI writing" guide. Detects and fixes patterns including: inflated symbolism, promotional language, superficial -ing analyses, vague attributions, em dash overuse, rule of three, AI vocabulary words, negative parallelisms, and excessive conjunctive phrases.

Jo5i4swastaken/Skills-Locker

Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.

Jo5i4swastaken/Skills-Locker

Agent Media OS — resolve any media need (BGM, SFX, image, icon) into a frozen local file + ledger record. One verb (`resolve`) handles the full cascade — project cache, global cache, HeyGen catalog search, freeze, register. Keeps search noise on disk, hands the agent a path. Use when a composition needs background music, sound effects, images, or icons.

Jo5i4swastaken/Skills-Locker

Author a HyperFrames slideshow composition — a presentation, pitch deck, or interactive deck with discrete slides, fragment reveals, branching sequences, and hotspot navigation. Use as an intent check when the user asks for a presentation, pitch deck, slide deck, interactive deck, or page-to-deck conversion that might be a slideshow; if the user did not explicitly ask for a slideshow / slide show, confirm before authoring.

Jo5i4swastaken/Skills-Locker

When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram, TikTok, Facebook, or other platforms, or wants to do social listening and engagement triage. Also use when the user mentions 'LinkedIn post,' 'Twitter thread,' 'social media,' 'content calendar,' 'social scheduling,' 'engagement,' 'viral content,' 'what should I post,' 'repurpose this content,' 'tweet ideas,' 'LinkedIn carousel,' 'social media strategy,' 'grow my following,' 'TikTok video,' 'Reels,' 'Shorts,' 'video script,' 'video hook,' 'short-form video,' 'create a reel,' 'social listening,' 'brand mentions,' 'competitor monitoring,' 'top posts to comment on,' 'find people asking for,' 'carousel,' 'slide-by-slide,' or 'document post.' Use this for social media content creation, repurposing, scheduling, short-form video scripting, and social listening. For broader content strategy, see content-strategy. For paid ads, see ad-creative. For earned media, see public-relations.

Jo5i4swastaken/Skills-Locker

Use when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, @supabase/ssr) in Next.js, React, SvelteKit, Astro, Remix; auth issues (login, logout, sessions, JWT, cookies, getSession, getUser, getClaims, RLS); Supabase CLI or MCP server; schema changes, migrations, security audits, Postgres extensions (pg_graphql, pg_cron, pg_vector).

相关技能