viral-breakdown
Researches a creator's niche: finds the creators actually winning, computes each creator's baseline views and keeps only videos that beat it by 3x or more, breaks down why each outlier worked from its
SKILL.mdskills/social/viral-breakdown/SKILL.md
GitHubViral Breakdown
Five agents study a niche so the user stops guessing what to post. Output of a normal week: five ideas that beat their own creator's normal by 3x or more, each with a hook ready to film. (For a month-long posting calendar, use a planning skill instead; this one ends at the weekly top five.)
Where it runs and what each source can really do
| Source | Works in | Gives you |
|---|---|---|
| Web search | Claude.ai and Claude Code | creator discovery, public profile pages. NOT reliable view counts for Instagram or TikTok |
yt-dlp (no login, no key) |
Claude Code | YouTube and Shorts view counts, upload dates, auto captions |
YouTube Data API key in .env (YOUTUBE_API_KEY) |
Claude Code | the same YouTube numbers via the official API |
| User pastes numbers or a screenshot of the profile grid | both | Instagram, TikTok, LinkedIn view counts |
| User pastes transcripts | both | breakdowns for any platform |
The skill never logs in to any account and never asks for a password.
Setup (start)
Ask in two short rounds, accept "skip", then save the answers as PROFILE and show it back.
- Your niche in one or two lines, and who you want watching.
- Platforms you post on, and how often.
- What viewers should do after watching (follow, comment a keyword, buy, book).
- Paste 3 to 5 of your past scripts or captions (best performer if you know it).
- Creators you already watch or compete with (handles or links), and any to leave out.
- Look-back window (default 90 days).
- Claude Code: is
yt-dlpinstalled (yt-dlp --version) or a YouTube API key set? Claude.ai: are you happy to paste Instagram/TikTok numbers?
Commands
| Command | Runs |
|---|---|
start |
setup questions above |
full run |
agents 1, 2, 3, then 4 on the ideas the user picks |
outliers / breakdown <link> / adapt <idea> |
that single agent |
weekly radar |
agent 5 (which reruns 2 and 3 on new videos) |
Agents
Read the agent file before running that step; it is the only home for that role's rules.
agents/01-creator-scout.md: 10 to 25 creators who post weekly to a similar audience.agents/02-outlier-finder.md: baseline per creator, keeps videos at 3x or more.agents/03-breakdown.md: hook, promise, structure and the idea underneath, from the transcript.agents/04-adapter.md: the user's own version, source named, nothing copied.agents/05-weekly-radar.md: the five best new ideas this week, each with a hook.
Shared files
Claude Code: files in research/. Claude.ai: notes the user saves into the Project knowledge.
PROFILE.md niche, audience, platforms, goal, voice samples
CREATORS.md agent 1 table
OUTLIERS.md agent 2 table, every row with source + capture date
BREAKDOWNS.md agent 3, one entry per outlier
IDEAS.md agent 4, status: new / picked / filmed / posted / skipped
RADAR-<date>.md agent 5 output
Safety rules (every agent)
- Every view count, date and baseline names its source and capture date. Too little data =
NOT ENOUGH DATA, never an estimate. - Outliers are relative to the creator's own baseline, never raw views.
- Breakdowns come from transcripts; without one the entry is marked
TITLE ONLY. - Adapt, never copy: no reused footage, script lines, graphics, titles or thumbnails. The source is always named.
- API keys live in
.env, never in chat.
End-of-run output
VIRAL BREAKDOWN: weekly radar, captured 2026-01-12
Scout 14 creators on file, 2 quiet this week
Outliers 6 new at 3x+ (2 STAR), 3 TOO NEW rechecked
Breakdown 5 from transcripts, 1 TITLE ONLY (IG, ask user to paste captions)
Top five RADAR-2026-01-12.md
Missing @example_creator TikTok numbers: paste a grid screenshot
Next "adapt 2" for a full draft of idea 2