From e89528cd13bbb0e9e2b9364b9742119716bb33f9 Mon Sep 17 00:00:00 2001 From: "Abdullah M. Nazif" Date: Fri, 9 Oct 2026 20:20:08 +0800 Subject: [PATCH 1/4] docs: protect skill edits during contributor setup --- CONTRIBUTING.md | 6 ++++++ README.md | 5 +++++ docs/guides/skills.mdx | 6 ++++++ 3 files changed, 17 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1fce02878e1..8631b0b07c6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,6 +9,12 @@ Thanks for your interest in contributing to Hyperframes! This guide will help yo 3. Install dependencies: `bun install` 4. Create a branch: `git checkout -b my-feature` +The published skill source lives in `skills/`. To install skills while working in +this checkout, use `npx hyperframes skills update`, which installs globally. Run +project-local `npx skills add ...` from a separate video project: its destination +can overlap `skills/` and overwrite uncommitted changes. The repo-native skills in +`.claude/skills/` and `.agents/skills/` are already included in the checkout. + ## Choosing work Start with [available newcomer issues](https://github.com/heygen-com/hyperframes/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+no%3Aassignee) or [help-wanted issues](https://github.com/heygen-com/hyperframes/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22+no%3Aassignee). Read the discussion and check existing PRs before starting; an unassigned issue may already have work in progress. Comment with your intended approach and coordinate a claim with a maintainer. diff --git a/README.md b/README.md index 4529ffdda70..abe63063b72 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,11 @@ For standalone skills (including OpenCode), use: npx skills add heygen-com/hyperframes ``` +Run project-local installs from your video project's directory. From a HyperFrames +checkout, use `npx hyperframes skills update` for a global install instead: a +project-local installer target can overlap the tracked `skills/` source and +overwrite uncommitted edits. See [contributor setup](CONTRIBUTING.md#getting-started). + > The picker opens with nothing pre-selected — the **Core Skills** group is all you need: the `/hyperframes` router installs each creation workflow on demand. Agents and non-interactive runs should use `npx hyperframes skills update` instead — it installs exactly the core set, whereas `skills add --all` installs all 21 published skills. The six repo-internal skills under `.claude/skills` / `.agents/skills` are excluded by default. For the full published set use `npx hyperframes skills`. > > `skills add` resolves the skills.sh registry blob, which can lag `main` by hours. `npx hyperframes skills update` installs from the current `main`, so reach for it when you need the newest copy of a skill. diff --git a/docs/guides/skills.mdx b/docs/guides/skills.mdx index 98227b95cd9..216ad9baca0 100644 --- a/docs/guides/skills.mdx +++ b/docs/guides/skills.mdx @@ -30,6 +30,12 @@ Run the interactive installer: 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**. The `/hyperframes` router installs a specialized creation workflow when the request needs one, so you do not need the full catalog up front. Start a fresh agent chat after installation, then ask it to use `/hyperframes`. From 00354a0b3a158456fd8ace4070c3132268318243 Mon Sep 17 00:00:00 2001 From: "Abdullah M. Nazif" Date: Thu, 15 Oct 2026 21:23:37 +0800 Subject: [PATCH 2/4] docs: keep skill picker guidance beside its command --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index abe63063b72..ddce01802da 100644 --- a/README.md +++ b/README.md @@ -53,15 +53,15 @@ For standalone skills (including OpenCode), use: npx skills add heygen-com/hyperframes ``` +> The picker opens with nothing pre-selected — the **Core Skills** group is all you need: the `/hyperframes` router installs each creation workflow on demand. Agents and non-interactive runs should use `npx hyperframes skills update` instead — it installs exactly the core set, whereas `skills add --all` installs all 21 published skills. The six repo-internal skills under `.claude/skills` / `.agents/skills` are excluded by default. For the full published set use `npx hyperframes skills`. +> +> `skills add` resolves the skills.sh registry blob, which can lag `main` by hours. `npx hyperframes skills update` installs from the current `main`, so reach for it when you need the newest copy of a skill. + Run project-local installs from your video project's directory. From a HyperFrames checkout, use `npx hyperframes skills update` for a global install instead: a project-local installer target can overlap the tracked `skills/` source and overwrite uncommitted edits. See [contributor setup](CONTRIBUTING.md#getting-started). -> The picker opens with nothing pre-selected — the **Core Skills** group is all you need: the `/hyperframes` router installs each creation workflow on demand. Agents and non-interactive runs should use `npx hyperframes skills update` instead — it installs exactly the core set, whereas `skills add --all` installs all 21 published skills. The six repo-internal skills under `.claude/skills` / `.agents/skills` are excluded by default. For the full published set use `npx hyperframes skills`. -> -> `skills add` resolves the skills.sh registry blob, which can lag `main` by hours. `npx hyperframes skills update` installs from the current `main`, so reach for it when you need the newest copy of a skill. - Try a prompt like: > Using `/hyperframes`, create a 10-second product intro with a fade-in title, a background video, and subtle background music. From 80c0217023f52b5b1f0d8c1033314184dc882d2d Mon Sep 17 00:00:00 2001 From: "Abdullah M. Nazif" Date: Sat, 24 Oct 2026 13:41:27 +0800 Subject: [PATCH 3/4] chore: prepare conflict resolution against current main --- docs/guides/skills.mdx | 55 ++++++++++++++++++------------------------ 1 file changed, 23 insertions(+), 32 deletions(-) diff --git a/docs/guides/skills.mdx b/docs/guides/skills.mdx index 216ad9baca0..3ed2e39590b 100644 --- a/docs/guides/skills.mdx +++ b/docs/guides/skills.mdx @@ -1,22 +1,21 @@ --- title: "Install and update agent skills" sidebarTitle: "Agent skills" -description: "Teach a coding agent how to create valid HyperFrames projects and load specialized workflows when needed." +description: "Teach a coding agent how to create valid HyperFrames projects." --- import { DocsVideo } from "/snippets/docs-video.jsx"; -HyperFrames skills teach coding agents the project format, animation rules, media workflow, validation loop, and creation workflows that generic web knowledge does not cover. +HyperFrames skills teach coding agents the project format, animation rules, media workflow, and validation loop that generic web knowledge does not cover. -The terminal output is a real run of the command. Afterwards the router reads a -request and chooses the workflow for it, instead of the agent guessing at the -framework's rules. +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 @@ -30,13 +29,7 @@ Run the interactive installer: 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**. The `/hyperframes` router installs a specialized creation workflow when the request needs one, so you do not need the full catalog up front. +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`. @@ -48,7 +41,7 @@ For a non-interactive agent or CI environment, use: 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 workflow. +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. Check freshness without changing anything: @@ -56,10 +49,10 @@ Check freshness without changing anything: npx hyperframes skills check ``` -Install or refresh one workflow explicitly: +Install or refresh one skill explicitly: ```bash -npx hyperframes skills update pr-to-video +npx hyperframes skills update slideshow ``` ## Use the skills in GitHub Copilot CLI @@ -112,23 +105,21 @@ 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. -## Let the router choose +## What the skills cover -The normal entry point is `/hyperframes`. It confirms the important intent, then selects a workflow from the input: +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). -| You provide | Workflow | +| Skill | What it covers | | --- | --- | -| A product website or product brief | Product launch video | -| A topic or script with no website capture | Faceless explainer | -| A GitHub pull request | PR-to-video | -| Existing talking-head footage | Captions or a designed recut | -| A music track | Music-driven video | -| A short design-led animation | Motion graphic | -| A presentation | Slideshow | -| A Figma file or frame | Figma import with assets, brand tokens, components, and reconstructed motion | -| Anything outside those shapes | General video | - -You can invoke a workflow directly when you already know it is the right one, but you do not need to memorize the names to start. +| `/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. | +| `/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. ## Install more only when you need it @@ -143,7 +134,7 @@ npx hyperframes skills Or install one named skill: ```bash -npx skills add heygen-com/hyperframes --skill hyperframes-animation +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. @@ -161,5 +152,5 @@ available in the [HyperFrames repository](https://github.com/heygen-com/hyperfra ## Related topics - [Make your first video](/quickstart) -- [Choose a specific creation workflow](/workflows) +- [Choose what to make](/workflows) - [Use authentication and hosted services](/guides/authentication) From 6b768bf6d06574389726f73ce2fa2649961a6ded Mon Sep 17 00:00:00 2001 From: "Abdullah M. Nazif" Date: Sat, 24 Oct 2026 13:41:46 +0800 Subject: [PATCH 4/4] docs: preserve checkout skill installation guidance --- docs/guides/skills.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/guides/skills.mdx b/docs/guides/skills.mdx index 3ed2e39590b..728fdbf6b70 100644 --- a/docs/guides/skills.mdx +++ b/docs/guides/skills.mdx @@ -29,6 +29,12 @@ Run the interactive installer: 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`.