Skip to content

Commit 274bf64

Browse files
committed
chore(cli): bring in the Parakeet branch round 5 with main
# Conflicts: # skills-manifest.json
2 parents f7999b2 + 6e23597 commit 274bf64

63 files changed

Lines changed: 2062 additions & 742 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude-plugin/marketplace.json‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,17 @@
66
"url": "https://hyperframes.heygen.com"
77
},
88
"plugins": [
9+
{
10+
"name": "hyperframes",
11+
"source": "./",
12+
"description": "Recommended: all published HyperFrames skills in one versioned bundle. Create and render videos from HTML; load workflows on demand without installing newer standalone skills.",
13+
"homepage": "https://hyperframes.heygen.com",
14+
"license": "Apache-2.0"
15+
},
916
{
1017
"name": "core-skills",
1118
"source": "./",
12-
"description": "The HyperFrames core set \u2014 install this one: the /hyperframes router, the hyperframes-* domain skills, and media-use. The router installs each creation workflow on demand. The full bundle (all skills at once) is `hyperframes`.",
19+
"description": "Legacy core-only installation. For release-managed bundled workflows, install hyperframes@hyperframes and then uninstall core-skills@hyperframes.",
1320
"homepage": "https://hyperframes.heygen.com",
1421
"license": "Apache-2.0",
1522
"skills": [
@@ -24,13 +31,7 @@
2431
"./skills/hyperframes-studio",
2532
"./skills/media-use"
2633
]
27-
},
28-
{
29-
"name": "hyperframes",
30-
"source": "./",
31-
"description": "All HyperFrames skills in one static bundle. Most setups want `core-skills` instead \u2014 the router installs creation workflows on demand. HyperFrames by HeyGen. Write HTML, render video. Compositions, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website capture for HyperFrames.",
32-
"homepage": "https://hyperframes.heygen.com",
33-
"license": "Apache-2.0"
3434
}
35-
]
35+
],
36+
"description": "HyperFrames video creation skills, versioned and updated as one plugin."
3637
}

‎.github/workflows/ci.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,16 @@ jobs:
134134
- "package.json"
135135
- ".github/workflows/ci.yml"
136136
codex_plugin:
137+
- "skills-manifest.json"
138+
- "packages/cli/package.json"
139+
- "plugin.json"
140+
- "gemini-extension.json"
141+
- ".claude-plugin/**"
142+
- ".cursor-plugin/**"
143+
- "scripts/package-agent-plugin*"
144+
- "scripts/agent-plugin-captions.test.mjs"
145+
- "scripts/set-version*"
146+
- "LICENSE"
137147
- ".codex-plugin/**"
138148
- "assets/**"
139149
- "skills/**"
@@ -643,6 +653,12 @@ jobs:
643653
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
644654
with:
645655
node-version: 22
656+
- name: Test portable plugin packaging
657+
run: node --test scripts/package-agent-plugin.test.mjs
658+
- name: Build portable agent plugin
659+
run: node scripts/package-agent-plugin.mjs
660+
- name: Exercise captions from the extracted portable bundle
661+
run: node --test scripts/agent-plugin-captions.test.mjs
646662
- name: Build upload-ready Codex plugin
647663
run: node scripts/package-codex-plugin.mjs
648664

‎.github/workflows/publish.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -214,3 +214,13 @@ jobs:
214214
fi
215215
gh release create "v${VERSION}" "${FLAGS[@]}"
216216
fi
217+
218+
- name: Build portable agent plugin
219+
run: node scripts/package-agent-plugin.mjs
220+
221+
- name: Attach portable plugin to release
222+
env:
223+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
224+
VERSION: ${{ steps.version.outputs.version }}
225+
REPO: ${{ github.repository }}
226+
run: gh release upload "v${VERSION}" dist/hyperframes-agent-plugin.zip dist/hyperframes-agent-plugin.sha256 dist/hyperframes-agent-plugin.json --repo "$REPO" --clobber

‎README.md‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,18 @@ HyperFrames is an open-source framework for turning HTML, CSS, media, and seekab
3535

3636
### With an AI coding agent
3737

38-
Install the HyperFrames skills, then describe the video you want:
38+
For Claude Code, install the versioned plugin:
39+
40+
```bash
41+
claude plugin marketplace add heygen-com/hyperframes
42+
claude plugin install hyperframes@hyperframes
43+
```
44+
45+
Enable auto-update for the **hyperframes** marketplace in `/plugin` → **Marketplaces**,
46+
then use `/hyperframes:hyperframes`. See the [plugin guide](docs/guides/plugins.mdx)
47+
for Copilot, VS Code, Cursor, Gemini CLI, updates, and migration.
48+
49+
For standalone skills (including OpenCode), use:
3950

4051
```bash
4152
npx skills add heygen-com/hyperframes
@@ -55,9 +66,15 @@ The skills teach agents the HyperFrames production loop: plan the video, write v
5566

5667
HyperFrames ships 21 skills agents load on demand. Read `/hyperframes` first — it's the router and capability map; it picks a workflow for any "make me a…" request — video, deck, or composition port — and points to the domain skills below.
5768

58-
Default to the **core set** — the router installs each creation workflow on demand. `npx hyperframes skills update` installs exactly that from anywhere; the interactive picker (`npx skills add heygen-com/hyperframes`) lists it as the "Core Skills" group, nothing pre-selected. The picker is interactive-only — a non-interactive or agent run without `--skill` installs all 21. Use `npx skills add heygen-com/hyperframes --all` to install all 20 deliberately (skips the picker), or `npx skills add heygen-com/hyperframes --skill <name>` for just one (bare name, no leading `/`).
69+
For standalone installation, default to the **core set** — the router installs each creation workflow on demand. `npx hyperframes skills update` installs exactly that from anywhere; the interactive picker (`npx skills add heygen-com/hyperframes`) lists it as the "Core Skills" group, nothing pre-selected. The picker is interactive-only — a non-interactive or agent run without `--skill` installs all 21. Use `npx skills add heygen-com/hyperframes --all` to install the complete published set deliberately (skips the picker), or `npx skills add heygen-com/hyperframes --skill <name>` for just one (bare name, no leading `/`).
70+
71+
Standalone installs stay lean after that: `npx hyperframes init` keeps the **core set** fresh (the router, the `hyperframes-*` domain skills, and `media-use` — plus whatever is already installed; `/figma` stays on demand) and never expands a partial install; the creation workflows install **on demand** — the router runs `npx hyperframes skills update <workflow>` before entering one. Nothing re-pulls the full set behind your back.
72+
73+
### Plugin packages
5974

60-
Installs stay lean after that: `npx hyperframes init` keeps the **core set** fresh (the router, the `hyperframes-*` domain skills, and `media-use` — plus whatever is already installed; `/figma` stays on demand) and never expands a partial install; the creation workflows install **on demand** — the router runs `npx hyperframes skills update <workflow>` before entering one. Nothing re-pulls the full set behind your back.
75+
Plugins bundle the full skill catalog and use their agent's update manager.
76+
`bun run package:agent-plugin` builds the committed portable ZIP, source metadata,
77+
and SHA-256 checksum. See the [maintainer checklist](docs/contributing/agent-plugins.mdx).
6178

6279
### Upload to Codex
6380

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
title: "Release agent plugins"
3+
description: "Build, verify, and publish HyperFrames plugin packages from one committed release."
4+
---
5+
6+
`skills/` is the canonical published skill source. Claude, Agent Plugins 1.0,
7+
Cursor, Codex, and Gemini manifests share the CLI release version. Keep vendor
8+
manifests for existing clients while the portable format is adopted.
9+
10+
## Build a committed release
11+
12+
Use the normal reviewed [release process](/contributing/release-channels).
13+
`set-version` updates all five plugin manifests. Commit the release before
14+
packaging; package builders intentionally exclude uncommitted changes.
15+
16+
```bash
17+
bun run package:agent-plugin
18+
bun run package:codex-plugin
19+
```
20+
21+
The portable builder writes these files under `dist/`:
22+
23+
- `hyperframes-agent-plugin.zip`: a `hyperframes/` root with manifests, skills,
24+
the skill catalog, brand assets, and license.
25+
- `hyperframes-agent-plugin.json`: source commit, version, skill inventory,
26+
archive size, and SHA-256.
27+
- `hyperframes-agent-plugin.sha256`: the archive checksum.
28+
29+
The publish workflow attaches the portable files to the GitHub release after npm
30+
publication. The Codex ZIP remains a separate submission artifact. Building it
31+
does not update the OpenAI directory listing.
32+
33+
## Verify before advertising support
34+
35+
1. Run packaging tests, skill validation, skill manifest checks, and manifest
36+
validation. Check that no contributor-only skills, LFS pointers needed at
37+
runtime, or dependencies on unbundled repository files entered the payload.
38+
2. In isolated profiles, install the full bundle and check its skill inventory.
39+
Exercise both Claude's namespaced router and each client's native discovery.
40+
3. Upgrade from release N to N+1 through the actual distribution source. Confirm
41+
the new version after reload; verify a pinned installation stays on N.
42+
A local-directory reload is not proof of marketplace auto-update.
43+
4. Run a local title-card workflow. Verify `init` does not refresh global skills,
44+
the CLI version matches the plugin, and plugin files remain unchanged. Check
45+
existing project dependencies without rewriting their lockfiles.
46+
5. Test migration from `core-skills` and duplicate standalone skills, then
47+
uninstall. Preserve unrelated skills and user edits.
48+
6. Record tested client versions, operating systems, source commit, and results
49+
in the PR/release notes. Mark unavailable clients as unverified.
50+
51+
The Claude marketplace keeps the old `core-skills` install identity for migration;
52+
new users should install `hyperframes@hyperframes`. Do not remove the old entry
53+
without testing migration on supported Claude versions.
54+
55+
## Distribution status and rollback
56+
57+
Track self-hosted repository installation, release artifact publication, native
58+
client verification, and public marketplace approval separately. Cursor public
59+
updates require review. OpenAI directory submissions follow their own process.
60+
Never describe a successful manifest check as a verified native installation.
61+
62+
For rollback, reinstall the prior tested release tag or archive and disable
63+
updates temporarily. Do not reuse a version number for changed plugin contents.
64+
If a public marketplace has a separate published revision, roll that back through
65+
its own process too.
66+
67+
## Related topics
68+
69+
- [Install agent plugins](/guides/plugins)
70+
- [Release channels](/contributing/release-channels)
71+
- [Test local changes](/contributing/testing-local-changes)

‎docs/docs.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -948,6 +948,7 @@
948948
"group": "Agent setup",
949949
"pages": [
950950
"guides/authentication",
951+
"guides/plugins",
951952
"guides/skills",
952953
"guides/webmcp"
953954
]
@@ -958,6 +959,7 @@
958959
"contributing",
959960
"contributing/catalog",
960961
"contributing/release-channels",
962+
"contributing/agent-plugins",
961963
"contributing/changelog-process",
962964
"contributing/testing-local-changes",
963965
"contributing/canary-rollouts",

‎docs/guides/plugins.mdx‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
title: "Install the HyperFrames plugin"
3+
sidebarTitle: "Agent plugins"
4+
description: "Install video creation skills as one versioned plugin and let your agent manage updates."
5+
---
6+
7+
The HyperFrames plugin gives your coding agent the complete set of video workflows:
8+
product promos, explainers, captions, motion graphics, and more. Skills load when
9+
needed; you do not have to install each workflow separately.
10+
11+
Choose one installation method per agent. Plugins receive updates through the
12+
agent's plugin manager. [Standalone skills](/guides/skills) remain available for
13+
OpenCode and other agents, or when you prefer the smaller core-only install.
14+
15+
| Agent | Installation route |
16+
| --- | --- |
17+
| Claude Code | HyperFrames' GitHub marketplace |
18+
| Copilot CLI | HyperFrames' GitHub marketplace |
19+
| VS Code / Copilot | Add the GitHub marketplace in the Extensions view |
20+
| Cursor | Import through a team marketplace, or load a local plugin |
21+
| Gemini CLI | Install the HyperFrames extension from GitHub |
22+
| Codex | Use your existing HyperFrames plugin; directory updates are published separately |
23+
| OpenCode | Use standalone skills |
24+
25+
You need Node.js 22+ and npm for the local CLI, plus FFmpeg for rendering.
26+
Install on each machine you use; a plugin does not synchronize your machines.
27+
28+
## Claude Code
29+
30+
Run in your terminal:
31+
32+
```bash
33+
claude plugin marketplace add heygen-com/hyperframes
34+
claude plugin install hyperframes@hyperframes
35+
claude plugin details hyperframes
36+
```
37+
38+
The inventory should include `hyperframes`, `general-video`, and `media-use`.
39+
Start a new session or run `/reload-plugins`, then try:
40+
41+
```text
42+
Using /hyperframes:hyperframes, make a 5-second title card that says "Hello world".
43+
```
44+
45+
**Enable automatic updates:** run `/plugin`, open **Marketplaces**, select
46+
**hyperframes**, and choose **Enable auto-update**. Third-party marketplaces do
47+
not enable this by default. To update manually:
48+
49+
```bash
50+
claude plugin update hyperframes@hyperframes
51+
```
52+
53+
Reload plugins after updating. To remove the plugin:
54+
55+
```bash
56+
claude plugin uninstall hyperframes@hyperframes
57+
```
58+
59+
See [Claude's plugin guide](https://code.claude.com/docs/en/plugins/install)
60+
for project-wide installation and managed update policies.
61+
62+
## GitHub Copilot CLI
63+
64+
```bash
65+
copilot plugin marketplace add heygen-com/hyperframes
66+
copilot plugin install hyperframes@hyperframes
67+
copilot plugin list
68+
```
69+
70+
Start a fresh session and ask Copilot to use the HyperFrames skill to make the
71+
same title card. Check `/skills list` if the skill is not visible.
72+
73+
```bash
74+
copilot plugin update hyperframes
75+
copilot plugin uninstall hyperframes
76+
```
77+
78+
These are explicit updates; do not assume Copilot CLI shares VS Code's update
79+
schedule. See [Copilot's plugin guide](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-installing).
80+
81+
## VS Code
82+
83+
Open the Extensions view and search `@agentPlugins`. Add
84+
`heygen-com/hyperframes` as a marketplace using the plugin marketplace command,
85+
then install **hyperframes** and verify its skills in Agent Customizations.
86+
Agent plugins must be enabled in VS Code settings.
87+
88+
VS Code checks for updates every 24 hours when `extensions.autoUpdate` is enabled.
89+
Use **Extensions: Check for Extension Updates** for a manual check. Disable or
90+
uninstall the plugin from the Extensions view. See [VS Code's plugin guide](https://code.visualstudio.com/docs/agent-customization/agent-plugins)
91+
for the current UI and workspace recommendations.
92+
93+
## Cursor
94+
95+
For a team marketplace, import `heygen-com/hyperframes` in **Dashboard → Plugins &
96+
MCPs** and add the HyperFrames plugin. Teammates install it from **Customize**.
97+
GitHub marketplace auto-refresh requires the Cursor GitHub App and the marketplace's
98+
**Enable Auto Refresh** setting.
99+
100+
For a local install, copy an extracted HyperFrames plugin folder to
101+
`~/.cursor/plugins/local/hyperframes`, then reload Cursor and check **Customize**.
102+
The folder must contain `plugin.json` and `skills/`. Local copies require manual
103+
replacement to update; they do not subscribe to GitHub changes. Enterprise policy
104+
may disable local plugin imports. Remove the local folder to uninstall that copy.
105+
106+
This repository's manifests are not proof of a public Cursor marketplace listing.
107+
Public listings and their updates go through Cursor review. See [Cursor's plugin
108+
guide](https://cursor.com/docs/plugins) for marketplace and local-install controls.
109+
110+
## Gemini CLI
111+
112+
```bash
113+
gemini extensions install https://github.com/heygen-com/hyperframes --auto-update
114+
gemini extensions list
115+
```
116+
117+
Restart Gemini CLI and ask it to use the HyperFrames skill for the title card.
118+
To manage the extension explicitly:
119+
120+
```bash
121+
gemini extensions update hyperframes
122+
gemini extensions uninstall hyperframes
123+
```
124+
125+
To stay on a specific release, install with `--ref <release-tag>` instead of
126+
`--auto-update`. Choose a release containing `gemini-extension.json`.
127+
See [Gemini's extension guide](https://geminicli.com/docs/extensions/reference/).
128+
129+
The embedded-captions workflow additionally needs project-local Sharp, Puppeteer
130+
with Chromium, and GSAP. Its skill includes the versioned installation command;
131+
keep those dependencies and their lockfile in the caption project. The plugin
132+
itself remains read-only and does not include browsers or model weights.
133+
134+
## Versions and updates
135+
136+
The plugin bundles workflows from one source snapshot and runs the CLI version
137+
recorded in its manifest. Your agent should use its bundled plugin launcher;
138+
it should not run `npx hyperframes skills update` during a plugin workflow.
139+
Existing project dependencies, downloaded media, and external services have their
140+
own versions and are not frozen by the plugin.
141+
142+
Update behavior depends on the client and source ref. For example,
143+
[Cursor GitHub Auto Refresh](https://cursor.com/docs/plugins#keep-plugins-up-to-date)
144+
follows pushes to the tracked branch, so skill content can change without a new
145+
CLI version. The manifest pins the CLI version, not the installed skill commit.
146+
For a repeatable installation, keep a release tag or an extracted release archive
147+
and disable automatic updates. Install that same release on each machine.
148+
Git-based installs may download the full source repository. Release ZIPs contain
149+
only the plugin payload, but loading an extracted ZIP locally requires manual updates.
150+
Only releases with a `hyperframes-agent-plugin.zip` asset provide that portable ZIP.
151+
152+
## Move from standalone skills or core-skills
153+
154+
Install the full plugin and verify its inventory first. In Claude, an older
155+
`core-skills@hyperframes` install can then be removed:
156+
157+
```bash
158+
claude plugin uninstall core-skills@hyperframes
159+
```
160+
161+
Use your standalone skill manager to remove only the old HyperFrames skills for
162+
that agent. Inspect the locations first: other agents may share a global skills
163+
store, and locally edited skills should be backed up. Do not delete an entire
164+
`.agents` or `.claude` directory. Restart the agent and confirm it selects the
165+
plugin copy rather than a duplicate standalone skill.
166+
167+
## If a workflow is missing or stale
168+
169+
1. Check the agent's installed plugin inventory and version.
170+
2. Update using that agent's plugin manager, then reload or restart it.
171+
3. Check whether an old standalone installation is also being loaded.
172+
4. For a pinned release, verify the workflow exists in that release. Do not mix
173+
skills from a newer release into the plugin folder.
174+
175+
## Related topics
176+
177+
- [Make your first video](/quickstart)
178+
- [Install standalone skills](/guides/skills)
179+
- [Plugin release checklist](/contributing/agent-plugins)

‎docs/guides/skills.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,10 @@ The terminal output is a real run of the command. Afterwards the router reads a
1818
request and chooses the workflow for it, instead of the agent guessing at the
1919
framework's rules.
2020

21+
Prefer a [versioned plugin](/guides/plugins) when your agent supports one. This
22+
page covers standalone installs, including OpenCode. Plugin users should update
23+
through their agent's plugin manager instead of running the commands below.
24+
2125
## Install for a person
2226

2327
Run the interactive installer:

0 commit comments

Comments
 (0)