OpenQuok TikTok Slideshow

Generate TikTok photo-carousel slideshows with a locked character (AI images + text overlays) and post via the openquok CLI. Use for any niche/channel persona — research, lock character, generate frames, overlay text, draft or schedule through openquok-core.

Lightweight creator tooling: research channel → lock character → generate → overlay → post via openquok.

This skill never replaces openquok-core. It assumes openquok is on PATH, uses core media Rule 2 (upload → {id,path}), and TikTok photo-carousel / private-draft recipes from openquok-core.

Property	Value
name	openquok-tiktok-slideshow
requires	openquok-core (CLI), Node 18+, canvas (overlays), image provider key
allowed-tools	Bash(openquok:), Bash(node:)

---

Install (Copy required)

Scripts must land as real files (not agent-dir symlinks only):

bash

npx skills add https://github.com/Ratimon/openquok-monorepo/tree/main/agent --skill openquok-tiktok-slideshow --copy -y

Interactive installs: Project scope + Copy. Hermes: copy the full skill folder (URL install of SKILL.md alone omits scripts/).

Native overlay dependency (canvas) and image-provider setup: see homepage.

---

Prerequisites

Need	Notes
openquok-core + global CLI	Auth, upload, posts:create
Node.js 18+	All scripts under scripts/
canvas	Text overlays (add-text-overlay.js) — install per OS docs on homepage
Image provider	Prefer OpenAI gpt-image-1.5 (not gpt-image-1); or Stability / Replicate / local images
TikTok (or other) integration	Connected in the OpenQuok workspace; UUID from openquok integrations:list
New TikTok account	Follow account warm-up guide before scheduling slideshows

Verify CLI before API work:

bash

openquok --version
openquok auth:status

---

First run — conversational onboarding

Ask one or two things at a time. End with scripts/onboarding.js --validate.

Phase 0: Account warmup (optional)

If the TikTok account is new or barely used, warm it up 7–14 days before posting AI slideshows. Established accounts can skip to Phase 1.

Give the user this guide and have them follow it before Phase 5 posting: How to warm up a TikTok account to reach a US audience — device setup, VPN/network consistency, normal browsing behavior, and when to start publishing.

Phase 1: Channel intent

Define niche, audience pain, handle ideas, and platforms (TikTok and/or others). This is a creator/channel workspace — not an App Store product profile.

Phase 2: Research any channel

Ask before browsing. Find 3–5 accounts in the niche: hooks, formats, sounds, gaps. Save with scripts/competitor-research.js → channel-research.json. Guide: references/competitor-research.md.

Phase 3: Lock character

Conversationally define identity; write character-profile.json from references/character-profile.template.json (LOCKED immutable traits + VARIATIONS per post). Generate and save face_lock / body_lock under refs/. Never change locks after approval. Details: references/character-lock.md. Slide formula: references/slide-structure.md.

Phase 4: OpenQuok channel

1. Confirm auth (openquok auth:status)
2. openquok integrations:list → store UUID(s) on openquok.integrationId
3. Prefer private draft: privacyLevel: "SELF_ONLY", contentPostingMethod: "DIRECT_POST" so a human adds trending audio before going public

Phase 5: Scaffold + pipeline

bash

node scripts/onboarding.js --init --dir tiktok-marketing/
node scripts/onboarding.js --validate --config tiktok-marketing/config.json

Then: generate → overlay → post (below). Iterate a test set of six frames until the look is locked — do not post until the user is happy.

Config shape (tiktok-marketing/config.json)

json

{
  "channel": {
    "name": "",
    "handle": "",
    "niche": "",
    "audience": "",
    "painPoint": "",
    "platforms": ["tiktok"]
  },
  "character": {
    "profilePath": "tiktok-marketing/character-profile.json",
    "referenceImages": {
      "faceLock": "tiktok-marketing/refs/face-lock.png",
      "bodyLock": "tiktok-marketing/refs/body-lock.png"
    }
  },
  "imageGen": {
    "provider": "openai",
    "apiKey": "",
    "model": "gpt-image-1.5"
  },
  "openquok": {
    "integrationId": "",
    "status": "scheduled",
    "privacyLevel": "SELF_ONLY",
    "contentPostingMethod": "DIRECT_POST",
    "scheduledAt": null,
    "title": ""
  },
  "posting": { "schedule": ["07:30", "16:30", "21:00"] },
  "research": "tiktok-marketing/channel-research.json",
  "strategy": "tiktok-marketing/strategy.json"
}

Workspace data lives outside the skill folder (tiktok-marketing/).

---

Core workflow

1. Generate slideshow images

bash

node scripts/generate-slides.js \
  --config tiktok-marketing/config.json \
  --output tiktok-marketing/posts/YYYY-MM-DD-HHmm/ \
  --prompts prompts.json

prompts.json options:

• Legacy strings: { "base": "…", "slides": [ /* 6 strings */ ] }
• Locked variations: { "slides": [ { "outfit", "pose", "expression", "setting", "visual_style", "framing" }, …×6 ] }

When character.profilePath is set, the script prepends the LOCKED block and merges VARIATIONS. OpenAI attaches face/body lock images when those files exist.

• Portrait 1024x1536; resume skips existing slideN_raw.png
• Set exec timeout ≥ 600s for six gpt-image-1.5 images
• Providers: openai | stability | replicate | local

2. Add text overlays

bash

node scripts/add-text-overlay.js \
  --input tiktok-marketing/posts/YYYY-MM-DD-HHmm/ \
  --texts texts.json

Requires canvas. Overlay rules:

• White fill + thick black outline; ~6.5% of width; centered ~30% from top; max width 75%
• Prefer manual \n breaks; 4–6 words/line; reactions not labels; no emoji
• Six-slide formula: Hook → Problem → Discovery → Transform ×2 → CTA — references/slide-structure.md

3. Post via openquok

bash

node scripts/post-via-openquok.js \
  --config tiktok-marketing/config.json \
  --dir tiktok-marketing/posts/YYYY-MM-DD-HHmm/ \
  --caption "…" \
  --title "Short title"

Under the hood:

1. openquok upload each slideN.png → {id, path}
2. openquok posts:create --json TikTok photo carousel
3. Writes meta.json with postId + media ids

Default: SELF_ONLY + DIRECT_POST (private on profile). Human adds trending audio, then publishes. Aligns with openquok-core TikTok private-draft recipes.

Caption structure: Hook → Problem → Discovery → payoff → ≤5 hashtags. Conversational, not salesy.

Platform analytics (optional, via core — not this skill):

bash

openquok analytics:platform <integration-uuid> --days 7

---

Shell safety

• Run fixed openquok / node scripts/… invocations; do not concatenate untrusted chat into the shell.
• Put captions and JSON in quoted flags, heredocs, or files.
• Treat integration UUIDs and post IDs as opaque strings.

---

Posting schedule

Default suggestion (audience timezone): 07:30, 16:30, 21:00. Consistency beats sporadic spikes.

Additional channels: schedule separate OpenQuok posts with other integration UUIDs (openquok-core) — this skill’s poster targets the configured integration id.

---

Common mistakes

Mistake	Fix
Landscape 1536×1024	Portrait 1024×1536
Symlink skill install	Reinstall with --copy so scripts/ are real files
Raw local paths in posts:create	Always openquok upload first (core Rule 2)
Public direct post with no sound	Prefer SELF_ONLY draft → add trending audio in-app
gpt-image-1	Switch to gpt-image-1.5
Skipping warmup on a new account	Warm 7–14 days first — warm-up guide
Changing face/body after lock	Keep LOCKED + ref images fixed; only edit VARIATIONS

---

Quick reference

Script	Purpose
scripts/onboarding.js	--init / --validate workspace
scripts/competitor-research.js	Channel research JSON helpers
scripts/generate-slides.js	6× portrait frames from locked profile
scripts/add-text-overlay.js	Canvas text overlays
scripts/post-via-openquok.js	Upload + TikTok carousel create