Content & Media Creation · saranambiar/hyperframes-video-agent-skills
hyperframes-scene-builder
Create and revise HyperFrames HTML video compositions with CSS, GSAP timelines, composition IDs, reusable components, render commands, and proof-frame validation. Use when an agent needs to build a scene, edit a composition, render HyperFrames output, or debug HyperFrames-specific scene behavior.
L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.
1How It Works & Mechanism
Prerequisites are explicitly stated: the rendering engine is HyperFrames, and scene sources are HTML/CSS/JS. Therefore, all rules revolve around "composition root + paused timeline + addressability + determinism" rather than general frontend development.
skills/hyperframes-scene-builder/SKILL.md
Use this skill when implementing or revising a HyperFrames scene. This skill assumes HyperFrames is the render engine and the scene source is HTML/CSS/JS.
What is being done here: Locking down the tech stack before providing rules; this is also the only skill in the family that directly provides HyperFrames CLI commands.
Timelines must be paused because frame rendering requires deterministic seeking—this is the prerequisite for "rendering the exact same frames from the same source."
skills/hyperframes-scene-builder/SKILL.md
- Use paused timelines for deterministic seekable animation.
What is being done here: Treating addressability and determinism as a hard contract (the family skill heygen-com's HF contract also requires paused GSAP timelines and tl.seek(0)).
Composition root and scoping discipline: Explicitly declare data-composition-id / data-width / data-height; selectors must be scoped strictly within the composition root, and global selectors that could pollute other sub-compositions are strictly prohibited.
skills/hyperframes-scene-builder/SKILL.md
- Avoid global selectors that can mutate other sub-compositions.
What is being done here: Addressing isolation issues when mounting multiple scenes simultaneously—the most practical pitfall in HyperFrames-style multi-composition-per-page architectures.
The rendering cycle follows "low-quality draft iterations → increase quality/framerate only upon finalization": Use draft quality + --workers 2 to inspect results quickly, ramping up only when the scene is approved or when framerate-sensitive motion needs validation.
skills/hyperframes-scene-builder/SKILL.md
Use higher FPS or quality only when the scene is approved or when testing frame-rate-specific motion.
What is being done here: Managing rendering costs as a constraint (including reducing worker count when GPU or Chrome is unstable) to avoid full-quality re-renders for every minor tweak.
Proof frames must come from the rendered MP4 rather than browser screenshots—screenshots bypass the encoding/compositing pipeline and mask real discrepancies.
skills/hyperframes-scene-builder/SKILL.md
- Generate proof frames from the rendered MP4, not only browser screenshots.
What is being done here: Codifying the rule that "verification must test actual artifacts"; the family skill render-qa also mandates extracting frames from the same final export.
Built-in HyperFrames-specific risk checklist: Timeline ID mismatches, unscoped selectors in nested compositions, GSAP overriding existing CSS transforms, CDN/font loading discrepancies between preview and rendering, media asset resolution failures in render workers, and oversized single files preventing agent inspection.
skills/hyperframes-scene-builder/SKILL.md
- CDN or font loading differences between preview and render.
What is being done here: Listing six known root causes of "preview passes ≠ render passes" for methodical elimination during troubleshooting.
Carryover discipline: If a transition misses a new label or graphic, the duplicated frame in the next scene must be updated concurrently.
skills/hyperframes-scene-builder/SKILL.md
- If a scene transition forgets a new label or visual, patch the next scene's carryover frame too.
What is being done here: Restating the carryover audit from scene-continuity-and-transitions on the "build" side to establish a double safeguard.
2Core Capabilities
01HyperFrames core render command trio: preview / lint / render (including --composition / --output / --fps / --quality draft / --workers)
02Composition and GSAP authoring rules: explicit composition roots, timelines registered to matching composition IDs, set-based initialization, using fromTo when CSS transforms exist, avoiding pure opacity and bounce eases, ensuring final frames are stable enough for proof-frame extraction
03Visual QA: extracting first frame / key beats / final frame PNGs; comparing reference scenes against the final frame rather than just the start; validating text scaling at video resolution; ensuring duplicated hidden frames in subsequent scenes are synced; checking theme colors across CSS/SVG/inline styles
04Common troubleshooting playbook: fixing transitions missing labels/graphics by updating next-scene carryover; investigating premature timeline object appearances via initial opacity/path progress/node visibility; revealing path points in sync with line progress; resolving text clipped by rings or cards by adjusting overall system scale rather than just the label; fixing clipped product UI using unclipped or dynamic framing
05Reusable component pattern catalog: GlassPanel, LogoRow, CaptionSafeArea, ChartFrame, PathCurve, PointReveal, CameraSwipe, FinalFrameCarryover, CTAStack—can be CSS classes, HTML snippets, or helper functions rather than formal JS classes
06File organization best practices vs. antipatterns: one scene per HTML file, granular sub-compositions, tokens near file top, reusable visual components, easily swappable asset paths; antipatterns include monolithic single files, uncommented magic numbers, duplicated colors, uncommented hidden final frames, and globally leaking CSS
07Proof-frame extraction checklist: first frame, first major reveal, primary animation midpoint, user-specified timestamps, final frame, next-scene carryover start (if applicable)
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| cli | HyperFrames CLI（npx hyperframes preview / lint / render），Node/npm 生态工具；首次 npx 会从 npm registry 解析该包 |
| package | HyperFrames 渲染器（本地合成与编码，含无头 Chrome/worker 渲染环境） |
| package | GSAP（时间线动画库；由组合页面引入，规则围绕暂停时间线与 set/fromTo 语义） |
| network | 产物期引用面：组合页面若引用 CDN 脚本或网络字体，preview 与 render worker 会各自拉取，行为可能不一致（按范式属产物期引用，不判级，仅记录） |
| cli | ffmpeg（间接：抽帧与证明帧由同族 render-qa skill 的 scripts/extract_proof_frames.py 承担） |
4Recommended Governance & Evidence
Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
- scripts/: Executing local scripts or commands: (executed by host agent) npx hyperframes preview / lint / render — Render in SKILL.md
- 网络端点: Declaring external network access: registry.npmjs.org (inferred): npx resolves or downloads hyperframes from the npm registry if not installed locally—standard tooling behavior
- 本地工作目录: File read/write and artifact output: compositions/*.html (scene sources, one file per scene) and shared tokens/components
Audit Notes: The skill directory contains only SKILL.md (pure instructions, no executable scripts, no network endpoints, no credentials). Its touchpoints are limited to the local CLI (npx hyperframes preview/lint/render via local headless browser rendering) and local disk I/O (compositions/, renders/, snapshots/), fully satisfying the criteria of invoking local tools/CLI only or local read/write only. No asset egress to external services: a full scan of this skill directory reveals no http(s):// endpoints, no fetch/requests calls, and no token/env variable reading. The only two aspects involving network access do not constitute asset leakage: ① npx resolving the CLI package (toolchain installation behavior driven by npx rather than an explicit documentation directive); ② output HTML pages referencing CDNs or web fonts loaded client-side by the browser (per classification guidelines, runtime output asset references do not affect skill tiering and are recorded in the reason only). All nine skills in this family share this evaluation baseline: SKILL.md-only directories, strictly local operations via CLI and file I/O, no endpoints, no credentials, and no external asset transmission.
5Second-Pass Verification
- [ok] 「无端点无凭证」是否成立 — 目录内正则扫描只命中 npx hyperframes 三条命令；无 http(s):// URL、无 token/env/cookie。父仓库 .gitignore 也把 .env 排除，属仓库层卫生，非本 skill 声明。
- [unlocatable] 渲染命令是否与 HyperFrames CLI 的真实用法相符 — 本仓未 vendored HyperFrames（README 明写 This repo does not vendor HyperFrames），pin 内无法核验 --composition/--output/--quality draft/--workers 这些参数是否与上游 CLI 一致；本次侦查为只读且不得运行渲染，故不验证，登记为待补。
- [ok] 「证明帧从渲染 MP4 抽取」在仓库层是否有落地工具 — scripts/extract_proof_frames.py 用 ffmpeg -ss <time> -i <video> -frames:v 1 -q:v 2 抽单帧，并可用 xstack 拼接触表；与本 skill 的要求（从渲染产物而非浏览器截图抽帧）一致。
- [discrepancy] 是否声明了 HyperFrames 的安装前提 — SKILL.md 直接给 npx hyperframes 命令，但未写 HyperFrames 的版本、安装方式或项目初始化要求（同族 end-to-end-video-playbook 也只把它当引擎名字）。用户需自行确保 CLI 可用，否则三条命令全部失败。
- [ok] 「预览与渲染的 CDN/字体差异」是否属可判级的外发 — 该条描述的是产物页在浏览器端拉取 CDN/字体（产物期引用），按风险范式不判级；本 skill 也把它写成需要注意的渲染风险而非流程中的联网步骤，故只记入 reason 与 risks，不升档。
- [ok] 组件清单是否真是约定而非强制的类 — SKILL.md 原文 These do not need to be formal JS classes. They can be CSS classes, HTML snippets, or helper functions as long as future agents can find and reuse them.——属约定而非 API，不存在「清单里的类未实现」这种缺口。
6Verdict & Scenarios
Best for: Suitable for: Scenarios where HyperFrames has already been selected as the rendering engine and HTML/CSS/JS scenes need to be built or modified—scaffolding compositions, authoring GSAP timelines, defining render commands, executing visual QA and proof-frame extraction, troubleshooting HyperFrames-specific issues like "preview passes but render fails", and handling selector isolation in multi-composition mounts.
Not for: Not suitable for: ① Cases where the rendering engine has not been decided or general web animations are required (use intake and design family skills first, or general frontend skills); ② Tasks requiring visual design systems and aesthetic judgments (use motion-design-systems); ③ Assembly, subtitling, audio mixing, or delivery acceptance workflows (use audio-sync-assembly / captions-and-music-bed / render-qa-and-surgical-changes); ④ Environments unable to install the HyperFrames CLI—all core capabilities of this skill (rendering and proof-frame validation) depend on it.
Install Agent-Ready
① Verified Mirror 2026-09-28
Option A · Direct DownloadDownload hyperframes-scene-builder.tar.gz
sha256:
Option B · Copy Guide for Agentb8691be00b4eea0e…Agents automatically download and verify mirrors from this JSON guide.
② Upstream GitHub
GitHub Repo ↗
Pinned to commit f6b043d9fd.