fix(cli): document Cursor skills install path

[miguel-heygen]

Problem

Fixes #644.

The README told Cursor users to install HyperFrames from the Cursor Marketplace or sideload .cursor-plugin/plugin.json via Settings -> Plugins -> Load unpacked. In Cursor 3.2.21, the reporter could not find a HyperFrames Marketplace plugin and the unpacked-manifest flow is not available, so the docs pointed users at a dead install path.

What this fixes

• Replaces the README Cursor Marketplace/sideload instruction with the supported skills path: npx hyperframes skills --cursor inside a project, or npx skills add heygen-com/hyperframes --agent cursor --yes before project creation.
• Updates Quickstart, CLI package docs, and Claude/Open Design setup tables to make Cursor a separate skills install path instead of grouping it with generic agent setup.
• Wires hyperframes skills --cursor through to the upstream skills CLI as --agent cursor --yes instead of ignoring the flag and using the broad --all install.
• Adds a regression test for the Cursor flag mapping.

Root cause

There were two separate drifts:

1. Public docs described a Cursor plugin install path that is not published/available to users today.
2. The HyperFrames skills wrapper documented tool-specific flags, but the command ignored every flag and always spawned npx skills add heygen-com/hyperframes --all.

Verification

Local checks

• bunx vitest run packages/cli/src/commands/skills.test.ts - 2/2 passed.
• bun run build:hyperframes-runtime - generated the missing fresh-worktree runtime artifacts.
• bun run --filter @hyperframes/cli typecheck - passed after runtime generation.
• bunx oxlint packages/cli/src/commands/skills.ts packages/cli/src/commands/skills.test.ts - 0 warnings / 0 errors.
• bunx oxfmt --check README.md docs/quickstart.mdx docs/packages/cli.mdx docs/guides/claude-design.mdx docs/guides/open-design.mdx packages/cli/src/commands/skills.ts packages/cli/src/commands/skills.test.ts - clean.
• git diff --check - clean.
• Temp install smoke from /tmp/hf-cursor-cli-proof:
  • bun /Users/miguel07code/.codex/worktrees/e605/hyperframes-oss/packages/cli/src/cli.ts skills --cursor
  • npx skills ls -a cursor --json
  • Verified 13 installed skills, all targeting Cursor, including hyperframes and hyperframes-cli.
• Cursor CLI check:
  • Installed the official Cursor CLI via curl https://cursor.com/install -fsS | bash.
  • cursor-agent --version returned 2026.05.05-84a231c.
  • A model-backed agent -p ... smoke was blocked by local auth: Authentication required. Please run 'agent login' first, or set CURSOR_API_KEY environment variable.

Browser verification

• Ran local docs preview with npx mintlify dev --port 3333.
• Used agent-browser to open http://localhost:3333/quickstart and verified the rendered Cursor note text.
• Used agent-browser to open http://localhost:3333/packages/cli#skills and verified the rendered npx hyperframes skills --cursor, .agents/skills/, Marketplace, and "Load unpacked" guidance.
• agent-browser errors --clear returned no page errors.
• Browser proof artifacts:
  • /tmp/hf-cursor-docs-browser-proof/quickstart-cursor-note.png
  • /tmp/hf-cursor-docs-browser-proof/cli-cursor-skills.png
  • /tmp/hf-cursor-docs-browser-proof/cursor-docs-flow-complete.webm

Notes

The checked-in .cursor-plugin/plugin.json remains in place for packaging/submission work. This PR stops presenting it as the current user install surface until a HyperFrames Cursor Marketplace plugin actually exists.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
hyperframes	🟢 Ready	View Preview	May 6, 2026, 3:08 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[jrusso1020]

@miguel-heygen I think still though that the main fix here is getting into the marketplace these are bandaids on how to install any skill no?

[miguel-heygen]

@miguel-heygen I think still though that the main fix here is getting into the marketplace these are bandaids on how to install any skill no?

​yeah, I wouldn't merge this