Communitygithub.com

Elis3omndz/Claude_Skills

HyperFrames 合成合約 — 建立一個可渲染的專案。用於合成結構、`data-*` 時間屬性、`class="clip"`、時間軌、子合成、變數、框架擁有的媒體播放、確定性渲染規則與驗證。在撰寫合成 HTML 前請先閱讀。

Claude_Skills 是什麼?

此技能定義了 HyperFrames 的技術合約,HyperFrames 是一個可從 HTML 渲染影片的框架。它詳述了如何構建一個「合成」——一個使用 `data-*` 屬性宣告時間的 HTML 檔案,並擁有可搜尋的動畫運行時,且媒體播放由框架控制。開發者將學到兩種根形式(獨立式與子合成式)、註冊暫停時間軸的關鍵規則、以及 lint 與運行時強制執行的非協商性規則,以避免如 CSS 與 GSAP 轉換衝突、巢狀計時媒體或動畫化 `.clip` 元素等常見陷阱。它也解釋了透過 `data-composition-id` 管理 ID 與時間軸鍵值、使用 `data-start`/`data-duration` 編輯既有合成、以及使用 `npx hyperframes` CLI 指令進行驗證。此技能支援 Claude Code、Cursor、Codex 等代理,並假設用戶熟悉 GSAP 動畫、Tailwind CSS 與命令列工具。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

外掛安裝: 在執行 setup 或 freshness 指令前,當此技能位於 HyperFrames 外掛中時,請遵循外掛執行規則。獨立安裝則保留下方更新說明。

HyperFrames 核心

代理陷阱(優先閱讀):

  • 使用 flex/inset 置中,不要在後續 GSAP x/y 動畫的節點上使用 CSS transform: translate(-50%,-50%)。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 模式、階段時間。Linux 上的 screenshot + software gpu 是慢速路徑。

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選擇整體式 vs 模組化;結構化模組化 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 回讀的情況。沒有抑制方法。
  • 永遠不要給一個帶 data-start 的 <video> 一個也帶有 data-start 的祖先。lint 會以 video_nested_in_timed_element(錯誤)拒絕它。計時要嘛在包裝元素上,要嘛在影片上,不能兩者皆有。
  • 每個 <audio> 都需要一個 id。lint 會以 media_missing_id 拒絕它,而且沒有 ID 的 <audio> 永遠不會被混音器拾取,因此渲染會是靜音的。
  • 永遠不要使用 autoAlpha 或 visibility 補間 .clip — 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 前綴,例如 #<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、運行時、版面配置、動畫和對比度中皆為 0 個發現)
  • 包含子合成的專案: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.

相關技能