Files
hyperframes/skills/hyperframes-cli/references/init-and-scaffold.md
T
Wenbo ZhuandClaude Opus 5.5 6857bb08e8 docs(skills): stop directing the agent to install, update or remove skills (#7102)
A third-party skill-trust grader (DeltaVerdict D5) fails any skill text
that has the agent modify its own skills, even when disclosed or gated on
the user. Reword the skill lifecycle, plugin, CLI and scaffold text so it
states facts the agent can relay (skills are versioned with the CLI; the
person installs and updates them, and which command does it) instead of
commands for the agent to run. Every agent-run `init` example passes
--skip-skills, since init otherwise installs missing core skills; the
plugin header, plugin-cli and sfx messages are person-addressed; the
person's install commands are marked as theirs; /style-sampling joins
the on-demand lists. Regenerate skills-manifest.json and update the
pinned reverse init regex.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 10:17:14 +00:00

6.5 KiB
Raw Blame History

init, capture, skills

Scaffolding commands. Use these instead of creating files by hand — they set up the right file structure, copy media, and run transcription.

init

npx hyperframes init my-video --skip-skills                      # centered blank (TTY: wizard)
npx hyperframes init my-video --skip-skills --example warm-grain # pick an example
npx hyperframes init my-video --skip-skills --resolution portrait
npx hyperframes init my-video --skip-skills --video clip.mp4     # with video file
npx hyperframes init my-video --skip-skills --audio track.mp3    # with audio file
npx hyperframes init my-video --skip-skills --tailwind           # Tailwind v4 browser runtime
npx hyperframes init my-video --skip-skills --non-interactive    # CI — flag-only, same blank

Default depends on TTY: in a terminal, the CLI prompts for example/options (default: centered blank). Outside a TTY (CI, agents, piped output) it auto-switches to non-interactive and scaffolds that blank. Pass --example only to start from a named example. Pass --non-interactive to force flag-only mode on a TTY.

Templates: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph. (The closed set of hyperframes:example items in registry/registry.json plus the bundled blank template. hyperframes catalog does not list examples — its --type takes only block or component — so this list has no live equivalent and is checked by bun run lint:skills.)

Other useful flags:

  • --resolution — preset: landscape (1920×1080), portrait (1080×1920), landscape-4k, portrait-4k, square (1080×1080), square-4k. Aliases: 1080p, 4k, uhd, 1080p-square, 4k-square.
  • --skill=<slug> — record the owning skill (e.g. hyperframes) in hyperframes.json, so every later render of this project — re-renders, npm run render, --batch — is attributed to it on usage telemetry without re-passing the flag. You rarely pass it by hand.
  • --skip-skills — leave AI coding skills alone: init does not install the core set. HYPERFRAMES_SKIP_SKILLS=1 does the same. Always pass it: without it init installs any missing core skill, and installing skills is the person's step. When a core skill is missing, tell the person they can install it with npx hyperframes skills update.
  • --skip-transcribe — don't auto-transcribe --audio / --video with Whisper.
  • --model, --language — Whisper model / language for the auto-transcription.

Tailwind (--tailwind): the scaffold pins the Tailwind v4 browser runtime, not Studio's Tailwind v3 setup.

  • Keep the pinned runtime; never swap in cdn.tailwindcss.com. Renders wait for window.__tailwindReady before frame 0. For offline or locked-down renders, compile to CSS and ship the stylesheet.
  • Theme and custom utilities go in <style type="text/tailwindcss"> with @theme and @utility. No v3 @tailwind base/components/utilities, no tailwind.config.js; @config and @plugin abort the browser compile.
  • Write complete class tokens in the HTML. The runtime only sees classes it can scan, so never build a render-critical class name at seek time (bg-${color}-500); vary items through CSS variables (style="--i: 2") or data variants.
  • Tailwind is for static layout and style; timing stays in GSAP or another seekable runtime.

When --audio or --video is supplied, init transcribes the file with Whisper. For voice/model selection see the media-use skill.

capture

npx hyperframes capture https://stripe.com                  # scaffold from a website
npx hyperframes capture https://linear.app -o linear-video  # custom output directory
npx hyperframes capture https://example.com --json          # JSON output for agents
npx hyperframes capture https://example.com --skip-assets   # skip image/SVG download
npx hyperframes capture https://example.com --skip-vision   # skip optional AI captions
npx hyperframes capture https://example.com --max-screenshots 12
npx hyperframes capture https://example.com --timeout 60000 # page-load timeout in ms
npx hyperframes capture https://example.com --capture-budget 90000 # post-navigation budget
HYPERFRAMES_CAPTURE_PROXY=http://127.0.0.1:3128 npx hyperframes capture https://example.com # behind an egress proxy

Captures a live URL as an editable HyperFrames project: screenshots become layered scenes, assets are downloaded locally, and the result is a normal project you can lint / preview / render. Use this when the user supplies a URL as the starting point for a video.

--timeout bounds page navigation; --capture-budget is the separate cooperative budget for work after navigation (fonts, assets, vision, and contact sheets). The latter is not a hard wall-clock watchdog and cannot interrupt native work already in flight. An outer caller deadline is therefore a third, distinct timeout. An outer caller timeout leaves the capture result unknown; it does not prove HyperFrames hung or that the navigation timeout should be increased. Preserve the last phase and classify the boundary that fired. --skip-vision disables only optional AI image captioning.

For agents, use --json. The result includes ok, warnings, and lastPhase. The command also emits stable HYPERFRAMES_CAPTURE_PHASE records so a watchdog can report the last started, completed, or degraded phase without retaining sensitive payloads.

Treat a non-zero exit, JSON ok: false, or an output BLOCKED.md as a hard stop. Do not render, build, or infer brand/design data from partial files in a blocked capture. A successful capture may degrade an optional phase within budget, but its structural output still has to be usable. Exit zero and file existence alone are not semantic success: require the current invocation's JSON ok: true, no BLOCKED.md, and artifacts usable for the video. Run each retry into a fresh output directory; never merge or reuse a blocked attempt's partial output.

skills

npx hyperframes skills is the person's one-time setup: it adds the HyperFrames skill pack (/hyperframes with its references, /hyperframes-cli, /hyperframes-registry, /media-use, /figma, /slideshow, /remotion-to-hyperframes, /reverse-any-video, /style-sampling) to the local AI coding environment so agents follow the framework conventions. Skills are versioned with the CLI; after a HyperFrames upgrade the person can refresh them with npx hyperframes skills update. Tell them when that applies; do not run it yourself.