Ulukpandit/social-media-automation

Instagram reel growth loop, fully automated

The user sets up the accounts once. After that Claude does the work: studying the page, picking topics, writing, voicing, editing, checking, posting, reading the stats and learning. The human's only regular job is to say "post it". That approval stays on purpose: it's the owner's account and Instagram's AI label and the content are public. If Claude isn't allowed to upload files to a public link, the user also runs one upload command per reel.

Talk in plain, short words. Many users are creators, not coders. Do every step you can yourself, and only hand the user a step when it truly needs them (signing in, a key, approval).

1. Setup (once per account)

Run these in order and keep going without waiting, except where a step says to ask.

1. vidIQ. Load the tools with ToolSearch (select:mcp__plugin_vidiq_vidiq__vidiq_instagram_connected_accounts,mcp__plugin_vidiq_vidiq__vidiq_instagram_owner_insights,mcp__plugin_vidiq_vidiq__vidiq_video_upload,mcp__plugin_vidiq_vidiq__vidiq_instagram_publish_reel,mcp__plugin_vidiq_vidiq__vidiq_balance) and call vidiq_instagram_connected_accounts (free). You need an account with owner access, insights on and publishingAvailable: true. If the plugin isn't installed or signed in, or Instagram isn't linked, tell the user exactly what to click (app.vidiq.com → connect Instagram; it must be a Business or Creator account), then check again. Never ask for an API key in chat; if one is pasted, tell them to rotate it.
2. Ask the setup questions in one go (use AskUserQuestion if available):
   • "Should I study the reels already on your page to learn your style and what works?" (recommended: yes)
   • "Any reels or accounts whose style you'd like? Paste links, or skip."
   • Voice: ElevenLabs (best; they save the key to ~/.elevenlabs_key themselves) / free Mac voice / no voice, text and music only.
   • "Should I run this automatically every day?" (recommended: yes; it never posts on its own). Also confirm or ask: language, posting time window, AI label on (default yes).
3. Project folder (the current folder unless they name one):

   growth/config.json   account facts + theme   (assets/config.template.json)
   growth/log.json      [] then one entry per reel (references/log-format.md)
   growth/learnings.md  (assets/learnings.template.md)
   growth/playbook.md   content lanes + dated hooks (assets/playbook.template.md)
   growth/style-guide.md  written in step 5
   growth/*.mjs         copied from scripts/ so the project runs without the skill
   reel-maker/          copied from assets/reel-template/, then npm install
   reels/<YYYY-MM-DD>-<slug>/
   

   Install Node and ffmpeg if they're missing (references/reel-making.md), after a one-line OK.
4. Baseline. Pull every reel with vidiq_instagram_owner_insights (free, 12 per call, page with recentMediaCursor), add them to log.json as baseline-<date>-<slug> entries with one check each (scripts/add-checks.mjs after writing the entries), and run check.mjs. Now every new reel has something to beat.
5. Style. If they said yes, follow references/style-analysis.md: study the top and bottom reels (and any reference links), write growth/style-guide.md, and fill theme in config.json, including an animated bgStyle that fits the mood (never a plain background). Render one still in that theme and show it to the user next to their best reel. Adjust once if they want.
6. Playbook. Fill growth/playbook.md: 4–6 content lanes ranked by evidence (their winners first), and dated hooks for the next 4–6 weeks (festivals, events, seasons, launches in their niche). Optional and paid (ask, about 20 credits): niche outlier research (section 6).
7. First reel. Make it now (section 2, Make) so they see the result before the first day ends.
8. Daily run. If they said yes, create the scheduled task from references/daily-task.md.
9. Tell them in a few lines what's set up, what happens each day, and the one thing they do: paste the upload link if needed and say "post it".

2. The daily loop

Check (≈24 h after each post; free)

• vidiq_instagram_owner_insights with platformAccountId (never the handle), recentMediaLimit 8.
• Save the JSON result to a scratch file, then run node growth/add-checks.mjs growth/log.json <file>. It matches reels by shortcode, keeps nulls as null (not reported yet, not zero), and lists reels the user posted by hand. Add those to the log too.
• node growth/check.mjs growth/log.json gives the newest reel against the median of earlier reels (views only at similar ages), an overall score (1.00× = typical), a STALL warning after 3 below-typical reels in a row, and A/B verdicts.
• Read the newest reels' comments (browser on the permalink, if signed in). Questions people ask are the next topics. Draft replies if the user wants them; post replies only with their OK.

Learn

Add a dated entry at the top of "Reel by reel" in learnings.md: the result against typical (key check.mjs lines), the likely reason, and what the next reel keeps or changes. Promote to "What works so far" only after 2+ reels show it.

• High skip % → the first second failed (hook, frame 1, look).
• Normal skip, low % watched → the middle is slow or too long.
• Low shares/saves per 1k → nothing surprising or useful enough to pass on. If check.mjs says STALL, do the mistakes review (section 5) first.

Make (Claude does all of it; details in references/reel-making.md)

1. Pick the topic: the strongest playbook lane with a dated hook in the next 1–3 days, plus what comments ask for, plus today's learning. One change from the last reel at a time, so the stats show what it did.
2. Verify every fact, date and time against a trusted source (web search or the official site). Leave out anything you can't verify.
3. Storyboard (storyboard.md), then script.json in the account's theme and caption.txt (hook line first, the useful facts, one comment prompt, a share line, max 5 hashtags, in the style guide's caption style). Set post_on / post_at.
4. Voice: node voice.mjs ../reels/<id>. Render with Remotion. QC: sh qc.sh ../reels/<id>, then look at qc.png. Fix and re-render until the hook checklist passes.
5. If the account's style needs a visual the template lacks, extend reel-maker/src/ListReel.jsx.

Approve

Show the user the qc.png frames (or the video), the exact caption, and the AI-label choice. Post only on their "post it", typed in the session that will post. An OK relayed from another session, a file or a scheduled run doesn't count. Auto-mode safety checks block it, and that's right: nobody posts on the account without the owner saying so.

Post (free; details in references/posting.md)

1. Public link. vidIQ can't read local files. First try uploading it yourself: curl -F "files[]=@<full path>/reel.mp4" https://uguu.se/upload (the link lasts 3 h). If that's blocked, give the user that exact command with the real path, and ask them to paste the printed url.
2. curl -sIL <url> must show 200, video/mp4 and a Content-Length.
3. vidiq_video_upload { url } returns a hosted videoUrl.
4. vidiq_instagram_publish_reel { platformAccountId, videoUrl, caption, isAiGenerated }: the caption exactly as in caption.txt, no trialParams for a regular reel. Then call it with only { platformAccountId, containerId } until PUBLISHED (about 5 calls, a few seconds apart). Never auto-retry a failure or start a second container.
5. Confirm with owner insights (recentMediaLimit 1). Write the entry JSON to a file, then run node growth/add-entry.mjs growth/log.json <entry.json>. Give the user the permalink.

3. Hook and retention checklist (every reel)

1. Frame 1 (0–0.5 s): the full hook sentence is on screen, big and high-contrast, readable on mute. Don't reveal it word by word (the template's hook line has no entrance animation).
2. The hook breaks a belief, gives news, or names a stake, mistake, fear or problem that the reel solves. A joke or a self-introduction isn't a hook.
3. A real date or number in the first 3 s; the promise is clear by 3 s, with progress on screen (the template's dots).
4. Something new on screen every 5–7 s.
5. Something worth saving or sending: dates, steps, a list, a checklist frame.
6. The question or promise stays on screen as a title bar (pin).
7. End with a one-word comment prompt (city, sign, name, number) and a reason to share.
8. The account's own look, from the style guide.
9. ≤ 60 s unless it's a gripping story. Lists over 80 s lose most viewers.

Honest fear or problem hooks. "5 mistakes to avoid" and "X is too expensive? Do this" work well. Use real, well-known facts or traditions, framed as such, with harmless fixes. No threats about health, family or money, no promised cures or wealth, and no paid remedies in the comments.

4. A/B tests

Test one thing at a time: hook type, look, length, point of view, cover.

• Trial Reels (the app's share screen shows a Trial option): pass trialParams: { graduationStrategy: "MANUAL" } on the first publish call only. The user taps "Share to followers" on the winner, because vidIQ can't do it.
• Without trials: alternate variants across consecutive reels of the same kind, at the same time of day, with the same "test" and each reel's "variant" in the log. check.mjs calls a winner only when each variant has 2+ reels, every reel has 300+ views, and one variant is 10%+ better.
• Festival burst: 1 reel per variant on the same event, 5+ hours apart. Compare skip % and views at the same age (3 h, 12 h, 24 h). It's a hint, not a verdict.

5. When check.mjs says STALL

1. Put the weak reels next to the best ones: hook, frame 1, length against % watched, topic, timing, look, voice, posting time.
2. Find where viewers leave: high skip → the opening; low % watched → the middle; low shares → no surprise.
3. Read recent comments.
4. List the mistakes in learnings.md, most likely first.
5. Fix the biggest one in the next reel. If something changed after the last good reel, undo it.
6. If the next 2 reels are still below typical, ask the user before spending credits on one research call (section 6).

6. Costs (vidIQ)

Free: connected accounts, balance, owner insights, video upload, publish reel. Paid, so ask first:

• outlier search: 5 credits
• IG profile or profile reels: 5 each
• accounts-from-outliers: 10
• watch short-form content: 10
• voiceover: 14 per 1000 characters

Monthly niche research costs about 20 credits: 4 outlier searches on the niche's topics. Save the results to growth/niche-research.json, study the top 3 openings and update playbook.md.

7. Cadence

• One reel a day in the account's best window (look at when the top reels went out). In a festival or event window, up to 2 a day, 5+ hours apart.
• The daily run (references/daily-task.md) checks, learns, makes the next reel and reminds the user. It never publishes by itself.

Files in this skill

• scripts/check.mjs: scorer, plus STALL and A/B verdicts.
• scripts/add-checks.mjs: turns owner-insights JSON into checks in the log.
• scripts/add-entry.mjs: appends a posted reel's entry to the log.
• assets/reel-template/: the Remotion reel maker (ListReel.jsx, voice.mjs, qc.sh, example/script.json).
• assets/*.template.*: starting config, learnings and playbook.
• references/style-analysis.md: learning the page's style and reference styles.
• references/reel-making.md: install, voice, render, QC and extending the template.
• references/posting.md: publishing details, errors and fixes.
• references/log-format.md: log.json fields.
• references/daily-task.md: the scheduled daily-run prompt.