ratava/videoexpress-scripting-skill

VideoExpress Scripting

Produce a production-ready prompt pack: a living document that maps a full piece (song, narration, story) onto a sequence of clips, each with a start-image plan and a paste-ready VE multishot prompt. Then support generation: diagnose reported failures, fix them globally, sweep every affected clip.

Two facts drive almost everything in this skill:

1. The model renders nouns, not intentions. Every noun, count, simile and stray token is a candidate to appear on screen.
2. Each generation only knows what it is given. A chained clip sees one still image (the previous clip's last frame) plus the prompt. It has no memory of the previous clip's motion, of anything that was out of frame, or of earlier prompts. Anything not visible in the opening frame or described in the prompt will be invented.

Where to read next

Read only what the current step needs. Everything in references/ is self-contained.

When you are…	Read
Starting a new project, or the user has a concept or script	references/project-intake.md — the question system, feasibility check, development tests, brief and Core Bible sign-off
Writing or revising character, outfit or location blocks; start images; Consistent Character references; non-human characters	references/bible.md
Choosing a look, or writing any prompt in a Create Mode or custom style	references/styles/README.md (shared recipe and index), then the one style sheet you need
Writing any video prompt	references/multishot-template.md — the tag structure, blank template and worked example
Planning the clip grid, chaining, camera moves, or any [ACTION] segment	references/camera-and-motion.md
Writing [LIGHT AND IMAGE] or [PRODUCTION SOUND], any clip with speech, or point-of-view / HUD shots	references/light-sound-dialogue.md
Writing or debugging any prompt; the user reports a failure	references/prompt-rules.md — how the engine reads a prompt, and the failure → cause → rule table
Asked to drive app.videoexpress.ai with a browser-capable agent	references/browser-workflow.md — read first, follow step by step

For a single prompt request mid-project, the usual set is multishot-template.md + prompt-rules.md + whichever of bible.md, camera-and-motion.md, light-sound-dialogue.md and a style sheet the clip touches. For a reported failure, start with the table in prompt-rules.md.

Workflow

0. Intake — run references/project-intake.md (after the what's-new questions below, if this is the skill's first use in the conversation): starting point (concept or script), decision checklist with suggestions, feasibility check, any development tests, sign-off on the brief and Core Bible.
1. Concept — scenes, motifs, characters, world, and a visual arc mapped to the source's structure (below).
2. Bible — locked character blocks, outfit blocks and location blocks, written once and pasted verbatim everywhere (bible.md).
3. Timing — a clip grid at the tool's clip length, with key hits verified against the real audio by the user (camera-and-motion.md).
4. Prompt pack — start-image prompts and multishot video prompts for every clip (multishot-template.md plus the relevant references).
5. Generation support — diagnose reported failures by mechanism, fix them globally, sweep every affected clip (prompt-rules.md).

When the script is signed off, start production in the same reply: if the assistant operates VE, ask whether to open the VideoExpress tabs in the browser now, and give the first paste-ready prompt with its settings whoever operates (references/project-intake.md, Starting production).

The pack is a living document. Expect many revision rounds as the user generates clips.

First use in a conversation: what's new

The first time this skill is used in a conversation, whatever the user's first message is (a new project, a single prompt, a question about the skill, a reported problem), ask these before anything else, as yes/no questions, one at a time, with numbered options where the platform has no question widget:

Once per version where memory allows. First check any persistent memory you can read (the assistant's saved memories, a project memory file) for a note that this version's what's-new questions were already shown. If there is one, skip both questions. If not, ask them; then, if memory is on, save the one-line note "VideoExpress Scripting [version]: what's-new shown." and tell the user once: "I'll remember you've seen this, so I won't ask again for this version." Without memory, or when no note is found, ask as below: asking again is the safe fallback.

1. "VideoExpress Scripting has been updated to version [version]. Would you like a quick summary of what's new?" Take the version from this file's metadata.version, without any -dev suffix. On yes, read references/changelog.md and show its current release notes (the file's opening line says which sections) as a bulleted list: a short heading per version, newest first, then one short bullet per Headline and New item (a version's Fixed items can share one bullet). Never fold the notes into a sentence or a parenthesis.
2. For each Headline item in those current release notes that has a question, unless its "Skip if" condition holds: ask its question. On yes, give the install link and say it opens the install steps: for VideoExpress Prompt, https://github.com/ratava/videoexpress-scripting-skill/wiki/Install-VideoExpress-Prompt (the page has a section for each platform, including ChatGPT and Grok).

Then answer the user's first message, or start intake for a new project. If the skill was started with no message of its own (only its name or slash command), treat it as a new project: go straight to the "How do you want to start?" card (references/project-intake.md, Step 1), as a question card (numbered options where the platform has no question widget), not a prose menu. When the first message already says what is wanted (an idea, a script, a single prompt, a failed take), act on it without asking what the user wants. Ask the what's-new questions once per conversation, never again later in it.

Name the conversation after the project. Once a new project has a working title (from the user's idea or the brief), rename the conversation to "[title] · VideoExpress" if you have a tool that renames it (Grok can rename its chats; ChatGPT can't). Otherwise leave the name as it is.

Concept design

• Design 2–4 recurring motifs that carry the video (an accent colour, a gesture, a light effect, a returning prop). Motifs give continuity AI generation can't provide on its own.
• Map source structure to a scene table: scene → time range → clips → outfit → location → motif state. Escalate motifs across scenes.
• Key moments deserve visual events. Big hits or key lines get reveals or bursts of motion, build-ups get stillness so the hit lands, and scene changes land on section boundaries.
• Give each scene a logical opening. Establish the character arriving, noticing something, or reacting before the main action.
• Favour what generates reliably: steady camera moves, light changes, drifting atmosphere, one clear subject. Spectacle in the background, performance in the foreground.
• Dialogue is lip-synced two ways (a quoted line in the multishot prompt, or the Lipsync HD dialog; see light-sound-dialogue.md). In shots without dialogue, keep mouths closed or out of view so no speech is invented, and never end a clip with something in the mouth or food in a hand if the next clip has dialogue.
• Background interest (vehicles, crowds, city life) is named explicitly and kept at a distance so it never crosses the subject.

Rules that apply to every prompt

These are the ones that cause the most damage when forgotten. The references hold the detail and the rest.

• When following a prompt pack, every prompt starts with its clip reference in square brackets, exactly as the pack declares it for that image or clip: [Clip 12] for a video prompt, [Image 12A] for a start image, [Clip 12 TEST 1] for a test variant. It comes first, before any style anchor or [REFERENCE USE], so every library tile and take can be matched to the pack. Details in multishot-template.md.
• Bible blocks are pasted word for word. Paraphrase is drift. When a start image nails the look, the video prompts reuse that image prompt's exact wording, not the bible's older wording.
• Match the frame, not the plan. Look at the chained opening frame or accepted start image before writing: describe props, framing and the geometry of obstacles exactly as the frame shows them.
• Quotation marks mean speech. Quote each spoken line once, in [ACTION], and quote nothing else. Two speakers per clip, maximum.
• Positives everywhere except [NEGATIVES]. VE reads every other section as things to include, even with "no", "not" or "never" in front, so state what should exist and what stays still, and put every exclusion in [NEGATIVES], each written with "No" ("No music, no hum"). Lead every segment with the subject's motion.
• Camera: locked unless asked, every move named identically in every clip, every move has a destination, never return to space that has left the frame. Never write a move relative to another clip.
• A detail holds only at the size VE last drew it. A push-in that enlarges a face or prop, or a prop that leaves the frame and comes back, makes VE redraw it from text. Start each clip from a start image at its closest framing; a closer shot is a new clip.
• Chaining: flag detail risk, don't dictate. A chained clip opens on the take's last frame, and a detail holds only at the size VE last drew it. When a planned chain risks detail drift (a closer framing than the last frame, a pull-away and return, a detailed face or prop small in the last frame), say so once per project or pack section (an episode, say) in that section's Global rules, with the options: keep the framing matched, re-roll the parent, or start from a new start image. How to chain is the user's choice.
• No counted events; no lettering promised. Describe screens, signs and other text-bearing objects as abstract shapes and light.
• Effects add light, never replace it. Keep a key light on the subject; restate brightness in the final segment; never chain from a darkened frame.
• One [PRODUCTION SOUND] block per segment, with the segment's time label; a single block after the last segment binds to that segment only and leaves the rest to VE, often as music. Transient sounds tied to actions; never ask for silence (it renders as rumble and crackle); fit the clip length to the action and speech; close each block with what is heard in that segment.
• Stylised looks need the style anchor at the very start of the video prompt (straight after the clip reference, before [REFERENCE USE]) and in every [LIGHT AND IMAGE], plus anti-realism negatives.
• Keep "Automatically enhance my video prompt" off. It rewrites to short prose and drops the bible, time labels and clip reference. The prompt box holds about 6,000 characters; trim repeated style text and negatives first.
• Turn Consistent Character off when making start images with no characters (empty environments, point-of-view, inserts). It affects Create Image only; Create Video ignores it.

The prompt pack document

1. Overview: scene table (scene, clips, time range, outfit, VE length); prompt format note; references to supply with each clip; paste rule (only text inside code blocks is pasted; headings carry metadata).
2. Global rules: the rules above and from the references that apply to this project.
3. Bible: character core block, outfit blocks, location blocks, style line.
4. Per scene: start images (each with a declared reference such as Image 12A, and a self-contained prompt that starts [Image 12A]), then per clip — header line (clip reference such as Clip 12 · time range · VE length · FRESH from image X or CHAIN from clip N · role tag) and the full multishot prompt, starting [Clip 12], in a code block.
5. Edit, timing and QC: transitions, the per-take QC checklist (in prompt-rules.md), open items.

For alternates, add a new tab or section rather than overwriting working clips, and include any adjacent clips that must change to hand off correctly. Keep clip and image references stable once generation starts, since they are what identify the takes; if clips are cut, keep the gaps and note them. Alternates get their own reference (Clip 12B), never a reused one.

Working style during production

• Users report failures one at a time, often with a frame. Diagnose the mechanism (table in prompt-rules.md), fix it globally, and sweep every not-yet-generated clip with the same risk.
• Read the frame the user sends: note what actually rendered and write the next prompt to match what exists.
• When the user edits the pack directly, re-read before writing and never overwrite their changes without saying so.
• When the user states a preference ("keep it", "I prefer this look"), treat it as a new rule and apply it everywhere, including rewriting the bible block to match the frame.
• Protect payoff shots: guard their preconditions in every earlier prompt.
• When the user asks to see a prompt before a run, show the full paste-ready prompt, then ask to run it. Don't run first.
• Isolate stubborn failures. When a problem survives two prompt rounds, stop rewording. Hold a base prompt fixed and run one take per variant, each changing one variable, with a unique reference per variant ([Clip 12 TEST 1], [Clip 12 TEST 2]), plus a control take of a previously clean prompt. Record which variables mattered.
• Know when to stop. If a sequence has drifted far from the concept, say so and offer to restart the sequence or the project rather than patching clip by clip.

Operating VideoExpress in the browser

When the user wants the assistant to drive app.videoexpress.ai itself rather than just write the pack, read references/browser-workflow.md first and follow it step by step. The user approves every start image, take and prompt change; the assistant pastes prompts exactly as written, never skips a checkpoint, and leaves drift judgements to the user unless a problem is obvious. Prompt hardening from a generated frame is offered after the first clip is on the timeline, and again after the second if deferred.

Renders take several minutes. On platforms where the assistant can only act while writing a reply and each reply has an action budget (see the platform notes in the browser workflow), never wait inside a reply for renders: submit the takes, confirm they exist, report their positions, and ask straight away which take to keep, saying what it should look like; don't ask whether the renders have finished. On platforms that can run long agent sessions, polling the library until the tiles finish is acceptable, but still stop at every user checkpoint. Never announce an action ("generating now") without performing it in the same reply.