TheMattBerman/shortform-idea-engine

Moteur d'idées pour vidéos courtes

Pipeline de la recherche au script qui transforme les vidéos aberrantes de concurrents en idées de vidéos courtes classées, adaptées à la marque, et en scripts prêts à l'emploi.

Quand l'utiliser

Utilisez ce skill lorsque l'utilisateur souhaite un pipeline d'idées de vidéos courtes : découvrir ce qui fonctionne dans une niche, comprendre pourquoi, générer des idées remixées et recevoir des scripts prêts à être tournés.

Ne pas utiliser pour :

• Une vidéo unique connue que l'utilisateur souhaite décoder : orienter vers video-decoder à la place.
• Une idée que l'utilisateur a déjà et souhaite transformer en script : orienter vers script-writer à la place.

Dépendances

Ce plugin est autonome. Il intègre tous les sous-skills et le script d'aide Gemini. Aucun environnement de skills partagé n'est requis. Les seules exigences externes sont trois clés API (voir section suivante).

Dépendance	Rôle dans ce skill
skill virlo (intégré)	Étape 1 mode mot-clé : découvre les vidéos courtes aberrantes par mot-clé de niche sur Instagram, TikTok et YouTube
skill scrape (intégré)	Étape 1 mode handles, Étape 2 et résolution d'URL CDN à l'Étape 4 : récupère les posts récents, les transcriptions, les images de couverture et les URL de médias directs via l'API ScrapeCreators
skill video-decoder	Étape 3 et Étape 4 : décode chaque vidéo aberrante en un enregistrement de décodage complet (hook visuel, hook écrit, hook parlé, racine, VV, IT, Format)
skill script-writer	Étape 7 : écrit un script prêt à être produit pour chaque idée approuvée
skill brand-profiler (intégré)	Étape 0 : construit un nouveau profil de marque lorsqu'aucun n'existe, en collectant tous les champs du schéma, y compris voice_tone
scripts/gemini-video-analyze.js (intégré)	Étape 4 analyse approfondie : exécute une analyse visuelle (rythme, cadence de coupe, style visuel, dispositifs de rétention, cadence du texte à l'écran) via OpenRouter Gemini

Clés API et dégradation gracieuse

Clés requises : VIRLO_API_KEY, SCRAPECREATORS_API_KEY, OPENROUTER_API_KEY.

Chargez-les à l'Étape 0 avant toute dépense :

source .env

Règles de dégradation :

Clé manquante	Effet
VIRLO_API_KEY	Le mode mot-clé est désactivé. Le mode handles fonctionne toujours. Signalez-le clairement à l'Étape 0.
OPENROUTER_API_KEY	L'Étape 4 (analyse approfondie) est entièrement ignorée. Tous les décodages restent superficiels. Les idées issues de décodages superficiels sont signalées comme "decoded-superficiellement" dans le tableau classé.
SCRAPECREATORS_API_KEY	Le moteur ne peut pas fonctionner. ScrapeCreators est nécessaire pour les transcriptions et les images de couverture dans tous les modes. Arrêtez-vous à l'Étape 0 et informez l'utilisateur clairement.

Pipeline

Étape 0 : Prise en charge

Demandez à l'utilisateur :

1. Mode : mode mot-clé (découvrir des vidéos par mot-clé de niche) ou mode handles (analyser des handles de concurrents spécifiques).
2. Chemin du profil de marque : le chemin vers un profil de marque rempli suivant references/brand-profile-template.md. S'il n'en existe pas, proposez d'en construire un en enchaînant avec le skill brand-profiler intégré, qui collecte tous les champs du schéma (voice_tone, audience, positioning, content_pillars, anti_topics, forbidden_constructions, proof_credibility, format_preferences, on_camera_talent) de manière interactive ou à partir d'un document de marque existant.
3. Identifiant de session : une étiquette courte en minuscules pour cette session (par exemple, ai-tools-keyword ou techcreator-handles). Utilisé pour nommer le dossier de la session.
4. Chemin de base de la session : où le dossier de la session doit être écrit. Le chemin de base par défaut est ./shortform-runs/ relatif au répertoire de travail actuel, produisant ./shortform-runs/YYYY-MM-DD-<slug>/. Si la session s'exécute dans un projet structuré avec sa propre zone de recherche ou de sortie, demandez à l'utilisateur s'il souhaite placer la session à cet endroit. Confirmez le chemin de base résolu avec l'utilisateur avant d'écrire un fichier.

Vérifiez les trois clés API. Signalez quels modes sont disponibles avant de dépenser des crédits. Créez le dossier de session au chemin de base confirmé (par exemple <base>/YYYY-MM-DD-<slug>/) et écrivez 00-intake.md avec le mode, la requête ou la liste de handles, le nom du fichier de profil de marque utilisé, le chemin de base de la session, les clés disponibles et les éventuelles substitutions.

Étape 1 : Découverte

Mode mot-clé. Invoquez le skill virlo pour découvrir des vidéos courtes aberrantes pour le mot-clé de niche. Effectuez la découverte dans les trois anneaux de concurrents définis dans video-decoder/references/decode-framework.md :

• Anneau direct : le mot-clé de niche exact tel quel.
• Anneau indirect : des expressions de mots-clés adjacentes à l'audience (même audience, angle thématique différent).
• Anneau adjacent : des expressions de mots-clés adjacentes au format (même format ou style de production, sujet différent).

Invoquez le skill virlo un anneau à la fois, en passant le nom de l'anneau et l'expression de mot-clé pour cet anneau. N'invoquez pas virlo pour plusieurs anneaux simultanément. Le skill virlo gère toute la mécanique d'orbite : il vérifie d'abord s'il existe une Comète couvrant le mot-clé de l'anneau et réutilise ses données accumulées (gratuitement) lorsqu'elle est disponible, et ne déclenche une nouvelle Orbite (coût : 0,50 $) que pour les anneaux sans Comète correspondante. La responsabilité de l'orchestrateur est le séquencement : attendre que virlo renvoie la liste classée des vidéos aberrantes pour un anneau avant d'invoquer virlo pour l'anneau suivant.

Après le retour des résultats de virlo pour un anneau, calculez la magnitude aberrante par vidéo. Les résultats de Virlo incluent un ratio aberrant au niveau du créateur, mais l'orchestrateur a besoin d'un ratio par vidéo pour l'Étape 4 et la grille de classement de l'Étape 6. Pour chaque créateur unique apparaissant dans les résultats de l'anneau, invoquez le skill scrape pour récupérer les posts récents de ce créateur (environ les 20 derniers) sur la plateforme concernée. Utilisez les posts retournés pour calculer un nombre médian de vues de base pour ce créateur. Calculez ensuite le ratio aberrant de chaque vidéo comme nombre_de_vues_video / mediane_vues_createur. Enregistrez les réponses JSON brutes dans raw/ pour chaque anneau et pour chaque récupération de base.

Mode handles. Invoquez le skill scrape pour récupérer les posts récents (environ les 20 derniers) pour chaque handle sur la plateforme concernée. Pour chaque handle, calculez le nombre médian de vues sur l'ensemble des posts retournés. Ne conservez que les posts qui dépassent la propre médiane du créateur de 2x ou plus (seuil aberrant). Enregistrez le JSON brut dans raw/.

Si un handle produit zéro post au-dessus du seuil de 2x (créateur à faible variance), incluez quand même le post récent le plus performant de ce créateur. Notez dans 00-intake.md que le handle n'avait pas d'aberration claire et que le meilleur post a été inclus comme solution de repli.

Dans les deux modes, le résultat de l'Étape 1 est une liste dédupliquée de vidéos aberrantes avec leur URL source, leur plateforme, leur handle de créateur et leur nombre de vues.

Étape 2 : Reçus

Pour chaque vidéo aberrante, invoquez le skill scrape pour collecter :

• Transcription : pour YouTube, invoquez le skill scrape pour récupérer la transcription par URL vidéo. Pour TikTok et Instagram, essayez d'extraire le texte de la transcription de la charge utile des posts déjà récupérée à l'Étape 1. Si la charge utile des posts ne contient pas de transcription pour une vidéo, invoquez la fonction de transcription du skill scrape pour cette URL vidéo en solution de repli avant de passer la vidéo à l'Étape 3.
• Image de couverture : l'URL de la miniature retournée dans la charge utile des posts. Pour YouTube, déduisez l'image de couverture comme https://img.youtube.com/vi/[VIDEO_ID]/hqdefault.jpg.

Enregistrez toutes les réponses brutes dans raw/ nommées par source et horodatage (par exemple scrapecreators-transcript-[video_id]-[timestamp].json). Chaque nombre de vues et indicateur d'engagement utilisé en aval doit être traçable jusqu'à un fichier dans raw/.

Étape 3 : Décodage

Exécutez le skill video-decoder sur chaque vidéo aberrante. Passez : le texte de la transcription (si disponible), l'URL de l'image de couverture (si disponible), le handle du créateur, la plateforme, la magnitude aberrante (ratio calculé à l'Étape 1) et l'affectation de l'anneau concurrent (classifiez l'anneau de chaque vidéo par rapport à la marque en utilisant les définitions d'anneau dans video-decoder/references/decode-framework.md).

Le skill video-decoder retourne un enregistrement de décodage complet par vidéo, incluant le hook visuel (dérivé de l'image de couverture et de tout texte visible à l'écran), le hook écrit et le hook parlé. Écrivez chaque enregistrement dans 01-decodes/[video_id].md. À ce stade, tous les décodages ont decode_depth: superficial.

Une transcription manquante seule N'est PAS une raison pour ignorer une vidéo. De nombreuses vidéos les plus aberrantes sont des vidéos de type texte superposé ou POV sans contenu parlé. Si la vidéo a une image de couverture ou une légende, décodez-la superficiellement avec spoken_hook: n/a. Ignorez une vidéo uniquement lorsqu'il n'y a vraiment rien à décoder : pas de transcription, pas d'image de couverture, pas de légende, ET aucun autre signal significatif (par exemple, un échec de récupération matérielle sans rien de récupérable). Enregistrez chaque vidéo ignorée comme decode-failed dans 00-intake.md avec l'URL de la vidéo et la raison exacte. Continuez le traitement des vidéos restantes.

Étape 4 : Analyse approfondie

Sélectionnez les 5 à 8 vidéos aberrantes les mieux classées par magnitude aberrante (ratio le plus élevé en premier).

Avant d'appeler l'assistant Gemini pour une vidéo, résolvez l'URL du média CDN direct pour cette vidéo en utilisant le skill scrape. Une URL de page sociale (par exemple, une URL de page TikTok ou Instagram) est rejetée par Gemini. Passez l'URL du média CDN à l'assistant, jamais l'URL de la page sociale. La méthode de résolution diffère selon la plateforme : consultez scrape/references/reading-scrape.md sous "Résolution d'une URL de média direct pour une vidéo" pour l'approche par plateforme (TikTok nécessite une recherche d'informations vidéo ; les URL des médias Instagram se trouvent dans la charge utile des posts déjà récupérée ; les URLs de vidéos YouTube sont transmises directement). Résolvez et utilisez les URL CDN rapidement pendant la session, car les URL CDN expirent.

Pour chaque vidéo sélectionnée, appelez l'assistant Gemini et redirigez stdout directement vers le fichier brut en une seule commande.

Le chemin de l'assistant doit être résolu comme un chemin absolu à partir du répertoire qui contient ce SKILL.md (le répertoire du skill shortform-idea-engine dans le plugin installé). Déterminez ce répertoire à l'exécution et construisez le chemin absolu vers scripts/gemini-video-analyze.js à l'intérieur. La redirection de sortie cible le dossier de session sous le chemin de base de session confirmé à l'Étape 0. Ces deux chemins sont résolus indépendamment : l'assistant à partir du répertoire du skill, la sortie à partir du chemin de base de la session.

OPENROUTER_API_KEY=<key> node <skill-dir>/scripts/gemini-video-analyze.js <cdnMediaUrl> "Analyse cette vidéo courte pour : le rythme (fréquence de coupe moyenne, segments notables rapides ou lents), le rythme des coupes (motif des coupes : coupe sur le beat, coupes de réaction, intercalaires de b-roll), le style visuel (étalonnage des couleurs, arrière-plan, mouvement de caméra, densité graphique à l'écran), la cadence du texte à l'écran (fréquence d'apparition des légendes ou des callouts par rapport au contenu parlé) et les dispositifs de rétention (hooks spécifiques, interruptions de motif, cliffhangers ou boucles utilisés au milieu de la vidéo). Retourne des notes structurées pour chaque dimension." > <run-base>/YYYY-MM-DD-<slug>/raw/gemini-<video_id>-<timestamp>.json

Où <skill-dir> est le chemin absolu vers le répertoire du skill shortform-idea-engine (le répertoire contenant ce SKILL.md) et <run-base>/YYYY-MM-DD-<slug>/ est le dossier de session confirmé à l'Étape 0.

La redirection enregistre la réponse Gemini brute dans raw/gemini-<video_id>-<timestamp>.json à l'intérieur du dossier de session pour que la traçabilité de l'Étape 8 puisse être satisfaite.

Relancez le skill video-decoder pour chacune de ces vidéos, en passant le bloc Gemini comme entrée d'analyse approfondie facultative. La relance retourne un enregistrement de décodage mis à jour avec decode_depth: deep et deep_notes renseignés. Écrasez le fichier 01-decodes/[video_id].md existant avec l'enregistrement approfondi.

Ignorer entièrement l'Étape 4 si OPENROUTER_API_KEY n'est pas défini. Tous les décodages restent superficiels et le drapeau "decoded-superficiellement" est noté par idée à l'Étape 6.

Étape 5 : Idéation

Regroupez tous les vecteurs viraux, sujets d'intérêt et formats de chaque enregistrement de décodage dans 01-decodes/. Générez 10 à 15 idées remixées. Chaque idée doit :

• Nommer le vecteur viral qu'elle emprunte (étiquette textuelle de l'enregistrement de décodage).
• Nommer le sujet d'intérêt qu'elle emprunte ou adapte.
• Nommer le format qu'elle utilise.
• Indiquer l'angle de marque : comment le VV, l'IT et le Format empruntés sont remixés pour s'adapter à cette marque spécifique (utilisez les champs content_pillars, audience et proof_credibility du profil de marque pour ancrer l'angle).
• Enregistrer la lignée source pour chaque élément emprunté : le creator_handle, le source_url et le video_id du ou des enregistrements de décodage dont l'élément a été extrait. Si un élément apparaît dans plus d'un enregistrement de décodage, listez-les tous. Cette lignée accompagne l'idée tout au long du classement et jusqu'au script.

Les poids des signaux d'extraction par anneau s'appliquent ici (de video-decoder/references/decode-framework.md) : les VV sont valides de tous les quatre anneaux ; les IT ont le signal le plus fort des concurrents indirects ; les Formats ont le signal le plus fort des concurrents adjacents. Pondérez votre remixage en conséquence, mais n'excluez pas mécaniquement des idées sur le seul critère de l'anneau.

Si le pool de décodages est trop petit pour supporter 10 idées distinctes sans fabriquer des combinaisons VV, IT ou Format qui ne sont pas présentes dans le pool, générez uniquement autant d'idées authentiques que le pool le permet. Notez le déficit et le nombre réel en haut de 02-ideas.md. N'inventez jamais d'extractions qui n'ont pas été décodées.

Étape 6 : Classement

Évaluez chaque idée à l'aide de references/ranking-rubric.md :

1. Vérifiez chaque idée par rapport à la liste des anti_topics du profil de marque. Toute correspondance est une disqualification immédiate (DQ: anti-topic). Supprimez les idées disqualifiées du tableau classé. Ajoutez chaque idée disqualifiée à une section clairement intitulée "Disqualifiées (anti-topic)" en bas de 02-ideas.md, sous le tableau classé, en listant l'idée et l'anti-topic spécifique qu'elle a déclenché.
2. Notez les idées survivantes sur deux axes : potentiel_viral (moyenne de cinq sous-facteurs : force du VV, magnitude aberrante, reproductibilité du format, fraîcheur du sujet, force du hook) et adequation_marque (moyenne de quatre sous-facteurs : correspondance de voix, correspondance d'audience, correspondance avec les piliers de contenu, crédibilité authentique). Les deux scores utilisent une échelle de 1 à 10.
3. Calculez combine = potentiel_viral * (adequation_marque / 10). Arrondissez à une décimale.
4. Triez par ordre décroissant de combine. En cas d'égalité, l'idée avec le potentiel_viral le plus élevé est classée en premier.
5. Écrivez le tableau classé dans 02-ideas.md dans cet ordre de colonnes : # | idée | racine | VV/IT/Format empruntés | vidéo source | viral | adequation marque | combiné | justification en une ligne. La cellule vidéo source affiche la vidéo source d'origine à laquelle l'idée remonte sous la forme @creator_handle / video_id. Si l'idée emprunte des éléments de plus d'une vidéo, listez la vidéo source principale en premier suivie de "+ N autres" où N est le nombre de sources supplémentaires traçables uniques au-delà de la principale. Si des notes d'analyse approfondies sont disponibles pour une vidéo source, mentionnez-le par un (deep) à côté de cette vidéo source dans le tableau.
6. À la fin du tableau classé, ajoutez une section "Avis de dégradation" répertoriant toute idée marquée comme "decoded-superficiellement", expliquant pourquoi l'analyse approfondie n'a pas été exécutée (OPENROUTER_API_KEY manquante) et notant que leurs scores de potentiel viral peuvent être moins fiables.

Étape 7 : Script

Demandez à l'utilisateur combien des meilleures idées classées doivent être transformées en scripts. Par défaut : top 3.

Pour chaque idée approuvée, invoquez le skill script-writer séquentiellement. Passez : l'idée de la section des idées approuvées, le profil de marque, le vecteur viral, le sujet d'intérêt, le format et les instructions de construction interdites (du profil). Le skill script-writer écrit un script prêt à être tourné dans le dossier de session sous 03-scripts/<video_idea_slug>.md.

Le slug de l'idée vidéo est une version en minuscules, avec traits d'union, du nom de l'idée (par exemple, ai-tools-reaction-remix).

Après chaque script, demandez à l'utilisateur "Approuvez-vous ce script ?" avec les options oui, non ou re-rendre. Enregistrez l'état d'approbation dans le pied de page YAML du fichier de script.

Si l'utilisateur répond re-rendre, appelez à nouveau le skill script-writer pour cette même idée, en lui passant la version précédente du script en entrée via le paramètre facultatif previous_version.

Étape 8 : Rapport récapitulatif

Écrivez un rapport de synthèse dans 04-summary.md qui documente l'ensemble du pipeline de la session. Incluez :

• Le nombre total de vidéos candidates découvertes.
• Le nombre de vidéos aberrantes transmises au décodage.
• Le nombre de décodages réussis (superficiels et approfondis).
• Le nombre de vidéos ignorées (avec URL et motif).
• Le nombre d'idées générées (par rapport au maximum).
• Le nombre d'idées disqualifiées (avec anti-topics déclenchés).
• Le nombre de scripts écrits.
• Toute dégradation subie (clés manquantes, modes indisponibles, décodages superficiels).
• Une table de traçabilité reliant chaque idée du tableau classé à sa vidéo source d'origine via l'URL de la vidéo source, le handle du créateur et le(s) fichier(s) brut(s) sous raw/ qui contiennent la preuve.

Références

• references/brand-profile-template.md définit le schéma du profil de marque.
• references/decode-framework.md définit les anneaux de concurrents, les définitions VV/IT/Format et les pondérations des signaux.
• references/ranking-rubric.md définit les calculs de score et les règles de disqualification.
• scrape/references/reading-scrape.md documente les chemins de résolution CDN spécifiques aux plateformes.

Tous les chemins de références sont relatifs au répertoire du skill shortform-idea-engine.