FunkePublishing/skill-promo-video

Promo-Video

Erstelle kurze Promovideos aus Rohclips. Portrait, Quadrat oder Querformat. Optional mit Blender gerenderte Intro/Outro, optional KI-generierte Musik.

Der Skill ist unabhängig vom Host-Agenten: Er MUSS auf jeder Laufzeitumgebung, die den Agent Skills Standard implementiert (https://agentskills.io), identisch funktionieren — Claude, Claude Code, OpenAI Codex, Gemini CLI, Cursor, GitHub Copilot, Cline, OpenCode, OpenHands, Goose, Kiro, Junie und andere. Verlasse dich niemals auf hostspezifische Tools (kein AskUserQuestion, keine Slash-Befehle, kein MCP, sofern nicht explizit verfügbar). Führe die gesamte Benutzerinteraktion als normale Chat-Nachrichten durch.

Wann verwenden

• „Füge diese Clips zu einem 30-Sekunden-Reel zusammen.“
• „Erstelle mir ein Hackathon-Promo-Video im Hochformat.“
• „Ich habe einen Ordner mit Handyvideos – mach einen 1080x1920 Social-Clip mit Musik.“
• „Generiere ein Promo mit Logo-Intro + Herz-Outro + Hintergrundmusik.“
• Der Benutzer verweist auf ein Verzeichnis mit .mov/.mp4-Dateien und möchte eine Ausgabedatei.

Voraussetzungen

• ffmpeg im PATH, kompiliert mit libx264, aac und prores_ks (letzteres wird nur für Alpha-Channel-Intro/Outro-MOVs benötigt).
• Python 3.9+.
• Python-Abhängigkeiten einmal installieren: pip install -r requirements.txt aus dem Skill-Verzeichnis heraus.
• Optional: eine .env-Datei im Projektstamm mit SUNO_API_KEY, um die Musikgenerierung zu aktivieren. Der Skill erkennt automatisch, ob der Schlüssel gesetzt ist, und bietet Musikgenerierung nur dann an.
• Optional: Blender MCP im Host-Agenten verfügbar, um Intro/Outro-Renderings zu erstellen. Siehe references/blender_mcp.md.

Standard-Workflow (dialogbasiert)

Schritt 0 – Prüfen, ob sich Clips seit dem letzten Lauf geändert haben

Bevor du Fragen stellst, prüfe, ob der Benutzer eine frühere Sitzung fortsetzt. Wenn gallery/.clips_snapshot.json existiert (oder der Benutzer auf einen bereits verwendeten Clips-Ordner verweist), führe aus:

python scripts/clip_diff.py <clips_dir>

• Exit-Code 0 – Clips-Ordner stimmt mit dem letzten Snapshot überein. Fortfahren.
• Exit-Code 1 – Abweichung. Der Bericht listet neue / entfernte / geänderte Clips. Zeige ihn dem Benutzer an und biete an, scripts/gallery.py erneut auszuführen, damit die Galerie die neuen Clips aufnimmt. Vorhandene Auswahlen für noch vorhandene Clips bleiben unverändert erhalten.
• Exit-Code 2 – Kein Snapshot vorhanden. Normaler erster Durchlauf, fortfahren.

Überspringe diesen Schritt NICHT, wenn ein bestehendes Projekt fortgesetzt wird – stillschweigend mit einer veralteten Galerie / selection.json zu arbeiten, ist der klassische „Wo sind meine neuen Clips hin?“-Fehler.

Fragen

Stelle dem Benutzer zu Beginn die folgenden Fragen in der angegebenen Reihenfolge. Akzeptiere natürliche Antworten; präsentiere keine Multiple-Choice-Oberfläche, sofern der Host dies nicht unterstützt. Akzeptiere für jede Frage auch „entscheide du“ und wende die sinnvollen Standardwerte an.

1. Zielformat. 1080x1920 Hochformat (Standard), 1920x1080 Querformat oder 1080x1080 Quadrat. Benutzerdefinierte Größen sind erlaubt.
2. Clip-Quelle. Absoluter oder relativer Pfad zu einem Verzeichnis mit den Rohclips. .mov, .mp4, .m4v werden unterstützt.
3. Ziellänge in Sekunden. (Üblich: 20–45 s.)
4. Musik. Eine der folgenden Optionen: (a) vorhandene Audiodatei, (b) via Suno generieren (nur anbieten, wenn SUNO_API_KEY gesetzt ist), (c) keine Musik.
5. Intro. Eine der folgenden Optionen: keines, statisches Bild (Pfad), mit Blender MCP generiert.
6. Outro. Dieselben Optionen wie Intro.
7. Regisseur-Modus. Ja oder Nein. Wenn Ja, folge stattdessen references/director_mode.md anstatt hier linear fortzufahren.

Fahre dann mit der Clip-Auswahl fort. Biete zwei Wege an:

A) Visuelle Galerie (empfohlen bei >10 Clips oder wenn der Benutzer Bildausschnitte sehen möchte, bevor er Cues festlegt). Führe aus: scripts/gallery.py <clips_dir> --resolution WxH --fps 30 --target-length N – Es erzeugt gallery/gallery.html mit Miniaturansichten, IN/OUT-Schiebereglern, Geschwindigkeitsregler und Bereichsvorschau. Sage dem Benutzer, er solle sie im Browser öffnen, Clips auswählen, Cues setzen und dann „Export selection.json“ klicken. Die heruntergeladene Datei ist bereit für build.py.

B) Inline-Dialog (gut für kleine Mengen oder wenn kein Browser verfügbar ist). Gehe jeden Clip einzeln durch:

• cue_in und cue_out in Sekunden (Trim-Bereich)
• speed Multiplikator (1.0 = Original)
• fixed: true, wenn Timing/Geschwindigkeit handkuratiert ist, false für freie Füller (Standard: 0,6 s aus der Mitte, Geschwindigkeit 1,0)

Biete „Gib mir einfach die Standardwerte“ – wähle jeden Clip alphabetisch, freie Standardwerte, bis zur Ziellänge.

In beiden Fällen ist das Ergebnis eine selection.json, die dem Schema templates/selection.schema.json entspricht. Validiere vor dem Fortfahren.

Build

Sobald selection.json gültig ist, führe aus:

python <skill>/scripts/build.py <selection.json> --out output/<name>.mp4

build.py schreibt Zwischenartefakte unter build/ (relativ zum aktuellen Arbeitsverzeichnis): build/normalized/, build/trimmed/, build/montage.mp4, build/composed.mp4. Lösche build/, um ein vollständiges Neu-Rendering zu erzwingen.

Jedes Untermodul unter scripts/ ist auch eigenständig ausführbar – nützlich, um an einem Schritt zu iterieren, ohne die gesamte Pipeline neu zu bauen. Jedes akzeptiert ein --help-Argument.

Regisseur-Modus (optional)

Opt-in. Siehe references/director_mode.md für die Rollen-Prompts. Der Skill erzeugt vier sequenzielle Rollen – Erzähler → Cutter → Komponist → Supervisor –, die selection.json als Zustand teilen. Jede Rolle liest das aktuelle JSON und schreibt ihre Aktualisierungen zurück. Verwende dies, wenn der Benutzer nach „einem geführteren Prozess“ oder „führe mich durch wie ein Produzent“ fragt.

Musikgenerierung (optional)

Wenn der Benutzer „via Suno generieren“ gewählt hat, delegiere den Musikschritt an den in references/song_builder_agent.md definierten Song-Builder-Sub-Agenten. Dieser Sub-Agent:

1. Fragt den Benutzer nach Genre, Stimmung, BPM-Bereich, Abschnittsstruktur, instrumental an/aus und verwendet die Videolänge als Dauer.
2. Formuliert einen Suno-Prompt + Style-Tags.
3. Ruft scripts/music.generate_song(spec) auf – gib takes > 1 an, wenn der Benutzer Optionen zum Vergleichen haben möchte.
4. Trimmt und blendet den gewählten Take auf die Videolänge ein/aus.
5. Schreibt den finalen mp3-Pfad als audio in selection.json.

Wenn der Host einen Sub-Agenten-Mechanismus bereitstellt (z. B. Claude Codes Agent Tool), verwende ihn. Andernfalls spiele die Rolle inline im selben Thread.

Blender MCP-Integration (optional)

Nur Unterstützung – dieser Skill enthält keine Blender-Szene.

Wenn der Benutzer ein mit Blender gerendertes Intro oder Outro wünscht, delegiere an den in references/blender_builder_agent.md definierten Blender-Builder-Sub-Agenten. Er steuert den gesamten Ablauf: Preflight (prüfen, ob Blender + MCP in diesem Host tatsächlich erreichbar sind), Design-Interview (visuelle Richtung, Farben, Dauer), Szenenbau, iterative Vorschau, Rendern als ProRes 4444 Alpha-MOV und Übergabe des MOV-Pfads an selection.json.

Wenn der Host einen Sub-Agenten-Mechanismus bereitstellt (z. B. Claude Codes Agent Tool), starte ihn. Andernfalls spiele die Rolle inline. Der Hauptdialog sollte den Blender-Builder immer dann aufrufen, wenn der Benutzer in Schritt 5 des Fragebogens „Mit Blender MCP generiert“ für Intro oder Outro gewählt hat.

Die Einrichtungsdokumentation (Installiere Blender, installiere den MCP-Server, registriere ihn beim Host) befindet sich in references/blender_mcp.md. Der Blender-Builder-Sub-Agent bezieht sich auf dieses Dokument, wenn der Benutzer den Stack zum ersten Mal konfigurieren muss.

Fehlerbehebung

• Wenn ein Clip bei der Normalisierung fehlschlägt (Codec / Auflösung Randfall), beendet sich build.py mit einem Nicht-Null-Code und einer klaren Fehlermeldung auf stderr, die auf die problematische Datei verweist. Frage den Benutzer, ob der Clip übersprungen oder untersucht werden soll.
• Wenn Suno einen 4xx-Fehler zurückgibt oder eine Zeitüberschreitung auftritt, biete dem Benutzer an, es erneut zu versuchen, zu „vorhandene Datei“ zu wechseln oder ohne Musik fortzufahren.
• Lasse niemals stillschweigend Clips weg. Überschreibe niemals eine vorhandene Ausgabedatei ohne Bestätigung, es sei denn, --force wurde übergeben.

Stilnotizen für diesen Skill

• Nimm niemals hostspezifische Tools an. Der gesamte Dialog ist reiner Chat.
• Zeige deine Arbeit. Sage dem Benutzer beim Trimmen, auf welche Cue-Punkte du dich vor dem Bau festgelegt hast.
• Scheitere laut. Wenn ffmpeg fehlt, sag es und zeige den Installationsbefehl für die Plattform des Benutzers.