jacky-skills

HyperFrames Ops

Before answering environment-related questions, first read experience.local.md in the same directory to get the latest local facts (proxy commands, version snapshots, historical Q&A).

0. Why an Independent Ops Layer is Needed

Third-party skills often describe only generic capabilities, unable to predict each machine's network, proxy, Node/FFmpeg version, font cache, login state, and tool combination. Directly modifying the official skill leads to update conflicts and mixes local facts into upstream generic instructions.

Therefore, the two layers are separated:

• Official skills are the capability source, remain updatable and replaceable.
• hyperframes-ops is the local adaptation layer, recording best practices, compatibility differences, failure modes, and verified workarounds.
• For creation questions, first read the official skill; for environment, combination, version, or local adaptation issues, then read this skill.
• When an upstream update invalidates old experience, mark it as invalid in local experience and re-validate; do not cover new behavior with old experience.

1. Project Identity (General Facts)

• HyperFrames is a HeyGen official open-source project: github.com/heygen-com/hyperframes, npm package hyperframes
• Positioning: Use HTML to write video compositions, render via headless Chrome into mp4 using a CLI (npx hyperframes)
• Environment requirements: Node.js >= 22, FFmpeg

2. Official Skills Distribution Mechanism

• Official skills are maintained and version-distributed together with the CLI; the manifest is located at the repository root: https://raw.githubusercontent.com/heygen-com/hyperframes/main/skills-manifest.json
• Composition: Core set (hyperframes / hyperframes-core / hyperframes-cli / hyperframes-animation / hyperframes-keyframes / hyperframes-creative / hyperframes-registry / remotion-to-hyperframes) + Workflow set (general-video, slideshow, motion-graphics, music-to-video, pr-to-video, product-launch-video, website-to-video, faceless-explainer, talking-head-recut, embedded-captions, media-use, figma). See skills check actual output for accuracy
• Management commands:
  • npx hyperframes skills check — Check versions against manifest
  • npx hyperframes skills update — Update all installed + clean up officially removed ones
  • npx hyperframes init — Force sync skills to latest (--skip-skills is currently disabled by the official tool)
• Installation location: global ~/.claude/skills/ (CLI auto-detects claude-code)
• Naming safety: The cleanup logic of skills update is based on lock file "source attribution" — it only deletes skills that originate from the official repository and have been removed. This skill, although prefixed with hyperframes-, is not under the official lock's attribution and will not be accidentally deleted by the official updater.

3. Troubleshooting Routing Table

Symptom	Route
skills check/update/init throws AbortError (fetchManifest timeout)	Network issue: CLI uses Node's built-in fetch to access raw.githubusercontent.com. Direct connection is impossible; proxy is required. Read experience.local.md for the one-shot command on this machine
npx hyperframes other network-related failures	Same as above; note that Node's built-in fetch (undici) does not read the HTTP_PROXY environment variable by default. On Node 24+, add NODE_USE_ENV_PROXY=1 (or --use-env-proxy)
Rendering/preview environment abnormalities	npx hyperframes doctor, npx hyperframes browser self-check; confirm Node >= 22, FFmpeg is available
Skill behaves like an old version	skills check to see version gap, skills update to align
heygen auth login --oauth token exchange failed (api2.heygen.com connection refused) or music library call timeout	heygen CLI is a Go program, respects HTTP(S)_PROXY environment variables (opposite to Node fetch, no additional flag needed); under restricted network, all heygen commands must use proxy. OAuth callback service only lives 5 minutes and requires an interactive shell (background/nohup will timeout due to missing callback). Machine-specific commands in experience.local.md
Rendered fonts incorrect (title widening, overflowing container, but lint/inspect shows all green)	The built-in 18 fonts are fetched from the network on-demand at runtime (@fontsource → ~/.cache/hyperframes/fonts). If fetching fails, it silently falls back to system fonts. Restricted network solution: download woff2 into the project and explicitly @font-face self-host
Creative questions (how to write compositions, animations, rendering parameters)	Not covered by this skill; go to the official hyperframes entry skill's routing table

4. Experience Write-back Protocol

• Write to experience.local.md (private to this machine, ignored by .gitignore in this directory): Newly encountered pitfalls and verified solutions, version/installation status snapshots (with date), machine-specific commands, proxy and network facts, historical Q&A
• Write back to this SKILL.md (committed to git, shareable): Official mechanism changes (distribution method, command semantics, cleanup logic), new generalized troubleshooting routes
• Criteria: If it holds true on another machine → SKILL.md; if only true for this machine → experience.local.md
• Each time this skill is invoked and resolves a HyperFrames environment issue, write the conclusion back according to the above layers, with the date.