AI UGC ad scripts: 2-second hook, shot list, captions, Kling / Veo prompts, compliance lint.

Quickstart · How it works · Examples · Install · FAQ

English · Русский · 简体中文 · Español · Português (BR) · 日本語 · 한국어

ugc-ad-director: AI UGC ad scripts and video prompts

AI UGC ads start with a script, not a prompt. This skill turns a product brief into a TikTok / Reels / Shorts ad script with the hook inside the first two seconds, five timed beats (hook → problem → demo → proof → CTA), a shot list, on-screen captions, voiceover, and a per-shot prompt for the image model, for Kling and for Veo 3 with spoken lines. A stdlib Python script lints the result and refuses what should not ship: an AI presenter talking like a customer, "clinically proven" without a source, a missing AI label.

It drafts; it does not fabricate. Presenters are fictional demonstrators, every claim needs evidence, and the AI-generated ad label is a caption from frame one. The ethics are in the lint, not in a footnote.

Hook by 2.0 s	Prompts per shot, per model	Compliance that fails the build
Twelve words max, said and captioned at once, chosen from a hook library by category.	First frame for image-to-video, a Kling clip prompt, a Veo 3 prompt with dialogue; consistent presenter wording across shots.	Fake testimonials, platform endorsements, unbacked claims and a missing AI label are errors, not warnings.

Quickstart

git clone https://github.com/uniqaiapp/ugc-ad-director && cd ugc-ad-director
python3 scripts/ugc_script.py lint examples/scripts/skincare-serum.json
python3 scripts/ugc_script.py render examples/scripts/skincare-serum.json --out serum.md

The first command prints ok, 0 errors, 0 warnings; the second writes a script sheet with the timeline table, voiceover, captions, shot prompts, claims and a compliance checklist. In an agent, say "write a 30-second UGC ad for " and the skill does the same from your brief.

Demo

How it works

1. Brief → facts. From a URL or a line of text the skill extracts the one thing the product does, who it is for, the annoyance it removes and anything checkable (label, spec, screen). Nothing else gets in; "revolutionary" is not a fact.
2. Hook first. One idea, ≤ 12 words, lands by 2.0 s, caption and voiceover together because the sound is usually off. references/hook-library.md has hooks by category and type (callout, contrarian, result-first, comparison, a test the viewer can do now) and a list of hooks to avoid.
3. Five beats with timings. hook → problem → demo → proof → cta, scaled to 15, 20, 30, 45 or 60 s (references/structure.md). Demo is the longest and shows one action. Proof is something checkable, preferably real footage of the real product or a real screen recording, even inside an otherwise generated ad.
4. Shots → prompts. Each shot carries subject, action, camera, setting, lighting, negative, audio. scripts/ugc_script.py prompts renders them as a still for the first frame, a Kling clip prompt (5 or 10 s, negative prompt, no slow motion) and a Veo 3 prompt with the spoken line as Dialogue (references/model-prompts.md).
5. Lint. Timeline contiguous and ending at duration_s; hook ≤ 2 s; beats in order; captions ≤ 48 characters per line; voiceover pace per shot; every generated shot has a prompt; first-person customer phrasing with an AI presenter is an error; "proven", "guaranteed", "#1", percentages and "results in N days" must sit in claims with evidence; the AI label must appear in a caption. Full list in references/script-format.md.

brief ──▶ hook ──▶ beats + timings ──▶ shots ──▶ script.json
                                                   │
                     lint (structure + compliance) ◀┘──▶ render (.md sheet) ──▶ prompts (image / kling / veo3)

The only numbers this README quotes come from python3 scripts/ugc_script.py stats examples/scripts/skincare-serum.json: 6 shots, hook ends at 2 s, 75 words of voiceover over 30 s (2.5 words/s), 7 caption lines, longest 41 characters, 5 generated shots, 2 claims with evidence. The beat splits and the 3.5 words/s pace ceiling are working defaults, not measured optima; the repo claims nothing about retention or conversion.

Examples

Eleven scripts across verticals in examples/: skincare, a meal-planning app, a kitchen gadget, dog chews (real customer with a release), a language course, B2B invoicing, a cleaning spray with no voiceover, running shoes, a travel eSIM, a coffee subscription and a pet camera. Every rendered sheet and prompt file is committed and reproduced byte-for-byte by the tests.

Before (the brief)

Dewline Barrier Serum: fragrance-free hydrating serum with ceramides and 2% niacinamide.
Audience: women 22-35 with dry, flaky skin under makeup. 30 s, AI presenter.

After (first three rows of the timeline in examples/rendered/skincare-serum.md)

This is the beginning of the README. Read the rest at the original. Read the full README ↗