feat: split lightweight HyperFrames default skill

[miguel-heygen]

Problem

HyperFrames should be discoverable as the default video path, but the existing default skills/hyperframes content was too heavy for default injection. It bundled the full production authoring workflow and implied CLI/runtime dependencies that are not safe to assume in every environment.

What this fixes

• Keeps skills/hyperframes as a lightweight default entry point with no bundled runtime dependency setup.
• Moves detailed production guidance to optional-skills/hyperframes as hyperframes-production.
• Moves the website capture-to-video workflow to optional-skills/website-to-hyperframes because it depends on the full production guidance.
• Makes explicit HyperFrames skill installs full-depth: hyperframes skills now passes --full-depth, and direct install docs/templates use npx skills add heygen-com/hyperframes --full-depth.
• Adds explicit HyperFrames CLI preflight guidance so agents check Node.js, hyperframes doctor, FFmpeg/FFprobe, Chrome, Docker, and resources before trying heavyweight commands.
• Makes render-only failure mode explicit in the default and CLI skills: if required deps are missing, stop before render and surface the clean install hint instead of attempting render and crashing.
• States the Node requirement clearly for agents: known minimum runtime for the current CLI is Node.js 20.12+; supported and CI-tested baseline is Node.js 22+; package manifests still declare Node.js 22+.
• Updates plugin metadata, docs, CLI templates, and capture prompts to route through the default lightweight video skill first, then optional production workflows when available.
• Extends the skill linter to cover both skills/ and optional-skills/.

Root cause

Default skills/ entries are bundled and discovered by default, so the full HyperFrames authoring skill made every default environment inherit production workflow guidance and dependency assumptions. The full skill is still useful, but it belongs behind optional discovery while the default skill should only provide routing, safe preflight, and the minimal composition contract.

Explicit HyperFrames installs are a different user intent: those users are choosing the HyperFrames skill set, so the CLI and docs should install through --full-depth and include the optional production workflows.

Verification

Local

• bun install
• npx skills add . --list
• npx skills add . --list --full-depth
• HOME="$(mktemp -d /tmp/hf-skills-home.XXXXXX)" npx skills add . --all --global --yes --full-depth installed 13 skills, including hyperframes-production and website-to-hyperframes
• bun run lint:skills
• bunx oxlint packages/cli/src/capture/agentPromptGenerator.ts packages/cli/src/commands/contrast-audit.browser.js scripts/lint-skills.ts
• bunx oxlint packages/cli/src/commands/skills.ts packages/cli/src/commands/skills.test.ts packages/cli/src/commands/init.ts
• bunx oxfmt --check README.md docs/quickstart.mdx docs/guides/prompting.mdx docs/guides/claude-design.mdx docs/guides/open-design.mdx docs/guides/claude-design-hyperframes.md docs/guides/website-to-video.mdx docs/packages/cli.mdx packages/cli/src/commands/init.ts packages/cli/src/templates/_shared/AGENTS.md packages/cli/src/templates/_shared/CLAUDE.md packages/cli/src/commands/skills.ts packages/cli/src/commands/skills.test.ts
• bunx oxfmt --check skills/hyperframes/SKILL.md skills/hyperframes-cli/SKILL.md
• bunx vitest run packages/cli/src/commands/skills.test.ts
• bun run build:hyperframes-runtime
• bun run --filter @hyperframes/cli typecheck
• bun run --filter @hyperframes/cli test
• git diff --check
• git diff --cached --check
• Sensitive-name scan over the staged source diff returned no matches
• Direct install snippet scan confirmed no remaining npx skills add heygen-com/hyperframes command without --full-depth

Node floor check

• Package manifests and CI declare/test Node.js 22+ for CLI/engine/producer support.
• Runtime dependency package engines bottom out at Node.js 18/18.14.1 for the relevant CLI render stack.
• Built CLI import smoke:
  • Node.js 18.20.8: fails to import, missing util.styleText.
  • Node.js 20.0.0: fails to import, missing util.styleText.
  • Node.js 20.10.0 and 20.11.1: fail to import, missing util.styleText.
  • Node.js 20.12.0: --version, --help, and doctor start successfully.
• Node.js 20.12.0 end-to-end smoke passed with the built CLI:
  • init demo --example warm-grain --non-interactive --skip-skills
  • lint .
  • render . --fps 24 --quality draft --workers 1 --output out.mp4 --quiet

Browser

• Served a local proof page that fetches and displays:
  • /skills/hyperframes/SKILL.md
  • /optional-skills/hyperframes/SKILL.md
  • /optional-skills/website-to-hyperframes/SKILL.md
  • /packages/cli/src/commands/skills.ts
• Verified via agent-browser that all required markers loaded, including the explicit --full-depth CLI install marker, the direct-install fallback hint, and the render-fail-fast instruction. The default skill is 3,553 bytes while the production guidance is optional.
• agent-browser errors returned no browser errors.
• Screenshot: .codex-artifacts/lightweight-hyperframes-skill/default-skill-proof.png.
• Recording verified with ffprobe: 7.8s, 152984 bytes.

Notes

The default skill does not install or download heavy dependencies. It tells agents to surface missing runtime requirements and only use npx hyperframes browser ensure when Chrome is missing and the user explicitly wants the CLI-managed browser path.

Existing users who already installed the previous full skill are not forced onto the lightweight skill. New default bundled users get the lightweight entry point; new HyperFrames-first users installing with the documented command get the optional production skills too. If someone uses an older direct install command without --full-depth, the lightweight skill now tells agents to prompt them toward the full-depth install when they ask for detailed production authoring.

[mintlify]

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

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

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