fix(cli): document Cursor skills install path

README.md

@@ -43,7 +43,16 @@ codex plugin marketplace add heygen-com/hyperframes --sparse .codex-plugin --spa
 ```
 
 For Claude Code, the repo also ships a [Claude Code plugin manifest](./.claude-plugin/plugin.json): test it locally with `claude --plugin-dir .`. The manifest intentionally omits `skills` because Claude Code auto-discovers the root `skills/` directory by convention, and for marketplace submission use the title `HyperFrames by HeyGen` plus the black/white icon assets at [`assets/claude-code-icon-dark.svg`](./assets/claude-code-icon-dark.svg) and [`assets/claude-code-icon-light.svg`](./assets/claude-code-icon-light.svg) for the two theme slots.
-For Cursor, the same skills are packaged as a [Cursor plugin](./.cursor-plugin/plugin.json) — install from the Cursor Marketplace, or sideload by cloning this repo and pointing **Settings → Plugins → Load unpacked** at the repo root.
+
+For Cursor, install the skills instead of looking for a Marketplace plugin or a "Load unpacked" manifest flow:
+
+```bash
+npx hyperframes skills --cursor
+# or, before creating a HyperFrames project:
+npx skills add heygen-com/hyperframes --agent cursor --yes
+```
+
+Then open the project in Cursor or run `cursor-agent` from the project directory. `hyperframes init` also writes `AGENTS.md` and `CLAUDE.md`; Cursor Agent CLI reads those project instructions alongside installed skills. The checked-in [Cursor plugin manifest](./.cursor-plugin/plugin.json) is for packaging/submission work, not the current user install path until the plugin is published.
 
 #### Try it: example prompts
 

docs/guides/claude-design.mdx

@@ -40,7 +40,8 @@ Claude Design produces a **valid first draft** of a HyperFrames video — brand
 | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
 | Claude Design               | Download [`claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) from GitHub and attach to your chat |
 | Claude Code                 | `npx skills add heygen-com/hyperframes`, then use `/hyperframes`                                                              |
-| Cursor / Codex / Gemini CLI | `npx skills add heygen-com/hyperframes`                                                                                       |
+| Cursor                      | `npx hyperframes skills --cursor` in a project, or `npx skills add heygen-com/hyperframes --agent cursor --yes` before project creation |
+| Codex / Gemini CLI          | `npx skills add heygen-com/hyperframes`                                                                                       |
 
 ## How it works
 

docs/guides/open-design.mdx

@@ -52,7 +52,8 @@ Open Design produces a **valid first draft** of a HyperFrames composition — pa
 | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Open Design (open-source)              | Drop [`open-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/open-design-hyperframes.md) into `skills/hyperframes-handoff/SKILL.md`   |
 | Claude Code                            | `npx skills add heygen-com/hyperframes`, then use `/hyperframes`                                                                                                             |
-| Cursor / Codex / Gemini CLI            | `npx skills add heygen-com/hyperframes`                                                                                                                                       |
+| Cursor                                 | `npx hyperframes skills --cursor` in a project, or `npx skills add heygen-com/hyperframes --agent cursor --yes` before project creation                                      |
+| Codex / Gemini CLI                     | `npx skills add heygen-com/hyperframes`                                                                                                                                       |
 | Claude Design (closed-source)          | Attach [`claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) to your chat                          |
 
 ## How it works

docs/packages/cli.mdx

@@ -800,7 +800,7 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
     Install HyperFrames skills for AI coding tools, including first-party runtime adapter skills:
 
     ```bash
-    # Install to all default targets (Claude Code, Gemini CLI, Codex CLI)
+    # Install to every agent target supported by the upstream skills CLI
     npx hyperframes skills
 
     # Install to specific tools
@@ -811,12 +811,12 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
 
     | Flag | Description |
     |------|-------------|
-    | `--claude` | Install to Claude Code (`~/.claude/skills/`) |
-    | `--gemini` | Install to Gemini CLI (`~/.gemini/skills/`) |
-    | `--codex` | Install to Codex CLI (`~/.codex/skills/`) |
-    | `--cursor` | Install to Cursor (`.cursor/skills/` in current project) |
+    | `--claude` | Install to Claude Code |
+    | `--gemini` | Install to Gemini CLI |
+    | `--codex` | Install to Codex CLI |
+    | `--cursor` | Install to Cursor's project skill target (`.agents/skills/`) |
 
-    Skills are fetched from GitHub and include composition authoring, Tailwind v4 browser-runtime guidance, GSAP animation patterns, Anime.js, CSS animation, Lottie, Three.js, and WAAPI adapter patterns, registry block/component wiring, and other domain-specific knowledge. The `init` command also offers to install skills automatically after scaffolding a project.
+    Skills are fetched from GitHub and include composition authoring, Tailwind v4 browser-runtime guidance, GSAP animation patterns, Anime.js, CSS animation, Lottie, Three.js, and WAAPI adapter patterns, registry block/component wiring, and other domain-specific knowledge. For Cursor, this is the supported install path today; do not look for a HyperFrames Marketplace plugin or a "Load unpacked" manifest flow. The `init` command also offers to install skills automatically after scaffolding a project.
 
     #### Troubleshooting: `fatal: active post-checkout hook found during git clone`
 

docs/quickstart.mdx

@@ -19,6 +19,10 @@ This teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) how to write co
   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).
 </Note>
 
+<Note>
+  Cursor users should install HyperFrames as agent skills, not from Marketplace. Inside a HyperFrames project, run `npx hyperframes skills --cursor`; before creating a project, run `npx skills add heygen-com/hyperframes --agent cursor --yes`. Then open the folder in Cursor or run `cursor-agent` from that directory. `hyperframes init` also writes `AGENTS.md` and `CLAUDE.md`, which Cursor Agent CLI reads as project instructions.
+</Note>
+
 ### Try it: example prompts
 
 Copy any of these into your agent to get started.

packages/cli/src/commands/skills.test.ts

@@ -46,4 +46,25 @@ describe("hyperframes skills", () => {
     expect(first!.args).toContain("add");
     expect(first!.env?.GIT_CLONE_PROTECTION_ACTIVE).toBe("0");
   });
+
+  it("forwards --cursor to the upstream skills CLI instead of installing every agent", async () => {
+    const { default: skillsCmd } = await import("./skills.js");
+    await skillsCmd.run?.({
+      args: { cursor: true },
+      rawArgs: ["--cursor"],
+      cmd: skillsCmd,
+    } as never);
+
+    const first = state.calls[0];
+    expect(first).toBeDefined();
+    expect(first!.command).toBe("npx");
+    expect(first!.args).toEqual([
+      "skills",
+      "add",
+      "heygen-com/hyperframes",
+      "--agent",
+      "cursor",
+      "--yes",
+    ]);
+  });
 });

packages/cli/src/commands/skills.ts

@@ -3,6 +3,13 @@ import { execFileSync, spawn } from "node:child_process";
 import * as clack from "@clack/prompts";
 import { c } from "../ui/colors.js";
 
+type SkillsCommandArgs = {
+  claude?: boolean;
+  gemini?: boolean;
+  codex?: boolean;
+  cursor?: boolean;
+};
+
 function hasNpx(): boolean {
   try {
     execFileSync("npx", ["--version"], { stdio: "ignore", timeout: 5000 });
@@ -12,9 +19,24 @@ function hasNpx(): boolean {
   }
 }
 
-function runSkillsAdd(repo: string): Promise<void> {
+function getSelectedAgents(args: SkillsCommandArgs): string[] {
+  const agents: string[] = [];
+  if (args.claude) agents.push("claude-code");
+  if (args.gemini) agents.push("gemini");
+  if (args.codex) agents.push("codex");
+  if (args.cursor) agents.push("cursor");
+  return agents;
+}
+
+function getSkillsAddArgs(repo: string, args: SkillsCommandArgs): string[] {
+  const agents = getSelectedAgents(args);
+  if (agents.length === 0) return ["skills", "add", repo, "--all"];
+  return ["skills", "add", repo, "--agent", ...agents, "--yes"];
+}
+
+function runSkillsAdd(repo: string, args: SkillsCommandArgs): Promise<void> {
   return new Promise((resolve, reject) => {
-    const child = spawn("npx", ["skills", "add", repo, "--all"], {
+    const child = spawn("npx", getSkillsAddArgs(repo, args), {
       stdio: "inherit",
       timeout: 120_000,
       // GH #316 — the upstream `skills` CLI shells out to `git clone`.
@@ -42,8 +64,25 @@ export default defineCommand({
     name: "skills",
     description: "Install HyperFrames skills for AI coding tools",
   },
-  args: {},
-  async run() {
+  args: {
+    claude: {
+      type: "boolean",
+      description: "Install to Claude Code",
+    },
+    gemini: {
+      type: "boolean",
+      description: "Install to Gemini CLI",
+    },
+    codex: {
+      type: "boolean",
+      description: "Install to Codex CLI",
+    },
+    cursor: {
+      type: "boolean",
+      description: "Install to Cursor",
+    },
+  },
+  async run({ args }) {
     if (!hasNpx()) {
       clack.log.error(c.error("npx not found. Install Node.js and retry."));
       return;
@@ -54,7 +93,7 @@ export default defineCommand({
       console.log(c.bold(`Installing ${source.name} skills...`));
       console.log();
       try {
-        await runSkillsAdd(source.repo);
+        await runSkillsAdd(source.repo, args);
       } catch {
         console.log(c.dim(`${source.name} skills skipped`));
       }