Long-Video Skill Development

The bundled demo skill dialogue-video-skill turns a topic into a multi-character dialogue video — research, script, assets, storyboard, per-shot generation, QA, and final edit, all executed autonomously by an agent. This guide takes it apart so you can build your own fully automated video pipeline skill.

1What a skill is

A skill is one folder; drop it into your agent’s skills directory and it’s installed:

dialogue-video-skill/
├─ SKILL.md          ← the showrunner manual: flow, boundaries, done criteria
├─ references/       ← stage cards: preproduction, generation, compose, subagent protocol — read on demand
└─ scripts/          ← deterministic code: index, gate validation, guarded submission

SKILL.md is not a prompt template — it is an operations manual the lead agent reads; references split by stage keep the context small; scripts own everything deterministic — validation, hashes, ledgers — so nothing depends on model memory.

2The nine-stage pipeline

The episode advances through fixed stages, each behind a gate; a failed gate never advances:

Stage state lives in OpenMontage’s dialogue-video pipeline. Recovery uses the native get_next_stage, and finished generation jobs are never resubmitted; an upstream change first invalidates the affected downstream checkpoints, then redo happens locally.

3Five architecture rules worth copying

1. Final package first. One project has exactly one ten-document final package (research, full script, asset design, scenes, grid descriptions, per-shot source prompts, …); no media generation starts until every document passes review. production.json stores only document paths, hashes, versions, and job bindings — never the content — so an edited-but-unreviewed document is rejected by the scripts.
2. Stage gates. validate.py checks deterministic contracts: file exists, hash matches, reference IDs bound. PASS advances; FAIL writes blocked. Scripts never replace taste — looking and listening belong to independent QA subagents.
3. Guarded submission. Every generation goes through guarded_mcp.py: validate the parameter contract before submitting, then append request, receipt, and hashes to the jobs.jsonl ledger; idempotency_key prevents duplicate paid draws. See Narrow MCP.
4. Subagent protocol. Only the showrunner connects to the media MCP. Subagents receive a stage card (generated by preproduction.py context --stage) and return artifacts — no projects, no generation, no retries, no preset edits. Self-review can only be marked self_review, never passed off as independent QA.
5. BLOCKED semantics. Missing capability, exhausted retries, failed QA — stop honestly and report which stage halted; never ship a failing version as passing. Never mass-draw on paid models with an unknown budget.

4Build your own

Forking dialogue-video-skill beats writing from scratch. Hand the repository to your coding agent:

Read SKILL.md and references/ in examples/skills/dialogue-video-skill. Keep the nine-stage gate architecture, final-package-first, and guarded submission; retarget the subject to [your format, e.g. a single-host finance explainer]: replace the asset strategy, shot style, aspect ratio, and QA standards. All media generation keeps going through the generic videofree MCP tools, and editing/compositing through film-studio plugin actions — no hand-rolled FFmpeg, no direct ComfyUI calls.

Keep the skeleton: SKILL.md sets boundaries and done criteria → references split the stages → scripts own deterministic validation and guarded submission. Freely replace: stage count and gate contents, asset strategy (character boards / product shots / charts), and QA standards (dialogue accuracy, lip sync, composition hierarchy).

Two more skill examples live in the repository — short-video-skill (short-form scripts) and videofree-creation (general creation) — useful contrasts at different complexity levels.

5Pilot, then scale

1. Pilot one 1-minute, 3-shot episode with a per-shot attempt cap in the task config (default 3) and a hard budget ceiling;
2. Watch progress in the gateway UI: the ai-project-progress plugin shows the nine stage states and project-archive files the final documents — the skill pushes after every gate;
3. After the pilot passes, add duration and shots; request high-res second takes as needed — any shot length may be refined, and version selection always requires human confirmation;
4. Delivery check: final video plays, measured size/duration/audio tracks recorded, dialogue QA passed, ledger complete.