byted-bp-seedance-viral-creative-rewrite-skill

Viral Creative Rewrite Skill

What This Skill Does

This skill helps a user create a stronger ad video from:

• a template video, provided by the user as a local path or accessible URL
• a user-provided product image, defaulting to ./assets/examples/source_product.jpg

The template video provides creative structure: hook, pacing, visual rhythm, CTA style. The product image provides the product identity, packaging, visual anchors, and confirmed selling points. The final video should keep the product image identity and borrow only the template's creative pattern.

Reference Loading

• Read references/state_machine.md when changing or auditing frontstage state transitions, opening prompts, detailed-analysis behavior, confirmation gates, missing-key behavior, bilingual parity, or transcript regressions.
• Read references/workflow.md when changing or auditing the user flow, confirmation gates, setup/prepare/execute behavior, review outputs, or local product image handling.
• Read references/prompt_alignment.md when changing analysis schemas, rewrite-planning prompts, prompt-package structure, or compatibility with earlier creative rewrite prompt patterns.
• Read references/chain_contract.md when changing or auditing cross-layer behavior: state, prepared artifacts, renderers, prompt compiler, execution gate, bilingual parity, and badcase regression coverage.

Hard Gates

• Treat "正式生成", "直接生成", or similar user wording as intent to enter the real-generation path, not permission to submit Seedance immediately.
• Always run or present the analysis/brief confirmation gate before real generation. The user must see the template logic, product-image anchors, rewrite strategy, forbidden carryover, prompt preview, audio setting, and cost/time warning before Seedance is called.
• Treat the conversation as a state machine. references/state_machine.md is the source of truth for frontstage state transitions, allowed output, forbidden output, and transcript regression invariants. Do not expose later-state actions in earlier-state messages:
  • START_OPENING: explain the skill, two media roles, default assets, category/face guidance, and ask for grouped inputs. Forbidden in this state: "确认生成", "confirm generation", --confirmed-brief, or any instruction that asks the user to approve final generation.
  • BRIEF_READY: after analysis/brief exists, show the compact brief, detailed-analysis option, edit option, and only then expose the generation-confirmation action.
  • DETAIL_VIEW: when the user asks for detailed analysis, print the full detailed-analysis sections and return to edit/confirm options.
  • GENERATION_CONFIRMED: after the user confirms the prepared brief, run scripts/confirm_generation.py; do not hand-write the result.
  • MISSING_KEY_FULL_GUIDANCE: if the confirmed runner path lacks ARK_API_KEY, show the reusable brief state, no-cost/no-call state, Seedance advantages, playable examples, and account/key setup.
• Support both Chinese and English user flows. Keep user-facing messages, compact brief text, detailed-analysis text, setup/missing-key guidance, and prompt preview in the user's language. Use ui_language: "zh" or ui_language: "en" when the language is explicit; use auto only when it is safe to infer from the user's request. This UI language is separate from the template spoken-language rule.
• For conversation language selection, the latest user turn wins. If the latest invocation/request is in English, including a local-path invocation such as /path/to/byted-bp-seedance-viral-creative-rewrite-skill use this skill, start and continue the frontstage flow in English even if earlier thread history is Chinese. If the latest invocation/request is in Chinese, use Chinese. Do not let old thread context override the language of the current invocation.
• Before planning the rewrite, classify the template into a template profile. This profile decides which signals are allowed to become hard generation constraints:
  • visual_product_texture: drinks, food, product static shots, material/texture demos, ingredient/product-state ads. Borrow shot order, camera pacing, product state changes, texture/satisfaction points, scene mood, and music mood. Do not add voiceover, lip sync, person ethnicity/appearance constraints, or subtitle logic unless the user explicitly asks.
  • human_demo: visible human demonstration, try-on, hand-use, or presenter action without a strong voiceover. Borrow human framing, action sequence, expression/eye-contact when structurally important, product-human relationship, and real scene context. Do not invent voiceover.
  • human_voiceover: presenter/creator video with spoken explanation. Borrow broad person appearance/market visual context, original template spoken language, voiceover rhythm, mouth/gesture synchronization, real scene, and action order. Generate a new non-identical person and original wording.
  • platform_cta: platform/account/search/CTA pages. Borrow only the closing function; do not inherit platform UI, account, watermark, search page, captions, or blank ending.
  • mixed: use only when several mechanisms are equally central, then expose the active transfer slots in the brief before asking for confirmation.
• Keep no-cost rehearsal and real prepare frontstage readouts aligned. They may differ in provider/cost wording, but they must use the same user-facing structure: status, brief summary, detailed-analysis option, edit option, confirmation option, and result-display expectation.
• Do not call Seedance until the user explicitly confirms the prepared brief.
• Video understanding and rewrite planning must be done by the host agent in the conversation. Do not call ModelArk/Seed/ARK Responses for template or product-image understanding.
• For local template-video understanding, inspect visual evidence at 1fps by default, meaning one timestamped frame per second. Use these per-second observations as evidence, then summarize them into every-5-second windows. If the video has very fast cuts, text flashes, or hand motions that may be missed, increase density for the relevant interval instead of lowering detail.
• When the template shows a person whose mouth is visibly moving, increasing frame density is not enough — frames cannot tell whether there is voiceover. You must also inspect the audio track (listen for spoken voiceover vs music/ambient only) before classifying the profile. Run scripts/extract_video_frames.py --with-audio, which exports audio_track.m4a and records has_audio_stream in the manifest, then actually listen. Do not infer human_demo vs human_voiceover from visual frames alone; screen-recording sources especially must have their original audio checked.
• If the user has chosen real generation and ARK_API_KEY is missing, still continue through agent-led video understanding, detailed analysis, and brief confirmation. Then show Seedance 2.5 advantages, playable production examples, and only after that show the account/key setup block: BytePlus registration, ModelArk/Seedance setup document for API key plus prepaid resource package activation, Doubao Seed 2.0 Pro permission page, and local .env placement.
• When the user asks "查看详细分析" / "show detailed analysis", never answer with a short recap such as "详细分析已展开", "shown above", "same prepared brief", or "the key decision is unchanged". You must print the full detailed-analysis body in the user's language: template video facts, every-5-second breakdown, product-image analysis, proposed generation script, generation constraints, and the next edit/confirm gate.
• When the user asks "查看详细分析" / "show detailed analysis", always execute scripts/render_detailed_analysis.py --prepared-input-json <prepared> with the bootstrapped skill-local Python. The final chat reply must be the complete stdout from this command. Do not hand-write "关键结论不变", "核心要复刻的是...", or any short profile recap.
• This applies to the real generation flow too, not just rehearsal. For every brief / detailed-analysis / confirmation step (render_brief.py, render_detailed_analysis.py, confirm_generation.py), the visible chat reply must reproduce the command's complete stdout. Leaving the output collapsed inside a tool-call box and replying only with a pointer like "以上是完整详细分析" / "shown above" does NOT count as forwarding — the analysis body must be in the visible reply. The brief and detailed-analysis stdout already end with the next-step gate (confirm / view detailed analysis / tell me what to change); do not strip those options, do not replace them with a binary "confirm only" AskUserQuestion widget, and re-offer them whenever the brief is edited and re-confirmed.
• When opening the skill, use scripts/render_opening.py --ui-language zh|en after runtime bootstrap and send the complete stdout. Do not hand-write a shorter opening.
• When showing a prepared brief, use scripts/render_brief.py --prepared-input-json <prepared> and send the complete stdout. Do not hand-write a shorter brief.
• When applying a user edit to an existing brief, use scripts/apply_brief_patch.py --prepared-input-json <prepared> --patch-json <patch> --prepared-json <patched> and send the complete stdout. Do not hand-write "已修改" without the refreshed brief.
• When showing a final generation result, use scripts/render_generation_result.py --result-json <result> and send the complete stdout. The generated video must be shown first.
• Always output setup, registration, and account URLs (BytePlus signup, ModelArk, API-key, model-management, docs links, etc.) complete and verbatim, exactly as the scripts print them. Never shorten a URL, drop its query string, or strip UTM / tracking parameters such as utm_source, utm_medium, or utm_campaign "for tidiness" — these carry channel attribution and registration benefits and must reach the user intact. If you show a shortened display text, the underlying link target must still be the full URL.
• Media markdown style: the scripts that print video/image links (run_rewrite_video.py, render_opening.py, render_generation_result.py) accept --media-style codex|link|both, default codex. Keep the default codex in Codex Desktop, where ![](absolute path) renders an inline preview. In a client that shows ![](path) as plain text but linkifies markdown links (e.g. Claude Code), pass --media-style link to emit clickable [label](file:///… ) links instead (or both if unsure). The link is only clickable once it is in your visible reply — forwarding the script stdout into the chat (not leaving it collapsed in a tool box) still applies. Local file:// links open only on the machine that ran the skill; for cross-machine sharing a public URL is required.
• To make media clickable, re-run the script with --media-style link (or both) and forward that output. Do NOT hand-convert ![alt](path) into [alt](path) yourself: a bare absolute path like C:/Users/... or /Users/... is not a valid URL, so the result renders as a link that does nothing when clicked. Only the --media-style link flag produces the correct file:// form (with proper percent-encoding); use it instead of editing the URL by hand.
• At skill startup, before showing the opening prompt or starting analysis, run scripts/ensure_runtime.py --ui-language zh|en --print-python from the skill root. This creates/reuses the skill-local .venv, installs requirements.txt there when needed, verifies imageio, imageio-ffmpeg, pillow, pydantic, httpx, and an ffmpeg executable, and prints the Python path to use. Do not assume Codex, Claude Code, system Python, or the bundled runtime already has these dependencies.
• Use the Python path printed by ensure_runtime.py for scripts/run_rewrite_video.py, scripts/extract_video_frames.py, and other skill scripts. Do not use the Codex bundled Python or system Python for this skill after startup bootstrap.
• If ensure_runtime.py fails because network or sandbox access is blocked, request permission and rerun the same startup bootstrap with network access. Do not wait until the user has chosen real generation to discover missing dependencies.
• Do not ask for object storage, material library, TOS, or bucket setup in the default flow. Explain local product-image handling only if the user asks.
• Use scripts/run_rewrite_video.py as the only runner. This skill is conversation-first: collect choices in chat, write a request JSON, then execute the non-interactive runner.
• Never drive a terminal wizard or stdin-based questionnaire from the agent. The package intentionally has no interactive runner.
• Use the host agent to create the prepared brief before generation. After the user reviews and confirms it, continue from --prepared-input-json; do not run any provider media-analysis step.
• For local template videos, use the bootstrapped skill-local Python to run scripts/extract_video_frames.py and extract 1fps timestamped frames for evidence before writing the prepared brief. Do not use browser screenshots or GUI playback as the default extraction path.
• During the real-analysis preparation state, keep user-facing progress terse. Do not print template conclusions, detailed analysis, raw request/prepared JSON, source_analysis, rewrite_plan, rewrite_brief, prompt_preview, full prompts, Python heredocs, or large shell command payloads before scripts/render_brief.py has rendered BRIEF_READY.
• If a prepared artifact must be hand-authored or patched, write it outside the skill source and validate/render it with a reusable script. Do not embed the full prepared JSON inside a shell command that can appear in the transcript.
• If the user changes only generation direction after preview, such as audience, claims, tone, constraints, output settings, or "add this lightly", apply a small --patch-json to the prepared JSON and refresh the prompt. Do not re-analyze the template video or product image unless those media changed. Do not use a patch to switch a prepared artifact from Chinese to English or English to Chinese; the saved analysis stays in its original language. If the user wants a different UI/analysis language, create a fresh request with the desired ui_language and run prepare again.
• Always write request, prepared, output, cache, and test artifacts outside the skill folder. Do not create an output/ directory inside the skill source.