Update to Squish

{
  "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).",
  "included_files": [],
  "skill_md_contents": "---\nname: video-navigation\ndescription: 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).\nlicense: Apache-2.0\nmetadata:\n  author: getsquish\n  version: \"0.1.0\"\n---\n\n# Video navigation: treat video as an address space\n\nYou have vision but cannot ingest video. When a task involves a video's content, do not guess\nand do not refuse — compress the clip into **timestamped contact sheets** (one image per\nwindow of the clip, frames sampled evenly, each cell stamped with its timecode) and read\nthose. The sheet is your index into the video; zooming is how you navigate it.\n\nThe reasoning primitive: **video → contact sheet → read the grid → zoom where it matters →\nanswer with timecodes.**\n\n**Non-goals.** This is a video *navigation and retrieval* skill, not a video *editing*\nworkflow. Navigation over editing; retrieval over transformation. It does not transcribe\n(sheets carry no audio) and a sheet is a sequence map, not motion replacement. Your\ndeliverable is answers with timestamps — absolute seconds that hand off cleanly to any\nediting or clipping tool, which is where this skill stops.\n\n## When to use\n\n- \"What happens in this video / screen recording?\"\n- The question spans time: before/after, a scene change, progress, \"find the moment when…\".\n- The answer needs precise citations (\"at 0:07 the press comes down\").\n- The clip is too long or too large to ingest any other way.\n\n**When not to use:** the user needs one specific frame only (extract that frame instead); the\nquestion isn't about visual content. **Pairing note:** if the question is about *what was\nsaid*, a transcript is the better index — pair with an ASR/transcript tool; this skill's\nindex is visual on purpose, and speech-free footage (where transcripts come back empty) is\nexactly where it is strongest.\n\n## What you need: a squisher\n\nAny tool implementing this contract (see **Wiring** below for today's implementations):\n\n> **(video, density?, start?, end?) → sheet image(s) + per-cell timecodes**\n\n- `density` — grid size per sheet (`3x3` … `6x6`): more frames per call.\n- `start`/`end` — window the run to a time range: more precision per frame.\n- Output: sheet images in time order, plus the timecode of every cell.\n\n## The navigation loop\n\n1. **Overview.** Squish the whole clip at default density. Long clips return several sheets —\n   read them in order; each covers a consecutive window.\n2. **Read the grid.** Cells run in time order, left→right, top→bottom. The pill in each\n   cell's corner is that frame's timecode. Adjacent cells that look alike = little changed in\n   that window; a hard visual break between cells = an event happened there.\n3. **Zoom.** Call again with `start`/`end` set to timecodes you actually read off a sheet.\n   Timecodes are **absolute to the source at every depth**, so ranges compose: overview →\n   range → moment. Pick the lever deliberately — **density packs more frames into one call;\n   a window packs more precision into each frame.** Long or fast-moving clip → denser grid;\n   pinning one moment → tighter window.\n4. **Confirm before you cite.** One last tight window around the found moment, dense enough\n   that the cell interval is at or below the precision you are about to claim. Check the\n   event actually sits where you'll say it does.\n5. **Answer with timecodes** (see Answer shape).\n\n## Evidence discipline\n\nThe coarse sheet is the **index** — it proposes where to look. The zoomed sheet is the\n**evidence** — it's what you cite. Concretely:\n\n- **Never cite a timecode finer than the cell spacing of the sheet you read it from.** If\n  cells are 2 s apart, \"at 1:07.3\" is a guess wearing a timestamp — zoom first.\n- **Bounded loop.** Beyond the overview, ~2 zoom rounds resolve almost anything. If ambiguity\n  survives, say plainly what you can and cannot tell instead of looping. The floor is real:\n  below ~2 ms/cell the tool refuses with a teaching error — you have run out of video.\n- Cite pill values verbatim; never interpolate between two cells.\n\n## Hard rules\n\nThese are correctness, not taste:\n\n1. **Timecodes are absolute at every depth.** A zoomed sheet's pills are source-video times,\n   not window-relative — cite them as read.\n2. **Read the overview before zooming.** Navigation starts from the index, not from a guess.\n3. **Local is free and private; remote transits Squish infrastructure and is metered.**\n   Local mouths process on-machine at no cost. The remote connector takes a public\n   `video_url` and Squish's server **fetches** it — nothing is uploaded from your machine\n   (the separate hosted file-upload API is the path where a file itself is uploaded), but\n   the footage does transit Squish infrastructure and spends quota/credits. Say so to the\n   user before switching lanes, and when the tool reports remaining quota or credits, use it\n   to plan and surface the trade-off (\"one free job left today — spend it on this?\").\n4. **Never answer with just file paths.** The user asked about the video, not your artifacts.\n\n## Anti-patterns\n\nApproaches that consistently fail:\n\n- **Frame-dumping** — extracting every frame into context. The sheet exists so this never\n  happens; thousands of frames of noise answer nothing.\n- **Zooming before reading the overview** — you'll drill into the wrong minute.\n- **Citing a mid-cell guess** — any timestamp finer than the sheet's cell spacing.\n- **Re-squishing the whole clip at high density when one range matters** — pay for precision\n  only where the question lives (this is real money on the remote lane).\n- **Treating a sheet as motion** — it's a sequence map; don't claim smooth motion detail\n  between cells.\n- **Burning remote quota to test wiring** — verify with the local mouth; it's free.\n- **Answering \"what was said\" from sheets** — no audio; pair with a transcript tool.\n\n## Wiring: today's implementations\n\nIf tool names differ from these, match by the contract shape above.\n\n| Mouth | How | Notes |\n|---|---|---|\n| **MCP (local)** | tool `squish_video` — register with `npx -y @getsquish/squish mcp` | args `{ video_path, density?, start?, end?, out_dir? }`; returns `files[]` + `timecodes[][]` (per-sheet, per-cell). Nothing leaves the machine. |\n| **CLI** | `npx -y @getsquish/squish <video> --json [--density 4x4] [--start 1:00 --end 1:15] [--out dir]` | stdout JSON: `files[]`, contract `squish-cli-v0` — no `timecodes[][]` field on this path; the timecodes are the pills burned into each cell, so read them off the sheets. Needs Node ≥ 20 + ffmpeg. |\n| **MCP (remote)** | Streamable HTTP connector at `https://api.getsquish.app/mcp` | input is `video_url` (public URL) — the server **fetches** it, so the footage transits Squish infrastructure; anonymous free lane (small daily cap) or `Authorization: Bearer` key; first sheet arrives inline. Quota errors are structured — relay the hint to the user (most lanes include a `billing_url`; ChatGPT-app traffic hears the daily reset + free local tool instead), don't retry blindly. |\n\n`density` accepts `3x3`–`6x6`; `start`/`end` accept seconds or sheet timecode strings like\n`\"1:07.3\"`. Read each returned sheet with vision, in order.\n\n## Answer shape\n\nIf the question was specific (\"find the moment when…\"), lead with that answer + timestamp.\nThen:\n\n1. **Summary** — what the clip shows, one or two sentences.\n2. **Key moments with timestamps** — each cited to a cell's timecode.\n3. **Anomalies** — anything odd and its timecode, or say there were none.\n\n## Provenance\n\nProven in the field: 55 MB / 20 s iPhone clip → one 3×3 sheet in ~4 s, narrated with correct\ntimestamps from the sheet alone (2026-07-02). Zoom loop: a scene cut pinned to 0.2 s by\nreading 34 frames instead of 3,088 (2026-07-07). Official Claude app, hosted connector:\nthree-level zoom converged on 0:06.85 ± 0.02 s in sub-second calls (2026-07-10). Web\n(no-install) equivalent for humans: https://getsquish.app\n"
}