Communitygithub.com

Elis3omndz/Claude_Skills

HyperFrames 合成合约 — 构建一个可渲染的项目。用于合成结构、`data-*` 时序属性、`class="clip"`、轨道、子合成、变量、框架管理的媒体播放、确定性渲染规则以及验证。在编写合成 HTML 之前阅读。

Claude_Skills 是什么?

此技能定义了 HyperFrames 框架的技术合约,该框架通过 HTML DOM 属性(如 `data-*` 属性、`class="clip"` 和 `data-composition-id`)声明式地生成视频。它指导开发者构建一个可查找、可确定性渲染的 HTML 合成文件,其中框架完全拥有媒体播放、动画时间轴和子合成。该技能适用于所有 HyperFrames 项目形态(独立或子合成),并支持在 Cursor 等 AI 编程工具中通过引用`/references` 下的参考文件和相邻领域技能(如 `hyperframes-animation` 和 `hyperframes-creative`)来实施。与 `hyperframes-cli` 配合使用进行验证,它强制实施一套严格的规则,以防止常见的布局和动画陷阱(例如 `gsap_css_transform_conflict`、`media_crossorigin_breaks_preview`),并确保可预测的渲染和回放。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Elis3omndz/Claude_Skills/tree/HEAD/.claude/skills/hyperframes-core

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

插件安装: 在运行设置或更新命令之前,如果此技能位于 HyperFrames 插件内部,请遵循 插件执行规则。独立安装则保留以下更新说明。

HyperFrames Core

Agent 陷阱(先阅读):

  • 使用 flex/inset 居中,而不是在一个节点上使用 CSS transform: translate(-50%,-50%) 然后通过 GSAP x/y 动画。Lint:gsap_css_transform_conflict。使用 fromTo 或 xPercent/yPercent。
  • 不要添加场景退出 tl.set(..., {visibility:"hidden"})。运行时已经隐藏了定时片段。对内部节点(或 .clip 上的 opacity)进行不透明度渐变就足够了。字幕硬性终止是另一条规则。
  • window.__timelines["id"] 必须与根元素的 data-composition-id 相匹配。
  • 在 render 之后,阅读摘要的第二行:beginframe vs screenshot、GPU 模式、阶段时序。screenshot + software gpu 在 Linux 上是慢路径。

HyperFrames 从 HTML 渲染视频。合成是一个 HTML 文件,其 DOM 使用 data-* 属性声明时序,其动画运行时可查找,并且其媒体播放由框架管理。

此技能是技术合约——如何构建一个 hyperframes 项目。以下是构建指南;每个主题的详细信息位于 references/(索引如下),按需阅读。流程文档(简报、故事板、评审、制作、调度、帧工)位于 /hyperframes → references/。其他关注点位于同级领域技能中——hyperframes-animation、hyperframes-creative、media-use、hyperframes-cli、hyperframes-registry。/hyperframes 中的能力映射说明了每个技能涵盖的内容。

参考

文件阅读目的
references/minimal-composition.md从最小可渲染合成骨架开始
references/composition-patterns.md选择整体式与模块化;构建模块化 index.html;选择子合成原型
references/data-attributes.md查找任何 data-*(根/片段/子合成宿主/遗留别名);使用 class="clip"
references/tracks-and-clips.md了解 data-track-index 的作用(和不作用)、z-index、相对于另一个片段的时间;使用 npx hyperframes timeline 列出每个轨道和片段
references/creator-editing-recipes.md复制真实的剪切/修剪/重新排序/重新定时/冻结/摄像机/遮罩/交叉淡入淡出/音频编辑配方及其限制
references/sub-compositions.md连接子合成(宿主属性、<template>、每个实例变量)并在其内部进行动画
references/variables-and-media.md声明变量;放置 <video>/<audio>、设置音量、修剪
references/determinism-rules.md构建可查找的时间轴;确定性禁止项;布局/文本适配
references/full-screen-motion.md使用共享背景创作全帧运动
references/tailwind.md在 Tailwind v4 项目中使用(init --tailwind;运行时合约与 Studio 的 v3 不同)

有关动画运行时细节(GSAP API、Lottie、Three.js 等),请参阅 hyperframes-animation → adapters/<runtime>.md。

构建合成

两种根形式(不可互换)

  • 独立(顶级 index.html):根元素 <div data-composition-id="…"> 直接位于 <body> 中,没有 <template> 包装器。包装独立的根元素会隐藏所有内容,并且 lint 会拒绝它(standalone_composition_wrapped_in_template,错误)。
  • 子合成(通过 data-composition-src 加载):将根元素包装在 <template> 中。这是要编写的形式:加载器也接受纯完整文档并回退到其 <body>,但示例和工具假定的是模板形式。

⚠ 传输规则:对于模板化的子合成,组装器会删除文件自身的 <head> <style>/<script>(packages/core/src/compiler/compositionAssembly.ts,hasTemplate 门),因此将 <style>/<script> 放在模板内部。<link> 始终被提升。 ⚠ 宿主 ID 约定:给予宿主插槽、内部模板和 window.__timelines["<id>"] 键相同的 id。支持不同的本地 id(组装器会回退到文件中的第一个根元素),但不匹配是静默的,因此请匹配它们,除非你有理由不这样做。

文件形状、宿主连接和预渲染检查清单 → references/sub-compositions.md。

根元素必须设置大小(静默布局错误)

独立的根元素使用 width/height: 100%。画布大小是 data-width/data-height。运行时将这些像素值应用到合成根元素上。不要在 #root 上硬编码 1920px/1080px。骨架 → references/minimal-composition.md。

一个暂停的时间轴

每个合成都注册恰好一个 gsap.timeline({ paused: true }) 在 window.__timelines["<id>"] 处(键 = 根元素 data-composition-id)。在异步回调(document.fonts.ready)内构建它是支持的;重要的是你仅在构建完成后注册。渲染长度是根元素的 data-duration,而不是时间轴的长度:运行超过它的时间轴会被截断,而提前结束的时间轴会保持其最后一帧。省略根元素 data-duration 则长度改为推断(时间轴、媒体窗口或适配器)。你不需要 window.__timelines = window.__timelines || {}:运行时在你的内联脚本运行之前创建注册表,并且 lint 不再要求它。不要手动将子时间轴嵌套到宿主中;运行时会自动嵌套已注册的子时间轴。完整合约(包括非 GSAP 运行时)→ references/determinism-rules.md + hyperframes-animation/adapters/。

首次 lint 陷阱(保证首次构建失败)

lint 确实会捕获的规则,但仅在事后。第一次就正确编写它们:

  • 永远不要将 CSS 初始值 transform 与 GSAP 对同一属性的补间动画配对——CSS 值和补间的起始值会冲突,并且 lint 会以 gsap_css_transform_conflict 拒绝它。使用 gsap.fromTo(el, { x: -40 }, { x: 0 }) 在补间内设置初始状态,而不是使用 CSS transform: translateX(-40px)。
  • 永远不要在 <video>/<audio> 上放置 crossorigin。lint 会无条件地以 media_crossorigin_breaks_preview(错误)拒绝它,包括用于 canvas/WebGL/WebAudio 回读。没有抑制方法。
  • 永远不要让 <video data-start> 有一个也携带 data-start 的祖先。lint 会以 video_nested_in_timed_element(错误)拒绝它。对包装器或视频进行定时,而不是两者都定。
  • 每个 <audio> 都需要一个 id。lint 会以 media_missing_id 拒绝它,并且没有 id 的 <audio> 永远不会被混音器拾取,因此渲染是静默的。
  • 永远不要对 .clip 使用 autoAlpha 或 visibility 进行补间——lint 会以 gsap_animates_clip_element 拒绝它。改为对子元素进行动画。
  • 命名的 CSS font-family 需要一个文件内的 @font-face 指向一个已提供的本地文件,否则 lint 会触发 font_family_without_font_face。
  • 子合成 #root 使用 width/height: 100%(或 inset: 0),而不是硬编码的 1920px/1080px。画布大小是 data-width/data-height。

lint 错误还会关闭布局和对比度审计:check 随后报告 0 sample(s) 和 0/0 text checks,这看起来像是一个干净的文件,但意味着没有运行任何检查。在信任这些数字之前清除 lint 错误。

不可协商的规则(自动化门可能遗漏的静默错误)

在此处列出;完整理由请参见链接的参考。不要违反:

  • 无渲染时时钟/未播种的 Math.random/网络/输入状态;repeat: -1 仅在有限的根元素 data-duration 下(导出片段到它——否则使用有限计数)。→ determinism-rules.md
  • 永远不要对 .clip 元素使用 display、visibility 或 autoAlpha 进行补间。框架拥有片段可见性,并且 lint 会拒绝它(gsap_animates_clip_element)。改为对子元素进行动画。→ determinism-rules.md
  • 正文文本中无 <br>;变换后的元素必须是块级并设置尺寸;脉动的绝对定位装饰元素需要峰值间隙。→ determinism-rules.md
  • <video>/<audio> 通过扁平文档查询找到,因此框架在任何嵌套深度(包括在子合成 <template> 或包装器内)查找和解码它们。一个硬性限制:如果 <video data-start> 位于另一个也带有 data-start 的普通元素内部,lint 会报错,并且失败是真实的(错误的源帧,然后片段在中间消失),因此将定时放在包装器或视频上,绝不要同时放在两者上。子合成宿主是例外的:子合成内的媒体可以正确渲染。另一个注意事项是时间轴,而不是放置位置:子合成时间轴不能对宿主根元素进行动画。→ variables-and-media.md
  • 保持每个 id 在组装后的页面中是唯一的(为子合成 id 添加前缀,如 #<id>-hero),以便你自己的 #id CSS 和 getElementById 调用能够解析。帧注入不再依赖于此:编译器在每个 video[src]/audio[src]/img[src] 上打上文档唯一的 data-hf-render-id。使用 <source> 子元素而不是 src 属性的媒体不会被打上标记,因此唯一的 id 在那里仍然重要。→ composition-patterns.md
  • 合成根元素的全屏填充在正常渲染中是没问题的。它仅在分层合成路径(HDR 内容,或使用着色器转换的合成)上被丢弃,在该路径中,引擎强制每个合成根元素透明,以便下面的图层显示出来。如果你的合成使用着色器转换或 HDR 媒体,请将填充放在一个全出血的子元素上(position:absolute; inset:0)。→ composition-patterns.md

编辑现有合成

  • 先读取文件。保留不相关的时序、轨道、ID、变量、媒体路径。
  • 要知道项目时间轴上有什么(轨道、片段、开始、结束、播放的内容),请运行 npx hyperframes timeline [--json],而不是读取 index.html 和每个子合成文件。
  • 匹配现有的合成 ID 和时间轴键。
  • 添加片段:有意地根据周围的片段设置其 data-start/data-duration。data-track-index 是 Studio 的显示通道,不是时序约束,因此不需要空闲。
  • 在根元素 data-duration 之后结束的片段会被截断:在同一个编辑中将根元素 data-duration 延长到片段的结束位置(lint 会发出 clip_ends_past_root_duration 警告)。
  • 任何合成元素上的 data-hidden 在预览和渲染中都会隐藏它,覆盖其时间窗口;它是非破坏性/可逆的,并由 Studio 的时间轴眼睛图标切换。
  • 添加子合成:在连接宿主之前验证其内部的 data-composition-id。

验证

使用 hyperframes-cli 了解命令详情

  • npx hyperframes check 通过(在 lint、运行时、布局、运动和对比度方面没有发现任何问题)
  • 包含子合成的项目:npx hyperframes snapshot --at <midpoints> 并目视检查每一帧
  • npx hyperframes preview --background 用于评审(用户可以在 Studio 的时间轴中编辑任何内容,并且服务器在调用命令后仍然存活)
  • 仅在用户批准后执行 npx hyperframes render

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

Elis3omndz/Claude_Skills

Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet `anchor` rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.

Elis3omndz/Claude_Skills

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

Elis3omndz/Claude_Skills

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

Elis3omndz/Claude_Skills

Use when audio already placed in a HyperFrames composition needs to be mixed: fade-in/fade-out, crossfade, track gain or volume, volume automation, ducking, a music bed that fights a voiceover (voiceover carve), effects on a track (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), automation envelopes drawn on a track's volume or any effect parameter, or one submix bus carrying a chain, a fader and an automation clock for several tracks at once (`<hf-audio-group>`). Don't use for sourcing or generating audio — finding BGM, SFX, or making a voiceover is `/media-use`. Don't use for clip timing or track layout, which is `/hyperframes-core`.

Elis3omndz/Claude_Skills

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

Elis3omndz/Claude_Skills

Use when a HyperFrames composition needs a punch-in, punch-out, zoom, reframe, Ken Burns treatment, camera move, visual match/whip handoff, or other seek-safe 2D/3D keyframes; also for GSAP, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth, or `hyperframes keyframes` diagnostics. Don't use for broad scene strategy, brand design, media sourcing, captions, or general video planning.

Elis3omndz/Claude_Skills

Use when working with a person on a HyperFrames project in Studio: first, whether their message asks for a change at all (questions, loose ideas and "don't change anything" get an answer and a plan, not an edit); for a new film, the plan, storyboard and build order that the HyperFrames launch films follow; and how the timeline should be laid out so it reads well (one caption track, one element kind per track, every scene a sub-composition) and where captions and key content may sit (safe zones). Don't use for how to perform an individual edit (split, trim, retime, volume, copy, swap): that is `creator-editing-recipes.md` in `/hyperframes-core`.

Elis3omndz/Claude_Skills

A short, design-led motion graphic where motion is the message — kinetic typography, stat count-up, chart/data-viz hit, logo sting / brand lockup, lower-third / callout / social overlay, animated map (highlight regions, connect places, zoom to a location), animated tweet / news-article / headline, webpage / UI animation (scroll, cursor, callouts), or fusing a real image's geometry into a chart. Usually under 10s (up to ~30s), no narration or live-action subject; renders to MP4 or transparent overlay. Longer / narrated / multi-scene → /general-video. Unclear → /hyperframes.

Elis3omndz/Claude_Skills

Turn a music track (an audio file, a video to pull audio from, or a track generated from a mood brief) into a beat-synced video — lyric video, slideshow, or kinetic promo. The music drives all pacing; any user-supplied images/videos are cut onto the same beat grid, and a complete video needs zero assets. Narrated pieces → the input-matched workflow (see /hyperframes). Unclear → /hyperframes.

Elis3omndz/Claude_Skills

Turn a product or marketing URL, pasted script, or brief into a product launch / promo video — SaaS promos, feature reveals, product demos, app and company launches. Use when the user wants to market, launch, promote, or reveal a product; the default for any commercial URL. Site tours / showcases of a website route here too — the brief carries the show-it-as-is intent. Unclear → /hyperframes.

Elis3omndz/Claude_Skills

Turn a GitHub pull request (a PR URL, owner/repo#N, or 'this PR' in a checked-out repo) into a code-change explainer video — changelog, feature reveal, fix, or refactor walkthrough built from the diff, commits, and files: the input is a code change, not a website. Not a product promo (/product-launch-video) or a no-PR topic explainer (/faceless-explainer). Unclear → /hyperframes.

相关技能