HyperFrames Motion Director: a Chinese-first Agent Skill for turning a README into a vertical motion video

An Agent Skill, not a renderer

The repository describes itself as an Agent Skill for planning, producing, and reviewing HyperFrames motion videos. That distinction decides whether the project is useful to you. It does not encode video. It does not ship a compositor. What it ships is instruction material plus Node.js scripts: a SKILL.md, templates, references, validation helpers, and evaluation cases under skills/hyperframes-motion-director/. The rendering itself is delegated to HyperFrames, and the README tells you to run the strongest checks the local HyperFrames CLI supports, naming validate, inspect, snapshot and render.

The intended user is someone who already works through an agent that can read skill files and execute shell commands, and who wants a product launch film, an article-to-video piece, or a kinetic typography promo without re-deciding the whole production process each time. The defaults are opinionated: vertical 9:16 at 1080x1920, concise screen copy, controlled visual assets, readable hold frames, and a review step before delivery. Chinese is the default language of the output, and the README states that other platforms have documented overrides rather than silent ones.

If you want a library you import into a Next.js app and render on a server, this is the wrong shape entirely. The deliverable here is a scaffold plus a set of contracts that an agent fills in.

The two-phase gate and the files it produces

Production is deliberately split. Phase one creates a brief and design proposal and waits for confirmation. Phase two generates assets, builds the composition, validates snapshots and renders, then writes a review report. The gate is the point: an agent that starts generating frames before anyone agreed on the direction burns image-generation calls and produces something nobody asked for.

The scaffold writes four core files. BRIEF_DESIGN_PROPOSAL.md holds direction, format, visual plan and motion plan. DESIGN.md holds the visual system, asset rules and layout contracts. STORYBOARD.md holds beats, screen copy, timing and transitions. REVIEW_REPORT.md holds checks, snapshots, issues and remaining risks. Three more files act as design-engineering contracts: SCENE_SCHEMA.json for structured scenes, slots, layout contracts, timing and snapshots; VECTOR_TEMPLATES.json for approved SVG scene systems, icon and decor rules, and rejection tests; MOTION_PRIMITIVES.json for the approved GSAP, SVG and CSS motion vocabulary plus plugin policy and selection rules. BEAT_MAP.json and MOTION_MAP.json are optional and cover music, voiceover or exact timing, and GSAP choreography and transition maps.

Two enforcement rules stand out because they are unusual. Background and component counts are derived from the actual story, product mechanism and proof needs rather than a fixed quota. And text-over-background layout contracts are settled before animation, which is the correct order and the one most pipelines get backwards.

Install and a first real use

The README gives a single install command through the skills CLI. It adds the skill from the GitHub repository path, so you need Node.js 18 or newer, which the README lists as a requirement.

npx skills add geekjourneyx/hyperframes-motion-director

After installation the README says to ask your agent for a HyperFrames motion video, a product launch film, an article-to-video piece, or a kinetic typography promo. The example prompt in the README is explicit about the gate, and you should keep that phrasing because it is what forces phase one:

Turn this README into a 12-second Chinese vertical HyperFrames promo.
Start with the brief/design proposal and wait for confirmation.

What you should see is a BRIEF_DESIGN_PROPOSAL.md and a DESIGN.md before any asset generation, not a finished video. If your agent jumps straight to frames, the skill has not been loaded.

For local development you can scaffold without the agent. The basic form creates a project directory:

node skills/hyperframes-motion-director/scripts/create_project.mjs ./my-motion-film

Adding both flags also creates the timing and motion maps, which the README lists as optional files:

node skills/hyperframes-motion-director/scripts/create_project.mjs ./my-motion-film --with-timing --with-motion

The README does not document what happens when the target directory already exists, so scaffold into a fresh path and inspect the output before pointing an agent at it.

Validation scripts are the real quality control

The repository ships its own checkers, and they are the part you can run without trusting an agent's summary of its own work. Package structure first:

node skills/hyperframes-motion-director/scripts/check-structure.mjs

Then per-project asset and artifact checks. The README lists a strict mode and a premium-asset mode for check_assets.mjs, plus separate validators for image assets, artifacts, and design engineering:

node skills/hyperframes-motion-director/scripts/check_assets.mjs <project-dir>
node skills/hyperframes-motion-director/scripts/check_assets.mjs <project-dir> --strict
node skills/hyperframes-motion-director/scripts/check_assets.mjs <project-dir> --require-premium-assets
node skills/hyperframes-motion-director/scripts/validate_image_assets.mjs <project-dir>
node skills/hyperframes-motion-director/scripts/validate_artifacts.mjs <project-dir>
node skills/hyperframes-motion-director/scripts/validate_design_engineering.mjs <project-dir>

These are structural checks. They can confirm that a manifest records accepted assets and revisions, that transparent cutouts are named, that dark and light contact sheets exist, and that the schema, vector and motion contracts are present. They cannot tell you whether the video is any good. The README is honest about the boundary: for implemented compositions it points you at the local HyperFrames CLI for validate, inspect, snapshot and render. Treat the Node scripts as a floor, not a verdict.

Where it breaks down

The dependency on an external HyperFrames toolchain is the largest constraint, and the README never states which version of that CLI is required. It says to run the strongest checks supported by the local CLI, which implies version drift is expected and handled by degradation rather than by pinning. That is a reasonable choice for a skill, and a bad one if you need reproducible output across machines.

Image generation is assumed. The enforcement list talks about Image Gen assets with a clear role, a quiet text zone, a crop-safe area and a local path, plus separate hero generations and independent vertical background plates. If you have no image-generation step in your pipeline, a large part of the skill's value evaporates, because the asset rules are written around generated material rather than footage you already own.

Chinese-first is a default, not a limitation, but it is a real orientation. The README says overrides for other platforms are documented, so an English-language promo is possible; it is simply not the path of least resistance, and the layout contracts are tuned for concise screen copy in that context.

Finally, the two-phase gate costs a round trip. For a throwaway internal clip, waiting for brief confirmation is friction you may not want.

HyperFrames vs Remotion, and what the skill actually adds

Remotion is the obvious comparison, and the difference is architectural. Remotion is a React-based video framework: you write components, and the composition is code you own and version. HyperFrames is the rendering target this skill plans for, and the skill's job is upstream of that, producing a brief, a storyboard, a scene schema and a motion vocabulary that an agent then implements.

So the honest framing is not that one replaces the other. If you are comfortable writing React and want full control over every frame, Remotion gives you that control directly, and this skill adds nothing except a planning layer you did not ask for. If you want an agent to take a README and produce a structured Chinese vertical promo with contracts and validation, the skill is doing work that a bare framework leaves to you.

The GSAP choreography contracts are the most concrete piece of that added value: labels, position parameters, plugin registration, transform aliases and performance rules are specified before implementation rather than discovered during debugging. The stated intent is motion that guides attention instead of repeating static slide patterns. Whether it achieves that is a judgement about the output, not about the repository, and the repository cannot make it for you.

Licence, maintenance and upgrade cost

The licence is AGPL-3.0. That is a copyleft licence with a network clause, and it is worth reading before you wire the skill into a hosted product, because the obligations attach to distribution and to providing source over a network. This is not legal advice; if your use is commercial and hosted, get a lawyer to read the licence text rather than a summary.

The last push was on 2026-07-26, and the newest release in the list is v2.8.0 from the same day, following v2.7.0 on 2026-07-24. The repository is not archived. The README describes an automatic release path: stable tags publish GitHub Releases after the tagged source passes repository checks, and a push to main repairs the newest stable tag when its Release is missing. RELEASING.md is named as the full procedure and recovery rules.

Upgrade cost is mostly the cost of re-reading SKILL.md and the reference files, since the contracts and templates can change between minor versions. The scripts are plain Node.js entry points with no install step of their own, so there is no dependency graph to untangle. Check CHANGELOG.md between tags rather than assuming template compatibility.

Editorial conclusion

Adopt it if you already have an agent that can run shell commands and you want a repeatable Chinese-first 9:16 pipeline with a brief gate and machine-checkable contracts. Do not adopt it if you expect a renderer: the skill only plans and validates, and the actual composition work belongs to the HyperFrames CLI. Before committing, run check-structure.mjs, scaffold a throwaway project with --with-timing --with-motion, and confirm that every validation script listed in the README exists in skills/hyperframes-motion-director/scripts/ and exits cleanly on the scaffold.

Frequently asked questions

Official sources

1. geekjourneyx/hyperframes-motion-director on GitHub
2. Issues
3. License: AGPL-3.0
4. README
5. Releases