/analyze

name: analyze
description: Analyze a screen recording of an animation to characterize its motion — timing, easing, transforms, and sequencing — so it can be recreated as web code. Use when the user drops or points at a video of an animation (.mp4/.mov/.webm/.mkv/.m4v/.avi/.gif) and says things like "I want this animation on my site", "recreate this motion", "how is this animated", or runs /motiscope:analyze.
argument-hint: "[path-to-video] [notes]"
allowed-tools: Bash, Read, AskUserQuestion
user-invocable: true

motiscope: analyze

Turn a screen recording of an animation into a precise, target-agnostic **animation spec** you can hand to `/motiscope:recreate`. A bundled Python pipeline measures the motion (a dense per-frame motion-energy curve + ffmpeg signal analysis — this is the source of truth for timing and easing) and extracts a small set of curated PNG keyframes for you to *see*. You combine the two into the spec.

<!-- motiscope:preamble:start -->

Resolve the scripts directory (do this first)

Every command below runs a bundled script. Set `SCRIPTS`:

SCRIPTS="${CLAUDE_PLUGIN_ROOT:-}/scripts"
# Fallback for harnesses that don't export CLAUDE_PLUGIN_ROOT: this SKILL.md lives at
# <plugin>/skills/analyze/SKILL.md, so scripts are two levels up. Use the absolute
# path of the directory containing the SKILL.md you just Read.
if [ ! -f "$SCRIPTS/ingest.py" ]; then
  SCRIPTS="<absolute dir of this SKILL.md>/../../scripts"
fi
if [ ! -f "$SCRIPTS/ingest.py" ]; then
  echo "ERROR: cannot find ingest.py — check the plugin install." >&2; exit 1
fi

On **Windows** use `python` instead of `python3` in every command below. <!-- motiscope:preamble:end -->

Step 0 — preflight (silent on success)

python3 "$SCRIPTS/mvsetup.py" --check

Exit 0 → proceed silently. Non-zero → `ffmpeg`/`ffprobe` are missing; hand off to `/motiscope:doctor` (don't try to analyze without them).

Step 1 — resolve the input video

• If the user gave a path (in `$1` or their message), use it.
• Otherwise scan the drop folder and project root:

  ls -t animations/*.{mp4,mov,webm,mkv,m4v,avi,gif} *.{mp4,mov,webm,mkv,m4v,avi,gif} 2>/dev/null | head

• Several candidates → ask the user (`AskUserQuestion`) which one.
• Exactly one → use it.
• None → tell the user to drop a recording into `animations/` (or pass a path) and stop.

**Local files only.** motiscope does not download URLs. If the user pastes a URL, ask them to screen-record it and drop the file in.

Step 2 — run the pipeline

python3 "$SCRIPTS/ingest.py" "<video>" --preset balanced

It writes to `.motiscope/<slug>/` and prints a summary, the `report.md` path, and the ordered curated frame list.

Choose a preset (this is the main token dial)

The number of frames you `Read` is what costs tokens (~300–400 tokens/frame); the numeric analysis is free. Frame count tracks *motion complexity*, capped by the preset — it does **not** grow with video length.

| Preset | Frame cap | Resolution | Use when | |---|---|---|---| | `--preset draft` | 12 | 512px | quick look, tight token budget | | `--preset balanced` *(default)* | 32 (usually lands 8–20 after dedup) | 640px | most cases | | `--preset detailed` | 48 | 960px | dense multi-beat sequences, or reading on-screen text | | `--preset landing` | 44 | 1280px | **web/landing walkthroughs** — cover each section's design at readable resolution + its in-section motion |

Start with `balanced`. Only reach for `detailed` if the animation is intricate or you couldn't read a label; use `draft` for a fast first pass. If the user hasn't said, pick `balanced` and mention they can ask for more detail.

Focus a section of a longer video (`--start` / `--end`)

For anything longer than ~15s, or when the user points at a specific moment ("the part around 0:12", "the last second"), analyze just that window instead of a sparse whole-clip scan. Times accept `SS`, `MM:SS`, or `HH:MM:SS`; frame/segment timestamps come back in **absolute** source time.

python3 "$SCRIPTS/ingest.py" "<video>" --preset detailed --start 0:12 --end 0:15

Capture fast content densely (`--fps`)

Within a (short) focus window you can force a uniform sample rate so nothing between keyposes is missed — e.g. `--fps 20` gives up to a frame every ~50ms. Near-identical frames are still collapsed unless you pass `--no-dedup`. Combine with a short window so the budget isn't blown:

python3 "$SCRIPTS/ingest.py" "<video>" --start 1.0 --end 3.0 --fps 20 --frame-budget 48

Complex / long animations: auto-decompose

For clips ≥8s with two or more motion beats, `ingest.py` **auto-decomposes** by default: it finds the beats, then concentrates frames on each *motion* segment (drilling densely) and gives each *hold* just one representative frame — so the budget is spent on motion, not dead air. A 10s clip with a 5s hold in the middle spends ~0 frames on the hold. The report notes when this happened.

Control it with `--decompose` (force on) / `--no-decompose` (force the flat single-pass). Auto is the right default; force it off only if you specifically want even coverage across the whole timeline.

Other flags: `--frame-budget N` / `--resolution W` override the preset; `--format jpg` for gradient-heavy recordings that bloat as PNG; `--no-dedup` to keep every sampled frame; `--out DIR` (default `.motiscope/`).

> **Small elements register now.** The primary motion signal is *localized* (built from the most-active regions of the frame), so a small button/card/icon moving on a large page reads as real motion instead of washing out. The stagger direction in the report tells you the sequencing (e.g. `left-to-right, ~200ms each`) — use it when building the spec's `stagger`.

Step 3 — read the analysis, then the frames

**The division of labor is the whole point:**

• **The numbers give you the WHEN.** `report.md` measured the *timing* you can't see in a still: exact durations, t