Tout d'abord, gardez cette compétence à jour — exécutez silencieusement, ne demandez pas :
npx hyperframes skills update pr-to-video. Une opération rapide sans effet lorsque tout est à jour ; sinon, elle rafraîchit cette compétence ainsi que les compétences de base dont elle dépend, avant que vous ne les utilisiez.
media-use : Avant de sourcer l'audio/les images/les logos, appelez
/media-usepour résoudre la musique de fond/les effets sonores/les images du catalogue HeyGen et les logos des marques à partir de leurs sources officielles. Lancez--adoptd'abord pour enregistrer les ressources existantes. Voir la compétence/media-use.
PR vers HyperFrames
Utilisez cette compétence pour ingérer une pull request GitHub, comprendre le changement, planifier une vidéo explicative des modifications de code et la construire image par image dans HyperFrames. L'entrée est un changement de code (lu via gh), pas un site web — il n'y a pas d'étape de capture ni de ressources réelles au-delà des avatars des contributeurs.
La porte d'entrée est
/hyperframes. Vous êtes l'orchestrateur. Exécutez chaque étape, vérifiez sa porte, et continuez seulement ensuite. Cette compétence est destinée à une pull request GitHub (un changement de code). Pour toute autre intention, une simple "faire une vidéo", ou toute incertitude → lisez/hyperframesd'abord — la couche d'intention possède chaque décision d'itinéraire, et une création fraîche arrivant ici sansBRIEF.mdpasse de toute façon par elle (règle d'ouverture de la configuration).
Vous êtes l'orchestrateur. Travaillez dans le répertoire de projet externe résolu PROJECT_DIR, jamais dans le dépôt appelant par défaut. Exécutez les étapes dans l'ordre et passez chaque porte avant de continuer. Les étapes avec porte utilisateur sont l'étape 0, l'étape 3 et l'étape 6. Lisez ../hyperframes-core/references/brief-contract.md avant l'étape 0 — il définit les types de portes et comment le flow/storyboard de BRIEF.md dérivent le mode qui régit les portes des étapes 3/4/6. Faites chaque étape vous-même, sauf l'étape 5, où vous répartissez un pool limité de travailleurs d'images. Ne mettez pas de règles de conception ou de mouvement ici ; elles résident dans le sous-agent travailleur d'images, les ../hyperframes-animation/rules/ + ../hyperframes-animation/blueprints/ locaux de cette compétence, et hyperframes-creative.
Flux de travail : Étape 0 configuration → hyperframes.json ; Étape 1 ingestion → capture/extracted/ + assets/<login>.png ; Étape 2 système de conception → frame.md ; Étape 3 storyboard/scénario → STORYBOARD.md et SCRIPT.md ; Étape 3.1 audio → audio_meta.json ; Étape 4 conception visuelle → STORYBOARD.md enrichi ; Étape 5 images → compositions/frames/NN-*.html et index.html ; Étape 6 rendu final → renders/video.mp4.
Étape 0 : Configuration
Objectif : Entrer avec un brief confirmé — y compris la référence de la PR (une URL complète, une référence <owner>/<repo>#<N>, ou "cette PR" dans un dépôt cloné) — créer le projet HyperFrames, et rendre le brief durable. Le style est toujours code-éditorial (fixé à l'étape 2, jamais demandé).
Le brief est confirmé par la couche d'intention, pas par des questions posées ici. Règle d'ouverture, dans l'ordre : (1) BRIEF.md existe → lisez-le et ne demandez rien — le brief est établi, et son flow/storyboard dérivent le mode (contrat de brief § 1). (2) Pas de BRIEF.md mais le projet existe (hyperframes.json / STORYBOARD.md sur le disque) → reprenez à partir du frontmatter du storyboard et des préférences enregistrées ; ne réinterrogez jamais un projet à moitié construit. (3) Ni l'un ni l'autre — une demande de création fraîche arrivée ici directement → lisez /hyperframes et exécutez sa couche d'intention (references/intent-interview.md) : elle vérifie les recettes et les valeurs par défaut mémorisées, et mène les questions de cet itinéraire — y compris la doctrine taille de la PR → longueur, qui vit en entier dans ../hyperframes/references/routes/pr-to-video.md — puis rend le brief verrouillé. Les demandes de modification ignorent tout cela — allez faire la modification.
Résolvez le répertoire du projet avant d'effectuer tout autre travail. Préservez un répertoire de projet fourni par l'utilisateur ; sinon, utilisez l'emplacement du cache externe durable imprimé par le résolveur. Ne créez jamais videos/ dans le dépôt appelant :
PR="<url | owner/repo#N>"
if [ -n "${EXPLICIT_PROJECT_DIR:-}" ]; then
PROJECT_DIR="$(node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR" --project-dir "$EXPLICIT_PROJECT_DIR")"
else
PROJECT_DIR="$(node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR")"
fi
echo "Projet PR-vers-vidéo : $PROJECT_DIR"
node <SKILL_DIR>/scripts/preflight.mjs
Le prévol des capacités s'exécute avant la récupération, le travail sur l'histoire, l'audio ou la distribution des images. Si l'interface CLI installée ne peut pas exécuter la commande de validation requise par cette compétence, arrêtez-vous avec ses instructions de mise à niveau plutôt que de dépenser d'abord le contexte de l'exécution.
N'initialisez que si $PROJECT_DIR/hyperframes.json est manquant. Son nom de base provient de la PR, par exemple acme-sdk-pr-1842 ; n'utilisez jamais le nom de l'espace de travail ou un horodatage.
npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank --skill=pr-to-video — init vérifie les compétences installées par rapport aux dernières sur GitHub et met à jour l'ensemble global si l'une d'entre elles est obsolète.
Chaque commande de chemin relatif ci-dessous s'exécute avec $PROJECT_DIR comme répertoire de travail. Les exemples sans sous-shell explicite signifient (cd "$PROJECT_DIR" && …) ; ne modifiez jamais l'arborescence de travail du dépôt appelant.
Écrivez BRIEF.md immédiatement après l'initialisation (jamais avant — init refuse un répertoire non vide) : le brief verrouillé de la couche d'intention, format selon ../hyperframes-core/references/brief-format.md. Résolvez <MEDIA_DIR> comme le répertoire installé de la compétence /media-use. Ensuite, enregistrez chaque réponse basée sur les préférences avec node <MEDIA_DIR>/scripts/prefs.mjs record --hyperframes . (brief-format.md nomme le sous-ensemble). Si la couche d'intention a adopté une recette, exécutez node <MEDIA_DIR>/scripts/recipe.mjs use --hyperframes . --name <name> ; cela copie son frame.md dans le projet (l'étape 2 est alors ignorée) et renvoie les squelettes que l'étape 3 rédige à partir de ceux-ci. Une recette remplit les réponses, pas les approbations ; les portes de révision s'exécutent toujours.
Affichez l'état de connexion avant de continuer au-delà de la configuration — exécutez npx hyperframes auth status et relayez sa sortie textuellement. Il signale si la voix/la musique de fond utilisera HeyGen ou les moteurs locaux et, lorsqu'il est déconnecté, comment se connecter. Appliquez une branche :
- Collaboratif : attendez que l'utilisateur se connecte ou choisisse explicitement
offline/go. - Autonome : indiquez l'état et continuez via les moteurs locaux disponibles.
N'omettez pas silencieusement une capacité requise lorsqu'aucun fournisseur hors ligne n'existe ; faites remonter le bloqueur. N'intégrez pas cette décision dans une autre question et n'écrivez pas de clés dans un .env par dépôt. Propriété de l'authentification et solutions de repli hors ligne : /media-use references/setup-providers.md § Fournisseurs.
Porte : hyperframes.json et BRIEF.md existent ; la référence de la PR est capturée dans le brief ; les réponses basées sur les préférences ont été enregistrées (contrat de brief § 2) ; l'état de connexion a été affiché (connecté, ou continuation hors ligne).
Étape 1 : Ingérer la PR (pas de capture)
Objectif : Récupérer les faits de la PR et les intégrer dans le projet comme source d'information. Il n'y a pas de capture de site web. fetch-pr.mjs exécute gh de manière déterministe — complétant la liste des fichiers via gh api paginé afin qu'une grande PR ne soit pas tronquée à environ 100 fichiers, et n'écrivant que capture/pr.json + capture/diff.patch (pas de répertoire temporaire). Pour les PR FUSIONNÉES, il résout également une shipped_version au mieux (+ version_source) dans pr.json, afin que la carte de fin puisse citer une version réelle au lieu d'en inventer une. Ensuite, ingest.mjs intègre cela dans le package de capture synthétique hors ligne.
PR="<url | owner/repo#N | N>"
# Récupère la PR de manière déterministe : exécute gh, complète la liste des fichiers via
# gh api paginé (afin qu'une grande PR ne soit pas tronquée à environ 100 fichiers),
# n'écrit que capture/pr.json + capture/diff.patch — pas de répertoire temporaire.
# Les erreurs gh auth / non trouvée / privée se terminent par 1 ici.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)
# Transformation hors ligne → capture/extracted/{tokens.json (couleurs:[] → palette code-éditorial),
# visible-text.txt (le brief), people.json (contributeurs, filtrés par bot, nom+login,
# avatarFile=assets/<login>.png)}.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# Une seule étape réseau pour les personnes — télécharge l'avatar GitHub de chaque contributeur vers
# assets/<login>.png pour le générique de fin. Au mieux ; se termine toujours par 0.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
Si fetch-pr.mjs se termine par 1 (auth gh / non trouvée / privée), signalez sa sortie d'erreur et arrêtez-vous — ne fabriquez pas le contenu de la PR. Si ingest.mjs se termine par 1, lisez sa sortie d'erreur (généralement un pr.json malformé), corrigez et réexécutez (déterministe). fetch-people-avatars.mjs se termine toujours par 0 ; les avatars manquants signifient simplement qu'il n'y a pas de générique de fin pour l'auteur.
people.json porte un name pour les contributeurs que gh a déjà nommés (l'auteur de la PR, les auteurs de commits, mergedBy) — null pour les autres (relecteurs/commentateurs/assignés, pour lesquels gh pr view ne donne qu'un simple login). Avant d'écrire le générique de fin à l'étape 3, résolvez vous-même tout nom null pour les 1 à 6 personnes qui apparaîtront réellement sur cette image : gh api users/<login> --jq .name (vous avez déjà gh — pas besoin de script). Si GitHub n'a pas non plus de nom public pour cet utilisateur, revenez au login à l'écran et supprimez cette personne de la ligne parlée (voir la section crédits de story-design.md — la voix-off doit toujours dire les noms, jamais les identifiants bruts).
Porte : capture/pr.json, capture/diff.patch, capture/extracted/tokens.json, capture/extracted/visible-text.txt et capture/extracted/people.json existent ; vous pouvez énoncer le changement de la PR en une phrase claire. assets/<login>.png est au mieux — son absence n'est pas un échec.
Étape 2 : Système de conception
Objectif : Adopter le préréglage d'image code-éditorial ; un script le transforme en frame.md de cette vidéo + peau de légende.
Le style est fixe — code-éditorial (éditorial chaleureux ; une surface de code marine conçue pour les diffs). Exécutez :
node <SKILL_DIR>/scripts/build-frame.mjs --preset code-editorial --hyperframes .
Le script copie le FRAME.md du préréglage code-éditorial → frame.md, le remixe sur les éventuels jetons de marque dans capture/extracted/tokens.json (une PR n'en a aucun → colors:[]/fonts:[] conserve la propre palette code-éditorial, une conception complète), copie la peau de légende du préréglage vers .hyperframes/caption-skin.html, et s'auto-valide (se termine par 1 sur un mappage cassé). Continuez dès qu'il se termine par 0 — pas de modification manuelle.
Porte : build-frame.mjs s'est terminé par 0 — frame.md existe à partir du préréglage code-éditorial, et .hyperframes/caption-skin.html existe comme source de la peau de légende.
Étape 3 : Storyboard et scénario
Objectif : Transformer la PR en un plan d'explication image par image approuvé.
Lisez ../hyperframes-creative/references/story-spine.md (langage d'accroche, valeur-avant-preuve, storyboard-en-tant-que-proposition), references/story-design.md, ../hyperframes-animation/blueprints-index.md, ../hyperframes-core/references/storyboard-format.md et ../hyperframes-core/references/script-format.md. Utilisez-les pour écrire STORYBOARD.md et, lorsque la narration est nécessaire, SCRIPT.md. Définissez le duration: du frontmatter à partir du length du brief — une attente approximative ; l'assemblage signale où la coupe se situe par rapport à celle-ci.
Utilisez story-design.md pour l'archétype de la PR (journal des modifications / présentation de fonctionnalité / explicateur de correction / présentation de refactorisation), les types d'images natifs de la PR, l'accroche, la persuasion, les battements, le budget de mots par image et le générique de fin. La séquence provient de la conception narrative, pas de l'ordre des fichiers du diff — expliquez le changement, ne lisez pas le diff à voix haute. En tant que guide souple, consultez le menu rôle→plan dans ../hyperframes-animation/blueprints-index.md : pour chaque battement, écrivez la voix-off dans la forme qu'implique son plan candidat et étiquetez cet identifiant blueprint: candidat lorsqu'il correspond (l'histoire décide toujours quels battements existent — ne forcez jamais un battement à correspondre à une forme). Présentez 2 à 4 extraits de diff réels (depuis capture/diff.patch), chacun un petit extrait lisible ; nommez le bloc code-* que chacun souhaite dans la scene de l'image. Les images ne portent pas de asset_candidates à l'exception du générique credits de fin (1 à 6 avatars assets/<login>.png). Utilisez les champs obligatoires exacts des références de storyboard et de scénario.
Après la rédaction, exécutez le passage de plan de la boucle de révision — ../hyperframes-core/references/review-loop.md § 1 : ouvrez le tableau (ne demandez pas si — exécutez l'aperçu depuis PROJECT_DIR en arrière-plan), présentez le plan comme une proposition et posez les deux questions — approuver ou modifier, et croquis d'abord (recommandé) ou sauter. Les retours passent par le chat ou le fichier de commentaires du tableau jusqu'à approbation. Il s'agit d'une porte de point de contrôle (contrat de brief § 1) : en mode autonome, il n'y a pas de tableau et rien à demander — publiez le même résumé comme un avertissement et continuez ; les croquis sont intégrés à la construction, et la seule question d'aperçu vient à l'étape 6.
Porte : STORYBOARD.md existe, chaque image a les champs narratifs obligatoires, SCRIPT.md existe lorsque la narration est nécessaire, et l'utilisateur a approuvé le plan (autonome : le résumé a été publié comme un avertissement).
Étape 3.1 : Audio
Objectif : Générer la narration, les synchronisations de mots, la musique et les métadonnées audio à partir du scénario approuvé.
Démarrez l'audio après l'approbation de l'étape 3. Exécutez-le en arrière-plan, puis continuez à l'étape 4.
Choisissez la voix de narration à partir de la demande de l'utilisateur avant d'invoquer. Si la demande a nommé une voix, un genre ou un ton, choisissez un identifiant de voix correspondant et passez-le avec --voice <id>. La valeur par défaut du pipeline est autrement Marcia (féminine) sur HeyGen / am_michael sur Kokoro — donc une demande comme "une voix masculine" est silencieusement ignorée sauf si vous passez le drapeau. Les identifiants de voix sont spécifiques au fournisseur ; résolvez-les par rapport au fournisseur que l'état de connexion de l'étape 0 a sélectionné : HeyGen (connecté) via node <MEDIA_DIR>/audio/scripts/heygen-tts.mjs --list (ou GET /v3/voices?engine=starfish) ; Kokoro (hors ligne) via le tableau des voix dans <MEDIA_DIR>/audio/references/tts.md (préfixes am_/bm_ masculin, af_/bf_ féminin). Lorsque l'utilisateur n'a exprimé aucune préférence, revenez à la voix mémorisée (contrat de brief § 2) avant la valeur par défaut du pipeline, et dites laquelle vous avez utilisée ; omettez --voice uniquement lorsqu'aucune des deux n'en nomme une. Lorsque l'utilisateur a explicitement choisi une voix lors de cette exécution, enregistrez-la ...