HyperFrames CLI skill: teach your agent the hyperframes command line

Source: heygen-com/hyperframes · Maintainer: HeyGen · License: Apache-2.0 · Checked: 24 October 2026

What is the HyperFrames CLI skill?

The HyperFrames CLI skill teaches a coding agent how to drive the hyperframes command line: which command does each job, how to read its JSON, and what to do when a build or render fails. It is the operating manual that sits next to the main HyperFrames skill, which holds the rules for writing a video as HTML.

HyperFrames is HeyGen's open-source framework for "turning HTML, CSS, media, and seekable animations into deterministic MP4 videos," in the repo README's words. The skill's own description says it covers "The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures."

Its skills.sh page listed about 1.2 million installs (snapshot, 24 October 2026), first seen on 31 March 2026. The README lists it in the core set of four skills, with /hyperframes, /hyperframes-registry and /media-use.

What does it do?

The SKILL.md is about 97 lines, with 12 reference files in references/ for the detail. It opens with one rule: run npx hyperframes <command> unless the project provides a wrapper. Every command has --help, most take --json, and a failure prints a Fix: line and exits non-zero.

Commands by job. A table groups the CLI so the agent picks the right tool:

It also marks validate, inspect and layout as deprecated aliases of check and tells the agent not to run them.

The loop. Five steps the agent follows on every video:

1. Run lint after the first pass and after structural changes.
2. Run check --json and fix every error. The skill warns that while a lint error remains, the layout and contrast audits don't run, so "0 samples" means nothing was checked.
3. Run snapshot and read the PNGs: "that is how you see the video."
4. Start preview --background, confirm the URL answers, give you the link and wait.
5. Render only when it is time, with --quality draft while iterating and delivery for the final, then confirm the file's duration with ffprobe.

Timeline edits. The timeline commands make "the edits Studio itself makes," so the project stays editable in HyperFrames Studio. Each edit can be previewed with --plan, several can be batched from a JSON file, and every run prints a receipt that timeline undo can revert.

Where to render. A second table covers local renders, a reproducible Docker render with --docker --strict, batch renders from a rows file, HeyGen's hosted cloud render, and your own AWS or Google Cloud with lambda render or cloudrun render.

Failure recovery. A symptom table handles the common breaks: Chrome missing, a heavy page timing out, slow Linux renders, a capture that writes BLOCKED.md, or a full disk. It warns never to delete .hyperframes, because that folder holds project history.

How do you install it?

The HyperFrames skills guide and README document three routes.

The core set, recommended for agents. This installs /hyperframes, /hyperframes-cli, /hyperframes-registry and /media-use from the current main branch:

npx hyperframes skills update

Just this skill, using the command shown on skills.sh:

npx skills add https://github.com/heygen-com/hyperframes --skill hyperframes-cli

The README notes that skills add reads the skills.sh registry copy, which "can lag main by hours." The CLI skill rarely works alone: the main skill sends command questions here, and this skill sends catalog work to /hyperframes-registry and media work to /media-use. Installing the core set is the simpler choice.

The Claude Code plugin, which bundles every published HyperFrames skill:

claude plugin marketplace add heygen-com/hyperframes
claude plugin install hyperframes@hyperframes

Plugin skills are namespaced, so the README calls the main skill /hyperframes:hyperframes. Claude Code's plugin docs explain marketplaces, and standalone skills go in the usual Claude Code skill folders. For other agents, see Codex skills and Cursor skills.

You need Node.js 22 or later and FFmpeg to render, per the README and the skill.

How do you use it?

You rarely call this skill directly. Ask for a video, and the agent loads the main skill and this one as it scaffolds, checks and renders. Call it by name when the task is about the tooling itself.

Example prompts (suggestions, not quotes from the repo):

• Use /hyperframes-cli to scaffold a portrait 1080x1920 project called launch-teaser and run check on it.
• Run check --json on ./promo, fix every error, then snapshot the midpoint of each scene and show me what you see.
• Move the outro clip to start at 9 seconds and trim the logo sting to 2 seconds. Show me the plan before applying it.
• Render ./promo at delivery quality to out.mp4 and confirm the duration matches the composition.
• The render failed with a Chrome error. Diagnose it with doctor and fix it.

For scaffolding, the init reference lists resolution presets such as landscape (1920×1080), portrait (1080×1920) and square (1080×1080), plus a --tailwind option. The CLI package docs cover the commands for people working without an agent.

Tips and limits

From the skill, its references and skills.sh, not from testing:

• Preview before render. The loop stops at a running preview. Say "render it" or "no stops" if you want the MP4 straight away.
• Cloud rendering is HeyGen's. The cloud reference says cloud render uploads a zipped project to HeyGen's managed cloud, "you pay per credit," and needs a sign-in with npx hyperframes auth login. The direct upload limit is 200 MB. Local rendering needs no account.
• Feedback reports. After a verified render, the skill tells the agent to send one feedback --rating report, plus a note for any feature you asked for that HyperFrames can't do, "unless telemetry is off." The feedback reference says reports go to a public channel and must leave out absolute paths and machine identifiers. If you don't want this, say so.
• Project history is a trial. The history commands sit inside a block marked "trial" in the SKILL.md, so they may change.
• Snyk warning. On skills.sh, Snyk's audit dated 22 October 2026 shows Warn, medium risk, for W011 "Third-party content exposure detected (indirect prompt injection risk)," because capture fetches live public web pages. Gen Agent Trust Hub and Socket showed Pass. Review captured content before letting the agent act on text from a site you don't control.

Under Apache-2.0 you can copy and modify the skill as long as you keep the license and notices.

Save it in your Kipt library

In Kipt, open Skills and paste the GitHub folder link into the import box. Kipt reads the SKILL.md together with its references/ folder. Because heygen-com/hyperframes holds several skills, Kipt shows a list, so you can take the whole core set in one go. Your copies live in your own private GitHub repo and install into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Kipt is not affiliated with HeyGen or the HyperFrames project.

Similar skills

• HyperFrames skill: the render contract and work loop; read it first.
• HyperFrames registry skill: the catalog behind catalog and add.
• media-use skill: music, voiceover, images and colour grades for a HyperFrames video.
• Remotion to HyperFrames skill: port existing video code into HyperFrames.
• Remotion skill: make videos in React instead of HTML.