claymation-ad

name	claymation-ad
metadata	{"packVersion":"1.2.0"}
description	Builds a hand-sculpted stop-motion CLAY ad on the Novoads REST API as a STORYBOARD: five to eight beats, each rendered from its own key frame, a storyteller narration laid into the gaps, a music bed, captions burned on, assembled locally with ffmpeg. Carries the genre's arc (named protagonist, inciting moment, social beat, quiet despair, sculpted clay infographic, discovery, transformation, resolution card), and also recreates a found clay ad by reading the reference video locally with ffmpeg and Whisper. Use for ANY clay or stop-motion ask at ANY length: "claymation ad", "stop-motion ad", "clay ad", "a quick clay ad", "plasticine characters", "make an ad like this clay one", or a reference video with sculpted clay characters in it. There is no one-call tier here, so ffmpeg is required. Not for the smooth 3D animated look (use pixar-ad, which covers every Pixar-style length), talking-head UGC (novoads-api), or a static image ad.

Novoads Claymation Ad

One product in. A 40 to 70 second hand-sculpted clay ad out, cut from five to eight separately rendered beats, with narration, music and captions.

This is the sibling of pixar-ad and it runs the same pipeline: the same gates, the same calls, the same still gate, the same local assembly. Read that skill for the pipeline. This file owns two things it does not: the clay look, and a narrative arc that is longer and quieter than the Pixar one.

The two are not interchangeable, and the difference is not decoration:

	Pixar storyboard	Claymation storyboard
Hook	an anthropomorphized problem with eyes, speaking	a named person in their kitchen, and a narrator
Arc	4 to 6 beats, a want and a turn	5 to 8 beats, a small life story
Voice	in-scene SYNC plus narration	a storyteller carrying almost all of it
Surface	smooth, wet-eyed, subsurface scattering	matte clay, thumbprints, tool marks
Runs on	want, then relief	affection for a character

Picking the wrong one is not a style mistake, it is a story mistake. If the product's pain is a moment, that is the Pixar skill. If it is a season of someone's life, it is this one.

Every clay ask lands here, including the short ones. There is no one-call clay tier. A five-beat short is the small end of this pipeline, not a different door: still per-beat renders, still ffmpeg, still an assembly.

Before anything: this runs on a Novoads account

1. A Novoads account with credits. https://novoads.ai — the entry offer is a $1 trial, never call it free.
2. An API key in .env at the repo root, as NOVOADS_API_KEY=novo_…. Check it with ./scripts/check-novoads-env.sh; if it is missing, run ./scripts/setup.sh. That is the whole setup: curl and jq, one key, no connector to add and no session to restart.
3. ffmpeg on your machine. The assembly happens here, not on the server. ffmpeg -version before you start.

REST key required. A Novoads MCP connector is not a substitute. If NOVOADS_API_KEY is missing or still the placeholder, stop before any generation work and tell the user: "Before continuing, create an API key at https://novoads.ai/dashboard/settings?tab=api and paste it into .env." That holds even when mcp__novoads__* tools are connected and authenticated in the session. Never call mcp__novoads__* tools from this repo's workflows: they are a different surface with different behavior, including the units they quote costs in. Repo installs verify with ./scripts/check-novoads-env.sh; a solo install checks NOVOADS_API_KEY in the environment.

Pack version. Every /v1 response carries X-Novoads-Pack-Version; mention a newer pack at https://github.com/novoads/agent-skills only when that header names a version NEWER than this file's metadata.packVersion — equal or older is nothing to say, and it is never a reason to stop.

Every HTTP mechanic here belongs to the pack, not to this skill. Auth, strict bodies, status codes, the poll loop, rate limits and error envelopes are written out once in skills/novoads-api/SKILL.md and its reference.md. The per-call fields this genre needs are in pixar-ad's The calls section, which this file shares unchanged.

What one run costs

Two shapes, and the choice is the operator's. What changes between them is the COUNT of the same components, never their kind:

Component	5-beat short	8-beat full
Cast sheet image	1	1
Beat stills	5	8
Beat clips	5 × 6s	8 × 7s
Voice-over lines	5	8
Music bed	1	1
Transcript, then one caption pass	1 each	1 each

There is no price column, on purpose. Every credit number this run shows a user comes from POST /v1/estimates, in this session, before anything is charged: price each KIND once, multiply by the counts above, and quote what came back. A rate written into a skill file goes on being quoted long after it moved.

The clips are most of the bill either way, and a still is a small fraction of the clip it seeds. That is the whole economic argument for the board gate.

Say the shape out loud before pricing it. An 8-beat clay ad is the most expensive thing in this family, and the honest question at Gate 0 is whether beats 3, 4 and 5 are earning the three extra clips they cost. They often are; the arc is what this genre is for. But the operator decides that, not you.

Hard constraints

Everything in pixar-ad's Hard constraints section applies unchanged: one call per beat, 4 to 15 seconds, 9:16, audioEnabled: true, a narrator line in the prompt OR the VO track and never both, one continuous voice, no styleFamily field. Read them there.

Three are different here:

• Five to eight beats, not four to six. The arc is a story and a story needs its middle. Below five beats it is a Pixar-shaped ad in clay, and the Pixar skill will render it better and cheaper.
• The narrator carries the ad. This genre is third-person storytelling, and the narration is not filler between spoken lines the way it is in the Pixar skill. Most beats are VO beats and that is correct here.
• At least one beat is still SYNC. Usually beat 3, the social beat, where a second character says the thing the protagonist has been avoiding. A whole ad of narration over silent faces is the failure this rule exists to prevent.

Two ways in

A. From a product

Run pixar-ad's Gate 0 and Gate 1 unchanged: is the pain emotional, visible on a face, in a relationship, impulse-priced; then the product read. One extra question at this length: does this product have a before and an after that a viewer would recognise a month apart? The transformation beat is the spine of the clay arc, and a product with no visible change does not have one.

B. From a found video

The other entry, and the one this genre is usually asked for: someone shows you a clay ad and wants theirs. Do not guess at its structure from the thumbnail.

Read the reference locally. Follow skills/analyze-video/SKILL.md: frames out with ffmpeg, dialogue out with Whisper, then read the beats off what you extracted. It costs nothing, needs no key, and — unlike a fixed-window reader — it covers the whole runtime, which is what a 60-second arc needs.

There is a hosted alternative, and it is not the default. POST /v1/analyses returns the structured hook/beat/casting breakdown in one synchronous call, priced through POST /v1/estimates with {"kind":"analysis"}. Reach for it only when ffmpeg is missing or the local read has already failed: the local path costs nothing, ffmpeg is a hard dependency of the assembly anyway, and /analyses defaults to reading the first 20 seconds, which is exactly the setup third a clay arc cannot afford to lose. If you do offer it, price it first and let the user choose. See reference.md § Ad analysis is on this API now.

Two things to hold on to whichever way you read it:

• Sample the whole video, not its opening. A clay ad spends its first third on setup, so a read that stops early gives you the hook, the casting and the palette and none of the arc. A board that claims eight beats from a partial read is a board with invented beats in it.
• Write our own story. Recreate the FORMAT, never the script: their protagonist, their brand and their claims are theirs. What transfers is the shape, the palette, the pacing and the narrator persona.

The clay look

Style lock — one paragraph, pasted verbatim into every prompt

Hand-sculpted stop-motion clay look. Plasticine characters with visible
fingerprint impressions and sculpting-tool marks, matte clay surfaces with
subtle micro-bumps, slightly asymmetric features, painted-on or sculpted
eyebrows. Real knit-fabric clothing with visible wool weave and stitch lines,
wooden and ceramic miniature-set props with hand-painted finishes. Warm tungsten
interior lighting, shallow macro depth of field, soft photographic bokeh.
Subtle imperfection in every surface. Vertical 9:16 composition.

Never name a studio or a franchise. The lineage this look comes from belongs to two specific studios, and naming either is both an IP problem and a worse prompt: the model reaches for their characters instead of your sculpt. "Hand-sculpted stop-motion clay" is what the words above are doing.

The negative block

no live-action footage, no photorealistic humans, no uncanny faces, no dead eyes,
no smooth 3D digital render, no glossy surfaces, no ray-traced reflections,
no subsurface scattering, no wet-eye highlights, no anime style,
no 2D illustration, no named or copyrighted animated film characters,
no extra fingers, no melted features, no morphing between frames,
no warped product labels, no on-screen text, no subtitles, no captions

Half of this block is doing a job the Pixar one does not: holding the render away from its own default. The video models smooth clay into 3D plastic over the length of a clip, so no smooth 3D digital render, no glossy surfaces and no subsurface scattering are load-bearing, not boilerplate.

Material detail — paste the lines that apply to what is in frame

Skin: matte plasticine, visible thumbprint impressions on cheeks and forehead,
small sculpting-knife creases at the corners of the eyes, slight asymmetry
between the left and right side of the face.
Hair: sculpted in distinct ribbon-strands of plasticine, individual strand
grooves carved with a tool, slightly stiff and not flowing.
Eyes: small matte clay orbs set into sculpted sockets, a single soft highlight,
no wet shine.
Knitwear: real chunky wool yarn, individual stitches visible, slight wear at the
cuffs and hems.
Wood props: hand-painted matte finish, visible grain, small dents and scratches
that suggest age.
Ceramic: hand-thrown irregular form, glaze pooling at the bottom edges, slightly
off-round.
Product packaging: a clay-shaded prop with a hand-painted label, the paint
slightly uneven and matte.

This block is the difference between clay and a cartoon of clay. Paste the relevant lines into every still prompt. Drop the ones for materials that are not in the frame; a knitwear line on a product close-up buys nothing.

Faces here may be quirky. That is a licence, not a defect

The Pixar sibling chases APPEAL: symmetrical, soft, a moment before a smile. This genre does the opposite and it is the single easiest thing to lose when the two skills sit side by side. Clay characters are allowed to be odd. Oversized noses, deep wrinkles where the sculptor pressed, eyes set slightly unevenly, a jaw that is not quite level. Quirky beats appealing here, and a clay protagonist rendered pretty reads as a 3D render wearing a clay texture.

Say it in the prompt, per character, or the model will smooth it out: "an oversized nose, deep sculpted wrinkles at the eyes, slightly uneven eye placement."

Smooth motion or stop-motion judder

Real stop-motion carries a 12 to 15 fps judder. Our renders come out smooth at 24 or 30, and smooth is the default because it is what the genre's own reference ads do.

If the operator wants the judder, it is a post step and never a prompt:

ffmpeg -i captioned.mp4 -filter:v "fps=12,fps=24" -c:a copy captioned-judder.mp4

Run it before the music bed goes on. music_mix.py stream-copies the picture, so every pass that re-encodes the picture belongs ahead of it — and then the file the mixer measures and verifies is the file you ship.

Asking the render for "stop-motion judder" does not control frame rate and does break the look. Do not put it in a prompt.

The arc

Eight beats, and the operator picks how many of them get made. The beat formulas, the variable tables and the worked prompts are in references/formulas.md.

#	Beat	Seconds	Track	Drop for the short?
1	Setup — the protagonist in their own world	7	VO	keep
2	Inciting moment — they notice the problem	6	VO	keep
3	Social validation — someone else says it out loud	8	SYNC	drop
4	Quiet despair — alone, at a mirror or a window	6	VO	drop
5	Clay infographic — the mechanism, sculpted	7	VO	drop
6	Discovery — they find the product	6	VO	keep
7	Transformation — weeks pass, the change is visible	9	VO	keep
8	Resolution — confident, then the end card	6	VO closes	keep

The 5-beat short is 1, 2, 6, 7, 8 and lands around 34 seconds. It is the right call for a first run with a brand, and it is what the dry run below uses.

Beat 3 is where the SYNC line goes when the short is not being made. When it is, promote the SYNC line to beat 6: the protagonist says one short thing to themselves when they find the product. Do not ship an ad where no mouth ever moves.

Beat 5 is optional even in the full arc. A sculpted clay chart sells a mechanism; it wastes 7 seconds on a product that has none.

Which beats earn their place, by category

Category	Arc	What changes
Supplement, stress, sleep	the full 8	Beat 5 is the one that sells it. Keep the chart
Beauty and skincare	8, chart optional	Beats 2 and 4 carry it: the mirror, then the reflection alone
Office or B2B	the full 8	Beats 1 to 4 in cool fluorescent light, warm only from the discovery on. The palette is the story
Food and kitchen	the 5-beat short	Beats 1, 6 and 7 dominate; if you keep beat 3, make it a family table rather than a cafe

The office row is the one worth reading twice. Everywhere else this genre is warm tungsten throughout; a fluorescent first half and a tungsten second half tells the arc in light before a word is spoken.

Everything else about the board — one action per beat, its own setup, the word budget, VO and SYNC never overlapping in the same beat, no em dashes, never "free" — is the Pixar skill's board section, unchanged.

The cast sheet

Same call, same single image, different contents. Clay ads usually carry two named characters, and the narrator is a third presence who is never on screen.

Write the sheet text first from the template in references/formulas.md, then render it. The template's slots that matter most here:

• A name. The narrator says it out loud, and a named protagonist is most of why this genre works. "Diane" is a person. "A woman in her 50s" is a stock photo.
• Middle-aged or older. The look flatters sculpted laugh lines and hooded eyelids, and the arc needs a life already in progress.
• The terse tag, 11 to 30 characters, anchored on wardrobe. Our renders re-cast on every cut, so this is what carries one face across eight beats.
• A narrator persona, chosen once from GET /v1/voices and reused for every line. Warm storyteller and wry observer are the two that fit; pick one and say which.

The gates

Gates 2 through 8 are pixar-ad's, unchanged, including:

• Gate 2 — price every kind once with POST /v1/estimates, multiply, announce in one line, proceed.
• Gate 3 — every still before any clip, each chained on the cast sheet and the previous still by the assetId that POST /v1/images returns, then STOP at the board gate. At eight beats there are eight clips waiting behind it. This gate is worth more here than anywhere else in the family.
• Gate 4 — clips in waves of at most five. Eight beats is two waves, five then three, because a sixth concurrent POST /v1/videos comes back 429 with details.reason: concurrency_limit, and that is a real refusal, not a queue.
• Gate 5 — one voice, chosen once from GET /v1/voices and passed as voiceId on every POST /v1/voiceovers. Gate 6 — generate the music bed. Laying it is the last thing that happens in the run and it belongs to music-mix and its scripts/music_mix.py, run over the captioned cut, never to hand-written ffmpeg.
• Gate 7 — trim each clip to its narration plus 0.5 seconds, concat, build ONE voice track, composite the end card from the real photograph, transcribe and read it back. Read the mix out of the Pixar skill rather than from here — the clip level is per beat, not one recipe, and this line used to restate it as a flat VO 100% / clip 28% / music 10%. That recipe was written when every beat was a VO beat. This genre has a SYNC beat (beat 3), where the clip's own audio IS the dialogue, and 28% buries it under a caption spelling out words the viewer cannot hear. One number cannot serve both cases, so this file states none — and the bed's level is no longer a number at all, it is whatever the mixer measures.
• Gate 8 — captions, and the BLOCKING caption gate. A garbled brand name is a failed run, not a note in the report.

Gate 7 in particular carries four rules this genre needs verbatim and does not restate here: trim to the VO or extend the VO to fill the shot, never atempo a long line to fit, re-check the caption's vertical position after trimming because the frame at the new cut is not the frame that was there, and build the voice track with amix=duration=longest — first ends the mix when its first input ends, which is how an eight-beat arc ships a silent resolution card.

Do the assembly in outputs/<ad-name>/, not in the directory you started in. The downloaded beats, beats.txt, the trimmed clips, the placed VO lines and the master are one run's working set — a dozen of them loose in a repo root is a diff somebody else has to explain. That includes the judder pass above: captioned-judder.mp4 and the master live there too.

Two caption looks fit this genre, and the preset guidance in the Pixar skill's Gate 8 is how you choose between them. The default is the heavy white sans with a thick dark outline. The alternative, and the one the genre's own reference ads use, is a solid warm-orange rounded block behind white text, sitting slightly tilted in the lower third. No preset renders that block, so it is the one case where the local burn is the right call rather than the fallback.

Two clay-specific additions:

The clay QA is its own check and it is not the Pixar one. Both checklists are in references/formulas.md. The one that matters: the render smooths clay into plastic over the length of a clip. Watch the last second, not the first frame. A still that passed and a clip that ends in glossy 3D is the single most common failure in this genre.

Beat 7's improvement must be localised. "Weeks later" on a whole face produces a different person, which reads as a lie and breaks continuity in one shot. Name the one thing that changed and say that everything else is unchanged.

Output format

Deliver in this order, no preamble:

1. PRODUCT READ — or, on entry B, the breakdown of the reference with a line saying how much of it was actually read.
2. FIT — one line confirming Gate 0, or a plain refusal naming a better format. If the pain is a moment rather than a season, hand off to pixar-ad and say so.
3. ARC LENGTH — 5-beat short or 8-beat full, and why, with both prices.
4. CAST + STYLE LOCK — the cast sheet text including the name and the terse tag, and the paragraph pasted into every prompt.
5. BEAT BOARD — the table. At least one SYNC beat.
6. COST — the POST /v1/estimates figures, announced in one line.
7. Then generate: cast sheet, all stills, stop at the board gate, clips, VO, music, composite the end card, assemble the voice mix, verify, caption, lay the bed with music_mix.py, and read the captions against the script before calling it finished.

The calls

Identical to pixar-ad's call list — POST /v1/uploads, /v1/estimates, /v1/images, /v1/videos, GET /v1/voices, POST /v1/voiceovers, /v1/music, /v1/captions, /v1/transcripts, and GET /v1/generations/{jobId} with its /watch — with the fields each one takes. Entry B adds no endpoint: the reference read is local ffmpeg and Whisper, and spends nothing.

Worked beat prompt

A finished beat 3 (social validation) POST /v1/videos prompt: the SYNC beat, one action, style lock and material detail included, negatives at the end. lib/generation/__tests__/claymation-storyboard-skill-prompts.test.ts reads this exact block and runs it through the same rule engine POST /v1/estimates lints with.

Hand-sculpted stop-motion clay look, vertical 9:16, animating the two characters
in the reference image. A sunlit miniature clay kitchen, green-painted wooden
cabinets, a red gingham tablecloth, warm tungsten light from a window on
camera-left.

Diane, a woman in her late 50s in a cream chunky knit cardigan, matte plasticine
skin with visible thumbprint impressions and deep sculpted laugh lines, sits
across the table from her friend in a sage-green cable-knit sweater.

From zero to three seconds Diane lowers her cup and her sculpted brow furrows.
From three to eight seconds her friend leans in and says: "You have not been
sleeping, have you." Diane holds still and her eyes drop to the table.

Camera: locked medium two-shot at table height, gentle handheld breathing motion,
no dolly, no zoom. Shallow macro depth of field with the window softly out of
focus.

Skin: matte plasticine, visible thumbprint impressions on cheeks and forehead,
small sculpting-knife creases at the corners of the eyes. Knitwear: real chunky
wool yarn, individual stitches visible, slight wear at the cuffs. Ceramic:
hand-thrown irregular cups, glaze pooling at the bottom edges.

Audio: two warm, unhurried voices at a kitchen table, close and intimate, with
faint kettle and street ambience behind them.

Both characters stay visually unchanged from the reference image: same face
proportions, same hair, same wool weave, same clay texture held to the last
frame. no live-action footage, no photorealistic humans, no uncanny faces, no
dead eyes, no smooth 3D digital render, no glossy surfaces, no ray-traced
reflections, no subsurface scattering, no wet-eye highlights, no anime style, no
named or copyrighted animated film characters, no extra fingers, no melted
features, no on-screen text, no subtitles, no captions

Failure modes

Everything in pixar-ad's Failure modes list applies. Four are this skill's own:

• The clay turned into plastic by the end of the clip. The most common failure here. The material detail block was thin or the negative block was missing its anti-smoothing lines. Re-render with both, and add "clay texture held to the last frame" to the constraints.
• The eyes went wet. A Pixar-style multi-catchlight eye leaked in. no wet-eye highlights in the negative block and a single soft highlight, no wet shine in the material block. Both, not either.
• The transformation beat produced a different person. The improvement was described on the whole face. Name the one thing and pin the rest.
• Eight beats and no mouth ever moved. Every beat went to the narrator. Beat 3 is a SYNC beat; if you dropped it for the short, beat 6 is.

Hard rules

• One product per run.
• Stop at the board gate. The operator approves the board before the clips fire.
• Never name a studio or a franchise, in a prompt or in ad copy.
• Never invent reviews, ratings, prices, or performance claims.
• Use the real brand and the real packaging from the photo.
• On-screen text is short words and numbers only, never sentences.
• No em dashes in ad copy. Never say "free" — the entry offer is the $1 trial.
• On entry B, recreate the format and never the script.
• The end card is composited from the real photograph. Never rendered.
• Transcribe the master before you call it finished, and read the burned captions against the script. A garbled brand name blocks the ship.