Skills / Departments / Marketing / Skills / Storyboarding / Scene Spec
All skills

/ skill

scene-spec

Departments/Marketing/Skills/storyboarding/scene-spec.md

Produce ONLY the schema-valid .video-gen-spec.json (no human-readable storyboard.md). Useful when feeding the spec directly to an external AI video tool.

Open as raw file

Run this skill

Heads up — this skill doesn’t have a structured form yet, so type the full prompt with all decisions baked in (the subprocess can’t answer follow-up questions). Edit me if needed.

Runs with bypassPermissions — local dev only.

scene-spec

Produce a standalone schema-valid .video-gen-spec.json. Two modes:

ModeInputUse case
Convert modestoryboard_md providedTake an existing human-readable storyboard.md and translate it into the strict spec for handoff to AI video gen tools.
Direct modescript_path + brief_path providedSkip the human-readable storyboard entirely; produce only the spec. Useful for scripted automation.

For most workflows, use storyboard-from-script which produces both. This skill is for narrow cases where only the spec is needed.

Pre-flight

  1. Either storyboard_md exists, OR script_path + brief_path both exist.
  2. Read schemas/video-gen-spec.schema.json — output MUST validate.
  3. If converting from storyboard_md: read it + parse scene blocks.

Procedure

Convert mode (storyboard_md → scene-spec.json)

  1. Read storyboard_md. Parse:
    • Frontmatter for: brand, template_archetype, duration_target_sec, aspect_ratio, script_ref, brief_ref, schema_version
    • Scene sections (Scene 1..N) for: scene_id, start_sec, duration_sec, visual_prompt, audio (VO line + music + SFX), caption, camera_behavior
    • Hook variants section
  2. Build the JSON with required top-level fields per schema: schema_version, pipeline: "demandgen-video", brand, market, output_dir, generated_at (current ISO timestamp), reference_images: [] (or populated if storyboard references them), scenes, global_settings, script (full script text), audio_spec, caption_spec, hook_variants.
  3. Validate against schema. Fix any errors before writing.
  4. Write to output_path (default: same directory as the source storyboard, named scene-spec.json).

Direct mode (script + brief → scene-spec.json)

  1. Read script + brief.
  2. Determine template_archetype if not provided (per storyboard-from-script Step 1).
  3. Decompose script into scenes (per storyboard-from-script Step 3).
  4. Build JSON same as Convert mode.

Append Log entry

Schema strictness

  • Default schema_version: "1.5" (Franky Shaw v3.0 augmentations — product_character, viral_template, icp_avatar.spoken_language).
  • For Demand Gen world-class plan features (per_hook_text_assets, creative_source segmentation, channel_bucket), use schema_version: "1.8".
  • Validate every output. Don't ship a broken spec.

Hard rules

  • MUST validate against schema. If validation fails, fix and re-write.
  • output_dir field in the JSON should point to where rendered video assets land (typically Brands/{brand}/Marketing/storyboards/{date}-{slug}/output/).
  • Don't fabricate scenes. If converting from storyboard.md and a section is unclear, surface to user.

Failure modes

  • storyboard.md scene parsing fails — surface specific section, ask Adam to clarify.
  • Schema validation error — print the offending field + expected shape; fix and retry.
  • Schema version mismatch (e.g., storyboard says v1.3, user wants v1.5 features) — flag, ask Adam to upgrade or downgrade.