---

name: write-video-ad-script description: Write a short-form video ad from an evidence-backed angle and the selected template's actual recipe. Reuses or fetches ad-angle-miner, preserves the chosen angle, plans words and visuals together, checks product claims and production fit, and delivers the strongest script with useful alternatives. Use before video production and for script rewrites. Customer language is one input alongside audience, promise, product proof, offer and format. status: active version: "1.0.4"

Human version

Summary. Turn a researched advertising promise into a video this template can actually make. First load the angle research, then bind it to the recipe's story, visuals, timing and assets. Write and check the complete concept before the user reviews it. The output is one recommended script, its visual plan and up to two viable alternatives. A model score is a quality screen; ad results establish performance.

---

Agent version

When to use

Use before production for voiceover, dialogue, chat, cards or lyrics. For a silent format, still plan its visual promise and payoff; skip spoken copy, not creative strategy.

When the user supplied exact lines, keep them verbatim. Check them in report-only mode and raise material timing, claim or format conflicts. Rewrite only with their authorization. This skill adds no review round of its own; the script goes into the run's existing review.

Inputs and precedence

Read this skill's files reference before creating working files. Required context:

• The brand and exact product, current facts, voice and prohibited claims.
• Audience, campaign objective, offer and CTA, using saved context and brief first.
• The selected template and full recipe: instructions, config, choices, assets and inputs.
• A validated angle context from ad-angle-miner, including source records.
• Reference footage or its observed beat map, plus available brand assets.
• The current sourced creative brief and applicable project/brand decisions, including exact rejected wording, pronunciations and user-locked copy.

The user's explicit direction and chosen angle are fixed. The recipe determines what is possible. If those conflict, explain the concrete conflict and offer a compatible execution or format before production. Do not silently replace the angle or rewrite the template. A reference provides a storytelling structure; the product's facts provide claims.

Step 0. Load the angle research, explicitly

Load ad-angle-miner with catalog_fetch {type: "skill", slug: "ad-angle-miner"} unless its instructions and handoff reference are already loaded; fetching it does not run research. Reuse an existing angle bank (this run, the brief's pointer, the product's saved angle-bank.json, then legacy miner output), normalize it to video-angle-bank.v1 with the preparation script, and keep the selected angle. With no usable bank, run the miner in video mode for this audience, product and template. Follow angle research for the order, the checks and what to record; never claim the miner ran when it did not.

Step 1. Bind the template before writing

Read the actual recipe, not just its catalogue card. Write shape.json with:

• Template id, format, story mechanism, audience and objective.
• Ordered slots, speakers, text kind, durations and explicit word/character/line limits.
• Product entrance, proof device, payoff and CTA placement allowed by this recipe.
• Available asset ids, permitted visual modes and any required demonstration.
• What can change and what stays fixed, including silence, music or lyric constraints.

For speech, read pacing. Set the desired cadence from the brief's explicit delivery direction or observed reference audio, then the recipe's default. Preserve explicit recipe limits and record any conflict. Without usable evidence, use a provisional 3 words per second for conversation or 2.5 for slow narration, labelled as a fallback.

Budget each spoken beat from its speech window, excluding pauses, silent demonstrations and end cards. Rates can differ across beats and speakers. Record the rate's source and keep recipe estimates separate from observed rendered delivery. Carry this plan into production direction. Read chat and cards against their own display time; lyric timing follows bars and syllables. A word estimate does not prove that a generated read fits. Do not change the recipe to express one run's target or promise forty words in fifteen seconds.

Examples of adaptation, not a fixed format catalogue:

| Recipe | Script must do | Failure to reject | |---|---|---| | iMessage conversation | Build a believable exchange and reveal through short turns | A sales monologue split into bubbles | | Product demonstration | Pair a supported benefit with a visible action or test | A testimonial over unrelated beauty shots | | Creator narration | Match what is said to what appears at that moment | Invented personal results or unavailable footage | | Silent product loop | Express one visual promise through reveal and final card | Forcing a spoken problem-solution script into it | | Music or lyrics | Make the product story work within musical timing | Treating a lyric as ordinary voiceover |

If the recipe lacks enough information, inspect the demo and capability instructions. Record any provisional timing. Resolve essential missing assets before approving a production plan that relies on them. In a requested writing-only test, specify the exact missing capture or reference and mark the draft not production-ready. A planned demonstration is not verified proof; never generate a fake UI to fill the gap.

Step 2. Form the creative brief

Before drafting, read current product evidence and the project's saved history, then save creative-brief.json (files reference): variant, buyer situation, supported mechanism, objective, offer (or "no offer supplied"), CTA, constraints, prior decisions with exact rejected wording, locked words and delivery intent. Pass it to prepare_angle_context.py --brief. Establish the message before choosing a reference. Buyer language sets voice; it never substantiates a claim, and fiction never poses as a real review. Follow the creative brief and buyer perspective and product explanation.

Step 3. Learn the reference's persuasion

Read the recipe's demo lines and timing, or inspect its footage when they are missing. Add at most three relevant references from existing research. For each record the opening visual and words, beat order, product entrance, proof, objection, payoff and CTA. Record what transfers and what belongs to the source brand.

Match the reference's persuasive purpose to the creative brief, not just its category or visible action. Complete inspection establishes what is in the source; it does not make the source appropriate for this brand. Reject an unsuitable transfer before writing.

For dialogue, load dialogue-writing. A format description, product page or imagined beat map is not an observed conversation. Reuse the miner's sources first; retrieve missing references when access is available.

For a street ad, inspect a complete commercial clip: its full visual interaction and spoken exchange. Record the edited opening, visible setup, why the participant engages, viewer hook, product connection, payoff, and any unseen approach as unknown. Match the offering and visible interaction (sampling, mic-only service conversation, or challenge), not just the format name. Keep ordered timestamped turns with words and actions; label paraphrases and retain the full transcript evidence separately. A hook snippet or an editorial radio interview cannot fill this gap. Load the selected renderer's [[references::render-street-interview]] street-script-writing guide and run its selector. If it returns needs-reference or unsupported-route, stop before writing dialogue for approval: report the gap and its listed alternatives. A provisional creative review, or a note that no complete reference was observed, is an open gate, not a pass. Seed summaries are source leads until a complete project observation replaces them.

For a podcast, an appropriate publisher transcript can establish turn structure. Editorial conversation may be provisional evidence of that mechanic, with missing commercial context explicit. Neither a transcript nor sampled frames establishes vocal delivery; record what was actually heard or viewed. Authorship and ad performance remain unknown unless independently evidenced.

Keep performance labels honest: running duration and variants show advertiser persistence; views show reach or engagement. Neither proves conversions, profitability or causal lift. Use measured first-party results when available and keep audience, placement, objective and measurement window attached. Never describe an untested reference as a proven winner.

Step 4. Choose distinct angle–execution pairs

When the angle is open, work from up to 10 researched candidates. Filter unsupported promises and incompatible executions first, then shortlist up to three with genuinely different promises or proof devices. Do not create ten paraphrases to fill a quota.

When the angle is selected, keep its id and promise. Write one concept with hook variations, or several executions within the same direction when useful. Batch assignments should be different where the brief permits, and use the bank once per brand and product.

Rank relevance, product credibility, template fit, feasible proof and hook payoff before freshness. Prefer clear, well-supported familiar angles over obscure weak ones. No arbitrary novelty cutoff. Fewer than three good concepts is better than padded alternatives.

Step 5. Write words and visuals together

Load scene and hook before writing dialogue. Plan the encounter, the literal first 0–3 seconds and the story's development/payoff first. Separate the participant's filming context from the context actually given to a new viewer. A complete question can be the hook; a reply-first opening needs its subject or task established in the retained picture, words or rendered text.

For every beat write the exact line, speaker, visual action, production mode and existing asset ids when applicable. Keep a proof plan and a claim ledger with current product fact ids. Every hook variant must lead into the same body's promise; repair the body when the promise changes.

Tie each material claim to the moment its demonstration is visible. Include action completion, recognition and text-reading time in the existing scene plan. Inspect the actual selected media before calling that plan feasible; metadata is a shortlist. Keep product truth/style references separate from usable production footage. If the needed proof is absent, narrow the claim or specify the missing capture; do not treat a simulated result as evidence. A useful silent format still communicates through exact on-screen words and visible actions, with no invented speech.

• Make the first moment intelligible and worth watching through words, visuals or both.
• Keep one main promise and pay it off visibly.
• Use the product's actual mechanism, differentiator or demonstration where the recipe fits.
• Match dialogue, cards and lyrics to their medium and the brand's voice.
• Make the offer and CTA clear. Respect the recipe's ending and permitted CTA placement.
• Brand visibility depends on objective and format. Do not ban an early product or brand simply because it is early.
• Include only supported product claims. A source id is traceability, not a semantic check.

For conversational formats, write the exchange before allocating it to timed slots. Use human speech and behavior, with matched language evidence and th