How to Integrate Claude Video with Claude Code vs Codex and Cursor: A Complete Guide

Claude Video is a self-contained Agent Skill that installs via native plugin commands on Claude Code and the npm CLI on Codex/Cursor, sharing identical runtime behavior across all platforms after a unified first-run setup.

Claude Video (bradautomates/claude-video) brings video analysis capabilities to AI coding assistants through a portable Agent Skill architecture. Whether you are using Claude Code or alternatives like Codex and Cursor, you can integrate the same /watch functionality using platform-specific installation commands while leveraging identical underlying scripts.

Claude Code Integration Workflow

Adding the Marketplace and Installing the Skill

To integrate Claude Video with Claude Code, you first register the marketplace repository and install the watch skill. Run these commands in your Claude Code session:

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

When you execute /plugin install, the plugin manager copies the entire skills/watch/ folder into the Claude Code plugin cache at ~/.claude/plugins/cache/claude-video/watch/.... The host reads skills/watch/SKILL.md to determine the entry point and resolve SKILL_DIR to the absolute path of the installed folder.

First-Run Setup and Configuration

Before the first /watch invocation, the skill automatically executes scripts/setup.py --check. This script verifies that ffmpeg, yt-dlp, and a Whisper API key are present. If any dependencies are missing, it scaffolds ~/.config/watch/.env and guides you through installation. This pre-flight check runs only once; subsequent calls execute silently.

Using the /watch Command

After installation, invoke the skill directly:

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

The entry point skills/watch/scripts/watch.py orchestrates the workflow: downloading the required segment, extracting frames with scripts/frames.py, generating transcripts via scripts/whisper.py or Groq, and returning the analysis.

Codex and Cursor Integration Workflow

Installing via the Agent Skills CLI

Codex and Cursor utilize the generic Agent Skills CLI rather than Claude Code's native plugin system. Install the skill globally using npm:

npx skills add bradautomates/claude-video -g

The -g flag copies the complete skills/watch/ directory—including SKILL.md and the scripts/ subfolder—into the host's skill directory (typically ~/.codex/skills/watch). Because the skill is self-contained, no additional file manipulation is required.

Cross-Platform First-Run Setup

Regardless of the host, the same scripts/setup.py --check executes on the first /watch invocation. It creates ~/.config/watch/.env and installs missing binaries exactly as it does on Claude Code, ensuring consistent environment preparation across platforms.

Invoking the Skill

Inside Codex or Cursor chat, use the identical slash command:

/watch https://youtu.be/dQw4w9WgXcQ summarize this video

The host resolves SKILL.md, locates scripts/watch.py, and executes it using the same harness-agnostic path resolution logic that works on Claude Code.

Architectural Consistency Across Platforms

Self-Contained Skill Design

The skill resides entirely within skills/watch/, containing both the contract (SKILL.md) and runtime scripts (scripts/). This containment ensures that copying the folder to any host—whether Claude Code's cache or Codex's skill directory—preserves all functionality without path breakage.

Harness-Agnostic Path Resolution

Unlike skills that rely on host-specific environment variables like CLAUDE_SKILL_DIR, Claude Video computes SKILL_DIR dynamically from the location of the currently read SKILL.md file. As defined in skills/watch/SKILL.md (lines 20-27), the scripts determine their base directory relative to the contract file, enabling portable execution.

Idempotent Setup Preflight

The scripts/setup.py script runs identically on every host, checking for ffmpeg, yt-dlp, and API keys before the main logic executes. This guarantees that platform differences stop at the installation boundary; runtime behavior remains consistent.

Key Source Files and Components

• Skill Contract (skills/watch/SKILL.md): Defines the slash command, version, and entry point. Lines 20-27 specify the path resolution logic that sets SKILL_DIR.

• Entry Point (skills/watch/scripts/watch.py): Orchestrates the video processing pipeline from download to transcription.

• Helper Scripts (skills/watch/scripts/): Includes download.py, frames.py, transcribe.py, whisper.py, setup.py, and config.py for modular functionality.

• Installation Metadata: .codex-plugin/plugin.json and .claude-plugin/plugin.json inform each host of the skill version and location.

• Build Script (skills/watch/scripts/build-skill.sh): Creates .skill bundles for claude.ai uploads.

Practical Code Examples

Claude Code (Plugin Commands)

/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video
/watch https://youtu.be/dQw4w9WgXcQ what happens at 30s?

Codex / Cursor (NPM CLI)

npx skills add bradautomates/claude-video -g

/watch https://youtu.be/dQw4w9WgXcQ summarize this video

Direct Script Invocation (Debugging)

For local debugging without the slash command infrastructure:

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

Summary

• Claude Video installs as a self-contained Agent Skill in skills/watch/ that works identically across Claude Code, Codex, and Cursor.
• Claude Code users install via /plugin marketplace add and /plugin install, while Codex/Cursor users use npx skills add -g.
• The first-run setup (scripts/setup.py --check) runs automatically on any host to configure ~/.config/watch/.env and verify dependencies.
• Path resolution is harness-agnostic; SKILL_DIR derives from SKILL.md location, eliminating host-specific environment variable dependencies.
• All platforms invoke the same /watch command backed by scripts/watch.py and helper modules in skills/watch/scripts/.

Frequently Asked Questions

Do I need to modify the skill code to use it with Codex instead of Claude Code?

No. The skill is intentionally host-agnostic. The same skills/watch/ folder containing SKILL.md and the scripts/ directory functions on both platforms without modification. Only the installation command differs between Claude Code's plugin system and Codex's npm CLI.

Where does the skill store its configuration and API keys?

The first-run setup creates ~/.config/watch/.env regardless of the host platform. This file stores your Whisper API key and other configuration parameters. The setup script at skills/watch/scripts/setup.py scaffolds this location automatically if it does not exist.

Can I run the video processing scripts manually without the slash command?

Yes. You can invoke scripts/watch.py directly by setting the SKILL_DIR environment variable to the path containing SKILL.md. For example: SKILL_DIR=$(pwd)/skills/watch python3 $SKILL_DIR/scripts/watch.py "URL". This is useful for debugging or automated pipelines outside of chat interfaces.

What dependencies are required for the first-run setup?

The scripts/setup.py --check verification ensures that ffmpeg, yt-dlp, and a valid Whisper API key (or Groq configuration) are present. If any component is missing, the script halts execution and provides installation instructions before creating ~/.config/watch/.env.

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