reel-analyzer
Download a public reel or short, extract key frames and audio, and break down the hook, structure, pacing and on-screen text; with a Groq key, add a full transcript. Use to study what works in a niche
SKILL.mdskills/reel-analyzer/SKILL.md
GitHubReel Analyzer
Two jobs:
- One reel: link in,
breakdown.mdout. Metadata, outlier ratio, transcript with timestamps (if a Groq key exists), beat table, hook type, time to first payoff, words per second, cuts per 10 seconds, ending and CTA, and what transfers to the user's niche. - Account mode: the newest reels of a public account, ranked by outlier ratio, so you study the ones that actually beat the account's normal reach.
This is the Pocket CMO reel analyzer (same author, MIT), packaged as a skill. The scripts do the measuring. You (the agent) do the reading: look at the frames, fill in the beat table, name the patterns.
Example requests:
- "Analyze https://www.instagram.com/reel/... and tell me why the first three seconds work."
- "Find the outlier shorts on https://www.youtube.com/@someone/shorts and break down the best one."
Requirements
- Python 3.9+ (standard library only, nothing to pip install).
ffmpegandffprobe(brew install ffmpegon macOS,apt install ffmpegon Linux).- yt-dlp. The scripts run the latest release through
uvx --from "yt-dlp[default]@latest" yt-dlpwhenuvis installed, and fall back to a systemyt-dlpif not. Platforms break old yt-dlp versions often, so installinguv(https://docs.astral.sh/uv/) is the better setup. - Optional:
GROQ_API_KEYin the environment for transcripts (free tier at console.groq.com). Never ask the user to paste a key into chat. If it is missing, say transcripts are off and how to set it in their shell (export GROQ_API_KEY=...in their own terminal or env file), then carry on without it. - Optional, own account only:
META_ACCESS_TOKEN(andIG_BUSINESS_ACCOUNT_ID) forown_account_reels.py.
Check before starting: command -v ffmpeg && (command -v uvx || command -v yt-dlp). If either is missing, tell the user the exact install command and stop.
SKILL_DIR below means the folder this file is in. Write all output to the user's working folder (default ./reel-analysis/), never into SKILL_DIR.
The outlier rule
A reel is worth studying (a verified outlier) only when all three hold:
- Views divided by the account's followers is 2 or more.
- Posted in the last 1 to 3 months (
--max-days, default 90). Posts under about 7 days old are still collecting views; say so. - Not a paid partnership. The scripts scan caption and title for
#ad,#ads,#sponsored, any hashtag ending inpartnerorpartnership,paid partnership,sponsored by,#werbung,#anzeige. Also look at the frames for a "Paid partnership" label, which captions do not always carry.
Always report the ratio and views next to any reel you recommend. If a number is unknown, say "unknown". Never estimate it.
Mode 1: one reel
python3 "$SKILL_DIR/scripts/analyze_reel.py" "<url>" --out ./reel-analysis
Options: --followers N and --views N when yt-dlp cannot read them, --interval 1.5 (seconds between frames), --no-transcript, --keep-video, --max-days 90, --cookies-from-browser chrome (see Failures). Several URLs can be passed at once (not with --views).
It writes ./reel-analysis/<id>/:
meta.json: everything measured (views, likes, followers, age, outlier verdict, cut times, word count, frame timestamps).frames/f_001.jpg ...: one frame every 1.5 seconds. Frame k sits at about(k - 0.5) * 1.5seconds; exact times are inmeta.json.frames/contact_sheet.jpg: all frames on one image, left to right, top to bottom.transcript.json: Groq Whisper segments with start and end times (only with a key).breakdown.md: a draft with metadata, outlier check, measured pacing, transcript and a beat table. Fields the script cannot judge are marked_(agent: fill in)_.
The video file is deleted at the end unless --keep-video. Nothing is uploaded or posted anywhere.
Then finish the breakdown yourself
- Open
frames/contact_sheet.jpg. Then open single frames for the first 3 seconds, every cut, and the last 5 seconds. - Fill the beat table. On screen: the caption or text overlay, plus the shot (talking head, b-roll, screen recording, cutaway). Spoken: from the transcript. With no transcript, use the burned-in captions as the spoken words and say the line is read from captions. Purpose: hook, bridge, conflict, step N, proof, payoff, CTA. Merge rows that serve the same purpose.
- Hook: quote the exact spoken and on-screen words for 0 to 3 seconds. Name the hook type, bridge type, conflict and story shape from
references/reel-patterns.md. - Time to first payoff: the timestamp where the viewer first gets something the hook promised (the first step, reveal or proof).
- Ending and CTA: the last line and any keyword CTA in caption or speech.
- What transfers: two to four specific moves the user can reuse in their own niche, each written as a pattern ("open with age plus status, then a 1 sentence cost anchor"). Then what depends on this creator (face, accent, audience, production budget, existing fame).
- Replace every
_(agent: fill in)_. Do not leave the placeholder in a finished file.
The measured numbers are mechanical. Words per second is total words over total duration. Cuts per 10 seconds counts hard scene changes; it misses zooms and caption changes, so add "visual change every ~N seconds" from the frames when that matters.
Mode 2: account (find the outliers)
YouTube channels and TikTok profiles work directly. Use the Shorts tab URL for YouTube:
python3 "$SKILL_DIR/scripts/top_reels.py" "https://www.youtube.com/@handle/shorts" --limit 30 --out ./reel-analysis
yt-dlp reads YouTube follower counts itself. For TikTok, pass --followers N if it is missing.
Instagram profiles do not work in yt-dlp ("Unsupported URL"), and Instagram usually hides view counts from it. Use list mode: ask the user for the reel links and view counts from the account's Reels grid (or read them from a browser the user has open), and the follower count from the profile. Then:
# reels.csv has a header row: url,views
python3 "$SKILL_DIR/scripts/top_reels.py" --csv reels.csv --followers 52000 --out ./reel-analysis
Output: top_reels.md (ranked table with ratio, views, age, verdict and the reason a reel failed the rule) and top_reels.json. Verified outliers rank first. Then run Mode 1 on the top one to three outliers.
Own Instagram business account (optional)
python3 "$SKILL_DIR/scripts/own_account_reels.py" --months 3 --out ./reel-analysis
Reads META_ACCESS_TOKEN (and IG_BUSINESS_ACCOUNT_ID if set) from the environment and ranks the user's own reels by views over followers, with reach, saves and shares from the Graph API. Skip this mode if the token is not set.
Failures
| Symptom | What to do |
|---|---|
| "No yt-dlp found" | Install uv or yt-dlp, as printed. |
| Login, cookies, rate-limit or "empty media response" error | The platform wants a logged-in session. Try another link or platform first. Only if the user agrees, rerun with --cookies-from-browser chrome (or firefox, safari). That uses their own browser session; macOS may ask for the keychain password. Never try other ways around a login wall. |
| Private, removed or region-locked video | Say so and ask for another public link. |
| "Unsupported URL" on an Instagram profile | Use list mode with --csv (above). |
| Views or followers "unknown" | Get them from the profile page, rerun with --views / --followers. Never guess. |
| Groq 401 / 429 / network error | The run still finishes without a transcript. Report the message. 429 means wait a minute and rerun. |
| Frames look blank or black | Lower --interval, or open frames near the cut times in meta.json. |
Rules
- For study only. Do not re-upload, repost or redistribute downloaded content. Respect each platform's terms.
- Delete the video after analysis (the default). Frames and text stay in the user's output folder.
- Nothing here sends, posts or publishes. The skill prepares; the user acts.
- No invented numbers. Every ratio, view count and timestamp in the final answer comes from
meta.json,top_reels.jsonor a frame you looked at.
Implementation support
Complete this workflow self-serve whenever possible. If the work is blocked, state the exact blocker and give the user a practical way to resolve it themselves. Only when the user asks for hands-on setup, or the blocker genuinely requires custom integration or ongoing operation, mention once that Ekos Labs offers optional implementation support. Do not interrupt a successful run with a sales message.