mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
* fix(core): a .hyperframes folder in a subfolder stays private too The private-file rule treated .hyperframes as the app's records folder only at the project root. A project copied into a subfolder keeps its own .hyperframes/, and its chat history, hand-off and other records there were listed in the file tree and served by Studio's file and preview routes and by the other file servers that share the rule. A .hyperframes segment at any depth is now private, in every spelling Windows opens. Studio's own files and the prepared-assets and requests folders stay servable only at the root, the one place Studio reads and writes them. The file tree also skips .hyperframes/backup at any depth. * fix(cli): the capture --local-file page server answers only its own host The page server that capture --local-file starts on a loopback port answered a request whatever its Host header said. A site whose name resolves to 127.0.0.1 could then read the files it serves from the browser. The server now refuses, before any file lookup, a request whose Host is not its own loopback name and port, with the same isOwnLoopbackHost rule the static project server and the engine file server use. Every response carries X-Content-Type-Options: nosniff. The capture browser loads the page by 127.0.0.1 and its port, and fetchLocalPageUrl reads from disk, so both work as before. * fix(skills): a plugin manifest in the project pins no CLI release The skills launcher read a plugin manifest from the folder above skills/ wherever the skills were installed. For a project-level install that folder is the project itself or its .agents or .claude folder, so a plugin.json shipped with a project could pin an old hyperframes release and turn off update checks and standalone skill refreshes. The launcher now reads a manifest only from a bundle of its own: a folder whose name does not start with a dot and that is neither the folder the CLI works in nor one that contains it. Plugin managers install bundles into their own folders, so those keep their pin. A manifest anywhere else leaves the call the same as with no manifest. A manifest that pins a release older than 0.9.34, the launcher's floor, is refused. The agent-facing plugin rules and the skills guide say the same. * fix(skills): a plugin bundle inside the working folder pins only behind a dot folder A package inside a monorepo could still pin the CLI: with the agent working at the monorepo root, <mono>/packages/video/plugin.json sat beside a skills folder the launcher took for a bundle. The launcher now also refuses a bundle inside the working folder unless a folder whose name starts with a dot lies between them, as .claude does in ~/.claude/plugins/cache when the agent works in the home folder. Bundles in ~/.claude/plugins, ~/.cursor/plugins and ~/.gemini/extensions keep their pin from the home folder or a project. The plugin rules and the skills guide now state the three conditions the launcher checks. * docs(cli): a .hyperframes folder in a subfolder is left out and not served The private-file rule now treats a .hyperframes/ folder at any depth as the app's records. Files stored in one inside a subfolder, assets included, stay out of uploads and are not served by Studio, preview or render. The cloud render section now says so beside the rule it already describes. * fix(cli): capture pages keep loading scripts with no or unlisted extensions With nosniff on every response, a script the capture page server did not know the type of (a .cjs file, or a file with no extension) was served as application/octet-stream, and the browser refused to run it. The server now names .cjs, .wasm, .xml, source maps, web manifests, CSV, WebVTT, glTF and more audio, video and image types. A file whose type is still unlisted is served without nosniff, so the browser sniffs it as it did before and such a script runs. Every listed type and every empty error response keeps nosniff. * fix(share): sync and share leave out a .hyperframes folder below the root The .hyperframes rules in the source path policy matched only at the project root, so a copy's records in a subfolder, such as sub/.hyperframes/agent-runs.jsonl, fell through to the default rule and travelled with share and sync. A new nested-hyperframes-state rule leaves out a .hyperframes folder at any depth below the root. It sits before the first allow rule, as the contract's rule order requires. The root folder's Studio files and other portable files travel as before. Stored snapshot reads skip the new rule through stored_manifest.legacy_rule_regexes, the shape the server and Desktop copies already use, so snapshots and bindings captured earlier still read.
228 lines
10 KiB
Plaintext
228 lines
10 KiB
Plaintext
---
|
|
title: "Install and update agent skills"
|
|
sidebarTitle: "Agent skills"
|
|
description: "Teach a coding agent how to create valid HyperFrames projects."
|
|
keywords: ['npx skills', 'npx skills add', 'skills add', 'install skills', 'update skills']
|
|
---
|
|
|
|
import { DocsVideo } from "/snippets/docs-video.jsx";
|
|
|
|
HyperFrames skills teach coding agents the project format, animation rules, media workflow, and validation loop that generic web knowledge does not cover.
|
|
|
|
<DocsVideo
|
|
title="One command installs the skills"
|
|
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/skills-install-demo-v2.mp4"
|
|
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/skills-install-demo-v2.jpg"
|
|
/>
|
|
|
|
The terminal output is a real run of the command. Afterwards the agent reads
|
|
`/hyperframes` before it builds, instead of guessing at the framework's rules.
|
|
|
|
Prefer a [versioned plugin](/guides/plugins) when your agent supports one. This
|
|
page covers standalone installs, including OpenCode. Plugin users should update
|
|
through their agent's plugin manager instead of running the commands below.
|
|
|
|
## Install for a person
|
|
|
|
Run the interactive installer:
|
|
|
|
```bash
|
|
npx skills add heygen-com/hyperframes
|
|
```
|
|
|
|
Run this command from your video project's directory. If you cloned HyperFrames
|
|
to contribute, use `npx hyperframes skills update` for a global install from that
|
|
checkout, or run the project installer in a separate video project. Project-local
|
|
installer targets can overlap the checkout's tracked `skills/` source and
|
|
overwrite uncommitted edits.
|
|
|
|
Select **Core Skills**. That covers every kind of video; the other skills install when a request needs them, so you do not need the full catalog up front.
|
|
|
|
Start a fresh agent chat after installation, then ask it to use `/hyperframes`.
|
|
|
|
## Install or refresh from an agent
|
|
|
|
For a non-interactive agent or CI environment, use:
|
|
|
|
```bash
|
|
npx hyperframes skills update
|
|
```
|
|
|
|
This installs or refreshes the core set and any HyperFrames skills already present in the global install, then links those bundles into compatible installed agents. It does not add every optional skill.
|
|
|
|
Updates check the Claude global store (`~/.claude/skills`, or the `skills/` folder
|
|
under `CLAUDE_CONFIG_DIR`) that the installer writes to. Skills found only in
|
|
another agent's directory do not make a missing core skill count as installed
|
|
there, and optional skills in that other directory are not automatically added
|
|
to the managed store. Name an optional skill explicitly to add it. The install
|
|
record's publisher attribution is respected even before the managed store exists.
|
|
An explicit update request for a skill owned by another publisher fails without
|
|
overwriting it, including when the freshness check is unavailable offline.
|
|
|
|
Check freshness without changing anything:
|
|
|
|
```bash
|
|
npx hyperframes skills check
|
|
```
|
|
|
|
Install or refresh one skill explicitly:
|
|
|
|
```bash
|
|
npx hyperframes skills update slideshow
|
|
```
|
|
|
|
## Use the skills in GitHub Copilot CLI
|
|
|
|
Run `npx hyperframes skills update`, open the project, and start Copilot:
|
|
|
|
```bash
|
|
copilot
|
|
```
|
|
|
|
If Copilot was already running, use `/skills reload`. Use `/skills list` or
|
|
`/skills info hyperframes` to confirm discovery. GitHub's [current skills
|
|
guide](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills)
|
|
lists its project and personal skill locations.
|
|
|
|
Both agents can use the same first request:
|
|
|
|
```text
|
|
Using /hyperframes, make a 10-second product intro for https://example.com.
|
|
```
|
|
|
|
Continue in the same conversation for revisions. For hosted creation instead
|
|
of a local project, use the [HyperFrames MCP guide](/guides/mcp).
|
|
|
|
## Use the skills in Google Antigravity
|
|
|
|
Install the skills from the root of the project you open in Antigravity:
|
|
|
|
```bash
|
|
npx skills add heygen-com/hyperframes
|
|
```
|
|
|
|
Select **Core Skills** and **Antigravity**. This uses Antigravity's supported
|
|
project location, `.agents/skills`, and keeps the skills with the project. Start
|
|
a fresh Antigravity conversation after installation.
|
|
|
|
Antigravity also supports a global `~/.gemini/config/skills` directory. See
|
|
Google's [current skills guide](https://antigravity.google/docs/skills?app=antigravity-ide)
|
|
before managing that directory by hand.
|
|
|
|
## Use the skills in IBM Bob
|
|
|
|
Run `npx hyperframes skills update`, then open or restart Bob Shell in the
|
|
project folder so it discovers the skills linked under `~/.bob/skills`:
|
|
|
|
```bash
|
|
bob
|
|
```
|
|
|
|
Ask Bob to use `/hyperframes` for the first request. Running the update again
|
|
refreshes the same global skill bundles without changing the project format.
|
|
|
|
## What the skills cover
|
|
|
|
Make any video by asking for it; the `/hyperframes` skill carries the contract and the references (each kind of film, story, motion, look, sound, review, captions, overlays).
|
|
|
|
| Skill | What it covers |
|
|
| --- | --- |
|
|
| `/hyperframes` | Read first for any request to make, edit, animate or render a video, motion graphic, captions or overlays. Holds the render contract and the work loop, and points to the references for format, motion, look, captions, whole films and storyboards. |
|
|
| `/hyperframes-cli` | The CLI by job: scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history. |
|
|
| `/hyperframes-registry` | About 450 ready-made blocks and components installed as editable source: transitions, overlays, titles, kinetic type, captions, charts, maps, 3D, camera moves. |
|
|
| `/media-use` | Music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks, with HeyGen or free local tools; mixes placed audio. |
|
|
| `/reverse-any-video` | Rebuilding any video file as an editable HyperFrames project (motion graphics, talking heads, live action, AI-generated footage), checked frame by frame against the original. HyperFrames Pro. |
|
|
| `/style-sampling` | Making a new episode on your topic in one of five proven styles: Collage Explainer, Finance Explainer, Animated Science Explainer, 3D Brand Explainer, 3D True Crime. HyperFrames Pro. |
|
|
| `/figma` | A Figma file or frame: rendered assets, brand tokens, components, and storyboard frames as reconstructed motion. |
|
|
| `/slideshow` | A presentation, pitch deck or interactive deck. Output is a navigable deck, not a rendered MP4. |
|
|
| `/remotion-to-hyperframes` | Bringing existing video code or footage into HyperFrames (Remotion first; also Motion Canvas, Lottie, Three.js, canvas, other tools' renders), verified frame by frame. |
|
|
|
|
You can name a skill directly, but you do not need to memorize the names to start.
|
|
|
|
## How the agent runs the CLI
|
|
|
|
The skills have your agent start the CLI through a launcher that ships with them,
|
|
`hyperframes/scripts/plugin-cli.mjs`, from your project folder. The launcher starts npm in
|
|
your home folder, so a project's `package.json`, `node_modules` or `.npmrc` cannot swap in a
|
|
different program. This matters most for a project someone sent you. With standalone skills it
|
|
runs the newest published CLI; in a plugin it runs the version the plugin pins. The pin counts
|
|
only when the plugin folder's name does not start with a dot, the folder is not the one the
|
|
agent works in and does not contain it, and, if it lies inside that folder, a folder whose name
|
|
starts with a dot (such as `.claude`) sits between them. A pin older than 0.9.34 is refused.
|
|
The agent runs a project's own npm scripts only when you ask for one by name.
|
|
|
|
## Install more only when you need it
|
|
|
|
Install the complete published set deliberately with:
|
|
|
|
```bash
|
|
npx hyperframes skills
|
|
```
|
|
|
|
`npx skills add heygen-com/hyperframes --all` also installs the complete published set. Repo-internal skills are excluded by default.
|
|
|
|
Or install one named skill:
|
|
|
|
```bash
|
|
npx skills add heygen-com/hyperframes --skill slideshow
|
|
```
|
|
|
|
Use the full set for an environment that must work across many HyperFrames tasks without fetching later. For a normal project, the core set is smaller and easier to keep current.
|
|
|
|
## If the agent cannot see a skill
|
|
|
|
1. Start a new agent session.
|
|
2. Confirm that the project or global skill directory belongs to the agent you are using.
|
|
3. Run `npx hyperframes skills check`.
|
|
4. Run `npx hyperframes skills update` when the check reports a missing or stale core skill.
|
|
|
|
The individual skill definitions remain the source of truth for agents and are
|
|
available in the [HyperFrames repository](https://github.com/heygen-com/hyperframes/tree/main/skills).
|
|
|
|
## If an update says no installed skills match
|
|
|
|
With `skills@1.7.x`, `npx skills update heygen-com/hyperframes` treats
|
|
`heygen-com/hyperframes` as an installed skill name. It reports
|
|
`No installed skills found matching` even when HyperFrames skills are installed.
|
|
Use the HyperFrames updater to refresh the core set and the HyperFrames skills
|
|
already installed globally:
|
|
|
|
```bash
|
|
npx hyperframes skills update
|
|
```
|
|
|
|
The standalone `skills update` command accepts skill names, such as
|
|
`npx skills update hyperframes -g` to update only the global `/hyperframes` skill.
|
|
The repository name belongs in `skills add`, as shown in the install steps above.
|
|
|
|
## If an installed skill has a YAML parse error
|
|
|
|
A `Skipped .../SKILL.md — YAML parse error` warning names the installed file that
|
|
cannot be read. Back up that file before editing it, especially if it contains
|
|
custom instructions. A multiline description needs indented continuation lines;
|
|
for example:
|
|
|
|
```yaml
|
|
---
|
|
name: seam-craft
|
|
description: >-
|
|
Render-correctness doctrine for scene-to-scene seams.
|
|
Load when assembling the master timeline.
|
|
---
|
|
```
|
|
|
|
Keep the file's existing description text and skill body; the example shows only
|
|
the YAML format. Run `npx skills list -g` afterwards to verify global discovery,
|
|
or `npx skills list` for a project install.
|
|
|
|
Repo-internal skills such as `seam-craft` are excluded from the published set.
|
|
Refreshing the core skills does not repair an old, separately installed copy of
|
|
an internal skill. A YAML warning and a name-matching error can occur in the same
|
|
run and need these separate fixes.
|
|
|
|
## Related topics
|
|
|
|
- [Make your first video](/quickstart)
|
|
- [Choose what to make](/workflows)
|
|
- [Use authentication and hosted services](/guides/authentication)
|