Squish

View saved version →

---
name: video-navigation
description: Navigate videos an agent cannot ingest directly - turn any clip into timestamped contact sheets, read the grid, zoom into ranges, and cite exact timecodes. Use when asked what happens in a video or screen recording, to find the moment something changes or appears, or to answer with timestamp citations from footage too long to watch. Retrieval and navigation only, not video editing. Works through any contact-sheet tool (Squish CLI/MCP - local needs Node >= 20 and ffmpeg on PATH; a hosted connector exists when local tools are unavailable).
license: Apache-2.0
metadata:
  author: getsquish
  version: "0.1.0"
---

# Video navigation: treat video as an address space

You have vision but cannot ingest video. When a task involves a video's content, do not guess
and do not refuse — compress the clip into **timestamped contact sheets** (one image per
window of the clip, frames sampled evenly, each cell stamped with its timecode) and read
those. The sheet is your index into the video; zooming is how you navigate it.

The reasoning primitive: **video → contact sheet → read the grid → zoom where it matters →
answer with timecodes.**

**Non-goals.** This is a video *navigation and retrieval* skill, not a video *editing*
workflow. Navigation over editing; retrieval over transformation. It does not transcribe
(sheets carry no audio) and a sheet is a sequence map, not motion replacement. Your
deliverable is answers with timestamps — absolute seconds that hand off cleanly to any
editing or clipping tool, which is where this skill stops.

## When to use

- "What happens in this video / screen recording?"
- The question spans time: before/after, a scene change, progress, "find the moment when…".
- The answer needs precise citations ("at 0:07 the press comes down").
- The clip is too long or too large to ingest any other way.

**When not to use:** the user needs one specific frame only (extract that frame instead); the
question isn't about visual content. **Pairing note:** if the question is about *what was
said*, a transcript is the better index — pair with an ASR/transcript tool; this skill's
index is visual on purpose, and speech-free footage (where transcripts come back empty) is
exactly where it is strongest.

## What you need: a squisher

Any tool implementing this contract (see **Wiring** below for today's implementations):

> **(video, density?, start?, end?) → sheet image(s) + per-cell timecodes**

- `density` — grid size per sheet (`3x3` … `6x6`): more frames per call.
- `start`/`end` — window the run to a time range: more precision per frame.
- Output: sheet images in time order, plus the timecode of every cell.

## The navigation loop

1. **Overview.** Squish the whole clip at default density. Long clips return several sheets —
   read them in order; each covers a consecutive window.
2. **Read the grid.** Cells run in time order, left→right, top→bottom. The pill in each
   cell's corner is that frame's timecode. Adjacent cells that look alike = little changed in
   that window; a hard visual break between cells = an event happened there.
3. **Zoom.** Call again with `start`/`end` set to timecodes you actually read off a sheet.
   Timecodes are **absolute to the source at every depth**, so ranges compose: overview →
   range → moment. Pick the lever deliberately — **density packs more frames into one call;
   a window packs more precision into each frame.** Long or fast-moving clip → denser grid;
   pinning one moment → tighter window.
4. **Confirm before you cite.** One last tight window around the found moment, dense enough
   that the cell interval is at or below the precision you are about to claim. Check the
   event actually sits where you'll say it does.
5. **Answer with timecodes** (see Answer shape).

## Evidence discipline

The coarse sheet is the **index** — it proposes where to look. The zoomed sheet is the
**evidence** — it's what you cite. Concretely:

- **Never cite a timecode fine

Preview of the first 4,000 characters. Read full instructions →