ext/hyperframes
2
0
Fork 0
mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-11 14:50:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor(skill): slim SKILL.md to step-pointer index, push to step files

Browse Source 
SKILL.md grew to 192 lines from a 124-line baseline. Most of the
bloat was content duplicated in the step reference files it points
to. Removed 6 sections that duplicated step content, composed 2
small additions into the step files where they actually belonged.

Removed from SKILL.md (already covered elsewhere):

- "Take your time" / "Quality matters more than speed" paragraph
  — operational philosophy already implicit in step-6-validate's
  cell-by-cell review prose.
- "Creative Tension Principle" section — step-3-storyboard.md:21
  already has the exact "What makes this video different from a
  generic [video type] for any [industry] brand?" single-sentence
  test. Duplicate removed; storyboard is the right home.
- "Step -1: What we're actually making" (30 lines: anti-patterns,
  video grammar, shot framing, camera moves) — duplicates step-3-
  storyboard.md:197+ (shot types), :229–232 (anti-patterns), and
  beat-builder-guide.md:126+ (shot framing).
- "Sub-agent mode" + "No sub-agents" preamble — step-5-build.md:286
  –292 already handles both parallel and serial runtimes.
- "Image-viewing capability" warning — operationally implicit in
  step-0 ("View the contact sheets") and step-6 ("View snapshots/
  contact-sheet.jpg cell-by-cell").
- "User Interaction Points" table — redundant with the inline 💬
  markers on Steps 3 and 4.

Composed into step files (content that wasn't there yet):

- step-1-design.md "Target length" paragraph: added the fast-pacing
  / billboard-per-beat exception (50-line DESIGN.md is enough when
  beats are single hero elements on full-bleed backgrounds, not
  full UIs).
- step-2-brief.md "Surprise me" section: added the global-propagation
  rule — when the user signals autonomous mode at Step 2, every 💬
  gate downstream (Step 3 storyboard approval, Step 4 TTS choice) is
  also skipped.

Step 5 SKILL.md gate paragraph trimmed from a 6-clause description
of the per-beat read to one line that points at step-5-build.md
for the full checklist.

Updated the techniques.md reference counts from "20" to "13" in
SKILL.md, beat-builder-guide.md, and step-3-storyboard.md to match
the techniques.md trim in the upstream branch.

Net: SKILL.md 192 → 131 lines.
This commit is contained in:
ukimsanov
2026-05-21 11:08:51 -07:00
parent 051c9c9de4
commit 7093ee900b
5 changed files with 10 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/website-to-hyperframes/SKILL.md
+4 -65
View File
@@ -6,31 +6,7 @@ description: |
# Website to HyperFrames
Capture a website, then produce a professional video from it — collaboratively with the user.
**Take your time on thinking and reviewing.** Quality matters more than speed. Read every reference file the steps point to. Look at every snapshot carefully. If a composition looks weak, revise it before moving on. A polished video is worth more than a rushed one delivered 5 minutes faster. That said: don't sit idle on stuck commands — escalate immediately if a process hangs (see Step 4 for escalation order).
**This is a collaborative workflow by default.** At key moments (marked 💬), you stop and ask the user what they want and refine based on their feedback.
**Autonomous mode exception:** If the user says "decide for me", "just build it", "surprise me", or gives any signal they don't want to be asked questions — skip ALL 💬 gates. Make all creative decisions yourself (video type, style, voice, storyboard), and present the finished result for feedback at the end. Do not ask four separate questions across four separate steps. Read the room once and commit.
**Sub-agent mode (default):** Step 5 dispatches one sub-agent per beat. Each sub-agent reads [beat-builder-guide.md](references/beat-builder-guide.md), builds, lints, snapshots, and verifies its own beat before reporting back. The main agent assembles the final video and does a final check.
**No sub-agents:** If the user says "no sub-agents", "build it yourself", or the runtime doesn't support parallel agents — the main agent builds all compositions sequentially using the same beat-builder-guide workflow. Same quality, just slower.
**This skill requires image-viewing capability** for the validate step (Step 6). If your agent cannot view PNG files, the snapshot review will be blind. Contact sheets (Step 0 and Step 6) are designed to minimize the number of images needed — but some visual verification is unavoidable.
---
## The Creative Tension Principle
Before writing the first beat of any storyboard, answer this in one sentence:
> **"What makes this video different from a generic [video type] for any [industry] brand?"**
If you can't answer it, you haven't thought enough. A product demo for a fintech tool and a product demo for a design tool should not share the same visual DNA. The answer comes from this specific brand's captured assets, its visual language, and what the user said they want — not from a lookup table.
This principle applies at every creative decision point: picking a visual style, choosing transitions, writing beats, building compositions. Every choice should be traceable to something specific about this brand, not just to "this is what I do for cinematic videos."
Capture a website, then produce a professional video from it.
Users say things like:
@@ -38,36 +14,7 @@ Users say things like:
- "Turn this website into a 15-second social ad for Instagram"
- "Create a 30-second product tour from https://..."
---
## Step -1: What we're actually making (REQUIRED before Step 0)
You're not making _a video_. You're making something that **stops scrollers** in the first 1.5 seconds and **feels alive in every single frame** — with motion, depth, momentum, like things exist in a physical world. **Think about how to go viral.** Slow intros are for cinematic trailers; videos shipping anywhere social or feed-based need a hook that beats the 1.5-second scroll threshold.
**Use the captured assets.** Open every SVG in `capture/assets/svgs/`. Open every illustration in `capture/assets/`. Read the descriptions in `capture/extracted/asset-descriptions.md`. Many of these will carry beats outright — the brand logo SVG drawing itself stroke-by-stroke, the hero illustration breathing as ambient depth, the captured gradient as a full-bleed background, the brand mark stamped onto every scene as identity. These are video gold. The capture exists because the brand's actual visual identity matters; using it is what makes the video feel like _this_ brand and not a generic dark cinematic template.
**Compose when there's no captured asset that fits.** For product UI sections where a clean captured asset doesn't exist (kanban boards, chat threads, dashboards, terminals, counters, code editors), build them from divs/SVG/CSS rather than pasting a screenshot. SVG path drawing, kinetic typography, counter animations via `tl.set()`, layered panels, shader-driven gradients — these are all part of HyperFrames' toolkit when no captured asset earns the beat.
**The screenshot trap is specifically about raw product-UI screenshots being pasted as full-bleed beat content.** Captured SVGs, illustrations, logos, hero art, gradients, photography — none of these are screenshots. They're brand assets. Use them. The trap is the "full-bleed dashboard.png + Ken Burns + voiceover" slideshow pattern, not the careful use of captured brand artifacts.
**This is a VIDEO, not a webpage rebuilt in divs.** Composing from divs is the right _medium_ (no screenshots) — but the WRONG outcome is to build a webpage-style layout and animate it 2 pixels. Videos use cinematic grammar: framing, depth, camera movement, scale, atmosphere. A kanban in a video is not "a kanban board centered in the frame at 80% scale with cards breathing 1px" — it's a SHOT: extreme close-up on a card sliding home, then the camera pulls back to reveal the full board, ambient particles + glow + depth give it weight. The composed divs are the subject; the cinematography is what makes it feel like film.
**Specific anti-patterns to refuse, every time:**
- **macOS window chrome** (traffic-light dots, address bars, browser tabs, breadcrumbs) unless the beat IS about the window/browser as the subject
- **Centered layout with chrome around it** — sidebar + header + content area + footer — that's a screenshot reproduced in CSS, not a shot
- **"Breathing" micro-animations** (y: ±1–2px, scale: 1.01) — invisible at 1080p/4K video scale, useless as motion, a sign the sub-agent ran out of ideas
- **Page-level navigation** — sidebars, headers, footers, breadcrumbs, "back" arrows unless the beat is specifically demonstrating navigation
- **"Settled" beats** where nothing moves except a counter pulse — every beat must have continuous, _visible_ motion across the entire duration
**Video grammar to USE in every beat:**
- **Frame the beat as a SHOT** — close-up / medium / wide / over-the-shoulder / Dutch angle. Pick deliberately, not "centered."
- **Camera motion is a primary element** — dolly in, push, parallax pan, orbit, pull-back. The camera moves THROUGH the composition; the composition doesn't sit still in front of the camera.
- **Scale as energy** — enter at 1.4× and settle to 1.0; extreme close-up that pulls back to wide; the subject grows or shrinks through the beat
- **Depth layers** — ambient background atmosphere, focal midground subject, accent foreground element — each moving at different parallax speed
- **Light as choreography** — glow tracks the subject, key moments lit with bloom, transitions happen through light shifts
- **Real motion magnitudes** — 30–100px movements, 0→1 opacity reveals, 0.7→1.0 scale changes — values that READ at video scale. Tiny micro-movements feel like a still image with twitches.
The workflow has 7 steps. Each produces an artifact that gates the next. By default it's collaborative — gates marked 💬 stop and ask the user. If the user signals autonomous mode ("decide for me", "surprise me"), every 💬 gate is skipped; see step-2-brief.md for how that propagates.
---
@@ -130,7 +77,7 @@ If Step 2 said no narration — ask about background music, then skip to Step 5.
Build index.html and compositions following the architecture and pacing chosen in the storyboard (Step 3). Sub-agents run `hyperframes lint` and `hyperframes snapshot` on each beat before reporting back.
**Gate:** **The main agent does NOT trust sub-agents' chat reports.** After every sub-agent completes, the main agent opens each `compositions/beat-N.html` and reads it top-to-bottom. For each beat: does the GSAP timeline use the data attributes correctly, do the brand colors from DESIGN.md actually appear in the CSS, are the captured assets the storyboard called for actually referenced, is the headline at video-readable size, does the beat serve the storyboard arc? Anything off — fix it inline or re-dispatch the sub-agent with the specific problem quoted.
**Gate:** Every `compositions/beat-N.html` has been read top-to-bottom by the main agent against DESIGN.md and STORYBOARD.md. The per-beat checklist lives in [step-5-build.md](references/step-5-build.md).
---
@@ -168,14 +115,6 @@ Beat count is not in this table intentionally — it should come from the storyb
- **Portrait**: 1080x1920 (Instagram Stories, TikTok)
- **Square**: 1080x1080 (Instagram feed)
### User Interaction Points
| Step | What to ask | Why |
| ---------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Step 2 (Strategy) | Message, narrative arc, audience, video type, style, format | The story is what every downstream choice flows from. Without it, beats are arbitrary. |
| Step 3 (Storyboard + Script) | Beat-by-beat approval, script review | Cheapest place to iterate. 30s to change a beat, 5min to rebuild a composition. |
| Step 4 (VO) | TTS provider choice, API key if needed | Voice quality makes or breaks the video. User may have provider preferences. |
### Reference Files
| File | When to read |
@@ -188,5 +127,5 @@ Beat count is not in this table intentionally — it should come from the storyb
| [step-4-vo.md](references/step-4-vo.md) | Step 4 — TTS provider choice, generation, timing |
| [step-5-build.md](references/step-5-build.md) | Step 5 — build index.html + compositions |
| [step-6-validate.md](references/step-6-validate.md) | Step 6 — lint, validate, snapshots (scaled to video length), preview |
| [techniques.md](../hyperframes/references/techniques.md) | Steps 3 & 5 — 20 visual techniques with code patterns (adapt, don't copy-paste) |
| [techniques.md](../hyperframes/references/techniques.md) | Steps 3 & 5 — 13 primitive animation techniques with code patterns (adapt, don't copy-paste) |
| [html-in-canvas-patterns.md](../hyperframes/references/html-in-canvas-patterns.md) | Step 5 — complete code patterns for HTML-in-Canvas effects (lives in the hyperframes skill) |