diff --git a/docs/docs.json b/docs/docs.json index 801791e48..cfe704ff5 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -74,6 +74,8 @@ "guides/pipeline", "guides/html-in-canvas", "guides/website-to-video", + "guides/antigravity", + "guides/copilot-cli", "guides/claude-design", "guides/open-design", "guides/prompting", diff --git a/docs/guides/antigravity.mdx b/docs/guides/antigravity.mdx new file mode 100644 index 000000000..d35c0155d --- /dev/null +++ b/docs/guides/antigravity.mdx @@ -0,0 +1,150 @@ +--- +title: Google Antigravity +description: "Set up HyperFrames in Google Antigravity — install skills, author compositions, and render video from the agent-first IDE." +--- + +Google Antigravity is Google's agent-first IDE built on VS Code. Its agent discovers and loads HyperFrames skills automatically based on your prompts, so you get correct compositions without memorizing framework internals. + +## Install skills + +Install the HyperFrames skill package into your project: + +```bash +npx skills add heygen-com/hyperframes +``` + +This places skill directories inside `.agents/skills/` at your workspace root — the location Antigravity scans for workspace-scoped skills. + + + If you want the skills available across all your Antigravity projects, install them to the global scope instead: + + ```bash + npx skills add heygen-com/hyperframes --agent antigravity --global + ``` + + Global skills live in `~/.gemini/antigravity/skills/` and load in every workspace. + + +Verify the skills are installed: + +```bash +ls .agents/skills/ +``` + +You should see directories like `hyperframes/`, `hyperframes-cli/`, `gsap/`, `tailwind/`, and others — each containing a `SKILL.md` that the agent reads on demand. + +## How skills work in Antigravity + +Antigravity uses **semantic matching** — when you type a prompt, the agent compares it against the `description` field of every available skill and loads the ones that are relevant. You don't need to invoke skills with a slash command (though you can reference them by name for precision). + +| You say | Agent loads | +|---|---| +| "Create a 10-second product intro with captions" | `hyperframes`, `hyperframes-cli` | +| "Add a GSAP scale-pop to the title" | `gsap` | +| "Use Tailwind for styling" | `tailwind` | +| "Transcribe this audio and add captions" | `hyperframes-media` | +| "Add a shimmer sweep transition" | `hyperframes-registry` | + +The skill is only injected into the agent's context window when it matches — this keeps the context clean and focused. + + + For the best results, mention "HyperFrames" or "composition" in your prompt so the agent matches the right skills immediately instead of guessing at generic web-video conventions. + + +## Create and preview a video + + + + Open Antigravity's integrated terminal and run: + + ```bash + npx hyperframes init my-video + cd my-video + ``` + + The wizard walks you through example selection and media import. Skills are installed automatically inside the new project. + + + + ```bash + npx hyperframes preview + ``` + + This launches the HyperFrames Studio in your browser with hot reload — edits to `index.html` appear instantly. + + + + In Antigravity's agent sidebar, describe the video you want: + + > Create a 15-second dark-themed product intro for my SaaS app with a fade-in title, hype-style captions, and a flash transition to the CTA. + + The agent reads the HyperFrames skill, writes valid HTML with `data-*` attributes and GSAP timelines, and saves it to your project files. The preview updates automatically. + + + + Talk to the agent like a video editor — don't re-prompt from scratch: + + > Make the title 2x bigger and swap the transition to a whip pan. + + > Add a lower third at 0:03 with my name. + + > Replace the background with assets/hero.mp4. + + + + ```bash + npx hyperframes render --output output.mp4 + ``` + + + +## Using multiple agents in Manager view + +Antigravity's [Manager view](https://antigravity.google/docs/agent) lets you orchestrate multiple agents in parallel. For complex multi-scene videos, you can split the work: + +- **Agent 1:** Author the intro scene and transitions +- **Agent 2:** Generate TTS narration and caption timing +- **Agent 3:** Build the data visualization scene + +Each agent picks up the relevant HyperFrames skills independently. Merge the output into a single `index.html` with `data-composition-src` references when all agents finish. + +## MCP alternative + +If you prefer zero-install cloud authoring, Antigravity supports remote MCP servers. Add the HyperFrames MCP connector to author and render compositions without the CLI — see [Antigravity's MCP documentation](https://antigravity.google/docs/mcp) for the exact setup steps in your version, then use the server URL: + +``` +https://mcp.heygen.com/mcp/hyperframes +``` + +Authorize via OAuth with your HeyGen account when prompted. See the [HyperFrames MCP guide](/guides/mcp) for full details on tools and prompting. The MCP handles rendering in the cloud; the CLI gives you local control. + +## Agent instruction files + +HyperFrames projects created with `npx hyperframes init` scaffold both `CLAUDE.md` and `AGENTS.md` automatically — these give the agent additional composition context beyond what the skills provide. + +- **`AGENTS.md`** — the cross-agent convention. Antigravity reads this regardless of which model you've selected (Gemini, Claude, or others). +- **`CLAUDE.md`** — read when Antigravity's agent uses a Claude model (Sonnet or Opus), providing Claude-specific project instructions. + +## Tips + +- **Mention the skill by name when precision matters.** "Using the hyperframes skill, add a grain overlay" is more reliable than "add a grain overlay" when the agent has many skills loaded. +- **Use `npx hyperframes lint` before rendering.** The linter catches structural issues (missing `class="clip"`, unregistered timelines, muted video violations) that the agent might miss on complex edits. +- **Install registry blocks for advanced effects.** Run `npx hyperframes add shimmer-sweep` to install pre-built blocks, then ask the agent to wire them into your composition. +- **Keep the preview server running.** Antigravity's file watcher + HyperFrames' hot reload means you see every agent edit in real time. + +## Next steps + + + + Vocabulary and patterns that produce better compositions. + + + 50+ ready-to-use blocks the agent can install and wire. + + + Motion principles and timeline authoring. + + + The 7-step structure agents follow for multi-beat videos. + + diff --git a/docs/guides/copilot-cli.mdx b/docs/guides/copilot-cli.mdx new file mode 100644 index 000000000..225c91229 --- /dev/null +++ b/docs/guides/copilot-cli.mdx @@ -0,0 +1,190 @@ +--- +title: GitHub Copilot CLI +description: "Set up HyperFrames with GitHub Copilot CLI — install skills, invoke them with slash commands, and render video from the terminal." +--- + +GitHub Copilot CLI brings AI-powered coding assistance to your terminal. HyperFrames skills teach it how to write correct compositions, GSAP timelines, and framework-specific patterns — so you get valid video HTML without reading the docs yourself. + +## Prerequisites + +- **GitHub Copilot subscription** — Free, Pro, Pro+, Business, or Enterprise all include CLI access +- **Copilot CLI installed** — `npm install -g @github/copilot` (or via the [install script](https://github.com/github/copilot-cli)) +- **Node.js 22+** and **FFmpeg** for the HyperFrames CLI + +## Install skills + +Install the HyperFrames skill package into your project: + +```bash +npx skills add heygen-com/hyperframes +``` + +This writes skill directories to `.agents/skills/` in your project — the path Copilot CLI scans automatically for workspace-scoped skills. + + + To make skills available across all your projects, install them globally: + + ```bash + npx skills add heygen-com/hyperframes --agent github-copilot --global + ``` + + Global skills live in `~/.copilot/skills/` and load in every Copilot CLI session. + + +If you install skills during an active session, run `/skills` to open the skills picker and verify they appear. New skills installed to the project directory are picked up automatically on the next prompt. + +## Using skills + +Copilot CLI supports both **explicit invocation** via slash commands and **automatic detection** based on your prompt. + +### Slash commands + +Prefix a skill name with `/` to load it explicitly: + +``` +/hyperframes Create a 10-second product intro with a fade-in title and dark background. +``` + +``` +/gsap Add a scale-pop animation to the title element. +``` + +``` +/hyperframes-cli How do I render at 60fps with Docker? +``` + +### Auto-detection + +Copilot also matches skills based on the `description` field in each `SKILL.md`. If your prompt mentions compositions, timelines, or video rendering, the agent loads the right skills without you specifying them: + +``` +Create a 9:16 TikTok hook video about AI productivity with bouncy captions. +``` + +Explicit invocation is more reliable when you have many skills installed — with large skill sets, the agent's token budget may not fit every skill description, so naming the skill directly guarantees it loads. + +### Skill management + +| Command | What it does | +|---|---| +| `/skills` | Open the interactive skills picker — browse, enable, or disable skills | +| `/skills add ` | Add an additional skill directory to the current session | + +## Create and preview a video + + + + ```bash + npx hyperframes init my-video + cd my-video + ``` + + Skills are installed automatically inside the new project. + + + + ```bash + npx hyperframes preview + ``` + + Opens the HyperFrames Studio in your browser. Edits reload automatically. + + + + In a second terminal: + + ```bash + copilot + ``` + + + + ``` + /hyperframes Create a 15-second dark-themed product intro with hype-style + captions and a flash transition to the CTA. + ``` + + The agent writes valid HyperFrames HTML — `data-*` attributes, `class="clip"` on timed elements, paused GSAP timelines registered on `window.__timelines`. The preview updates as files are saved. + + + + Keep prompting without re-specifying the full context: + + ``` + Make the title 2x bigger and add a lower third at 0:03. + ``` + + ``` + Swap the transition to a whip pan. + ``` + + + + ```bash + npx hyperframes render --output output.mp4 + ``` + + Or ask the agent: + + ``` + /hyperframes-cli Render this composition to output.mp4 at high quality. + ``` + + + +## Agent mode + +Copilot CLI's agent mode can handle multi-step tasks autonomously — scaffolding a project, writing the composition, installing registry blocks, and rendering in sequence: + +``` +/hyperframes Scaffold a new project called "launch-video", create a 30-second +product launch video with 5 scenes, install the flash-through-white transition +block, and render to mp4. +``` + +In agent mode, Copilot runs terminal commands (like `npx hyperframes init` and `npx hyperframes render`) on your behalf. Review the commands before approving them — especially if the skill pre-approves `shell` in its `allowed-tools`. + + + Only pre-approve `shell` or `bash` in skill `allowed-tools` for skills you trust. The HyperFrames skills do not pre-approve shell access — the agent will ask for confirmation before running terminal commands. + + +## MCP alternative + +Copilot CLI also supports MCP servers for cloud-based authoring without the local CLI. Use the `--additional-mcp-config` flag to add the HyperFrames MCP server to your session: + +```bash +copilot --additional-mcp-config '{"mcpServers":{"hyperframes":{"url":"https://mcp.heygen.com/mcp/hyperframes"}}}' +``` + +Or save the config to a file and reference it: + +```bash +copilot --additional-mcp-config @mcp-config.json +``` + +Authorize via OAuth when prompted. See the [MCP guide](/guides/mcp) for full details. + +## Tips + +- **Always start with `/hyperframes` for composition work.** This loads the full skill context — composition rules, data attributes, GSAP patterns, caption formats — that generic web knowledge doesn't cover. +- **Use `/skills` to check skill status.** If output looks wrong, open the skills picker to verify the HyperFrames skills are enabled. +- **Run `npx hyperframes lint` before rendering.** The linter catches structural issues the agent might miss on complex multi-scene edits. +- **Keep the preview server running in a separate terminal.** You see every edit reflected in real time while prompting in Copilot CLI. +- **Install registry blocks for transitions and effects.** `npx hyperframes add shimmer-sweep` installs pre-built blocks, then prompt the agent to wire them in. + +## Next steps + + + + Vocabulary and patterns that produce better compositions. + + + 50+ ready-to-use blocks the agent can install and wire. + + + Motion principles and timeline authoring. + + + The 7-step structure agents follow for multi-beat videos. + + diff --git a/docs/guides/prompting.mdx b/docs/guides/prompting.mdx index 59d82052b..69fcd2978 100644 --- a/docs/guides/prompting.mdx +++ b/docs/guides/prompting.mdx @@ -1,6 +1,6 @@ --- title: Prompt Guide -description: "How to prompt Claude Code, Cursor, Codex, and other AI agents to author Hyperframes compositions — with copy-pasteable examples and vocabulary tables." +description: "How to prompt Claude Code, Cursor, Codex, Google Antigravity, GitHub Copilot CLI, and other AI agents to author Hyperframes compositions — with copy-pasteable examples and vocabulary tables." --- Hyperframes is built for AI agents — compositions are plain HTML, the CLI is non-interactive, and the framework ships [skills](https://github.com/vercel-labs/skills) that teach agents the patterns docs alone don't cover. This guide shows how to prompt agents effectively once skills are installed — the vocabulary that changes output, the iteration patterns that save time, and the rules that prevent breakage. diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index a3d7e533f..ea9cfb754 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -13,7 +13,7 @@ Install the HyperFrames skills, then describe the video you want: npx skills add heygen-com/hyperframes ``` -This teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) how to write correct compositions, GSAP timelines, Tailwind v4 browser-runtime styles, and first-party adapter animations. In Claude Code the skills register as slash commands — `/hyperframes` for composition authoring, `/hyperframes-cli` for the dev-loop commands (init, lint, preview, render), `/hyperframes-media` for asset preprocessing (TTS, transcription, background removal), `/tailwind` for `init --tailwind` projects, `/gsap` for timeline animation help, and `/animejs`, `/css-animations`, `/lottie`, `/three`, or `/waapi` when a composition uses those runtimes. Invoking the slash command loads the skill context explicitly, which produces correct output the first time. +This teaches your agent (Claude Code, Cursor, Gemini CLI, Codex, [Google Antigravity](/guides/antigravity), [GitHub Copilot CLI](/guides/copilot-cli)) how to write correct compositions, GSAP timelines, Tailwind v4 browser-runtime styles, and first-party adapter animations. In Claude Code the skills register as slash commands — `/hyperframes` for composition authoring, `/hyperframes-cli` for the dev-loop commands (init, lint, preview, render), `/hyperframes-media` for asset preprocessing (TTS, transcription, background removal), `/tailwind` for `init --tailwind` projects, `/gsap` for timeline animation help, and `/animejs`, `/css-animations`, `/lottie`, `/three`, or `/waapi` when a composition uses those runtimes. Invoking the slash command loads the skill context explicitly, which produces correct output the first time. Claude Design uses a different entry path. Open [`docs/guides/claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) on GitHub, click the download button (↓) to save it, then attach to your Claude Design chat. It produces a valid first draft you can refine in any AI coding agent. See the [Claude Design guide](/guides/claude-design).