Communitygithub.com

storyboard-architect

Transformez un brief vidéo en storyboard et liste de plans avec spécifications techniques, minutage, texte à l'écran et justification par plan.

Qu'est-ce que storyboard-architect ?

Storyboard Architect est une compétence d'agent IA conçue pour les équipes de pré-production vidéo, les créateurs de contenu et les agences. Elle transforme un brief créatif en un ensemble de fichiers déterministes et exploitables—storyboard lisible, données structurées pour le montage, calque de texte dissocié et instantané de la charte graphique—sans intervention humaine supplémentaire. La compétence s'exécute en neuf étapes contraintes : lecture de la charte graphique, sélection d'un framework de rythme narratif, minutage, rédaction des plans, séparation du texte, verrouillage de la série, écriture de la justification, cliché de la charte et enregistrement de l'empreinte d'audit. Les formats de sortie incluent `storyboard.md` (rapport humain), `shots.json` (schéma strict), `text-overlays.json` (calque de texte) et `run.json` (piste d'audit hachée). Les frameworks de rythme pris en charge sont Hero Trilogy, Pain-Proof-Promise, Founder Explainer, Content Spiral et les structures personnalisées. Les packs de marque sont fournis via `_starter.md` ou des configurations client. La compétence s'intègre nativement avec `visual-prompt-forge`, `visual-asset-critic` et `storyboard-html-preview` en consommant `shots.json` et `text-overlays.json`. Elle fonctionne dans les environnements Claude (Claude Code, Cursor, Codex) et est utilisée via des invites comme « storyboarde une vidéo promotionnelle de 30 secondes pour mon produit ».

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/dheerazsah/video-editor-skills/tree/HEAD/skills/storyboard-architect

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Storyboard Architect

Vous transformez un brief créatif en un storyboard déterministe. La sortie est un ensemble de fichiers qu'un monteur, une agence ou un développeur peut exploiter sans poser de questions.

Ce n'est pas un exercice d'écriture créative. La sortie est un cahier des charges.

Quand l'utiliser

Déclenchez cette compétence lorsque l'utilisateur :

  • Demande un storyboard ou une liste de plans pour une vidéo (« storyboard d'un explainer de 30 secondes pour... », « liste de plans pour une pub TikTok sur... »)
  • Demande à planifier des plans, décomposer des séquences ou rédiger une liste de plans
  • Fournit un script, un brief ou un document de concept en attendant une sortie structurée de pré-production
  • Mentionne un framework de rythme par son nom (Hero Trilogy, Pain-Proof-Promise, etc.)
  • Fait référence à un fichier de charte graphique ou pack existant

Si l'utilisateur ne veut que des prompts pour un générateur d'images (sans structure narrative), utilisez directement visual-prompt-forge.

Ce que vous produisez

Pour chaque exécution de storyboard, créez cet ensemble exact de fichiers dans le répertoire de sortie de travail :

output/
├── run.json                   # Identité de l'exécution + chaque entrée figée par empreinte de contenu
├── storyboard.md              # Lisible, structuré par plan
├── shots.json                 # Lisible par machine, schéma dans templates/shots.schema.json
├── text-overlays.json         # Texte à l'écran + minutage
└── brand-lock.snapshot.md     # Copie figée de la charte utilisée (piste d'audit)

run.json est ce qui rend le reste de l'arborescence vérifiable plus tard. Un nom de fichier ne dit rien sur les octets qu'il contient, donc l'instantané à côté d'un ensemble d'images n'est pas une preuve qu'il s'agit de l'instantané à partir duquel elles ont été construites. Les empreintes dans run.json sont cette preuve. Écrivez-le une fois, en dernière étape, après que les quatre autres fichiers sont finalisés. Tout dans run.json sauf rounds est écrit une fois et jamais modifié. rounds est en ajout seul : visual-prompt-forge ajoute une entrée par tour de prompt et ne modifie jamais une entrée antérieure.

Si l'utilisateur demande des prompts d'images ou un aperçu HTML, déléguez à visual-prompt-forge ou storyboard-html-preview ; ces compétences consomment shots.json directement. N'essayez pas de faire leur travail ici.

Où se trouvent les outils et packs

Après ./install.sh, les validateurs et aides sont dans ~/.claude/shotkit-tools/ et les packs de marque sont dans ~/.claude/shotkit-brand-packs/. Une installation --project place les deux sous ./.claude/ à la place. Depuis un clone du dépôt, ils sont dans tools/ et brand-packs/. Les commandes ci-dessous donnent d'abord le chemin installé puis le chemin clone. Ils ne nécessitent aucune configuration : sk exécute chaque outil et fournit les deux packages Python qu'utilisent les validateurs.

Entrées

Vous avez besoin de ces éléments. Si l'un manque, demandez avant de rédiger.

EntréeObligatoire ?Valeur par défaut si absente
Brief (problème, audience, objectif)OuiDemander
Durée totaleOuiDemander
Format d'imageOuiDemander (16:9, 9:16, 1:1)
Framework de rythmeNonSuggérer en fonction du brief
Chemin du fichier de charteNonUtiliser ~/.claude/shotkit-brand-packs/_starter.md (clone : brand-packs/_starter.md) et signaler l'absence
Style de voix off (VO présente, écran seul, sous-titres)NonDemander si peu clair
Générateur(s) cible(s) pour les prompts avalNonNoter comme « à spécifier »
Résultats d'audit, brand/audit-findings.json de whystrohm-auditNonSauter l'étape 1b

Budget de lecture

Ce fichier contient ce dont une exécution normale a besoin : les champs, les vocabulaires et les formes de fichiers. Ne lisez pas les références, les modèles et les exemples à l'avance. Cela coûte des minutes à l'utilisateur avant que le premier fichier ne soit écrit.

  • Toujours lire : la charte.
  • Lire lorsque la décision l'exige : references/beat-frameworks.md pour un framework que vous ne maîtrisez pas, references/timing-rules.md lorsque le brief et la durée ne concordent pas, references/on-screen-text.md lorsque vous n'êtes pas sûr qu'un texte doive être à l'écran.
  • Lire lorsque le validateur le dit : les schémas dans templates/. Ses messages nomment le champ et la règle, donc corrigez d'abord à partir du message.
  • Lire en dernier, si jamais : les exemples.

Workflow

Suivez cette séquence. Ne sautez pas d'étapes même si le brief semble simple.

Étape 1. Lire la charte

Si un chemin de fichier de charte est fourni, lisez-le en premier. Extrayez :

  • Palette (hex)
  • Typographie
  • Descripteurs d'ambiance
  • Liste « Jamais » (ce que cette marque ne fera jamais visuellement)
  • Langage de mouvement
  • Ton de la voix
  • Préférences de format d'image

Si aucune charte n'est fournie, copiez ~/.claude/shotkit-brand-packs/_starter.md (depuis un clone, brand-packs/_starter.md) dans la sortie sous brand-lock.snapshot.md. Le starter est une charte neutre et remplie, donc l'instantané réussit sa vérification et les superpositions ont de vraies couleurs à utiliser. Définissez brand_lock_configured: false dans run.json, et dites à l'utilisateur que l'exécution a utilisé la charte de démarrage et comment la remplacer : demandez une charte depuis leur site, ou remplissez _template.md.

Ne prenez pas d'instantané de _template.md. Il est vide intentionnellement, et une palette vide échoue à la vérification de l'instantané. N'inventez pas non plus de palette pour une vraie entreprise : une charte inventée ressemble à une décision que l'entreprise n'a pas prise.

Étape 1b. Lire les résultats d'audit, s'il y en a

Si l'utilisateur pointe vers brand/audit-findings.json, ou s'il se trouve dans le dossier brand/ du projet et que le brief concerne la même entreprise, lisez-le. Son format est contracts/audit-findings.v1.schema.json dans ce dépôt. Vérifiez que contract est audit-findings et version est "1" avant de l'utiliser.

  • Le premier des top_gaps est un candidat pour la séquence problème ou monde : le problème auquel le film répond.
  • rewrite.after est un candidat pour une ligne de superposition. Utilisez-le uniquement tel qu'écrit. Un espace réservé entre crochets signifie que la preuve manque, donc omettez cette ligne plutôt que de la remplir.
  • Nommez le fichier et son audited_at dans la section Brief de storyboard.md.

Le brief décide toujours. Les résultats informent les séquences ; ils ne remplacent jamais ce que l'utilisateur a demandé.

Étape 2. Choisir le framework de rythme

Lisez references/beat-frameworks.md. Choisissez celui qui correspond au brief. Cas courants :

  • Pain-reframe-promise → contenu de conversion
  • Hero Trilogy → films de présentation de produit
  • Founder Explainer → contenu de marque personnelle
  • Content Spiral → typographie cinétique / articles d'opinion

Si aucun ne correspond parfaitement, construisez une structure de rythme personnalisée mais documentez pourquoi dans la section de justification de storyboard.md.

Étape 3. Définir le minutage

Lisez references/timing-rules.md pour les calculs. Cadence par défaut :

  • Accroche : 0–2 secondes
  • Problème/mise en place : 2–4 secondes (pour 15s), 2–6 secondes (pour 30s) ou 2–10 secondes (pour 60s)
  • Preuve/reformulation : tiers central
  • Promesse/appel à l'action : 3–4 secondes finales (pour 15s), 4–6 secondes (pour 30s), 6–10 secondes (pour 60s)

Ne luttez pas contre le framework. Si le brief et la durée ne concordent pas, signalez le désaccord avant de rédiger.

Étape 4. Rédiger la liste de plans

Lisez references/shot-grammar.md pour le vocabulaire contrôlé. Les noms de champs ci-dessous sont les noms de champs du schéma. templates/shots.schema.json définit additionalProperties: false, donc un quasi-match comme environment au lieu de environment_ref est un échec de validation, pas un synonyme.

  • id, séquentiel, avec zéro non significatif (shot_01, shot_02...)
  • beat, la séquence que ce plan sert
  • start / end, horodatages en secondes, décimal autorisé. end doit être après start
  • framing, ECU / CU / MCU / MS / MLS / WS / EWS
  • angle, eye-level / high / low / overhead / dutch
  • motion, static / push / pull / pan-left / pan-right / tilt-up / tilt-down / handheld / orbit / whip / rack. Les onze sont légaux ; l'énumération du schéma fait autorité et references/shot-grammar.md explique quand chacun est utile
  • depth_of_field, optionnel, shallow / deep / rack
  • subject, ce qui est dans le cadre, structuré
  • environment_ref, référence au langage du verrouillage de série, par défaut series_lock.environment
  • lighting_ref, référence au langage du verrouillage de série, par défaut series_lock.lighting
  • on_screen_text, null, un identifiant de superposition de texte, OU un tableau d'identifiants lorsqu'un plan porte plus d'une superposition
  • vo, ligne de voix off, ou null
  • rationale, une phrase expliquant pourquoi ce plan à ce moment

Note sur rack : comme valeur de motion, cela signifie que le point de vue est le mouvement du plan ; comme valeur de depth_of_field, cela signifie que la mise au point change en cours de plan. Même mot, deux champs, deux significations.

Étape 5. Séparer le calque de texte

Chaque élément de texte à l'écran devient une entrée dans text-overlays.json. N'intégrez jamais le texte dans la description visuelle. Chaque superposition a :

  • id, text_01, text_02...
  • shot_id, le plan sur lequel cette superposition apparaît
  • content, le texte réel
  • font, référence à la typographie de la charte
  • position, center, lower-third, upper-third, left-third, right-third, ou {x, y} en pourcentages
  • size, display, headline, body, caption
  • weight, regular (400), medium (500), semibold (600), bold (700), black (900)
  • color, hex (doit provenir de la palette de la charte)
  • enter, { at: secondes, animation: fade-in | slide-up | slide-down | type-on | hard-cut }
  • exit, { at: secondes, animation: fade-out | slide-up | slide-down | hard-cut }

Ensuite, définissez le traitement typographique et vérifiez les mots :

  • Traitement typographique. Marquez les deux ou trois mots qui portent chaque titre avec emphasis, nommez la marque une fois avec un kicker ou un lockup, et utilisez un plate lorsque le cadre est chargé. Les champs et quand les utiliser sont dans references/on-screen-text.md, sous « Traitement typographique ».
  • Le contrôle linguistique. Avant d'écrire le fichier, passez chaque ligne dans references/hooks-and-language.md : une première ligne qui est une accroche et non un slogan, des mots spécifiques, une idée par ligne, rien que le brief n'ait pas donné.
  • Une marque sans police. Choisissez un appariement dans type-pairings.md du dossier des packs de marque et écrivez-le dans la charte. Ne prenez pas Inter par défaut.

Enter et exit ont des vocabulaires d'animation différents, et templates/text-overlays.schema.json fait autorité pour les deux. Un plan peut porter plus d'une superposition ; listez chaque identifiant dans le tableau on_screen_text de ce plan, sinon les superpositions supplémentaires ne s'affichent nulle part.

Étape 6. Verrouiller la série

Définissez les ancrages d'environnement, d'éclairage et de personnage qui s'appliquent à tous les plans. Ceux-ci vont en haut de shots.json sous series_lock. Sans cela, la génération d'images produira des plans incohérents.

Étape 7. Écrire la justification

Chaque plan a une justification d'une phrase. Pourquoi cette séquence. Pourquoi ce cadrage. Pourquoi ce texte à l'écran. C'est la piste d'audit. Ne la sautez pas.

Étape 8. Prendre un instantané de la charte

Copiez le fichier de charte (ou modèle) dans la sortie sous brand-lock.snapshot.md. Ajoutez ces deux commentaires tout en haut, dans cet ordre :

<!-- snapshot taken: 2026-05-07T14:23:00Z -->
<!-- source: brand-packs/whystrohm.md -->

L'horodatage est un instant UTC complet, YYYY-MM-DDThh:mm:ssZ. Une date nue ne peut pas distinguer deux exécutions faites le même jour, ce qui est le cas important. La source est le chemin depuis lequel il a été copié, ou la chaîne littérale template default pour une exécution non configurée. Après une installation, un chemin de pack est ~/.claude/shotkit-brand-packs/whystrohm.md ; depuis un clone du dépôt, c'est brand-packs/whystrohm.md. Les deux passent le validateur. Des commentaires supplémentaires après ces deux sont acceptables.

validate_brand_lock.py --snapshot <path> vérifie les deux lignes. Exécutez-le :

~/.claude/shotkit-tools/sk validate_brand_lock.py --snapshot output/brand-lock.snapshot.md
# depuis un clone du dépôt :
# tools/sk validate_brand_lock.py --snapshot output/brand-lock.snapshot.md

Étape 9. Écrire run.json

Dernière étape, après que les quatre autres fichiers sont finalisés. Remplissez templates/run.schema.json. Ces champs sont obligatoires :

ChampValeur
version"1.0", le format run.json
run_idhorodatage UTC compact, un tiret, 8 caractères hexadécimaux (ci-dessous)
created_atle même instant que YYYY-MM-DDThh:mm:ssZ
shotkit_versionligne 1 de ~/.claude/shotkit-tools/VERSION ; dans un clone du dépôt, VERSION à la racine
projecttitle, duration_s et aspect de shots.json, plus framework et seed si défini
inputs.shots_ref, inputs.shots_sha256shots.json et son SHA-256
inputs.text_overlays_ref, inputs.text_overlays_sha256text-overlays.json et son SHA-256, ou les deux null sans texte à l'écran
inputs.brand_lock_ref, inputs.brand_lock_sha256brand-lock.snapshot.md et son SHA-256
inputs.brand_lock_sourcele pack depuis lequel il a été copié, ou template default

Optionnel : operator, inputs.brand_lock_configured, generators, rounds, meta.

head -n 1 ~/.claude/shotkit-tools/VERSION     # depuis un clone du dépôt : head -n 1 VERSION
shasum -a 256 output/shots.json output/text-overlays.json output/brand-lock.snapshot.md

run_id est l'horodatage UTC compact, un tiret, puis 8 caractères hexadécimaux, par exemple 20260730T142300Z-9f2c1ab4. Le suffixe hexadécimal empêche deux opérateurs débutant une exécution dans la même seconde d'entrer en collision. Définissez brand_lock_configured: false lorsque l'instantané est un modèle non rempli.

Laissez rounds vide. Tout dans run.json sauf rounds est écrit une fois et jamais modifié. rounds est en ajout seul : visual-prompt-forge ajoute une entrée par tour de prompt et ne modifie jamais une entrée antérieure.

Formats de sortie

storyboard.md

Un titre par section, dans cet ordre : le brief tel que donné, les hypothèses que vous avez faites, le framework et pourquoi, le verrouillage de série, puis un bloc par plan (id, séquence, temps, caméra, sujet, texte à l'écran, VO, justification), puis le script VO complet s'il y en a un. templates/storyboard.md.tpl a la mise en page exacte si vous le souhaitez.

shots.json

Doit être validé contre templates/shots.schema.json. La structure est :

{
  "version": "1.2",
  "project": { "title": "...", "duration_s": 30, "aspect": "9:16", "framework": "..." },
  "brand_lock_ref": "brand-lock.snapshot.md",
  "series_lock": {
    "character": "...",
    "environment": "...",
    "lighting": "...",
    "color_grade": "..."
  },
  "shots": [
    {
      "id": "shot_01",
      "beat": "hook",
      "start": 0.0,
      "end": 2.0,
      "framing": "MCU",
      "angle": "eye-level",
      "motion": "static",
      "depth_of_field": "shallow",
      "subject": { ... },
      "environment_ref": "series_lock.environment",
      "lighting_ref": "series_lock.lighting",
      "on_screen_text": ["text_01"],
      "vo": "Ce produit résout un problème que vous connaissez.",
      "rationale": "Accroche visuelle directe pour capter l'attention."
    }
  ]
}

text-overlays.json

{
  "version": "1.0",
  "overlays": [
    {
      "id": "text_01",
      "shot_id": "shot_01",
      "content": "Le problème que vous connaissez",
      "font": "Brand Sans",
      "position": "lower-third",
      "size": "headline",
      "weight": "bold",
      "color": "#1A1A2E",
      "enter": { "at": 0.5, "animation": "fade-in" },
      "exit": { "at": 1.8, "animation": "fade-out" }
    }
  ]
}

run.json

{
  "version": "1.0",
  "run_id": "20260730T142300Z-9f2c1ab4",
  "created_at": "2026-07-30T14:23:00Z",
  "shotkit_version": "1.0.0",
  "project": {
    "title": "Vidéo promotionnelle Produit X",
    "duration_s": 30,
    "aspect": "9:16",
    "framework": "pain-reframe-promise"
  },
  "inputs": {
    "shots_ref": "output/shots.json",
    "shots_sha256": "abc123...",
    "text_overlays_ref": "output/text-overlays.json",
    "text_overlays_sha256": "def456...",
    "brand_lock_ref": "output/brand-lock.snapshot.md",
    "brand_lock_sha256": "ghi789...",
    "brand_lock_source": "brand-packs/whystrohm.md",
    "brand_lock_configured": true
  },
  "rounds": []
}

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Skills associés