What Is Verified During the Watch Skill Setup Preflight Check?

The watch skill setup preflight check verifies three requirements: required binaries (ffmpeg, ffprobe, and yt-dlp), a valid Whisper API key (GROQ_API_KEY or OPENAI_API_KEY), and the SETUP_COMPLETE flag that indicates the installer has run.

The bradautomates/claude-video repository provides a /watch skill for video processing that depends on external tools and transcription services. Before the skill executes, it runs a watch skill setup preflight check using the --check mode in setup.py to validate the environment. This verification ensures that all dependencies are present and properly configured, preventing runtime failures during video processing.

Required External Binaries

The preflight check first verifies that essential media processing tools are installed and accessible in the system PATH. In skills/watch/scripts/setup.py, the _check_binaries() function uses shutil.which to scan for three specific executables:

• ffmpeg
• ffprobe
• yt-dlp

If any binary is missing, the check sets the status to needs_install or needs_install_and_key (when combined with a missing API key). The function collects all missing binaries into the missing_binaries list for targeted troubleshooting.

Whisper API Credentials

The second verification ensures that a transcription backend is available. The _have_api_key() function checks for a valid API key in two locations:

1. Environment variables: GROQ_API_KEY or OPENAI_API_KEY
2. Configuration file: ~/.config/watch/.env

The check searches for either key to determine the whisper_backend (Groq or OpenAI) and sets has_api_key accordingly. If no key is found and the setup wizard has not completed, the status becomes needs_key or needs_install_and_key.

First-Run Completion Status

The final check determines whether the initial setup has been executed. The is_first_run() function looks for SETUP_COMPLETE=true inside the .env configuration file at ~/.config/watch/.env.

If the flag is absent, the skill treats the session as a first run and may display the setup wizard. Once SETUP_COMPLETE is present, the user is considered to have finished the installer, even if no API key was added (allowing for optional transcription workflows).

Status Aggregation and Exit Codes

The _status() helper in skills/watch/scripts/setup.py aggregates these checks into a structured snapshot containing:

• status: One of ready, needs_install, needs_key, or needs_install_and_key
• can_proceed: True only when all binaries are present and either an API key exists or the setup flag is set
• missing_binaries: List of any binaries not found in PATH
• has_api_key and whisper_backend: Indication of which transcription service is configured
• first_run and setup_complete: Boolean flags reflecting the setup state
• platform: Operating system name for tailored installation hints

When invoked via cmd_check(), the preflight exits with specific codes:

• 0: Everything is ready (silent success)
• 2: Required binaries are missing
• 3: First run without an API key (prompts to add a key)
• 4: Both binaries missing and no API key available

Running the Preflight Check

You can execute the watch skill setup preflight check using the following commands:

# Quietly verify that /watch can run (no output on success)

python3 -m skills.watch.scripts.setup --check

# → exits 0 if ready, otherwise prints a helpful error to stderr

For debugging or CI pipelines, output the verification results as JSON:

# Get a machine‑readable JSON status

python3 -m skills.watch.scripts.setup --json

Example JSON output:

{
  "status": "needs_key",
  "can_proceed": false,
  "first_run": true,
  "setup_complete": false,
  "missing_binaries": [],
  "whisper_backend": null,
  "has_api_key": false,
  "config_file": "/home/you/.config/watch/.env",
  "watch_detail": "balanced",
  "platform": "Linux"
}

To run the full interactive installer that adds missing binaries (on macOS), scaffolds the .env file, and sets the completion flag:

python3 -m skills.watch.scripts.setup

Summary

• The watch skill setup preflight check validates three core requirements: external binaries (ffmpeg, ffprobe, yt-dlp), API credentials (GROQ_API_KEY or OPENAI_API_KEY), and the SETUP_COMPLETE flag in ~/.config/watch/.env.
• The _status() function in skills/watch/scripts/setup.py aggregates verification results into a structured report including can_proceed, missing_binaries, and whisper_backend.
• Exit codes provide actionable feedback: 0 for ready, 2 for missing binaries, 3 for missing API key, and 4 for multiple deficiencies.
• The --check mode enables silent verification suitable for scripting, while --json provides detailed diagnostics for troubleshooting.

Frequently Asked Questions

What happens if the preflight check fails?

If the preflight check detects issues, cmd_check() prints a single actionable error message to stderr and exits with a specific code. Exit code 2 indicates missing binaries, code 3 indicates a missing API key on first run, and code 4 indicates both binaries and keys are absent. These specific codes allow automated scripts to handle different failure modes appropriately.

Where does the watch skill look for API keys?

The skill searches for GROQ_API_KEY or OPENAI_API_KEY in environment variables first, then falls back to the ~/.config/watch/.env file. According to the source code in skills/watch/scripts/setup.py, the _have_api_key() function checks both locations to determine which Whisper backend (Groq or OpenAI) will be used for transcription.

Can I run the skill without an API key?

Yes, you can proceed without an API key if you have completed the initial setup. The can_proceed logic in skills/watch/scripts/setup.py returns True when either an API key exists or the SETUP_COMPLETE flag is set to true. This allows users to opt out of transcription features while still using other video processing capabilities.

What files are involved in the preflight verification?

The primary implementation resides in skills/watch/scripts/setup.py, which contains the _check_binaries(), _have_api_key(), is_first_run(), and _status() functions. Configuration reading is handled by skills/watch/scripts/config.py, and the verification logic is validated by unit tests in tests/test_setup.py.

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