Shorts Hook & Retention QA — Video File Check

Stop guessing why they swipe. Measure the file.

Hook advice usually reads your script. This reads your video: the rendered MP4, second by second. When does the first cut land? Does anything move in the first three seconds? How long until the first sound? Where does the picture go static, where does the audio go silent, and where do both happen at once?

You get timestamps and an edit list — not a score.

📦 This is a downloadable skill, not a hosted agent. You get the files and run them on your own machine, in your own Claude Code, Codex, OpenClaw, or Hermes. Your video is never uploaded and never modified. It needs Python 3.9+, numpy and FFmpeg.

What it measures

The opening — black frames · a frozen first picture · fade-in length · how dark or flat frame one is (it is your autoplay preview) · time to first sound

The hook window (first 3 seconds, adjustable) — first cut · number of cuts · motion compared with the rest of your video · loudness compared with the rest of your video

The middle — every cut and shot length · the longest shot and where it sits · static stretches · silences · dead zones: no cut, no motion and no sound at the same time

The ending — a black or silent tail that delays the loop · a hard audio end

The file — orientation · aspect · resolution · frame rate · loudness · true peak · clipping

A folder of videos — one comparison table across all of them, so you can see which of your own openings is the odd one out

What comes back

1. Verdict — pass / pass with warnings / fail
2. The first seconds, in a table — second · cut? · motion · audio level
3. An edit list — time | what was measured | the edit, earliest first
4. What is already fine
5. What the check cannot see — stated plainly, every time

Sample

Input: Check ./short_final.mp4 before I post it to Shorts.

Output (excerpt, from a real 61-second clip):

PASS WITH WARNINGS · 61.0 s · profile shorts

Second	Cut?	Motion	Audio
0–1	no	0.003	−20.7 dBFS
1–2	no	0.004	−19.3 dBFS
2–3	no	0.004	−20.9 dBFS

Time	Measured	Edit
0.0–11.0 s	No cut until 11.0 s and almost no motion; the longest shot of the video is the first one	Open on the shot that now starts at 28.3 s (the shortest, 2.4 s), or add a punch-in before 3 s
12–21 s	9 s static, no cut	Insert b-roll or an animated caption
whole clip	Average shot 7.6 s over 8 shots	Tighten the 44–61 s section; it holds two 8-second shots back to back

Fine: sound from 0.11 s · −18.0 LUFS · no clipping · no dead tail.
Not measured: what is said, captions, topic, thumbnail.

Honest about what it is

• No view or retention predictions, no "virality score". It measures mechanics — the part of a short you can verify from the file.
• Platform rules are marked. A value is treated as a platform rule only if it was confirmed on an official platform page, with the source and date in the file. Everything else is an editing default you can change.
• Slow can be right. Pacing findings are observations with numbers, not verdicts. A calm tutorial is allowed to be calm.

What you get

shorts-hook-retention-qa/
  SKILL.md                    the workflow your agent follows
  README.md                   install + command reference
  LICENSE.txt
  scripts/video_qa.py         read-only checker → Markdown + JSON report
  references/checks.md        every check: what was measured, why, the edit
  references/profiles.json    thresholds, each marked verified or unverified

One readable Python script. No compiled code, no network calls, no dependencies beyond numpy and FFmpeg. About a second per one-minute clip.

FAQ

Does it edit my video? No. It reads the file and reports. You make the edits in your own editor.

Does it upload anything? No. It runs locally.

Do I need an agent? No. The script runs from a terminal by itself. The skill adds the reading: turning measurements into a ranked, timestamped edit list.

Which platforms? Any vertical short. Profiles for Shorts, Reels and TikTok are included; only values confirmed from official pages are enforced as rules.

How accurate is cut detection? Hard cuts: 90 of 94 found in testing, with no false cuts. A cut between two similar-looking shots can be missed, and dissolves are not counted as cuts.

Can it tell me if my hook line is good? No. It cannot hear words or read captions. It tells you what happens on screen and in the audio while that line plays.

Limits — please read before buying

• Measures the file; cannot read speech, captions, faces or topic.
• No performance predictions of any kind.
• Requires Python, numpy and FFmpeg on your machine.
• Licence. Personal or single-organisation use, including commercial projects. Redistribution or resale of the files is not permitted. Full terms in LICENSE.txt.