Claude Video Skill Installation Guide: Cross-Platform Setup for Claude Code, Codex, and Web

Install the watch skill via marketplace commands in Claude Code, npx skills add for Codex/Cursor, or manual upload for claude.ai web, then let the automated setup.py handle dependency detection and API key configuration.

The claude-video repository by bradautomates provides a harness-agnostic watch skill that enables Claude to analyze video content through frame extraction, caption parsing, and Whisper transcription. Whether you are using Claude Code in your terminal, Codex in your IDE, or the claude.ai web interface, the installation process adapts to your specific host environment while maintaining a consistent runtime contract defined in skills/watch/SKILL.md.

Claude Code Installation

For Claude Code users, installation leverages the built-in plugin marketplace.

Execute these commands in your Claude Code session:

/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video

This registers the skill from the .claude-plugin/ manifest and makes the /watch command available immediately within your Claude Code workspace.

Codex, Cursor, and Agent Skills Hosts

For Codex, Cursor, Copilot, Gemini CLI, and over 50 other Agent Skills-compatible hosts, use the universal Node.js installer.

Install globally to make the skill available across all projects:

npx skills add bradautomates/claude-video -g

Or omit the -g flag to install locally within your current project directory only. This command references the .codex-plugin/ and .agents/plugins/ manifests to scaffold the skill environment.

Claude.ai Web Interface

For the claude.ai web interface, you must manually upload the bundled skill file.

1. Download the watch.skill bundle from the latest release of the repository.
2. Navigate to Settings → Capabilities → Skills in the Claude web interface.
3. Click the + button and upload the watch.skill file.
4. Enable "Code execution and file creation" under Capabilities to allow the skill to process video files.

This method bypasses the command-line tooling entirely while preserving full functionality.

Manual and Development Installation

For developers contributing to the skill or users preferring manual control, clone the repository and create a symbolic link to your skills directory.

git clone https://github.com/bradautomates/claude-video.git
ln -s "$(pwd)/claude-video/skills/watch" ~/.claude/skills/watch

For Codex development, adjust the target path accordingly:

ln -s "$(pwd)/claude-video/skills/watch" ~/.codex/skills/watch

This method exposes the raw skills/watch/ directory, allowing you to modify scripts/watch.py or other modules and test changes immediately without rebuilding bundles.

First-Run Setup and Binary Detection

Regardless of installation method, the first execution of /watch triggers skills/watch/scripts/setup.py to verify your environment.

The setup script performs three critical functions:

1. Binary validation – Checks for ffmpeg, ffprobe, and yt-dlp in your system PATH.
2. Auto-installation – On macOS, automatically installs missing binaries via Homebrew; on Linux and Windows, prints exact installation commands.
3. Configuration scaffolding – Creates ~/.config/watch/.env with mode 0600 (read/write for owner only) containing placeholders for GROQ_API_KEY or OPENAI_API_KEY, plus the default WATCH_DETAIL setting.

Subsequent invocations use the silent --check mode of setup.py (approximately 100ms) to validate the environment without re-running the full installation routine.

Skill Architecture and Key Files

The watch skill follows a harness-agnostic design where the only required environment variable is SKILL_DIR, which points to the location of skills/watch/SKILL.md.

Core implementation files include:

• skills/watch/SKILL.md – The skill contract defining the entry point, version, and usage instructions.
• skills/watch/scripts/watch.py – Central orchestrator that coordinates download, frame extraction, and transcription pipelines.
• skills/watch/scripts/setup.py – Pre-flight installer handling binary dependencies and API key configuration.
• skills/watch/scripts/config.py – Reads the user configuration from ~/.config/watch/.env at runtime.

All scripts reference ${SKILL_DIR}/scripts/ for internal imports, ensuring portability across Claude Code, Codex, Cursor, and manual installations.

Running the Skill Manually

After setting the SKILL_DIR environment variable, you can invoke the skill directly for debugging or development purposes:

SKILL_DIR="$(pwd)/skills/watch"
python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/dQw4w9WgXcQ" --detail balanced

Common usage patterns include:

Basic video analysis with default balanced detail:

/watch https://youtu.be/dQw4w9WgXcQ what happens at the 30-second mark?

Efficient mode for faster processing (keyframes only):

/watch https://youtu.be/abc --detail efficient

Specific time range with denser frame sampling:

/watch https://youtu.be/abc --start 2:15 --end 2:45

Higher resolution for text-heavy content:

/watch video.mp4 --resolution 1024

Disable Whisper fallback (frames and captions only):

/watch video.mp4 --no-whisper

Summary

• Claude Code users install via /plugin marketplace add and /plugin install commands.
• Codex, Cursor, and 50+ hosts use npx skills add bradautomates/claude-video -g for global installation.
• claude.ai web requires downloading the watch.skill bundle from releases and uploading via Settings → Capabilities.
• Manual installation involves cloning the repository and symlinking skills/watch/ to ~/.claude/skills/ or ~/.codex/skills/.
• First-run setup automatically handles ffmpeg, ffprobe, and yt-dlp dependencies while scaffolding ~/.config/watch/.env for API keys.
• The skill is harness-agnostic, relying only on the SKILL_DIR environment variable to locate SKILL.md and the scripts/ directory.

Frequently Asked Questions

Can I use the Claude Video skill without installing ffmpeg manually?

Yes. On the first run, skills/watch/scripts/setup.py automatically detects missing binaries and installs them via Homebrew on macOS. For Linux and Windows systems, the script outputs the exact commands needed to install ffmpeg, ffprobe, and yt-dlp, but you must execute them manually before proceeding.

What is the difference between installing with and without the -g flag in npx skills?

The -g flag installs the skill globally, making the /watch command available in any directory you open with Codex, Cursor, or other Agent Skills hosts. Omitting the flag restricts the skill to the current project directory only, useful for testing or project-specific configurations.

Where does the skill store my OpenAI or Groq API keys?

The skill writes API keys to ~/.config/watch/.env with file permissions set to 0600 (readable only by your user account). This file is read at runtime by scripts/config.py and never committed to version control, ensuring your credentials remain private even when using manual or development installation methods.

How do I build the .skill bundle for manual upload to claude.ai?

Run the build script located at skills/watch/scripts/build-skill.sh from the repository root. This generates dist/watch.skill, which you can then upload directly to the Claude web interface via Settings → Capabilities → Skills without using any command-line marketplace tools.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}