Demo Skills: Install & Use

The repository ships two demo skills under examples/skills/ — story-video-skill and OpenMontage. The first produces general story-driven long videos; the second carries pipeline state and checkpoints — together they hand the whole video pipeline to an agent. They are production instructions and tooling for an agent, not double-click software. Finish the installation guide first, then connect them to the agent you already use.

1What this skill does

story-video-skill is a general story-driven long-video skill: you supply a story (or co-create one with the agent), and the subject matter and form of expression follow the story — action, fights, chases, suspense, adventure, narration, dialogue, ambient sound, or silent shots. It does not presuppose multi-character dialogue or explainer structure; it will not force your story into a two-person conversation.

The skill owns story planning, assets, storyboards, prompts, generation scheduling, QA, and project progress / creation archives; actual image, video, and audio generation remains bound by the current VideoFree Studio plugin capabilities, and editing, mixing, and export run through the gateway’s film-studio plugin.

2Prepare two complete skill folders

In the VideoFree Studio repository, examples/skills/ contains the two folders below. Copy both whole folders (including references/ and scripts/) into your agent’s skills directory — never copy only SKILL.md.

Your agent's skills directory/
├─ story-video-skill/  ← story planning, assets, storyboards, generation scheduling, QA
└─ openmontage/        ← pipeline state, stage checkpoints, artifact validation

OpenMontage is an independent third-party toolkit, not built by VideoFree Studio — keep its full source, AGPL-3.0 license, copyright, and attribution notices intact. This skill’s integration with it (the story-video pipeline) is documented in OpenMontage’s docs/story-video-integration.md and is not an official upstream release.

Media generation is called directly through VideoFree Studio’s MCP by the lead producer role — configure it as in step 4. The repository also ships videofree-creation (API client and MCP guide) for lightweight API-only integration.

3Have the agent check its environment

Generation happens on the VideoFree Studio gateway side; the agent side needs Python 3.10+ (with OpenMontage’s requirements installed) and ffprobe (for download validation). Editing, mixing, and rendering all go through gateway film-studio plugin actions — you do not need Remotion or HyperFrames locally. Send it this:

Install the videofree demo video skills for me. I have prepared the story-video-skill and openmontage folders. First confirm this agent’s skills directory, then copy the complete folders preserving all assets, scripts, and licenses. Check Python 3.10+ and ffprobe, and install openmontage’s requirements.txt in the Python environment you actually use. Configure my videofree MCP for the lead producer: [gateway URL, e.g. http://127.0.0.1:8765/mcp]. Refresh skill discovery, validate media capabilities. Check only — do not generate anything or spend quota yet.

4Connect VideoFree Studio’s MCP

Add an HTTP MCP server to the agent’s configuration, name it videofree, and set the URL to http://<gateway-machine-IP>:8765/mcp. It starts with VideoFree Studio — no extra service. No token is used today; if authentication is enabled later, the scripts read VIDEOFREE_API_TOKEN as a request header.

On the same machine use http://127.0.0.1:8765/mcp directly. From another machine you must replace 127.0.0.1 with the gateway machine’s real LAN IP — do not copy the example blindly.

Have the agent check health and list capabilities first (get_health, list_capabilities). Results coming back means the connection works. Configuration formats differ per platform — follow your agent’s HTTP MCP documentation and story-video-skill/references/install.md; one platform’s JSON is not a universal format.

5Refresh skills and run the readiness check

Refresh or restart the agent so it picks up the new skills, then walk the capability checklist in story-video-skill/references/install.md: the Qwen image chain and H3 conversion, film-studio compose actions, progress and archive plugins, and image/video/audio review capability. Whatever is missing must be reported honestly — without Qwen capability the skill stops rather than falling back to another image model; without review capability it never pretends a review passed.

With subagents, only the lead producer connects to media generation tools; give script, storyboard, and QA roles permissions per task. Permission isolation belongs in host settings — skill text alone cannot enforce it.

6Make one short first, then loosen automation

For the first run, send a real story and confirm planning, generation, and composition all work:

Using story-video-skill, turn the story I provide into a 3-minute long video; let the story decide the subject and form — it needs a chase and a fight, and keep the key dialogue from the original story. Finish and review the ten-document final package first, then execute within the approved budget. Tell me the production plan, expected generation count, and whether a second take is needed — wait for my confirmation before generating.

You can also explicitly request pure action, narration, ensemble scenes, animation, suspense, and so on; anything unspecified is planned from the story, never defaulted to an explainer dialogue.

State the review-authorization boundary clearly. H3 video conversion confirmation waits for your human approval by default; the agent may confirm on your behalf only for shots you have explicitly delegated — a vague “just finish everything” does not count as that authorization. If something ambiguous appears — unclear identity, over budget — the agent must still stop and ask.

Example: “Plan approved, at most 12 generation submissions, second takes allowed; continue automatically where unambiguous, ask me first about identity or budget issues.”

7Image candidates: 2–4 per submission, one batch QA

In image stages (subject drafts, locked references, storyboard grids) you can submit 2–4 candidates at once and run a single batch QA over the whole set, locking only the QA-passed, hash-bound winner. This merges submission and review round-trips.

8Project ownership, resume, and common failures

• Project & media ownership: the skill creates its own gateway project via create_project (AI-created flag) and submits every generation with that project ID, so automated output never mixes with your manual generations. The gateway UI’s ai-project-progress and project-archive plugins show progress and drafts throughout; if the plugins are missing, it degrades to a local ledger and says so.
• Working directory: each production uses its own run directory (run_root) for the production plan, downloads, ledger, and QA records — never pile finished cuts into the skill folders. The final cut lands in the agreed delivery directory, not necessarily the VideoFree Studio project folder; ask where it will output before starting.
• Resume: every generation goes through guarded_mcp.py and is written to the jobs.jsonl ledger (request, receipt, hashes, idempotency key). After an interruption, recovery reads the ledger and OpenMontage stage checkpoints — finished generation jobs are never resubmitted; changing upstream content first invalidates the affected downstream checkpoints, then redo happens locally.
• Common failures: missing capability, exhausted retries, failed QA — the skill stops honestly (BLOCKED) and reports which stage halted; it never ships a failing version as passing. QA failures redo only the affected assets/shots; passed candidates are not regenerated.

To take this skill apart — final-package-first, stage gates, guarded submission — and build your own fully automated pipeline for a different format, see Long-Video Skill Development.