product-demo: one UI state to another, as a video

Two screenshots of the same interface — before and after a state change — go into one Ofox video job as the first and last frame, and the model animates the change between them.

This skill is a thin, scenario-specific layer over ofox-video-core. It owns how to capture a usable pair, the prompt for a UI transition, and the pre-generation cost estimate; ofox-video-core owns talking to the Ofox API correctly and safely (the OFOX_API_KEY handling, the no-resubmit rule, error-code mapping, download/verification, and reporting the downloaded file's absolute VIDEO_PATH). Read that skill's safety contract before using this one — it is not restated here.

The shared prompt craft is in ../ofox-video-core/references/prompt-structure.md, the pre-prompt question rules in ../ofox-video-core/references/creative-brief.md, and the spend rule in ../ofox-video-core/references/approval-gate.md. This file carries only what is specific to a UI pair.

Where the core skill lives

Resolve once, before the first call:

for d in ../ofox-video-core \
         ../ofoxai-skills-ofox-video-core \
         ~/.agents/skills/ofox-video-core \
         ~/.agents/skills/ofoxai-skills-ofox-video-core \
         ~/.claude/skills/ofox-video-core; do
  [ -f "$d/references/ofox-video.sh" ] && echo "$d" && break
done

Examples below are written as ../ofox-video-core/... (the skills.sh / ClawHub / npx ofox-skills layout, where a skill's directory is named after the skill). If the probe found a different directory — LobeHub unpacks each skill as ofoxai-skills-<name>, so the sibling there is ofoxai-skills-ofox-video-core — substitute it, in the ofox-video.sh commands and in the references/*.md links alike.

That ../ is relative to this skill's own directory, which is also where the probe has to run: every example below assumes the working directory is the one this SKILL.md sits in. From anywhere else nothing resolves — use the absolute path the probe printed (candidates 3–5 are absolute already), or, in a clone of this repo, skills/ofox-video-core/references/ofox-video.sh from the repo root.

Nothing found → the core skill isn't installed; see "If the script isn't found".

Before generating: the availability check

Run this once per session (not on every request):

bash ../ofox-video-core/references/ofox-video.sh check

If it fails, follow ofox-video-core's guidance (install curl/jq, or get an OFOX_API_KEY at https://app.ofox.ai) — don't dead-end the conversation, and don't re-run this check on every subsequent request once it has passed.

check reports whether the key is present, not whether it is valid; it makes no network call. The key is an ordinary environment variable in the shell that runs the script — the script reads nothing from a .env file on its own, so if a project keeps it in one it has to be sourced into the same shell before the command runs.

A failing check is not a stop sign for this conversation. It exits 2 when OFOX_API_KEY is unset, but models, providers and generate --dry-run all run without a key — so a keyless user can still get the two captures read, the prompt written and the job priced, and only needs the key at the moment they say yes to the cost table. Do that work first rather than opening with a signup link; see "Pricing a job with no API key".

Why this skill exists, and what it is built on

This scenario was expected to fail. Generative video models fabricate text — every other scenario skill in this repo carries an AVOID: subtitles, on-screen text line for exactly that reason — and a user interface is almost entirely text. The prediction was that the interpolated middle would turn the UI's strings to mush and a demo built this way would be worthless.

It was tested, and the prediction was wrong. Job 5e59baa2, bytedance/seedance-2.5, 4 seconds, 480p, billed 44 cents. The inputs were two genuine Chrome-rendered screenshots of one pricing/usage panel, differing in four places:

What the delivered clip's own frames show:

• at t=1.3s the four changed values are mid-fade — and already correctly spelled and correctly positioned;
• the labels that did not change stay solid through that moment. The model cross-faded only the values that differed;
• by t=2.0s every string is crisp and correct;
• no garbling, no invented text, no layout drift.

Why the pessimistic reasoning failed, and this is the load-bearing part: the repo's AVOID: on-screen text lines exist for text the model has to invent. With both endpoints supplied, it is interpolating between two given renderings instead — a different task with a different failure profile. Copying that AVOID line into this skill would be cargo-culting a rule whose premise does not hold here, so this skill does not carry one; see "The prompt" below.

It happened twice

Job 427278b4 (2026-09-15), same model, duration, tier and input pair, again 44 cents, with the prompt filled in from this file's own template by an agent working from this skill and nothing else — so what that run tested was the skill rather than the API. Read off the delivered clip's final frame: all four changed values render correctly and legibly — Business, $99.00, 25, Manage seats — the layout is identical to the input capture, nothing drifted, and no text was invented.

Same pair, so it widens nothing about the inputs. What it adds is that the template in this file, not a hand-written prompt, produces the result, and that the result replicated rather than being one lucky roll — which matters more here than in most scenarios, because a seed does not reproduce a take on this API, so a second run really is a second sample.

What those jobs do not establish

• One pair, one app, one panel, four changed values, at 480p and 4 seconds, twice. It is two clips on the same input, not a guarantee, and the second is a replication rather than a broadening. Read the draft's frames before anyone ships the output.
• Nothing about a pair that differs in many places, or in layout rather than in values. Every difference has to be resolved in the middle, and this run only bounded the easy case.
• Nothing about a model other than bytedance/seedance-2.5. The catalog lists i2v for the current video models, but i2v says nothing about locking both ends at once — that granularity is not in the catalog and has not been tested here.
• Nothing about a pointer or cursor moving to the control that changed. A cursor that is in neither screenshot is an element the model would have to invent, which is the class the AVOID lines were written for. Untested, and not recommended without a paid run to settle it.
• Nothing about screen recording. If the user can record their real app, that is free, exact, and better than any of this.

The timing, from the sibling scenario

The same two-frame mechanism was measured for motion in the same session (job 259c3ce2, a moving object rather than a UI): the change is front-loaded, covering about 53% of the distance in the first quarter of the clip and arriving at three seconds of four, then holding. The UI job is consistent with that shape — crisp and settled by t=2.0s of a 4-second clip — but the UI clip was read for legibility rather than sampled for an easing curve, so treat "it settles early and then holds" as the pattern to plan for, measured directly on the motion clip and observed to be compatible here.

Practical consequence: the tail of the clip is a hold on the final state. That is usually what a docs GIF wants anyway. Budget duration knowing the last beat is stillness, and don't plan for the change to land on the final frame.

Before writing the prompt: the brief

The shared rules — the three tiers, one round of at most four questions, the "Let the AI decide" discipline, the order with the approval gate — are in ../ofox-video-core/references/creative-brief.md. This section adds only this scenario's question set.

Almost every axis is settled by the two screenshots: the subject, the layout, the colours, the framing and the output's shape are all in the pair. Zero questions is the common case when both files arrive with names that say which is which.

The question set

Not asked: duration and resolution (rows in the cost table), the model, the provider, the audio flag, the aspect ratio.

Skip rows specific to this scenario

On top of the generic rows in creative-brief.md:

From answers to prompt — traceability

The recap for this scenario

Brief:
- Start state: /Users/me/caps/plan-starter.png (given)
- End state:   /Users/me/caps/plan-business.png (given)
- What differs: plan name, price, seat count, button label — 4 changes
- Emphasis: none, plain cross-fade (the measured behaviour)
- Duration / resolution / audio: 4s / 480p / off — one row below; 720p as a second row
- Frame shape: 1440x900 on both files, so the clip comes out in that shape

Then the full prompt, then the cost table, all in one message.

Capturing the pair

The pair is the whole job. Everything the model is asked to do lives in the difference between the two files, so a bounded difference is the entire craft here.

• Capture both from the real application. A mockup, a Figma frame or an AI-generated "UI" already contains invented text, and then the demo is a demo of something that does not exist. The measured job used two genuine Chrome-rendered screenshots.
• Change one thing, or a small bounded set. The measured pair differed in four places, all of them values in place. Every difference is resolved in the middle of the clip, and you pay for all of them in one job.
• Same window size, same scroll position, same zoom, same theme. Resize the window once and capture both without touching it. A different scroll offset turns "one value changed" into "the whole page moved", which is a different and unmeasured problem.
• Same pixel dimensions on both files. The measured pair matched. A mismatched pair has not been run here; matching them first costs nothing. Read the real pixels (sips -g pixelWidth -g pixelHeight <file>, identify <file>) rather than trusting a filename or an export dialog — this repo has more than one record of a reported size disagreeing with the file actually on disk.
• Crop to the shape you want the clip in, before generating. With frames attached the output follows the frames — see "The frames decide the shape". Crop, never pad: a padded frame makes the bars part of the video.
• Hide anything you don't want animated for four seconds. Real customer names, real email addresses, a live token in a URL bar. The clip is a shareable artifact and the middle frames are generated, so anything private in the capture is private in the output too.
• Crop out a real person's face if the UI happens to show one. bytedance/seedance-2.5 refuses a photoreal-person reference at submission (input_moderation_failed, nothing billed) — a documented ofox-video-core behaviour. An avatar illustration is a different case and has not been tested here either way.
• A local file beats a remote URL when one is available. ofox-video-core base64-encodes a local readable file into the request; a publicly reachable URL has been rejected upstream at least once in this repo.

The prompt

The prompt's job here is smaller than in any other Seedance scenario: both endpoints are supplied and the model can see them. It has to name what changed so the cross-fade lands on the right elements, and say that everything else holds still.

Vocabulary and the general formula are not repeated here — see ../ofox-video-core/references/prompt-structure.md. Two things from that file bear on this template: negative clauses are honoured more reliably than positive ones, and a camera verb on its own tends not to produce a camera move — which is why the VIEW line below asks the frame to stay put rather than asking it to travel.

SCREEN: the first frame and the last frame are two screenshots of the same <app or page name>, captured at the same window size and the same scroll position. Every element keeps the position, size, typeface, weight and colour it has in those two images.
CHANGE: between them, <element> reads "<value in the first frame>" and becomes "<value in the last frame>"[; <element 2> goes from "<A>" to "<B>"; …]. Those are the only things that change; every other label, number, icon and control stays exactly as it is.
VIEW: the view is locked — the screen is shown flat and straight on, framed exactly as it is in the two screenshots, at the same scale and in the same position. The framing does not move, scale, rotate or tilt at any point, and the page does not scroll.
ENDING: the clip settles on the second screenshot and holds it.
AVOID: a cut, a fade to black, a dissolve of the whole screen, a wipe or a slide transition; camera shake, zoom, pan or reframing; new panels, menus, dialogs, tooltips, toasts or badges appearing; a mouse pointer or cursor appearing; the layout shifting, reflowing or resizing; letters or digits becoming blurred, doubled or malformed.

The VIEW line says "framed exactly as it is in the two screenshots", not "the interface fills the frame". Whatever the pair shows — a full window, a panel with room around it, a cropped detail — is already the framing, and it is the two attached images that decide it. Telling the model the interface fills the frame is a description only when it happens to be true; on a capture with page around the panel it reads as an instruction to re-frame, which means inventing what sits outside the images it was given. Say what the pair is framed like, or say nothing about it. If a tighter crop is wanted, crop both captures before generating, exactly as with the aspect ratio.

There is deliberately no blanket "no on-screen text" item in that AVOID list, and it is the one line not to copy in from the other scenario skills. Those lines exist for text the model has to invent. Here both endpoints are supplied, so it is interpolating between two given renderings — the measured run kept every string correctly spelled and correctly positioned throughout — and a blanket prohibition on text would be pointed at the user's own interface. What this list does forbid is text-shaped things that are in neither capture (a tooltip, a toast, a badge) and text that stops being text (blurred, doubled, malformed glyphs), which are the real failure modes.

Worked example

The measured pair: one pricing panel, four values changed.

SCREEN: the first frame and the last frame are two screenshots of the same pricing and usage panel, captured at the same window size and the same scroll position. Every element keeps the position, size, typeface, weight and colour it has in those two images.
CHANGE: between them, the plan name reads "Starter" and becomes "Business"; the price reads "$29.00" and becomes "$99.00"; the seat count reads "3" and becomes "25"; the button label reads "Upgrade plan" and becomes "Manage seats". Those are the only things that change; every other label, number, icon and control stays exactly as it is.
VIEW: the view is locked — the screen is shown flat and straight on, framed exactly as it is in the two screenshots, at the same scale and in the same position. The framing does not move, scale, rotate or tilt at any point, and the page does not scroll.
ENDING: the clip settles on the second screenshot and holds it.
AVOID: a cut, a fade to black, a dissolve of the whole screen, a wipe or a slide transition; camera shake, zoom, pan or reframing; new panels, menus, dialogs, tooltips, toasts or badges appearing; a mouse pointer or cursor appearing; the layout shifting, reflowing or resizing; letters or digits becoming blurred, doubled or malformed.

Quote the values verbatim, in quotes, exactly as they appear — including the currency symbol and the decimals. They are strings that exist in both captures; retyping them approximately in the prompt is the one way to introduce a discrepancy into a job that otherwise has none.

Checking the draft

Read the artifact, not the status. STATUS completed says nothing about legibility. The check that produced the evidence above — run on both jobs — and the one to repeat:

# the delivered clip's own first and last frames, against the two inputs
ffmpeg -i out.mp4 -frames:v 1 first.png
ffmpeg -sseof -0.1 -i out.mp4 -frames:v 1 last.png
# and the middle, where the cross-fade lives
ffmpeg -ss 1.3 -i out.mp4 -frames:v 1 mid.png

Look at three things: are the changed values spelled correctly and in the right place at the mid-point; do the unchanged labels stay solid; has anything moved. If ffmpeg isn't installed, open the file and scrub — the point is that a human or an agent looks at frames, not that a particular tool is used.

The frames decide the shape

With a frame attached, the output's aspect ratio follows the frame, and how it gets there depends on the model:

• on bytedance/seedance-2.5, ofox-video-core forces aspect_ratio=adaptive and prints a NOTE: saying so, because the API requires it for image-to-video on that model. Anything you passed is overridden;
• on a model whose catalog entry lists adaptive, the script defaults to it when you pass no --aspect-ratio, and keeps your value if you pass one;
• on a model that does not offer adaptive, the script sends no ratio and says so — the frames' shape may not survive.

So: don't pass --aspect-ratio on this route, on any model. Crop both screenshots to the shape you want before generating; that crop is what decides the output. A browser window is rarely 16:9, and a padded frame bakes the bars into the video — crop instead. Relay the NOTE: the script prints; it names which branch applied.

This needs ofox-video-core 1.22.0 or newer. On an older core, a non-Seedance model with frames attached sent no ratio at all, with nothing printed to say so.

Recommended defaults

Choosing a model

The model stays never-ask — the agent doesn't raise it. But never-ask is not "never listen": if the user names a model, use it.

Model ids, prices, resolutions, durations and aspect ratios are not written down in this file on purpose. They are catalog facts, they change, and this repo has five recorded defects that trace to a hardcoded copy of somebody else's value table. Read them live instead, free and with no API key:

bash ../ofox-video-core/references/ofox-video.sh models      # models, tiers, ranges
bash ../ofox-video-core/references/ofox-video.sh providers   # the price matrix

Worth telling the user before they switch: the text-preserving cross-fade was measured on bytedance/seedance-2.5 only. The catalog says the current models do i2v, but i2v does not distinguish "one end locked" from "both", and it says nothing at all about what happens to lettering — so another model is an untested route for the one property this whole scenario depends on.

Before you spend: the approval gate

Never submit a paid job until the user has seen a cost table and said yes. The rule, the table's required columns and where the numbers come from are written down once for every Ofox skill in this repo: ../ofox-video-core/references/approval-gate.md.

Get the numbers from --dry-run, which validates everything and prints the estimate without sending a request:

bash ../ofox-video-core/references/ofox-video.sh generate --dry-run \
  --prompt "..." \
  --frame-first-image /path/to/before.png \
  --frame-last-image  /path/to/after.png \
  --duration 4 --resolution 480p --generate-audio false \
  --out-dir /absolute/path/to/out

Relay the Estimated cost: line it prints — never a number of your own — then wait for a yes, then re-run the identical command with --dry-run removed. The estimate a real run prints comes microseconds before the request goes out, too late to relay.

The brief recap goes in the same message as the prompt and the table, above them.

The cost anchor this skill has, with the parameters it was measured at attached, because a figure without them is not a measurement: bytedance/seedance-2.5, 4 seconds, 480p, first+last frames, 44 cents billed — twice, on jobs 5e59baa2 and 427278b4, at the same figure. It is not a quote for any other combination — an image-to-video job bills at the text-to-video tier, so a longer or higher clip scales from the dry run, never from this number.

Afterwards the actual bill is VIDEO_COST from the finished job. Report it as money, not as the raw ten-decimal string.

Worth saying out loud when the user is deciding: a screen recording of the real app costs nothing and is exact. This skill earns its keep when there is no running app to record — a design that isn't built, a state that is hard to reach, a before/after across two releases — or when a clean animated transition is wanted from captures that already exist.

Confirm both captures are attached, before the money moves

The dry run's own output names the model, the duration and the resolution and says nothing about the frames — so a mistyped flag, or a path that quietly matched only one file, reads as a perfectly healthy quote and shows up in the delivered clip instead. --print-payload closes that: it dumps the request body on stderr before the dry run stops (the API key travels in a header, never in the body), and the two frame_type entries are the part to read:

bash ../ofox-video-core/references/ofox-video.sh generate --dry-run --print-payload \
  --prompt "..." \
  --frame-first-image /path/to/before.png \
  --frame-last-image  /path/to/after.png \
  --duration 4 --resolution 480p --generate-audio false \
  --out-dir /absolute/path/to/out \
  2>&1 >/dev/null | grep -o '"frame_type":"[a-z_]*"'

Measured output on a two-frame job:

"frame_type":"first_frame"
"frame_type":"last_frame"

Two lines, in that order, is the confirmation. One line means one of the two flags didn't take; a different order means the before/after captures are on the wrong flags, which is the backwards-clip failure below and is free to fix at this point. Grep the payload rather than printing it whole: each capture is base64-inlined into that JSON, so the body runs to megabytes.

--out-dir is worth passing to the dry run for the same reason — the script creates and enters it here, and a path it can't use fails as exit 6 with nothing submitted. Pass the same directory to the real run; a different one afterwards re-opens the question the dry run just settled (an exit 6 after a create costs the job's price, and is recovered with poll JOB_ID --out-dir <writable dir>, never with a second generate).

Several takes to choose from

The middle is generated, so it is a roll — and legibility is the thing being rolled for. When the user wants options, batch prices the whole set up front, waits on the takes concurrently, and builds a contact sheet:

bash ../ofox-video-core/references/ofox-video.sh batch --dry-run \
  --prompt "..." --takes 3 \
  --frame-first-image /path/to/before.png --frame-last-image /path/to/after.png \
  --duration 4 --resolution 480p --out-dir /absolute/path/to/out

Quote BATCH_COST_TOTAL, not BATCH_COST_PER_TAKE, and give the takes a row each. If one take in three is usable, that clip cost the whole total. At --dry-run the total is the Estimated cost: ~$… for N takes line; the two BATCH_COST_* keys are what the real run prints afterwards.

The contact sheet is three frames per take at thumbnail size, so it is good for "did the layout hold" and not good enough for "is the text correct" — open the individual takes for that. Hand the user the CONTACT_SHEET path on its own line, then the take paths beneath it. Each TAKE line carries seed=N, which is how a take is named and re-submitted higher — an aim at that take, not a promise of it (see the --seed row above).

Submission is sequential and only the waiting runs in parallel, so the whole total is committed within seconds of the yes — the cost table is the only place a batch can be stopped.

Pricing a job with no API key

models, providers and generate --dry-run all work with OFOX_API_KEY unset. So when a user hasn't signed up yet, quote the job first and let them decide whether it's worth registering — don't open by sending them to a signup form.

If the script isn't found

bash: ../ofox-video-core/references/ofox-video.sh: No such file or directory

Nothing is broken — this skill delegates all execution to ofox-video-core and reaches it by relative path, and that path just missed. Two different situations wear this message, so run the probe in "Where the core skill lives" before deciding which:

• The probe printed a directory — the core is installed and only the directory name was wrong, which is the normal LobeHub case (ofoxai-skills-ofox-video-core). Re-run the command against what the probe printed. Nothing needs installing.
• The probe printed nothing — ofox-video-core really is absent, and the fix belongs to whichever installer the user already has: npx ofox-skills (this repo's own) or the underlying npx skills add ofoxai/skills --skill '*' --agent '*' --global --yes for skills.sh; on LobeHub or ClawHub, install ofox-video-core from the same publisher.

Either way, say which skill is missing and where it was expected rather than relaying the raw path error, which names neither.

A broken link to a shared reference has the same two causes: this skill packages only its SKILL.md and CHANGELOG.md, so prompt-structure.md, creative-brief.md, approval-gate.md and api-params.md are out of reach whenever the script is. The skill still works without them — the template, the question set and the defaults are written out here.

Exit codes worth knowing

Full table in ../ofox-video-core/SKILL.md. The ones that come up:

How long to tell the user it will take

generate blocks while it polls, up to --max-wait (default 540s). A short low-resolution clip is usually one to three minutes. Say so before starting, so the wait isn't silent.

If your tool call can't stay open that long, use create (submits and returns a job id in seconds) followed by poll, instead of generate. That way a timeout can never strand a job whose id you never saw.

Where the file lands

Always pass --out-dir, and make it an absolute path. Without it the script writes to the current working directory — which, given that the examples here run from this skill's own directory, would drop the user's video inside an installed skill. Relay the absolute VIDEO_PATH the script prints, on its own line.

The dry run is where a bad directory gets caught: generate --dry-run (and batch --dry-run) creates and enters --out-dir before it quotes, and exits 6 without submitting anything if it can't. That only covers the directory you actually passed it, so give the real run the same one — swapping it afterwards puts you back to discovering the problem after the job is paid for.

Pass --name too — name the file after the state change rather than leaving the script to guess from the prompt's opening words, which here describe a window size. The clip lands as <name>-<short job id>.mp4 with a .json sidecar holding the full job id, the prompt, the seed and the real cost.

Generating

bash ../ofox-video-core/references/ofox-video.sh generate \
  --prompt "<the UI-transition prompt built above>" \
  --name "<short description, e.g. plan upgrade starter to business>" \
  --frame-first-image "/absolute/path/to/before.png" \
  --frame-last-image  "/absolute/path/to/after.png" \
  --duration 4 \
  --resolution 480p \
  --generate-audio false \
  --out-dir /absolute/path/to/out

No --aspect-ratio on purpose, on any model — see "The frames decide the shape".

This one call validates the parameters, submits the job, polls to completion, downloads the mp4, and prints STATUS, JOB_ID, VIDEO_PATH, VIDEO_SECONDS, SEED and VIDEO_COST. Report the actual values from that output — never the estimate, and never a path or cost you didn't see the script print. Do not re-implement any of the request, poll or download logic here.

Common failure modes and fixes

When NOT to use

• The real app can be recorded. A screen recording is free, exact, and shows the actual interaction. Say so before quoting a job — this skill is for when there is nothing to record.
• Only one screenshot exists. There is no destination to interpolate towards. Capture the second state, or record instead.
• The pair is not a user interface. A moving object, a product, a scene — that is keyframe-animation, the same mechanism with different prompt advice and its own measured behaviour.
• The two captures are different screens entirely, not two states of one. Every difference is resolved in the middle, and a whole-screen replacement is a cut — two clips and an editor are cheaper and more predictable.
• The demo needs a pointer, a click, a typed input or a multi-step flow. Those are elements and events that exist in neither endpoint, and none of it has been tested here. A screen recording, or one job per state change joined in an editor, is the route with a floor under it.
• The interface is a mockup rather than the product. Then the clip is a demo of something that does not exist, whatever it looks like.