anton-abyzov/vskill

/remotion-best-practices

Verwenden Sie diesen Skill immer dann, wenn Sie eine Remotion-Komposition schreiben – animierte Demo-Videos, Produkt-Walkthroughs, Hackathon-Einreichungen, erzählte Präsentationen – alles, was über npx remotion render in MP4 gerendert wird.

Der Skill bündelt zwei Wissensebenen:

1. Remotion-Grundlagen – die offiziellen Regeldateien des Remotion-Teams unter github.com/remotion-dev/skills (Kompositionen, Animationen, Schriftarten, Audio, Übergänge, FFmpeg, Untertitel, etc.).
2. Regeln für Demo-Video-Handwerk – Erkenntnisse aus einem langen Iterationszyklus beim Erstellen der vskill / Skill Studio Hackathon-Demo. Dies sind die Regeln, deren Verletzung zu einer „Diashow“ anstelle eines glaubwürdigen Produkt-Walkthroughs führt.

Lesen Sie beide Ebenen, bevor Sie mit dem Schreiben beginnen.

---

Umfang und Anwendbarkeit

Die Level-2-Handwerksregeln unten wurden aus einem bestimmten Projekt abgeleitet: der vskill / Skill Studio Hackathon-Demo (Anthropic / Claude Code „Built with Opus“ Hackathon, April 2026). Sie spiegeln das Erscheinungsbild dieses Produkts wider – Studio-Chrome mit Breadcrumb-Kopfzeile, Seitenleistenbaum, dunklen verified-skill.com-Seiten mit serifenloser Schrift, Terminalszenen, einer These „Inter ist KI-Schrott, eine unverwechselbare Serife ist Exzellenz“.

Wenden Sie diese Regeln nicht wörtlich auf nicht verwandte Demos an. Eine Consumer-Mobile-App, ein Finanz-Dashboard, ein Spiel oder eine B2B-SaaS-Präsentation wird ihre eigene visuelle Sprache, ihr eigenes Tempo und ihre eigenen Zielgruppenerwartungen haben. Ein „Speichern-dann-Veröffentlichen“-Ablauf, eine verified-skill.com/queue-Seite oder eine Studio-Seitenleiste mit PROJECT/PERSONAL/PLUGINS-Zählern ist Inhalt, nicht Handwerk.

Verwenden Sie diese Ebene als Referenz für die zugrunde liegende Technik: das Kamera-Zoom-Muster, die Cursor-Ziel-Disziplin, das inhaltsbündige Hervorhebungsrechteck, die Zustandsübergänge an Ort und Stelle, die Voiceover/script.ts-Kopplung, die Render+Audio-Boost-Pipeline – diese verallgemeinern sich. Die genauen Konstanten (1,72× Zoom, x=1488 Schaltflächenmitte, v1.0.0 → v1.0.1 Versions-Pill, „Tier-1-Muster · Tier-2-LLM · Socket“ Zuordnung) sind Skills Studio-spezifisch – übersetzen Sie, kopieren Sie nicht.

---

Ebene 1 – Remotion-Grundlagen

Spiegelt den upstream remotion-best-practices-Skill unter https://github.com/remotion-dev/skills/blob/HEAD/skills/remotion/SKILL.md wider.

Neues Projekt einrichten

Wenn Sie sich in einem leeren Ordner oder Arbeitsbereich ohne vorhandenes Remotion-Projekt befinden, erstellen Sie eines mit:

npx create-video@latest --yes --blank --no-tailwind my-video

Vorschau starten

Starten Sie das Remotion-Studio, um ein Video in der Vorschau anzuzeigen. Das Studio-HMR lädt bei Dateiänderungen neu – Sie benötigen KEINEN separaten preview_start-Mechanismus, und Bash run_in_background ist der richtige Weg, um es über Änderungen hinweg am Leben zu erhalten.

npx remotion studio --port=3030

Rendern

# Einstiegspunkt muss die Datei sein, die registerRoot() aufruft (normalerweise src/remotion/index.ts)
npx remotion render src/remotion/index.ts <CompositionId> out/video.mp4 --concurrency=8 --log=info

Häufige Fallstricke:

• Übergabe von Root.tsx als Einstiegspunkt → Fehler: "Diese Datei enthält kein registerRoot". Verwenden Sie index.ts.
• TransitionSeries führt Eigenschafts-Introspection bei direkten Kindern durch; umwickeln Sie Kinder NICHT mit <React.Fragment>. Verwenden Sie flatMap, um ein flaches Array von <TransitionSeries.Sequence>- und <TransitionSeries.Transition>-Elementen zurückzugeben.
• interpolate(frame, [a, b], …) erfordert strikt a < b. Wenn Sie b aus Konstanten ableiten, überprüfen Sie dies bereits beim Entwurf des Szenenbudgets – Remotion wirft "inputRange must be strictly monotonically increasing" beim allerersten ausgewerteten Frame und die gesamte Komposition kann nicht geladen werden.

Einzelframe-Render-Prüfung

npx remotion still <composition-id> --scale=0.25 --frame=30

Von den offiziellen Regeldateien abgedeckte Themen

(Laden Sie bei Bedarf aus dem offiziellen Skill-Repository – github.com/remotion-dev/skills/tree/HEAD/skills/remotion/rules/.)

• compositions.md – Definieren von Kompositionen, Standbildern, Ordnern, Standard-Eigenschaften, dynamischen Metadaten
• animations.md – interpolate, spring, Easing, frame-basierte Mathematik
• transitions.md – @remotion/transitions (Ein-/Ausblenden, Schieben, Wischen), wie man sie in TransitionSeries verkettet
• assets.md – staticFile(), Img, Audio, Video, Schrifteinbindung
• fonts.md – @remotion/google-fonts und lokale Schriftartregistrierung
• audio.md – Importieren, Trimmen, Lautstärke, Geschwindigkeit, Tonhöhe
• captions.md, subtitles.md – Untertitelspuren und Synchronisation
• ffmpeg.md – Trimmen, Zusammenfügen, Audio-Operationen via FFmpeg-Aufruf
• silence-detection.md, extract-frames.md, get-audio-duration.md, get-video-duration.md – Mediabunny-Dienstprogramme
• charts.md, gifs.md, light-leaks.md, 3d.md – Spezialisierte Rendering-Rezepte

---

Ebene 2 – Demo-Video-Handwerksregeln

Dies sind die Regeln, die über einen langen Iterationszyklus erarbeitet wurden. Behandeln Sie sie als Standardeinstellungen, nicht als optionalen Feinschliff – die meisten von ihnen stammen aus "das sieht komisch aus, behebe es"-Rückmeldungen, die mehrere Runden zur Lösung benötigten.

A. Referenztreue

A1. Holen Sie sich immer die echte Referenz

Wenn der Benutzer sagt "mach es wie bei 2:43 in diesem YouTube-Video", extrahieren Sie den Frame und studieren Sie ihn. Nähern Sie sich nicht aus dem Gedächtnis an.

QUELLE="/Users/antonabyzov/Movies/.../Source.mov"
ZIEL_VERZ=".specweave/.../assets/keyframes"
for t in 102 105 108 110 112; do
  ffmpeg -y -ss "$t" -i "$QUELLE" -frames:v 1 -q:v 2 "$ZIEL_VERZ/at-${t}s.jpg" -loglevel error
done

Lesen Sie dann jedes JPG und gestalten Sie basierend auf dem, was tatsächlich auf dem Bildschirm zu sehen ist – Typografie, genaue Schaltflächenbeschriftungen, Badge-Farben, Seitenleistenbaum-Layout, Position des Suchfelds, Zählwerte (z. B. PROJEKT (1), PERSÖNLICH (0 von 12), PLUGINS (0 von 50), VERFÜGBAR (62)).

A2. Verwenden Sie echte Logos und Symbole, keine Näherungen

• Glocken-Badge skill-studio-logo.png – kopieren Sie es in jede Studio-Szene als <Img src={staticFile("...")} />. Rendern Sie kein ✷-Zeichen und nennen Sie es ein Logo.
• Anbieter-Symbole – holen Sie sich das echte SVG/PNG für Claude, Anthropic, OpenAI, OpenRouter, Ollama, LM Studio (z. B. von lobehub/static-png). Ersetzen Sie es nicht durch Emojis.
• Maskottchen – zeichnen Sie sie mit gestalteten Divs, um die Form genau zu treffen. Das Claude-Code-Maskottchen hat einen pfirsichfarbenen #e08160-Körper mit zwei quadratischen Augen, zwei seitlichen Hand-Noppen auf Körpermitte und zwei Beinpaaren darunter (▪ ▪ ▪ ▪). Keine ASCII-Kunst.
• App-Fenster-Chrome – wenn Sie eine Website in einem "Chrome-Browser" zeigen, rendern Sie einen echten Chrome-Browserrahmen: abgerundete Ecken, Verkehrslicht-Punkte, ‹ › ↻ Navigation, gesperrte Vorhängeschloss-URL-Leiste mit einer echten URL (localhost:3000/hero, keine zusätzlichen Leerzeichen, kein Mittelpunkt).

A3. Gleichen Sie YouTube-Referenzlayouts Pixel für Pixel ab

Bevor Sie eine Szene aus der Vorstellungskraft neu gestalten, listen Sie die sichtbaren Elemente im Referenz-Frame auf und überprüfen Sie jedes gegen Ihre Ausgabe:

• Bannertext – genaue Wortwahl (Fähigkeiten zur Überprüfung einreichen, nicht Reiche eine Fähigkeit ein)
• Tab-Reihenfolge – Übersicht · Bearbeiten · Tests · Ausführen · Auslöser · Versionen
• Vertrauensabzeichen – T1 UNGESCANNT, Sicherheitsscan –, Vertrauenswürdiger Herausgeber
• Filtereingabe – immer über VERFÜGBAR in der Seitenleiste
• Zählungen – halten Sie sie über Folien hinweg konsistent (PERSÖNLICH (0 von 12) überall, nicht (11) auf einer Folie und (0 von 12) auf einer anderen)
• Kopfzeilen-Steuerelemente rechts (in dieser Reihenfolge): 🔍 Fähigkeiten finden [⌘K] · + Neue Fähigkeit · ● Modellauswahl · 🔔 Glocke

B. Kamera-Zoom

B1. Kamera-Zoom ist vollflächig, nicht abschnittsskaliert

Skalieren Sie nicht ein einzelnes Panel innerhalb des Chrome. Wickeln Sie das gesamte Chrome (obere Leiste + Körper) in ein Transform-Div und skalieren + verschieben Sie dieses:

<div
  style={{
    width: "100%",
    height: "100%",
    transform: `translate(${cameraTx}px, ${cameraTy}px) scale(${cameraScale})`,
    transformOrigin: "50% 50%",
    willChange: "transform",
  }}
>
  {/* OBERE LEISTE + KÖRPER */}
</div>

Cursor + Klick-Wellen-SVGs gehen innerhalb dieses Wrappers, damit sie mit dem Chrome skalieren und an ihrem Ziel kleben bleiben.

B2. Zuerst klicken, dann zoomen

Der Betrachter muss das Klickziel im Kontext sehen und dann für die Konsequenz herangezoomt werden. Reihenfolge:

Frame 130   Cursor nähert sich der Schaltfläche
Frame 174   Klick-Welle
Frame 184   Schaltfläche zeigt "Wird ausgeführt…"
Frame 188   Kamera-Zoom startet (1.0 → 1.55+ über ~30 Frames)
Frame 220+  Zoom gehalten – Kaskade/Ergebnisse/Bildlauf-Enthüllung passiert hier

Zuerst zoomen und dann klicken fühlt sich an wie eine Präsentationsfolie. Zuerst klicken und dann zoomen fühlt sich an, als hätte der Benutzer die Aktion ausgeführt und die Kamera ist gefolgt.

B3. Wählen Sie einen Maßstab, der das Chrome tatsächlich von der Leinwand drückt

Ein bescheidener 1,1× ändert fast nichts. Damit "die obere Leiste die Leinwandoberkante verlässt", benötigen Sie ≥ 1,5× in Kombination mit einer Verschiebung, die den Brennpunkt in die Leinwandmitte bringt. Berechnen Sie Ziel ≥ (canvasHalfHeight) / (Abstand vom Brennpunkt zur oberen Leiste) – für eine Zeile bei y=540 und eine 64 Pixel hohe obere Leiste sind das ≥ ~1,5×. Verwenden Sie 1,55–1,85× als Standardwerte für "Ansichtsfenster füllen".

C. Cursor-Klickziele

C1. Treffen Sie das tatsächliche Element

Wenn der Cursor auf der falschen Schaltfläche landet (+ Neue Fähigkeit vs. der Modellauswahl-Pill), denkt der Betrachter, die Demo sei defekt. Leiten Sie das Ziel jedes Mal aus dem Layout neu ab – raten Sie keine Pixelwerte.

Für eine flex-rechtsbündige Steuerungsleiste mit padding: "0 22px":

// Rechte Kante → 22 Pad → Glocke (32) → 14 → Modell (~290) → 14 → Neue Fähigkeit (~120) → 14 → Fähigkeiten finden (~150)
NEUE_FAEHIGKEIT_PILL_X = 1920 - 22 - 32 - 14 - 290 - 14 - 60   // = 1488 (Schaltflächenmitte)
SUCHE_PILL_X           = 1920 - 22 - 32 - 14 - 290 - 14 - 120 - 14 - 75  // = 1339

Sobald Sie die Konstante haben, verwenden Sie sie sowohl für die Cursor-Annäherungsinterpolation als auch für die Cursor-Entfernungsinterpolation, damit die Klick-Welle genau auf der Pill landet, nicht 200 Pixel rechts davon.

C2. Heben Sie das Ziel hervor, während der Cursor sich nähert

Fügen Sie eine *Aktiv-Eigenschaft zu geteilten Kopfzeilenkomponenten hinzu (z. B. sucheAktiv, neueFaehigkeitAktiv auf StudioHeader), die die Cursor-Szene für das Annäherungs- + Klick-Fenster einschaltet. Die Schaltfläche erhält:

• 1,08× Skalierung
• Weichen Indigo- oder Lila-Ring via box-shadow: 0 0 0 4px rgba(99,102,241,0.30)
• transition: all 0.15s ease

D. Hervorhebungen und Rechtecke

D1. Hervorhebungsrechtecke sind inhaltsbreit, nicht vollzeilig

Wenn der Benutzer ein rotes Rechteck um zwei Terminalzeilen haben möchte, umwickeln Sie nicht die übergeordnete Flex-Spalte – das erstreckt sich über die Zeile. Verwenden Sie:

<div
  style={{
    display: "inline-flex",
    flexDirection: "column",
    alignSelf: "flex-start",
    width: "fit-content",
    border: "2px solid #dc2626",
    borderRadius: 6,
    padding: "10px 16px",
    backgroundColor: "transparent",
  }}
>
  {/* die zwei Zeilen, nichts weiter */}
</div>

Alles, was außerhalb des Rechtecks sein sollte (z. B. die dritte Zeile "Generiere Komponente…"), muss ein Geschwisterelement sein, kein Kind.

D2. Anmerkungen: Rechtecke Ellipsen vorziehen

Ein handgezeichneter Rechteckstrich um eine Zeile wirkt wie "Textmarker auf der Leinwand", was die meisten Benutzer meinen, wenn sie "hebe dies hervor" sagen. Eine Ellipse kann dekorativ wirken.

<svg viewBox="0 0 1000 100" preserveAspectRatio="none">
  <rect
    x="6" y="6" width="988" height="88" rx="6" ry="6"
    fill="none"
    stroke="#ea580c"
    strokeWidth="3.6"
    strokeDasharray="2160"
    strokeDashoffset={2160 * (1 - progress)}
  />
</svg>

D3. Verwenden Sie Orange (#ea580c) für "das ist neu" und Rot (#dc2626) für "das ist der Fehler"

Die gleiche Demo kann beides enthalten. Mischen Sie nicht.

E. Layoutmuster für Produkt-Chrome

E1. Studio-Kopfzeile ist eine einzige gemeinsame Komponente

Verwenden Sie eine StudioHeader.tsx mit diesem kanonischen Layout, das von jeder Studio-Szene aufgerufen wird:

• Links: Logo-Bild (40 × 40 PNG) + "Skill Studio" Wortmarke + Breadcrumb [Authoring|Verfügbar] / [Bereich] / [Ordner] / [Fähigkeit]
• Rechts: 🔍 Fähigkeiten finden [⌘K] · ✦ + Neue Fähigkeit · ● Modellauswahl · 🔔 Glocke

Übergeben Sie breadcrumb, glockenBadge, sucheAktiv, neueFaehigkeitAktiv als Eigenschaften. Die Kopfzeile jeder Szene ist dann pixelstabil.

E2. Seitenleiste hat ein konstantes Filtereingabefeld über VERFÜGBAR

Jede Studio-Seitenleiste – Durchsuchen, Aktualisieren, AuthorEvals, ConsumeInstall, AuthorEditAndPublish – erhält das gleiche Fähigkeiten filtern…-Eingabefeld über dem VERFÜGBAR-Baum. Füllen Sie es auf Folien, auf denen der Benutzer bereits gesucht hat, mit der kontextbezogenen Abfrage (frontend-Design) vor.

E3. Seitenleistenbreiten und Typografie

• Breite: 400 px (oder 460 px auf Folien mit tief verschachtelten Bäumen)
• Äußerer Abstand: 24–30 px
• Gruppenüberschriften (VERFÜGBAR, AUTHORING): 18–19 pt, Buchstabenabstand 1,6, Gewicht 700
• Unterüberschriften (FÄHIGKEITEN, .CLAUDE): 15–16 pt, Buchstabenabstand 1,4
• Zeilentext: 17–19 pt
• Versions-Pill: 13–14 pt Mono mit 1 px Rahmen, aufgefüllt 3/10
• Vertikale Abstände: 12–14 px zwischen Abschnitten, 22–36 px über Abschnittsüberschriften

Schmale, dichte Seitenleisten fühlen sich an wie Einstellungsfenster. Weite, offene Seitenleisten fühlen sich an wie echte Produkt-UI.

F. Zustandsübergänge an Ort und Stelle

F1. Kein Bildlauf nach links zwischen Szenen, die sich wie ein Bildschirm anfühlen sollten

Wenn "Klicken auf Installieren → Baum aktualisiert sich mit neuer Fähigkeit" wie eine kontinuierliche Interaktion wirken soll:

• Setzen Sie transitionType: null auf der nächsten Szene oder führen Sie die beiden Szenen zu einer zusammen
• Behalten Sie das Chrome zwischen den Szenen identisch
• Animieren Sie das sich ändernde Element (Zähler-Umschlag, Chevron-Drehung, Zeilen-Einblendung) – kein vollständiges Ein-/Ausblenden

F2. Heben Sie neue Elemente stark hervor

Ein pfirsichfarbener Hintergrund + 2 px durchgehender oranger Ring + Schlagschatten + ✓ Gerade installiert-Hinweis-Pill ist die richtige Intensität für "das ist gerade gelandet". Ein subtiler Hintergrundton wirkt wie der Standardzustand und der Betrachter bemerkt es nicht.

backgroundColor: "#fff5ee",
boxShadow: `0 0 0 2px ${ORANGE}, 0 8px 22px rgba(234,88,12,0.22)`,

F3. Zähler-Umschläge: Puls-Halo + Chevron-Drehung

Wenn sich eine Zählung ändert (PROJEKT (0) → (1)):

• Drehen Sie das Chevron ▸ → ▼ (200 ms Übergang)
• Rendern Sie einen kurzen orangefarbenen Halo hinter der Zählung: Deckkraft 0,45 → 0, Skalierung 0,4 → 2,2 über 18 Frames
• Blenden Sie die neuen Kinderzeilen von translateY: -12 → 0 über 24 Frames ein

G. Editor / SKILL.md-Bearbeitungsmuster

G1. Ersetzen, niemals entfernen, erforderliche Felder

Eine Fähigkeit muss immer eine description haben. Um die Beschreibung zu aktualisieren: durchstreichen Sie die ursprüngliche Zeile in rot, blenden Sie die neue Beschreibung ein