Skip to content

Make videos on the computer you already own. FreeVideo runs MiniMax H3 in as little as 8 GB of VRAM and 16 GB of RAM, and adapts its acceleration path to your hardware.

Ship the agent skill with the install-skill command

Bowen Xued216e98fc443
diff --git a/MANIFEST.in b/MANIFEST.in
index 3b2bfbc..d5944a9 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -11,6 +11,7 @@ recursive-include web/fonts *.woff2
recursive-include web/tutorial *.webp *.mp4
recursive-include freevideo_engine/assets *.png *.ico
recursive-include freevideo_engine/launcher *.qml
+recursive-include freevideo_engine/agent/skill *.txt
recursive-include freevideo_engine/launcher/licenses *.txt
recursive-include freevideo_engine/licenses *.txt
recursive-include constraints *.txt
diff --git a/freevideo_engine/agent/cli.py b/freevideo_engine/agent/cli.py
index 793729b..d32dc74 100644
--- a/freevideo_engine/agent/cli.py
+++ b/freevideo_engine/agent/cli.py
@@ -47,6 +47,8 @@ def build_parser():
commands.add_parser('status', help='Readiness, limits, LoRAs, VLM and queue')
commands.add_parser('guide', help='How to write H3 prompts')
commands.add_parser('schema', help='JSON Schemas of jobs')
+ command = commands.add_parser('install-skill', help='Copy the FreeVideo skill where Codex, Gemini CLI, Cursor and Claude Code read skills')
+ command.add_argument('--target', choices=('agents', 'claude'), action='append', help='Default: both')
command = commands.add_parser('capabilities', help='Read the studio capability cache')
schema.cli_arguments(command, schema.contracts()['GET', '/capabilities']['query'])
command = commands.add_parser('asset', help='Download a saved library video or thumbnail over HTTP')
@@ -179,6 +181,11 @@ def main(argv=None):
return {'from_job': value} if JOB_ID.fullmatch(value) else {'library': value} if LIBRARY_ID.fullmatch(value) \
else {'path': str(Path(value).resolve())} if Path(value).exists() else {'file': value}
+ if args.command == 'install-skill':
+ from . import skill_install
+ print(json.dumps({'installed': skill_install.install(tuple(args.target or ('agents', 'claude')))}, indent=2))
+ return 0
+
try:
client = Client(args.url, root=args.root, name='freevideo-cli')
if args.command in EXTRA_COMMANDS:
diff --git a/freevideo_engine/agent/skill/freevideo/SKILL.txt b/freevideo_engine/agent/skill/freevideo/SKILL.txt
new file mode 100644
index 0000000..bf1211f
--- /dev/null
+++ b/freevideo_engine/agent/skill/freevideo/SKILL.txt
@@ -0,0 +1,38 @@
+---
+name: freevideo
+description: Make videos with the user's local FreeVideo through its MCP tools or the `freevideo agent` command line. Use when the user asks to generate or continue a video, edit a picture, cut a timeline or make a multi-shot film in FreeVideo.
+---
+
+# FreeVideo
+
+FreeVideo runs on the user's own computer. Everything below goes through its MCP server (tools named `freevideo_*`) or the same operations from a shell: `./freevideo agent <command>` (Windows: `freevideo.cmd agent`).
+
+## Before anything else
+
+1. Call `freevideo_status`. If it is not ready, tell the user what is missing; do not retry in a loop.
+2. Read `freevideo_prompt_guide` once before writing a prompt. Prompts are English sections; dialogue and on-screen text stay in the user's language.
+3. Call `freevideo_plan` with the job you intend to run. It returns the real frame count, the number of parts and a time estimate for this computer. Tell the user the estimate before a long run.
+4. The user sees the same work in the FreeVideo window. A tool may answer `needs_confirmation`: wait for the user (`freevideo_wait` without an id), then repeat the identical call once approved. If the user declines, stop and say so; do not retry with a changed reference.
+
+## Pick the right task
+
+- One video, up to 60 seconds: `freevideo_generate`. Longer than the device can do in one run is cut into parts and joined automatically.
+- Start from or end on a picture: pass it as first or last frame. Make the picture first with `freevideo_generate_image`.
+- A film of several shots to choose between: the `freevideo_drama_*` tools. See `references/film.md`.
+- Existing footage on a timeline: the editing project tools. See `references/edit.md`.
+- A picture to change: `freevideo_edit_image` for a quick change, the `freevideo_image_*` tools for layered edits. See `references/image.md`.
+- Several independent jobs: `freevideo_submit_batch`.
+
+## Running jobs
+
+- A job takes minutes. Call `freevideo_wait` with the job id; it returns after at most 25 seconds. If the job is still active, call it again with the same id. Never submit the same job twice.
+- A failed or interrupted generation is continued with `freevideo_resume`; only unfinished parts run.
+- `freevideo_cancel` only for a job you started and the user wants stopped.
+- Look at a result before reporting it: `freevideo_look` (a frame or a contact sheet).
+- Report what you made with the saved-video id (`freevideo_library`), not a local path.
+
+## Rules
+
+- Do not start a second generation while one for the same request is running; the computer has one GPU.
+- Never claim a video is good without looking at it.
+- Keep your own chat short; the user is watching progress in FreeVideo.
diff --git a/freevideo_engine/agent/skill/freevideo/references/edit.txt b/freevideo_engine/agent/skill/freevideo/references/edit.txt
new file mode 100644
index 0000000..18dfcf4
--- /dev/null
+++ b/freevideo_engine/agent/skill/freevideo/references/edit.txt
@@ -0,0 +1,11 @@
+# Editing projects
+
+Projects are the timelines shared with the FreeVideo editor page.
+
+1. `freevideo_projects` lists them; `freevideo_project_create` starts an empty one.
+2. Footage from the user's disk: `freevideo_import_media`, then poll `freevideo_imports` until `ready` (`failed` is final). Insert the returned `import:<id>` source.
+3. Always `freevideo_project_read` first. Edits carry the revision and clip ids you just read. On a `project_changed` error, read again and recompute; do not retry the old edit.
+4. `freevideo_editor_operations` applies 1 to 64 edits atomically. Prefer it to `freevideo_project_write`, which replaces the whole timeline.
+5. `freevideo_project_generate` makes new picture and sound for selected clips or a frame range, as the Generate button does.
+6. Subtitles: `freevideo_project_listen` with mode `align` times lines you give, `transcribe` writes down what is said.
+7. `freevideo_export` renders one saved revision to MP4 in the saved videos. Wait for the returned job.
diff --git a/freevideo_engine/agent/skill/freevideo/references/film.txt b/freevideo_engine/agent/skill/freevideo/references/film.txt
new file mode 100644
index 0000000..e2a2f75
--- /dev/null
+++ b/freevideo_engine/agent/skill/freevideo/references/film.txt
@@ -0,0 +1,12 @@
+# Films of several shots
+
+Use this only when the film needs separately chosen shots. A single video of up to 60 seconds is one `freevideo_generate` job.
+
+1. Reuse or make cast cards: `freevideo_cast_list` first (reuse a matching card), then `freevideo_cast_create`; `freevideo_cast_generate` makes reference pictures when the user gave none.
+2. `freevideo_drama_plan` previews the shots without starting.
+3. `freevideo_drama_start` creates the durable film. Read it with `freevideo_drama_get` (use `since` and `wait`).
+4. For each shot whose takes are done: `freevideo_drama_sheet` shows timed frames and the previous chosen last frame. Look, then `freevideo_drama_choose`. A continuation can only start after the previous shot is chosen.
+5. A take that missed: `freevideo_drama_reshoot` with a short note on what to change, then review the sheet again.
+6. When every shot is chosen: `freevideo_drama_finish`, then read the film until its output is ready.
+
+Only the user may pause or resume a film. If it is paused, stop acting and long-wait.
diff --git a/freevideo_engine/agent/skill/freevideo/references/image.txt b/freevideo_engine/agent/skill/freevideo/references/image.txt
new file mode 100644
index 0000000..775e9f2
--- /dev/null
+++ b/freevideo_engine/agent/skill/freevideo/references/image.txt
@@ -0,0 +1,6 @@
+# Pictures
+
+- Quick change (crop, rotate, flip, pad, adjust, text, shapes, overlays, remove burned-in captions): `freevideo_edit_image`. The result is a new input file usable as a first frame or reference.
+- Layered edits like the image editor page: `freevideo_image_create` opens a session, `freevideo_image_read` gives the document and revision, `freevideo_image_operations` applies 1 to 64 edits atomically, `freevideo_image_render` makes a PNG input file. Read the revision and layer ids before each edit; on `image_changed` read again.
+- A new picture from a prompt, or combining input pictures, or a first frame with cast members: `freevideo_generate_image`.
+- Check the result with `freevideo_look` before using it.
diff --git a/freevideo_engine/agent/skill_install.py b/freevideo_engine/agent/skill_install.py
new file mode 100644
index 0000000..d36d784
--- /dev/null
+++ b/freevideo_engine/agent/skill_install.py
@@ -0,0 +1,31 @@
+"""Copy the bundled FreeVideo skill folder where Agents that support SKILL.md look for it."""
+from pathlib import Path
+import shutil
+
+SOURCE = Path(__file__).resolve().parent / 'skill' / 'freevideo'
+# Codex, Gemini CLI and Cursor read ~/.agents/skills; Claude Code reads ~/.claude/skills.
+TARGETS = {'agents': ('.agents', 'skills'), 'claude': ('.claude', 'skills')}
+
+
+def target_dir(target, home=None):
+ return Path(home or Path.home()).joinpath(*TARGETS[target]) / 'freevideo'
+
+
+def install(targets=('agents', 'claude'), home=None):
+ """Replace the installed copy (only our own freevideo folder) and return the paths written."""
+ written = []
+ for target in targets:
+ destination = target_dir(target, home)
+ destination.parent.mkdir(parents=True, exist_ok=True)
+ staging = destination.with_name('.freevideo-installing')
+ shutil.rmtree(staging, ignore_errors=True)
+ for source in SOURCE.rglob('*.txt'):
+ # Stored as .txt so the update payload only carries file types every launcher accepts; agents read .md.
+ copy = staging / source.relative_to(SOURCE).with_suffix('.md')
+ copy.parent.mkdir(parents=True, exist_ok=True)
+ shutil.copyfile(source, copy)
+ if destination.exists():
+ shutil.rmtree(destination)
+ staging.rename(destination)
+ written.append(str(destination))
+ return written
diff --git a/pyproject.toml b/pyproject.toml
index 0fbe352..fe22466 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -36,4 +36,4 @@ include = ["freevideo_engine*"]
[tool.setuptools.package-data]
"freevideo_engine.prompt_vlm" = ["model.json"]
"freevideo_engine.image_gen" = ["image_models.json", "licenses/NOTICE.txt"]
-freevideo_engine = ["stage_estimate_params.json", "build-version.txt", "build-identity.json", "release_notes.json", "dependencies.json", "model_files.json", "model_shares.json", "prepared_models.json", "macos_reference_catalog.json", "superseded_tables.json", "bootstrap_versions.json", "curl_windows.json", "git_linux.json", "git_macos.json", "gcc_linux.json", "uv_downloads.json", "torch_downloads.json", "test_prompts.json", "windows_bootstrap.ps1", "assets/*.png", "assets/*.ico", "launcher/*.qml", "launcher/licenses/*.txt", "licenses/*.txt", "licenses/runtime/*.txt", "subtitle_pack.json", "frame_preview_weights.json"]
+freevideo_engine = ["stage_estimate_params.json", "build-version.txt", "build-identity.json", "release_notes.json", "dependencies.json", "model_files.json", "model_shares.json", "prepared_models.json", "macos_reference_catalog.json", "superseded_tables.json", "bootstrap_versions.json", "curl_windows.json", "git_linux.json", "git_macos.json", "gcc_linux.json", "uv_downloads.json", "torch_downloads.json", "test_prompts.json", "windows_bootstrap.ps1", "assets/*.png", "assets/*.ico", "launcher/*.qml", "launcher/licenses/*.txt", "licenses/*.txt", "licenses/runtime/*.txt", "subtitle_pack.json", "frame_preview_weights.json", "agent/skill/freevideo/*.txt", "agent/skill/freevideo/references/*.txt"]