oma-video
Create short, explainer, or recorded-demo videos through the OMA video CLI. Use for scripts, narration, assets, composition, and video delivery.
How do I install this agent skill?
npx skills add https://github.com/gracefullight/stock-checker --skill oma-videoIs this agent skill safe to install?
- Gen Agent Trust Hubwarn
This skill provides a video generation pipeline using Remotion, Playwright, and MoneyPrinterTurbo. It includes internal drivers that dynamically load code and modules based on directory paths passed as arguments, and it handles external media assets and untrusted user briefs for content generation.
- Socketwarn
2 alerts: gptSecurity, gptAnomaly
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Video Router
Scheduling
When to use
Use this skill for a short/reel, README or code explainer, or demo walkthrough.
| Request | Mode | Default aspect | Required source |
|---|---|---|---|
| Short, reel, social clip | shorts | 9:16 | Topic or brief |
| README, code, data explanation | explainer | 16:9 | Topic or source path |
| Demo or walkthrough | demo | 16:9 | Human recording via --capture |
When NOT to use
Use oma-image for a still image, oma-slide for a deck, oma-voice for
audio only, and oma-explanation for an interactive HTML explainer. Editing an
existing finished video and live streaming are out of scope.
Structural Flow
Inputs are a brief plus optional mode, aspect, locale, captions, visual, voice,
music, duration, compositor, capture path, and seed. Outputs live in
.agents/results/videos/<timestamp>-<shortid>-<mode>/:
script.json,timing.json, andrender-spec.jsonform the deterministic asset bus.- Captions and acquired audio/visual assets are recorded in
manifest.jsonwith hashes, providers, cost, warnings, and exit code. - A successful real render contains
<mode>-<slug>.mp4, an encoded video stream, and a positive ffprobe duration.
OMA_VIDEO_MOCK=1 is a test harness only. It can create deterministic text
placeholders with an .mp4 name; those files are never a user deliverable. A
missing HyperFrames/MPT toolchain, an un-authored composition, a render error, or
an invalid video fails with diagnostics and leaves the script/render spec for
recovery.
Decide and confirm
Infer mode when clear: short/reel -> shorts; README/code/data/explain ->
explainer; demo/walkthrough/capture -> demo. For a one-line request, state
the inferred mode, aspect, duration, visual strategy, captions, locale, and
voice/music before invoking. Do not make the user complete a questionnaire
when those defaults are clear.
Ask only when it changes the result: an ambiguous mode/source, a required demo recording, or a cost confirmation. Respect an explicit mode, aspect, duration, captions, or voice verbatim.
For a demo, a human records the screen and controls login. --source web --url
provides context only; it never automates login or starts a recorder. Without
--capture, return guided capture instructions and stop.
Logical Operations
Guardrails
- Keep output and capture paths inside
$PWDunless external output is explicitly allowed. Validate capture formats and copy external assets into the run directory. Mask URL query/hash tokens in logs and manifests. - Provider configuration is key-optional: use the configured chain. Paid providers require their environment key and the cost guardrail. Local fallbacks may replace voice, visuals, captions, or music; record coverage in warnings. A compositor failure is never a fallback video.
- Before a paid provider action or rerun, compare the planning estimate with
cost.guardrail_usdor--max-usdand reuse existing spend authorization. In an active OMA video workflow, record the actual paid, limited, fallback, or declined choice before executing it (execution protocol Step 2). Pass--yesorOMA_VIDEO_YES=1only for an already authorized paid action; the event does not grant permission. - Respect
limits.max_duration_sec(180) andlimits.max_scenes(40). Cancel subprocess work on SIGINT/SIGTERM. - Keep run directories. Never auto-prune a user’s video artifacts.
--dry-runwrites only planning artifacts and does no provider render. It does not prove an MP4 exists.
Canonical command path
# Plan or create the asset bus. Supply --script whenever an agent authored it.
oma video generate "Jeju coffee" --mode shorts --aspect 9:16 \
--captions tiktok --script ./script.json --output json
# Deterministic planning only; no real render or provider work.
oma video generate "explain this project" --mode explainer --seed 42 --dry-run
# Human-recorded demo input.
oma video generate "feature walkthrough" --mode demo --capture <absolute-path>.mp4
# Scaffold the per-run HyperFrames project, author index.html as instructed,
# then render and validate the encoded output.
oma video compose <runDir> --output json
oma video render <runDir> --output json
# Diagnose required toolchains without changing a run.
oma video doctor
oma video provider list
oma video generate --output json returns
{exitCode, runDir, manifestPath, scriptPath, renderSpecPath, warnings, error}.
Read video and asset paths from the manifest; the JSON envelope has no
outputs field.
Failure and recovery
-
Missing HyperFrames composition:
oma video compose <runDir>prepares the project and authoring contract. Author<runDir>/hyperframes/index.htmlusing the generatedAUTHORING.md, then invokeoma video render <runDir>. The command lints, renders, and ffprobes the output. Fix a reported composition or toolchain failure and re-run; return a failure report when it cannot render. -
Missing MPT toolchain:
--compositor mptrequires the installed checkout, its virtual environment, and ffmpeg. Useoma video doctor --install-mptwhen setup is authorized and available. MPT setup failures, driver failures, and non-video output fail with the diagnostic; they do not write a placeholder MP4.
Success means all asset schemas and manifest hashes validate and a real MP4 passes video-stream and duration validation. A partial success may use a key-free visual, timing, caption, or music fallback, but it still requires that real video validation.
References
Conditional resources
Load only what the task needs:
resources/execution-protocol.mdfor the full ordered pipeline, failure mapping, and JSON reporting rules.resources/vendor-matrix.mdbefore changing providers, keys, cost, or fallback order.resources/script-schema.mdwhen authoring or validating--scriptinput.resources/prompt-tips.mdwhen turning a brief into scene prompts.resources/hyperframes-authoring/README.mdand the selected mode guide before writingindex.html.resources/checklist.mdbefore handing a real video to a user.
Verification
For CLI/runtime changes, add a regression test for the affected success and failure paths. At minimum run the focused Vitest files, for example:
cd cli
bunx vitest run commands/video/providers/compositor.test.ts \
commands/video/orchestrator.test.ts
bunx biome check commands/video/providers/compositor.ts \
commands/video/providers/compositor.test.ts
Do not run a live render merely to test documentation or a mock-only branch.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/gracefullight/stock-checker/oma-video">View oma-video on skillZs</a>