/virality

name: virality
description: >-
  Find what is already working in a niche, then rewrite it in the user's own voice for their
  audience and hand back a shoot-ready short-form video script (Reels, TikTok, Shorts), with a
  LinkedIn post or long-form version as a secondary output. Ranks posts by how far each beat its
  creator's own median, names the hook formula, scores hooks, and strips AI tells. Use when the
  user says "make me a viral video", "write a reel/TikTok/short", "what's working in my niche",
  "find viral videos", "rewrite this in my voice", "give me a hook", "script my next video", or
  wants content that performs. Fuses Jake's LinkedIn and YouTube agent skills.

virality

One workflow: niche in, shoot-ready viral video script out. It finds what is already working, breaks the winners down, and rewrites the pattern (never the video) in the user's voice for the user's audience. Every tool is Python 3 standard library and runs from `tools/` in this folder.

python3 tools/collect.py pasted.txt export.csv yt.json -o candidates.json   # normalize
python3 tools/swipe.py candidates.json --min 2.0                            # outliers
python3 tools/hookscore.py hooks.txt                                        # score + formula
python3 tools/hookscore.py --list                                           # the 26 formulas
python3 tools/speech.py --line "I saved \$400 on flights." --wpm 170        # time a line
python3 tools/humanize.py draft.txt --report -o clean.txt                   # strip AI tells
python3 tools/detect.py draft.txt clean.txt                                 # 5-check panel
python3 tools/title.py --title "..." --cover "THREE WORDS"                  # title + cover

Paths are relative to this skill folder. Write the user's working files to `./virality/<slug>/` in their current directory, never inside the skill folder.

Hard rules (Jake's, non-negotiable)

1. **The hook leads with a concrete payoff**: money made, money saved, time saved, or a number, inside the first ~8 words spoken or on the first on-screen card. "I saved $400 on flights" beats "AI can book travel". `hookscore.py` reports this as PAYOFF: LEADS / LATE / MISSING. 2. **Real proof over vibes.** The beat after the hook shows the receipt: the screenshot, the result, the number on screen. If there is no proof, the hook is a claim, so soften it. 3. **One CTA: comment a keyword.** One word, said out loud and shown on screen, plus what they get: `Comment PLAN and I'll send you the list.` Put the same ask as caption line 1. 4. **Never invent a number, result, client or source.** Missing figure: ask, or write `{{your number}}` and flag it. A script with placeholders is not shoot-ready. 5. **Copy the formula, never the video.** The hook shape, structure, length and pacing. Not their words, footage or edit. Attribute every winner you studied. 6. **No em dashes** in anything you hand over. `humanize.py` removes them.

Step 1: the brief (niche, audience, offer, voice)

Read `~/.claude/virality/audience.md` and `~/.claude/virality/voice.md` if they exist (also check `~/.claude/youtube/voice.md` and `~/.claude/linkedin/voice.md` from Jake's other packs). If missing, fill them from `templates/audience.md` and `templates/voice.md`:

• Ask ONE batched question: niche, the one viewer, the offer and comment keyword, platforms,

and 3 to 5 of their own captions or video transcripts (or links you can read).

• Build the voice from those samples using the method in `templates/voice.md`. Measure their

pace with `python3 tools/speech.py their_video.srt` and use it as `--wpm` from then on.

• Collect their proof bank: real numbers they will put their name on.
• Do not proceed on a thin idea. "Post about AI" needs: what happened, to whom, what it cost

or returned.

Step 2: find what's working

Goal: 30+ posts across 6 to 12 creators (from `audience.md`), at least 4 per creator, recent (last 90 days). Sources, in order of preference:

1. **The user's own posts.** Their last 20 to 30 with view counts. Their own outliers are the strongest evidence that exists. 2. **YouTube Shorts / YouTube**, public, no login. If yt-dlp is installed (`python3 -m yt_dlp --version`), list a channel's public Shorts with counts: `python3 -m yt_dlp --flat-playlist --playlist-end 40 -J "https://www.youtube.com/@HANDLE/shorts" > a.json` If it is not installed, say so and use another source. Never pass cookies or log in. 3. **TikTok, Instagram, LinkedIn**: the user reads the numbers off their own screen and pastes them (they are already logged in on their phone), or a public analytics site. You may use web search to find public posts and accounts. Never log into an account, never ask for a password, never scrape behind a login, never automate a logged-in browser.

Paste format (one post per line, `|` or tab separated), then normalize:

@creator | 1.2M | first line of the hook or caption | url | 0:41

python3 tools/collect.py pasted.txt a.json b.json -o virality/<slug>/candidates.json
python3 tools/swipe.py virality/<slug>/candidates.json --min 2.0

`swipe.py` ranks by **views as a multiple of each creator's own median**, so a 400K post on an account that usually does 30K outranks a 2M post on an account that usually does 2M. Creators with fewer than 4 posts are skipped, on purpose: one or two posts is not a median. 3x and above is a strong signal; under 1.5x is that creator's normal day. Say the sample size out loud: 12 posts is an anecdote, 40 across 6 creators is evidence.

Step 3: break the winners down

Take the top 3 to 5 outliers. Get each transcript (their captions, the user's paste, or `yt-dlp --write-auto-subs --sub-format json3 --skip-download URL` for public YouTube). For each:

| field | how | | --- | --- | | hook formula | `python3 tools/hookscore.py --hook "their first line"` (name from `tools/hooks.json`) | | payoff | the PAYOFF line from the same run: