---
name: tiktok-carousel-studio
description: "Your daily carousel machine. Claude watches the TikTok creators you follow, picks the carousels that are blowing up, and remakes them with your product and your own AI creators, one per account. Ready-to-post slides, captions and hashtags every morning."
---

# TikTok carousel studio

Turns what works on other creators' TikTok carousels into ready-to-post carousels for a brand's AI creator accounts. It runs on demand or every morning.

**Needs:**
- the Arcads connector
- Python 3 with Pillow (`pip3 install pillow`)

Scripts live in this skill's `scripts/` folder. Call them by absolute path. Below, `$S` stands for that folder (`~/.claude/skills/tiktok-carousel-studio/scripts`).

**Two modes:**
- **Setup:** no `<Brand>_carousels/brand.json` exists yet. Do section 1 once, then section 2.
- **Daily run:** the brand kit exists. Go straight to section 2.

Stop only at the ✋. Raise problems instead of improvising around them.

## 1. Setup: 3 questions, then save the kit

Ask these in **one message**, numbered and short, with examples. Accept partial answers and fill the rest with the defaults shown.

> **1. Brand, product and accounts.** Which brand and product? Send a product link or photo. Then, for each TikTok account: its handle, its **niche** (e.g. hair, skincare, bloating & gut) and its personality in a line or two. **Do you already have a character for each account?** If yes, send the character sheet (image). If not, describe her in a few words (age, look, style) and I'll create her reference.
>
> **2. Who to watch.** Which TikTok creators should I follow? Send as many handles as you like, at least one.
>
> **3. Rhythm and delivery.** How many carousels a day (default 3)? Should one format go to all your accounts the same day, or one format per account? Do you want to approve a plan each morning, or full auto? Where should results go: a folder, a Slack channel, or a Notion page?

### After the answers

1. **Create the folder:**
   ```bash
   python3 $S/init_brand.py "<Brand>"
   ```
   This makes `<Brand>_carousels/` with `brand.json` (from `refs/brand.template.json`), `seen.json`, `library/` and `runs/`. A filled example is `refs/brand.example-novomins.json`.

2. **Arcads brand:** find it with `arcads_list_brands`, or create it with `arcads_create_brand`. Create one project with `arcads_create_project`: `<Brand> TikTok carousels`.

3. **References.** Register every reference once:
   - **Uploading a local file:** `arcads_get_upload_url` → `curl -T <file> -H "Content-Type: image/jpeg" '<presignedUrl>'` → `arcads_register_image`.
   - **Already in Arcads:** use the asset id as is.
   - **What to register:**
     - the product sheet (or a clean packshot)
     - a **close-up crop of the front label**, which keeps label text readable (rule in section 3)
     - one character sheet per account (the ones they sent, or the ones created in step 4)
   - **Temp upload keys are single-use.** Never pass the same `external-api-temp-uploads/…` path to two calls; always use the registered asset id.

4. **Characters.** For each account, one reference that every future generation uses.
   - **They sent a sheet:** register it as is.
   - **No character yet:** create the sheet.
     - Use `arcads_generate_image_nano_banana`, `model: "nano-banana-2-1"`, `aspectRatio: "16:9"`, `resolution: "2K"`, `thinkingLevel: "HIGH"`, `nbGenerations: 1`, with the character-sheet prompt in `refs/prompt-patterns.md`, built from her description, niche and personality.
     - Make all the accounts' sheets in parallel.
     - Make the characters look clearly different from each other (hair, skin tone, age, style) so the accounts never look alike.
     - Aim for real, natural people, not model-perfect faces.

   ✋ Show all the sheets together. Remake only the ones they reject (one new take each), then register the approved ones. From here on, never change a character: every shot uses her registered sheet.

5. **Fill `brand.json`:**
   - product: what it is, `allowed_claims`, `banned` words (always ban cure/treat/disease words for supplements)
   - `characters`: account, sheet, look, **specialty**, personality, settings, never
   - `creators` (any number, at least one)
   - `daily`:
     - `carousels_per_day`
     - `same_format_on_all_accounts`
     - `approval`: `"morning"` or `"auto"`
   - `share.deliver_to` (folder, slack or notion), with the channel or page

6. **Schedule it (if they want it every morning).** If `mcp__scheduled-tasks__create_scheduled_task` exists, create a task at the hour they choose (default 08:00, every day) with the prompt `Run the tiktok-carousel-studio daily run for <Brand> in <absolute folder path>.` Otherwise tell them how to schedule it themselves.

✋ Show the kit in a compact table: product, one row per account (character, niche), the creators followed, then rhythm and delivery. Wait for one OK. Never ask these questions again unless they ask to change the setup.

## 2. Daily run

Make today's folder: `runs/YYYY-MM-DD/` with `sources/`, `raw/`, `out/`.

### 2.1 Scan

1. **Pull posts:** `arcads_search_social_posts` with `handles` (max 5 per call; loop over `creators`), `platforms: ["tiktok"]`, `sort: "recent"`, `since` = date of the last run folder, `limit: 30`, `productId` = brand.
2. **Filter:** keep `mediaKind: "carousel"`. Drop postIds in `seen.json`.
3. **Rank:** by `trendScore`, then by views relative to the account's followers and the post's age.
   - Posts under 24 h old have few views. Use them only if nothing older qualifies, and say so.
   - The same carousel reposted with one text changed (a common tactic) counts as **one** format. Keep its best version.
4. **Pick:** the top `carousels_per_day`. If nothing new qualifies, say so and stop. Never pad with weak posts.
5. **Import:** `arcads_import_social_video` (≤5 links per call). It returns one image asset per slide, in order.
   - Get each slide's signed URL with `arcads_get_download_link`. Never retype a signature by hand.
   - Write a small `downloads.json` and run:
     ```bash
     python3 $S/fetch.py <json>
     ```
     into `sources/<letter>/` with a strip.
6. **Read:** read each strip yourself.

### 2.2 Breakdown and plan ✋ (skip the stop if `approval` is `"auto"`)

**Breakdown.** For each source carousel, one row per slide:
- role (hook / problem / list item / proof / product / CTA)
- what the photo shows (framing, POV or selfie, face or not, props, light)
- the exact on-screen text and its position
- layout: single photo, 2×2 collage (a b / b a), or chat screenshot

Name the format in one line, e.g. "girl problems 2×2 collage → product dose → jar".

**Plan.** For each carousel:
- **Accounts.** Send the format to the character whose **specialty** fits best, and write the text in her tone. With `same_format_on_all_accounts`, make one version per account, each with its own photos. Among equal fits, rotate so every account posts.
- **New shot per slide.**
  - Same composition and role.
  - Products → ours.
  - Competitor products → generic and unbranded.
  - A face only where the original shows one.
  - Faceless shots (hands, legs, objects, POV) keep identity safe and are cheap to vary.
- **Reuse first.** Anything already in `library/` is not regenerated. The product-in-hand shot needs **one version per skin tone**, so a light hand never shows up on a dark-skinned character's account.
- **Text.**
  - Keep the original's voice and rhythm, adapted to the product.
  - Drop lines that don't apply.
  - Only `allowed_claims`; never `banned` words.
- **Post copy:** caption and hashtags in the account's tone.
- **Count:** new photos vs reused from the library.

Show one compact table per carousel. With `approval: "morning"`: post the plan where results go (or in chat), then wait for the OK. After that, run to the end without stopping.

### 2.3 Generate

**Settings:**
- `arcads_generate_image_nano_banana`, `model: "nano-banana-2-1"`, `aspectRatio: "9:16"`, `resolution: "2K"`, `nbGenerations: 1`.
- `productId` and `projectId` from the kit, `title: <brand>_<date>_<carousel>_<shot>_v1`.
- All shots in parallel.

**References:**
- the character sheet for any shot with her face, body or skin
- the product sheet for product shots
- nothing for pure props

Write prompts with `refs/prompt-patterns.md`. The essentials:
1. "Casual vertical iPhone photo" + POV / selfie / mirror selfie
2. What is in frame, where, how big
3. The identity line, or "match her <skin tone> exactly"
4. Anatomy guards ("exactly ONE hand", "exactly five fingers")
5. "Real snapshot, slight grain"
6. "Keep the top third calm for text"
7. "No text, no logos, no watermark"

**Then:**
- Poll with `arcads_get_asset` (`waitSeconds: 40`).
- Download with `fetch.py` into `raw/`.
- Copy reusable shots into `library/` and list their asset ids in `brand.json → library`.

### 2.4 Assemble

Write `runs/<date>/carousels.json`. Format and slide keys are in the `compose.py` docstring. A full example is `refs/brand.example-novomins.json` and the shape below:

```json
{"brand": "<Brand>", "photo_dirs": ["raw", "../../library"], "out_dir": "out",
 "carousels": {"A_jade_girl_problems": {
   "character": "Jade", "account": "@…", "caption": "…", "hashtags": ["#…"],
   "source": "<tiktok url>", "source_dir": "sources/A", "source_label": "@creator",
   "slides": [
     {"kind": "collage", "a": "imsg:I'm outside x", "b": "A_shower_feet", "text": "girl problems"},
     {"kind": "photo", "img": "prod_jar_light", "text": "stay consistent & thank me later 💅", "pos": 0.22,
      "sub2": "dirt cheap too 🤫", "sub2_pos": 0.78}]}}}
```

Run:

```bash
python3 $S/compose.py runs/<date>/carousels.json
python3 $S/compare.py runs/<date>/carousels.json
```

New hooks, texts or chat lines on the same photos are a JSON edit and a re-run: **zero generations**. Use them for variations.

## 3. QA (full size, crop to check)

1. **Hands and anatomy:** finger count, two legs, no extra limbs.
2. **Product label:** read it at full size.
   - Nano Banana garbles small label text ("FRIENDLY FRIENDLY", "FLAOURED").
   - Fix: an **edit pass that only changes the label**, with refs [the shot, the label close-up], `thinkingLevel: "HIGH"`, prompt from `refs/prompt-patterns.md`.
   - **One change per pass.** Changing the hand and the label in one pass brought the typo back.
   - If two shots share the same base image (offset 0,0), paste the fixed label lines from one onto the other with a feathered mask.
   - Never repaint label text with a system font; it looks fake.
3. **Identity and skin:** face shots match the sheet. Faceless shots match the account's skin tone.
4. **Text:**
   - not over a face or the product
   - inside the safe zone (out of the top 10 % and bottom 20 %)
   - claims only from the kit
5. **Reach risks** (revealing or bathroom shots): flag them; never change them silently.

Fix only what fails, then re-run `compose.py` and `compare.py`.

## 4. Deliver

- **Files:** `out/<carousel>/01.jpg…` (1080×1920, in order), `out/posting_sheet.csv` (account, caption, hashtags, source) and `out/compare_*.jpg`.
- **`deliver_to`:**
  - **folder:** show the compare boards in chat (final versions only) with a 3-line summary.
  - **notion:** add a dated toggle to the brand's page with each compare board (upload with `notion-create-file-upload`) and the posting sheet as a table.
  - **slack:** one message per account with the caption, hashtags and the folder path or Notion link. The Slack connector cannot attach images, so link to where the slides are.
- **Seen list:** append today's postIds to `seen.json`.
- **Posting itself:** the team uploads the slides in TikTok photo mode or their scheduler. This skill never posts.

**On a scheduled run with `approval: "morning"`:** stop after the plan (2.2), post it where results go, and end. When someone replies "go", run 2.3 → 4.
