# video-agent-skills

A CLI tool and agent skill that uses Gemini to critique, describe, reverse-engineer, and compare motion/design videos.

## What it does

- Returns candid, production-focused feedback on a video
- Produces factual timestamped scene descriptions without critique
- Compares a reference video with a candidate recreation scene by scene
- Reverse-engineers the likely prompt behind a finished video
- Supports text output and structured JSON for recreation loops

## Install

```bash
./scripts/install.sh
```

## Configure the API key

Set `GEMINI_API_KEY` or `GOOGLE_API_KEY`, or create:

```text
~/.config/video-agent-skills/.env
```

```env
GEMINI_API_KEY=your_key_here
```

## Commands

Critique a video:

```bash
video-agent-skills feedback -video /path/to/video.mp4
video-agent-skills feedback -video /path/to/video.mp4 -tone nice
```

Describe a video without critique:

```bash
video-agent-skills describe -video /path/to/video.mp4
video-agent-skills describe -video /path/to/video.mp4 -format json
```

Compare a candidate recreation with its reference:

```bash
video-agent-skills compare \
  -reference /path/to/reference.mp4 \
  -candidate /path/to/candidate.mp4

video-agent-skills compare \
  -reference /path/to/reference.mp4 \
  -candidate /path/to/candidate.mp4 \
  -format json
```

Reverse-engineer the likely prompt:

```bash
video-agent-skills reverse -video /path/to/video.mp4
```

Common options:

```text
-model string     Gemini model name (default: gemini-3-flash-preview)
-prompt string    Prompt override
-api-key string   Gemini API key override
```

Command-specific options:

```text
-tone string      feedback: nice|normal|harsh|super-harsh
-format string    describe/compare: text|json
```

## Agent skill installation

Local Claude Code install:

```bash
./scripts/install-claude-skill.sh
```

Local Codex install:

```bash
./scripts/install-codex-skill.sh
```

NPM install:

```bash
npm install @dunctk/video-agent-skills
```

The npm installer installs the skill for both Claude Code and Codex and downloads a prebuilt binary for the current platform. Force a source build with:

```bash
VIDEO_AGENT_SKILLS_FORCE_BUILD=1 npm install @dunctk/video-agent-skills
```

Supported prebuilt targets:

- darwin/amd64
- darwin/arm64
- linux/amd64
- linux/arm64
- windows/amd64

## Example feedback

![Example feedback output](docs/example-feedback.png)