agentleFS
raphaelbgrraphaelbgr/ai-video-prompting/skills/wan-3-prompting/SKILL.md

wan-3-prompting

Skill0 starsChanged 2 months agoMITView on GitHub

Use when writing or fixing prompts for Wan 3.0 video generation (Alibaba), via any API route - multi-clip film scripts, reference-to-video with real people, or when generated scenes come out illogical (objects that refuse to disappear, actions that get skipped, the wrong person speaking). Encodes the official Alibaba prompt rules, the API surface that actually exists, and the failure modes already paid for.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every illogical scene traces back to one of these.

    line 19
  2. Distinctive:

    Keep the negative prompt at 8–20 tokens.

    line 67
  3. Distinctive:

    Never combine contradictory terms — "drone shot zooming into close-up" confuses the model.

    line 123
  4. Distinctive:

    Read from a provider OpenAPI schema and live model list.

    line 132

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Wan 3.0 prompting

Researched against primary sources (Alibaba Model Studio official prompt guide, Runware Wan 3.0 API docs, the Wan 3.0 prompt guide, and a provider OpenAPI schema read directly). Background write-up with the full citation trail: docs/wan-3-research.md.

[NV] = not verified — confirm before relying on it.


1. The five rules that break scenes

Every illogical scene traces back to one of these. They are documented behaviour, not bad luck.

  1. No state change inside a shot. Alibaba is explicit: "cuts happen BETWEEN clips, not within". An object that disappears, clothing that tears, lights that switch — each must become a cut. (Cost: two paid generations on a necklace that refused to leave a neck.)
  2. One action beat per shot. "Keep actions simple and short." A 5s clip cannot do "sprints + vaults a planter + shoulders through a door". Two beats = two clips.
  3. Label speakers, never pronouns. With two people on screen, "He says" makes the model guess. Use [Man in the black tuxedo, firm]: "...".
  4. Address references by identifier. The model binds Image1 / Image2 written in the prompt text to the uploaded reference array. Natural language ("the man from the first reference") is measurably weaker.
  5. Name the camera explicitly. The default behaviour is a gentle drift. A locked frame requires the literal words static, locked-off.

Also documented as unreliable: precise lip sync to specific words. Ask for the line, accept the approximation, or dub in post. Writing "precise lip sync" does not buy it.


2. Prompt skeleton

Order matters more than sentence construction. Subject and setting first, then action, then camera, then audio — Runware is explicit that this ordering "lands more predictably".

Image1 is <one clause, no facial description>. Image2 is <one clause>.
<SETTING + LIGHTING, one sentence>.
<ONE action beat. Who does what, using Image1/Image2 as the subjects.>
Camera: <exactly one of: static locked-off | push-in | pull-back | pan | tilt |
         orbit | handheld tracking>.
[<Label>, <tone>]: "<line, accents intact>"
Audio. Foreground: <verb-driven event>. Bed: <verb-driven ambience>.
       Background: <verb-driven distant layer>.
Style: <lens>, photorealistic, <grade>, film grain.

Plus, as a separate API field — never inside the prompt text:

negative_prompt: low quality, blurry, distorted face, deformed hands, unnatural
movement, text, watermark, subtitles, shaky camera, duplicated people

Keep the negative prompt at 8–20 tokens. Specific beats generic: "flicker, exposure flicker, frame hopping" works; "stable video please" does not. Stacking 80 tags makes it impossible to know what fixed anything.

The base formulas Alibaba publishes:

CaseFormula
BaseEntity + Scene + Motion
AdvancedEntity(desc) + Scene(desc) + Motion(desc) + aesthetic control + stylization
With sound… + sound description (voice / SFX / score)
Multi-shotOverall description + shot number + timestamp + shot content
Image-to-videoMotion + camera move only — the image already carries entity, scene and style

In image-to-video, describing what is already in the image is wasted; describing what is not in it produces hallucination or is ignored.


3. Identity with real people

Say as little as possible about the face. Descriptive text about eyes, hair or jaw pulls the render toward a generic average and fights the reference photo.

  • Restate wardrobe in every shot (the generator never sees the other shots).
  • Never restate faces.
  • Body fidelity, one short line per shot: Keep natural, realistic body proportions. Do not slim or idealize. The negative-only form ("do NOT slim") was ignored on its own; an affirmative physical description over-corrected. This short line plus good references is the balance that held.

4. Audio: three named layers, written as verbs

The docs require each layer to be its own directive, in order of prominence, and to use verbs for sound events, not nouns or adjectives.

Not "wind, cables humming, held breath". Write the event happening:

Audio. Foreground: the mask tearing free with a sharp rip of fabric.
      Bed: cables groaning under load.
      Background: the city humming far below.

Audio is generated natively on the Wan 3.0 family — always direct it.


5. Camera — the six moves that respond by name

static / locked-off · dolly / push-in · pull-back · pan / tilt · orbit · handheld tracking

Never combine contradictory terms — "drone shot zooming into close-up" confuses the model; pick one perspective. Emotional intent per move, per Alibaba: push-in = intimacy or tension · pull-out = scale or isolation · tracking = puts the viewer alongside · orbit = emphasises importance · locked = stillness and focus.


6. API surface that actually exists

Read from a provider OpenAPI schema and live model list. Exact field names vary by provider; the capabilities are the point.

FieldReality
duration2s to 30s — not just 5s. Match duration to beat count (~5–8s per beat)
resolution480p / 720p / 1080p. No 4K, despite marketing
aspect_ratioadaptive, 16:9, 9:16, 1:1, 4:3, 3:4
promptup to 20,000 characters — length was never the constraint
negative_promptsupported, and routinely forgotten
reference_image_urlsdata URLs accepted; short side ≥ 240 px; up to 5 references, each identity controlled independently
audiogenerated natively; audio input is false on this model (no voice cloning)
no seedno reproducibility on the video route — a re-run is a new roll
keyframespresent in some schemas but not supported by this model — it belongs to keyframe-driven models
elements / @Element1a different model family (Kling), not Wan
creativity / realism / sharp / noisemarked "enhancement models only" — inert here

Prompt-extend is the most dangerous silent default [NV] on any given route: Wan's own tooling ships it on, and it rewrites your prompt before generation, which quietly destroys timecoded shot control. If timecoded shots come back ignored, suspect this first.


7. AI Director Mode — several shots in one generation

Because duration reaches 30s, 4–6 shots can render in a single pass with the model handling transitions and cross-shot identity itself. This is usually better continuity than stitching separate 5s generations.

Overall: Image1 and Image2, <wardrobe>. <Grade>. Character consistency across all shots.
Shot 1 [0-6s]:   <shot type> - <content, under 20 words>
Shot 2 [6-12s]:  <shot type> - <content, under 20 words>
Shot 3 [12-18s]: <shot type> - <content, under 20 words>
Audio: <three layers>. Style: <lens, grade, grain>.

Rules: 4–6 shots max · each shot description under 20 words · the character reference declared once in the Overall line, never repeated per shot (Identity Lock handles the rest).


8. The fixing pass — run this on any draft script

  1. Beat count. Count action beats per shot. More than one → split the shot.
  2. State changes. Anything appearing/disappearing, clothing changing, light switching → split into a before-shot and an after-shot. The cut sells the change.
  3. Pronouns. Replace every "he/she says" with a labelled speaker plus tone.
  4. References. Rewrite subjects as Image1 / Image2.
  5. Camera. Exactly one named move per shot; write static, locked-off where the frame should hold. Never combine contradictory moves.
  6. Audio. Rewrite noun lists into three verb-driven layers.
  7. Wardrobe. Restate in every shot. Faces: never.
  8. Duration. Match to beats (~5–8s each) instead of defaulting to 5s.
  9. Negative prompt. Attach it to every generation.
  10. Continuity. Run skills/multiclip-continuity — props, wardrobe progression, cast, knowledge, audio bridges, setup/payoff — then produce the regeneration ledger.

9. Operational rules for paid API routes

  • Log the job id the instant a job is queued, to a file. On most routes it is the only handle on a paid job, and some providers have no list endpoint — a killed script buries the id in an unflushed buffer and the money is gone.
  • Quote before you generate where the provider offers it.
  • Retrieval may return raw MP4 bytes rather than a URL — branch on Content-Type, do not look for a URL field. A working implementation is in reference/venice_video_provider.py.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.