Update to HeyGen

{
  "description": "Write and revise spoken video scripts for UGC, explainers, talking-head videos, and picture stories. Use for audience-focused hooks, clear narrative development, evidence-based claims, and useful endings before video or narration production.",
  "included_files": [],
  "name": "script-writer",
  "skill_md_contents": "---\nname: script-writer\ndescription: Write and revise spoken video scripts for UGC, explainers, talking-head videos, and picture stories. Use for audience-focused hooks, clear narrative development, evidence-based claims, and useful endings before video or narration production.\n---\n\n# Script Writer\n\n## 1. Establish the viewer promise\n\nWrite for a listener who hears the words once while watching a changing image. Deliver a script that can be spoken naturally, supported visually, and fulfilled within the brief. Writing a script does not authorize voice or video generation.\n\nInherit the parent workflow's audience, topic, target outcome, approximate runtime, destination, language, tone, evidence, and approval requirements. For standalone writing, ask only for gaps that materially affect the result; propose sensible defaults for minor creative details. Distinguish a product name from the viewer's reason to care. Finish this sentence privately: “After watching, this audience will understand/feel/do ___ because they have seen ___.”\n\nApply the format-specific guidance below for [UGC](#7-ugc-videos), [explainer](#8-explainer-videos), [talking head](#9-talking-head-videos), or [picture story](#10-picture-story-videos). Preserve a user-provided structure when it works. The parent owns production tools, scene limits, voice choice, and approval gates; these writing patterns do not replace those rules.\n\nKeep a brief evidence ledger for factual work: claim, supporting source or supplied material, qualification, and what the image can honestly demonstrate. Verify uncertain, time-sensitive, or consequential claims. Do not turn a generated image, animated chart, or scripted creator into evidence. If a fact is missing, ask for it, narrow the statement, or label a hypothetical example; never invent precision.\n\n## 2. Build an argument or story with forward motion\n\nStart with the actual subject: a concrete problem, consequential question, observable action, misconception, or surprising but supported contrast. The hook makes a promise the video can deliver. Avoid greetings, “in today's video,” vague superlatives, false urgency, and an unexplained logo intro. Choose one hook internally unless the user asks for alternatives.\n\nDevelop the middle through causes, evidence, choices, and consequences. Each beat should change the viewer's understanding or the story's situation. A useful sequence is **question → necessary context → mechanism/action → example or proof → implication**. Adapt it; do not force every story into identical slots. If removing a sentence loses neither meaning nor momentum, remove it.\n\nUse transitions that explain relationships: why the next step follows, what changed, or what problem remains. “Next,” “also,” and “finally” cannot do all the structural work. Resolve one question before opening another unless the brief calls for a deliberate mystery. Do not postpone the entire payoff to a last-second reveal when earlier partial answers would sustain interest.\n\nEnd by delivering the promised answer or changed state. Then choose **one** appropriate close: a concrete next action, a practical test the viewer can try, a meaningful implication, an emotional resolution, or a question made more interesting by the explanation. Avoid generic “What do you think?” endings, unrelated engagement asks, a recap that repeats every line, and several stacked CTAs. Let an informational or reflective video end without selling something.\n\n## 3. Write for the ear, with human energy\n\nUse familiar words, concrete nouns, active verbs, and sentences that fit a natural breath. Vary sentence length so short lines earn emphasis rather than making the whole script choppy. Address one viewer; contractions and direct questions can help when they suit the speaker. Read the actual words aloud when possible and revise places that snag, require backtracking, or hide the main clause.\n\n**Be engaging without “presidential” talk.** Avoid ceremonial openings, grand collective declarations, portentous parallel phrases, and inflated language about transformation. Do not manufacture authenticity with repeated “honestly,” “literally,” “game changer,” or verbal filler. Give the voice something specific to notice, explain, or feel.\n\n| Weak copy | Stronger shape |\n| --- | --- |\n| “Today, we stand at the dawn of a revolutionary new way to plan.” | “Your calendar is full. Which task actually needs that time?” |\n| “This innovative solution provides unparalleled convenience.” | “The handle folds flat, so it fits in this drawer.” Only use when verified. |\n| “There are a variety of factors that contribute to the outcome.” | Name the relevant factor and explain what it changes. |\n\nIntroduce a technical term with the concrete idea it names, then use it consistently. Give pronouns clear referents. Prefer one useful example to several abstract restatements. Use analogy to illuminate a mechanism, and state where it stops matching when that matters. Avoid a metaphor that creates the wrong mental model.\n\nMake numbers speakable and interpretable: pair quantities with units, denominators, dates, or comparisons needed to understand them. Retain qualifications and negations. Put long source details in notes unless attribution is essential to the spoken claim. Pronunciation hints belong outside the script until an approved speech-ready form is chosen.\n\n## 4. Write sound and visuals as partners\n\nSeparate **exact spoken text** from **visual direction**, **on-screen text**, **sound cues**, and **source notes**. Stage directions must never be sent to speech synthesis. Describe what changes on screen, not simply “relevant B-roll” or “nice animation.” Let narration explain the relationship or significance while the image makes it visible; avoid narrating every obvious action.\n\n**Use time as the primary information hierarchy.** Introduce an idea, let its evidence register, then change or replace it. Do not write several simultaneous ideas that can only fit as a page of labels. Give dense diagrams, unfamiliar terms, and consequential reveals space. Plan chapters and recurring motifs that orient the viewer without mechanically adding divider cards or slogans.\n\nCaptions remain valuable for access and silent viewing. Avoid additional duplicate headings and decorative text competing with them; preserve requested or default subtitles while removing irrelevant visual clutter. Detailed text choreography belongs to [captions](../captions/SKILL.md), and explanatory state design belongs to [motion graphics](../motion-graphics/SKILL.md).\n\n## 5. Budget for natural delivery\n\nEstimate spoken length before approval, including room for breaths, visual comprehension, and a resolved ending. As a house starting point, many short English scripts fit around 110–140 words per minute; a dense 60-second explainer may begin around 110–135 words. Language, speaker, age, terminology, and tone change the fit. These ranges are editorial estimates, not universal speaking rates or proof of duration.\n\nIf the draft is too long, narrow the promise, remove repeated explanation, simplify phrasing, or cut a secondary example. Preserve evidence and necessary qualifications. Do not solve excess copy by instructing the narrator to rush or by planning post-production time compression. If an exact supplied script conflicts with a hard duration limit, show the conflict and obtain permission before changing it.\n\nWrite the full through-line first, then split into beats or scenes. Carry sentences across visual cuts when useful. Actual speech audio establishes final timing later; never present estimated beat times as measured word alignment. Once narration exists, revisions to spoken content require the parent workflow's approval and regeneration rules.\n\n## 6. Review and deliver the usable script\n\nDo an editorial pass for the hook's truth, causal/story continuity, spoken clarity, factual support, tone, visual feasibility, and payoff. Test the script against the intended audience's knowledge, not the writer's familiarity. Read the middle and ending with the same care as the first line. Check that the strongest claim retains its qualifier and the most prominent on-screen phrase does not invert its meaning.\n\nDeliver the complete spoken script, a compact beat/scene plan with estimated durations and visual changes when useful, and only the production/source notes needed for execution. Keep a clean speech-only version. Identify unresolved claims or pronunciation issues before generation. Do not overwhelm the user with several drafts when one polished version is requested.\n\nHonor the parent's review gate. Faceless-explainer requires confirmation of the complete spoken script before narration. Picture-story first generates one asset-board image, then presents that board and the complete script together for a single approval before narration and batched scene-picture generation. Do not ask for script approval separately while its board is still pending. Talking-head and UGC retain their own rules. For standalone scriptwriting, deliver the requested draft without adding a generation approval ceremony. Supporting skills inherit accepted decisions and do not restart intake.\n\n## 7. UGC videos\n\nWrite around an observable situation and a specific reason to care. A practical arc is **recognizable friction → demonstration → observable result → relevant next step**. Lead with the action or concern, not a résumé of the creator or a list of product adjectives. The product should earn the claim through what the viewer can see or through verified supplied evidence.\n\nUse a natural, concise creator voice. Do not invent scarcity, discounts, or guarantees.\n\nUGC claim rules: positive everyday benefits evident from the product's design and category (\"easy to carry\", \"slips into a bag\") need no source. Testimonial-style lines, usage history, statistics, and comparisons are allowed: use supplied ones as written, and mark any the user did not supply \"[confirm]\" in the script table so the user's approval covers them. Never make medical or health claims. Preserve an authorized real testimonial's words and scope. Do not infer voice-cloning consent from a photo or quick video, repeat resolved consent questions, or invent category bans beyond actual HeyGen and host requirements.\n\nAdapt the script to the selected UGC format:\n\n| Format | Narrative spine | Writing decision that matters |\n| --- | --- | --- |\n| Product | Need → distinct demonstrations → visible payoff | Tie each benefit to a different useful action; avoid repeating the same beauty shot in words. |\n| Review | Specific question → evidence → grounded assessment | Explain who the feature suits and any material limitation; never invent a real testimonial. |\n| Unboxing | Expectation → opening → one reveal → inspection | Preserve discovery order. Don't announce unseen contents early or reopen the package in a later beat. |\n| Tutorial | Goal/prerequisites → verified ordered actions → completion check | Each line must match an achievable step and its visible result. Don't omit a prerequisite for pace. |\n| Try-on | Outfit reveal → silhouette/fit evidence → material/movement → final look | Let the view establish what is visible. Don't claim all-day comfort, durability, or sizing history without evidence. |\n| Website | User problem → actual UI action → visible result → next step | Write to the real captured interface and exact labels. Never invent a feature because the copy needs a payoff. |\n\nFor commercial work, connect attention, meaningful product or brand presence, audience relevance, and a clear next action. Introduce the product naturally through its role in the story. Adapt sound and framing to the destination without treating a hook/body/close structure or a fixed cut frequency as a performance guarantee.\n\nKeep one audio owner per beat. A visible speaker's line belongs to that performance; an off-screen explanation can bridge close-ups when the parent supports it. Do not write overlapping creator dialogue and voiceover that say the same thing. Physical demonstrations need enough time to complete, even when the script is short.\n\nExample shape for a verified folding object: “This is the awkward part: where does it go afterward? Fold the handle here. Now it fits in the drawer. Check the folded dimensions against your space.” The actual product, action, and fit must be verified; this is not reusable factual copy.\n\n## 8. Explainer videos\n\nChoose a question narrow enough to answer. Make the audience's starting model explicit privately: what do they think happens, what is missing, and what should change in that understanding? Start on the tension, then show the mechanism. A list of benefits or facts is not an explanation.\n\n**Explain clearly and thoroughly within that promise.** For each central concept, establish what it means in concrete terms, how it works, why one step causes the next, and what follows in a worked example. Supply the missing reasoning between true statements. Do not glide past the mechanism with polished, sweeping, or presidential declarations such as “Constraints shape outcomes” or “Technology changes how we work.” Naming a concept, listing its parts, or asserting its importance does not teach it. Depth comes from resolving the viewer's likely how/why questions, not from adding jargon or more topics.\n\nKeep one example alive long enough to trace its starting conditions, intermediate steps, and result. For a short explainer, spend most of the explanatory time inside that example; an eight-second example buried in a two-minute survey does not supply depth. Explain an analogy's mapping and relevant limits rather than letting it stand in for the mechanism. If the time budget cannot support that explanation, narrow the scope; do not compress it into a laundry list. Preserve exact supplied wording unless revision is authorized, and flag a depth/runtime conflict before production.\n\nUse **concrete question → example and essential terms → causal steps within the example → changed condition or limit → answer** as a starting structure. Research factual mechanisms and consequential claims before approval; keep evidence and uncertainty in working notes. Introduce names before asking viewers to track them in a diagram. For each causal link ask what changes and why: “equipment improves output” needs an account of the task, delay, or constraint the equipment changes. Each step should enable a visible demonstration, not just another labeled box.\n\nControl concept density separately from speaking speed. Introduce a new term only when needed, show its role, then give the result time to register before the next relationship. A normal words-per-minute rate does not make a rapid tour of unrelated concepts understandable. Preserve a broad overview when explicitly requested, but connect it with one central question and distinguish what is explained from what is merely summarized. End by using the example to answer the opening or predict a new case; avoid broad aspirations that the demonstration has not established.\n\nPlan small payoffs throughout. In a short explainer, two or three connected beats can function as chapters without formal labels. In a longer one, each chapter answers a sub-question and earns the next. Use a recurring concrete motif to preserve orientation, then transform it as the explanation develops. Do not repeat the hook in every chapter. Chapters orient the viewer, but fixed-playback video still needs sufficient reading and comprehension time within each beat; a chapter marker cannot substitute for a useful hold.\n\nAn original worked example: “Imagine a team prepares six requests an hour, but one reviewer can approve only three. Each hour, three more requests join the waiting pile. Adding another preparer would send even more work to that same reviewer, so it could not increase the number approved. Instead, keep arrivals at six an hour and raise review capacity to six. New requests now stop adding to the pile, but the existing backlog remains; clearing it requires spare review capacity or fewer arrivals.” Identify these as illustrative numbers and assumptions. Reveal the incoming work, review limit, accumulating queue, and changed outcome in order. This explains the constraint instead of merely saying that bottlenecks matter.\n\nBefore approval, check whether the intended viewer could explain the mechanism back and predict what changes if one condition changes. Repair unexplained leaps, undefined terms, and conclusions that only repeat the premise. Correct facts and confident delivery alone do not pass this check.\n\nEnd with the mental model in usable form, a practical observation to try, or an implication that changes how viewers see the subject. A reflective question should be specific enough that the explanation helps answer it. For commercial explainers, make the CTA follow the demonstrated value. For factual topics, retain uncertainty and important exceptions.\n\n**Faceless-explainer:** default to about **two minutes** unless the user specifies otherwise. For an unfamiliar mechanism, roughly 190–240 English words is a starting estimate, with room for reasoning and resolved visual holds; word count is not a quota. Build one central question, one sustained example, and usually two to four causal steps. Style-matched illustrations can establish the concrete world while motion graphics demonstrate the mechanism. Follow the parent skill's two-batch image plan and combined script/visual-plan approval. Narration is created first after script approval; actual audio replaces provisional timing, and visuals follow speech rather than equal-duration slides.\n\n## 9. Talking-head videos\n\nWrite something a person can plausibly say to another person. Start with the point, a question, or a concrete observation. Develop one argument with a specific example or evidence, then land the takeaway. Personal warmth can come from specificity, honest uncertainty, a useful aside, or a restrained moment of humor; it does not require artificial filler.\n\nDistinguish the presenter's real perspective from a scripted promotional role. Do not invent an anecdote, credential, emotion, or lived experience and attribute it to a real person. Use the supplied speaker's vocabulary and authorized positions. Preserve an exact supplied script unless revision is authorized.\n\nKeep most sentences easy to deliver in one thought. Vary rhythm and leave room for an expression, breath, or important line to land. Put emphasis/delivery notes outside spoken text. If the argument only works as dense written prose, rewrite it before generation rather than relying on subtitles to rescue it.\n\nPlan which ideas benefit from the face and which need evidence. A personal statement, qualification, or invitation may belong on the presenter; a mechanism, product detail, or numerical relationship may need a cutaway. Write narration that flows across those cuts without “as you can see on this slide” filler. Do not require constant jump cuts, punch-ins, or changes to the presenter's framing.\n\nThe [talking-head workflow](../talking-head/SKILL.md) keeps avatar picture and dialogue at natural speed and preserves its native composition. The script should fit that performance. Do not plan to accelerate A-roll or crop away its background to accommodate dense copy or labels.\n\n## 10. Picture-story videos\n\nWrite a through-line that can be represented as a sequence of distinct pictures. For narrative, develop **want → obstacle → choice → consequence → resolution**. For educational material, develop **question → depicted states → explanation → takeaway**. Give each picture a clear state or moment; a still cannot visibly perform several successive actions at once.\n\nUse concrete actions, settings, and consequences that pictures can establish. Let narration supply motives, relationships, context, or changes that the image alone cannot convey. Avoid both extremes: describing every visible detail or telling a story the images cannot possibly support. Make spatial or temporal transitions clear when the picture changes.\n\nMaintain entity names, appearance, setting, chronology, and relevant object state across scenes. Do not reset a solved problem, reveal an object before it enters the story, or accidentally change the protagonist's goal. Keep fictional invention distinct from historical claims; a generated reconstruction is not documentary evidence.\n\nWrite continuous narration first. Under the [picture-story workflow](../picture-video/SKILL.md), the approved script becomes one narration master. Plan picture changes around meaning and actual word timestamps: one sentence can use several pictures, and one picture can remain through several sentences. Vary shorter cuts with longer holds according to what the viewer needs to understand; do not impose sentence boundaries or equal picture durations on the edit.\n\nExample: “The gate stayed shut. Mira waited” can share a picture of the closed gate. “Then she noticed a gap, followed the path, and reached the garden” can use several pictures within one sentence. Distinct depicted states serve the story; neither punctuation nor a fixed cut quota determines their timing.\n\nHand the full spoken script to the picture-story parent for presentation alongside its generated asset board in one confirmation turn. After both are approved, hand the text to narrator for continuous speech and plan distinct scene pictures internally for batched generation and Python editing. Reuse character identity and style, never a finished scene image in a later interval. Keep character dialogue and narrator lines distinguishable, and do not imply animation when the output consists of static pictures.\n"
}