---

name: write-video-ad-script description: Write or revise a short-form ad from a sourced angle and reference. Plan connected words, product proof and sound; expose production gaps before script review. status: active version: "2.0.3"

Human version

Summary. Turn a researched advertising promise into a feasible video in the requested format. First load angle research, then bind it to the agreed 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 format/route and any actual template recipe: capabilities, 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. Actual route capabilities determine what is possible. A supplied reference controls the agreed custom structure; templates supply compatible components. Expose concrete gaps and feasible alternatives within existing review, without silently replacing angle or required demonstration. 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 reference, format and production route before writing

Read the actual selected route/recipe, not just its catalogue card. For custom work, carry the agreed reference structure and real capability limits into shape.json:

• Actual selected template/route identity, 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 custom work, read reference and performance. Map actual source intervals to adapted lines, actions/proof and sound. Preserve agreed reference structure rather than force nearest-template scene count or pace. Keep speech separate from music/ambience/effects and intentional total silence.

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 actual reference/demo lines and timing, inspecting complete picture and sound. Frames/transcripts alone cannot establish delivery, continuous action or soundtrack; record missing duties and keep source observations distinct from adaptation. 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, including picture and speech. Record opening, setup, engagement, hook, product connection and payoff; mark unseen approaches unknown. Match the actual offering and interaction. Keep timestamped words and actions, label paraphrases and retain the full transcript. Snippets, radio interviews and seed summaries cannot replace this observation. Run the selected renderer's street-script-writing selector (in the render-street-interview skill). Needs-reference or unsupported-route stops approval; report the gap and supported alternatives.

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. Prefer measured first-party results, with their context. Never call an untested reference 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 write 4-5 concepts with different promises and openings, each a different angle type (angle_type, listed in the files reference) chosen by what the viewer already knows; see hook families. When the angle is selected, keep its id, promise and angle type, and write 4-5 executions that differ in hook family and opening. Batch assignments differ where the brief permits; use the bank once per brand and product.

Rank relevance, product credibility, template fit, feasible proof and hook payoff before freshness: a clear, supported familiar angle beats an obscure weak one. If the evidence supports fewer than four distinct concepts, write fewer and say why; never pad with paraphrases.

Step 5. Write words and visuals together

Read hook families before writing hooks, voice before any line (draft 3 hooks each), and 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, its on-screen words (13 or fewer; 8 in beat 1), speaker, visual action, production mode and existing asset ids when applicable. Beat 1's picture, line and on-screen words must say the same thing. 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 silent format communicates through exact on-screen words and visible actions, with no invented speech.

• Make the first moment intelligible and worth watching, with or without sound.
• 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; early is not wrong by itself.
• Include only supported product claims. A source id is traceability, not a semanti