Communitygithub.com

storyboard-architect

Convierte un brief en vídeo en un storyboard y una lista de tomas con especificaciones, tiempos, texto en pantalla y justificación por toma. Úsalo cuando el usuario solicite un storyboard, una lista de tomas, desglose de beats o preproducción estructurada para un vídeo, o entregue un guion o concepto para dividirlo en tomas. Produce run.json, storyboard.md, shots.json, text-overlays.json y brand-lock.snapshot.md. Planifica el vídeo; no lo renderiza. Se combina con visual-prompt-forge, visual-asset-critic y storyboard-html-preview.

¿Qué es storyboard-architect?

Storyboard Architect es una habilidad de IA para agentes como Claude Code que transforma un brief creativo, guion o concepto en un storyboard determinista y un conjunto de archivos de especificaciones. Genera cinco archivos clave: run.json (identidad y hash de auditoría), storyboard.md (narrativa legible para humanos por toma), shots.json (datos estructurados maquinables), text-overlays.json (texto en pantalla con tiempos) y brand-lock.snapshot.md (instantánea de las directrices de marca). El flujo de trabajo sigue pasos rigurosos: lee el bloqueo de marca, selecciona un marco de beats (como Héroe-Trilogía o Pain-Proof-Promise), asigna los tiempos según reglas predefinidas, redacta la lista de tomas con un vocabulario controlado de encuadres, ángulos y movimientos, separa la capa de texto, aplica el tratamiento tipográfico, define un bloqueo de serie para coherencia visual, escribe la justificación para cada toma y finalmente genera el archivo run.json como cierre. Esta habilidad es ideal para planificación de preproducción de anuncios, contenido de redes sociales o vídeos corporativos, y está diseñada para ser consumida por editores, agencias o desarrolladores sin preguntas adicionales. Se integra con las habilidades complementarias visual-prompt-forge (para generar prompts de imagen), visual-asset-critic (crítica de activos) y storyboard-html-preview (vista previa HTML). No renderiza vídeo, solo especifica el plan.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Storyboard Architect

Estás convirtiendo un brief creativo en un storyboard determinista. El resultado es un conjunto de archivos sobre los que un editor, agencia o desarrollador puede actuar sin necesidad de hacer preguntas adicionales.

Esto no es un ejercicio de escritura creativa. El resultado es una especificación.

Cuándo usarlo

Activa esta habilidad cuando el usuario:

  • Solicite un storyboard o una lista de tomas para un vídeo ("storyboard para un vídeo explicativo de 30 segundos sobre...", "lista de tomas para un anuncio de TikTok sobre...")
  • Pida planificar tomas, desglosar beats o escribir una lista de tomas
  • Entregue un guion, brief o documento conceptual esperando una salida de preproducción estructurada
  • Mencione un marco de beats por nombre (Héroe-Trilogía, Pain-Proof-Promise, etc.)
  • Haga referencia a un archivo de bloqueo de marca o pack existente

Si el usuario solo desea prompts para un generador de imágenes (sin estructura narrativa), usa directamente visual-prompt-forge.

Lo que produces

Por cada ejecución de storyboard, crea este conjunto exacto de archivos en el directorio de salida de trabajo:

output/
├── run.json                   # Identidad de ejecución + cada entrada fijada por hash de contenido
├── storyboard.md              # Legible por humanos, estructurado por toma
├── shots.json                 # Legible por máquinas, esquema en templates/shots.schema.json
├── text-overlays.json         # Texto en pantalla + tiempos
└── brand-lock.snapshot.md     # Copia congelada del bloqueo de marca usado (pista de auditoría)

run.json es lo que hace que el resto del árbol sea auditable más adelante. Un nombre de archivo no dice nada sobre los bytes que contiene, por lo que la instantánea que está junto a un conjunto de fotogramas no es prueba de que sea la instantánea a partir de la cual se construyeron. Los hashes en run.json son esa prueba. Escríbelo una vez, como último paso, después de que los otros cuatro archivos estén finalizados. Todo en run.json, excepto rounds, se escribe una vez y nunca se edita. rounds es de solo añadido: visual-prompt-forge añade una entrada por ronda de prompts y nunca cambia una anterior.

Si el usuario solicita prompts de imagen o vista previa HTML, transfiere a visual-prompt-forge o storyboard-html-preview; esas habilidades consumen shots.json directamente. No intentes hacer su trabajo aquí.

Dónde están las herramientas y los packs

Después de ejecutar ./install.sh, los validadores y ayudantes están en ~/.claude/shotkit-tools/ y los packs de marca están en ~/.claude/shotkit-brand-packs/. Una instalación --project coloca ambos en ./.claude/ en su lugar. Desde un clon del repositorio están en tools/ y brand-packs/. Los comandos a continuación proporcionan primero la ruta instalada y luego la ruta del clon. No necesitan configuración: sk ejecuta cada herramienta y proporciona los dos paquetes de Python que utilizan los validadores.

Entradas

Necesitas estas. Si falta alguna, pregunta antes de redactar.

Entrada¿Obligatoria?Valor por defecto si falta
Brief (problema, audiencia, objetivo)SíPreguntar
Duración totalSíPreguntar
Relación de aspectoSíPreguntar (16:9, 9:16, 1:1)
Marco de beatsNoSugerir según el brief
Ruta del archivo de bloqueo de marcaNoUsar ~/.claude/shotkit-brand-packs/_starter.md (clon: brand-packs/_starter.md) y señalar la carencia
Estilo de voz en off (VO presente, solo en pantalla, subtítulos)NoPreguntar si no está claro
Generador(es) objetivo para prompts posterioresNoAnotar como "por especificar"
Hallazgos de auditoría, brand/audit-findings.json de whystrohm-auditNoOmitir el Paso 1b

Presupuesto de lectura

Este archivo contiene lo que necesita una ejecución normal: los campos, los vocabularios y las formas de los archivos. No leas las referencias, las plantillas ni los ejemplos por adelantado. Eso le cuesta al usuario minutos antes de que se escriba el primer archivo.

  • Leer siempre: el bloqueo de marca.
  • Leer cuando la decisión lo requiera: references/beat-frameworks.md para un marco que no conozcas de memoria, references/timing-rules.md cuando el brief y la duración no coincidan, references/on-screen-text.md cuando no estés seguro de si una línea debe estar en pantalla.
  • Leer cuando el validador lo indique: los esquemas en templates/. Sus mensajes nombran el campo y la regla, así que corrige a partir del mensaje primero.
  • Leer al final, si acaso: los ejemplos.

Flujo de trabajo

Sigue esta secuencia. No te saltes pasos, incluso si el brief parece simple.

Paso 1. Leer el bloqueo de marca

Si se proporciona una ruta de archivo de bloqueo de marca, léelo primero. Extrae:

  • Paleta (hex)
  • Tipografía
  • Descriptores de estado de ánimo
  • Lista "Nunca" (lo que esta marca nunca hará visualmente)
  • Lenguaje de movimiento
  • Tono de voz
  • Preferencias de relación de aspecto

Si no se proporciona un bloqueo de marca, copia ~/.claude/shotkit-brand-packs/_starter.md (desde un clon, brand-packs/_starter.md) en la salida como brand-lock.snapshot.md. El iniciador es un bloqueo neutral y completo, por lo que la instantánea pasa su verificación y las superposiciones tienen colores reales para usar. Establece brand_lock_configured: false en run.json, e informa al usuario que la ejecución usó la marca iniciadora y cómo reemplazarla: pide un bloqueo de marca de su sitio, o completa _template.md.

No uses _template.md como instantánea. Está en blanco a propósito, y una paleta en blanco falla la verificación de instantánea. Tampoco inventes una paleta para una empresa real: un bloqueo de marca inventado parece una decisión que tomó la empresa.

Paso 1b. Leer los hallazgos de auditoría, si los hay

Si el usuario señala brand/audit-findings.json, o está en la carpeta brand/ del proyecto y el brief es para la misma empresa, léelo. Su formato es contracts/audit-findings.v1.schema.json en este repositorio. Verifica que contract sea audit-findings y version sea "1" antes de usarlo.

  • La primera de top_gaps es candidata para el beat de dolor o del mundo: el problema que responde el vídeo.
  • rewrite.after es una línea de superposición candidata. Úsala solo tal como está escrita. Un marcador de posición entre corchetes significa que falta la prueba, así que omite esa línea en lugar de rellenarla.
  • Nombra el archivo y su audited_at en la sección de Brief de storyboard.md.

El brief sigue siendo quien decide. Los hallazgos informan los beats; nunca reemplazan lo que el usuario solicitó.

Paso 2. Elegir el marco de beats

Lee references/beat-frameworks.md. Elige el que coincida con el brief. Casos comunes:

  • Pain-Reframe-Promise → contenido de conversión
  • Héroe-Trilogía → vídeos de producto héroe
  • Founder Explainer → contenido de marca personal
  • Espiral de Contenido → tipografía cinética / piezas de opinión

Si ninguno encaja limpiamente, construye una estructura de beats personalizada pero documenta por qué en la sección de justificación de storyboard.md.

Paso 3. Distribuir los tiempos

Lee references/timing-rules.md para los cálculos. Cadencia predeterminada:

  • Beat de gancho: 0–2 segundos
  • Dolor/configuración: 2–4 segundos (para 15s), 2–6 segundos (para 30s) o 2–10 segundos (para 60s)
  • Prueba/reencuadre: tercio medio
  • Promesa/CTA: últimos 3–4 segundos (para 15s), 4–6 segundos (para 30s), 6–10 segundos (para 60s)

No luches contra el marco. Si el brief y la duración no coinciden, saca a relucir el desacuerdo antes de redactar.

Paso 4. Redactar la lista de tomas

Lee references/shot-grammar.md para el vocabulario controlado. Los nombres de campo a continuación son los nombres de campo del esquema. templates/shots.schema.json establece additionalProperties: false, por lo que un error por poco como environment en lugar de environment_ref es un fallo de validación, no un sinónimo.

  • id, secuencial, rellenado con ceros (shot_01, shot_02...)
  • beat, a qué beat sirve esta toma
  • start / end, marcas de tiempo en segundos, se permite decimal. end debe ser posterior a 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. Los once son válidos; el enum del esquema es la autoridad y references/shot-grammar.md explica cuándo cada uno vale la pena
  • depth_of_field, opcional, shallow / deep / rack
  • subject, lo que está en el encuadre, estructurado
  • environment_ref, referencia al lenguaje del bloqueo de serie, por defecto series_lock.environment
  • lighting_ref, referencia al lenguaje del bloqueo de serie, por defecto series_lock.lighting
  • on_screen_text, nulo, un id de superposición de texto, O un array de ids cuando una toma lleva más de una superposición
  • vo, línea de voz en off, o nulo
  • rationale, una oración que explique por qué esta toma en este momento

Nota sobre rack: como valor de motion significa que el rack focus es el movimiento de la toma; como valor de depth_of_field significa que el enfoque cambia a mitad de la toma. Misma palabra, dos campos, dos significados.

Paso 5. Separar la capa de texto

Cada pieza de texto en pantalla se convierte en una entrada en text-overlays.json. Nunca incorpores texto en la descripción visual. Cada superposición tiene:

  • id, text_01, text_02...
  • shot_id, en qué toma se superpone
  • content, el texto real
  • font, referencia a la tipografía del bloqueo de marca
  • position, center, lower-third, upper-third, left-third, right-third, o {x, y} porcentajes
  • size, display, headline, body, caption
  • weight, regular (400), medium (500), semibold (600), bold (700), black (900)
  • color, hex (debe provenir de la paleta del bloqueo de marca)
  • enter, { at: segundos, animation: fade-in | slide-up | slide-down | type-on | hard-cut }
  • exit, { at: segundos, animation: fade-out | slide-up | slide-down | hard-cut }

Luego establece el tipo y verifica las palabras:

  • Tratamiento tipográfico. Marca las dos o tres palabras que llevan cada titular con emphasis, nombra la marca una vez con un kicker o un lockup, y usa un plate donde el encuadre esté ocupado. Los campos y cuándo usar cada uno están en references/on-screen-text.md, bajo "Tratamiento tipográfico".
  • La pasada de lenguaje. Antes de escribir el archivo, pasa cada línea por references/hooks-and-language.md: una primera línea que sea un gancho y no un eslogan, palabras específicas, una idea por línea, nada que el brief no haya dado.
  • Una marca sin tipografía. Elige una combinación del type-pairings.md de la carpeta de packs de marca y escríbela en el bloqueo de marca. No uses Inter por defecto.

Enter y exit tienen diferentes vocabularios de animación, y templates/text-overlays.schema.json es la autoridad en ambos. Una toma puede llevar más de una superposición; enumera cada id en el array on_screen_text de esa toma, o las superposiciones adicionales no se renderizarán en ningún lado.

Paso 6. Bloquear la serie

Define los anclajes de entorno, iluminación y personaje que se aplican en cada toma. Estos van al principio de shots.json bajo series_lock. Sin estos, la generación de imágenes producirá fotogramas incoherentes.

Paso 7. Escribir la justificación

Cada toma tiene una justificación de una oración. Por qué este beat. Por qué este encuadre. Por qué este texto en pantalla. Esta es la pista de auditoría. No la omitas.

Paso 8. Instantánea del bloqueo de marca

Copia el archivo de bloqueo de marca (o plantilla) en la salida como brand-lock.snapshot.md. Añade estos dos comentarios al principio, en este orden:

<!-- instantánea tomada: 2026-05-07T14:23:00Z -->
<!-- fuente: brand-packs/whystrohm.md -->

La marca de tiempo es un instante UTC completo, YYYY-MM-DDThh:mm:ssZ. Una fecha simple no puede distinguir dos ejecuciones realizadas el mismo día, que es el caso que importa. La fuente es la ruta desde la que se copió, o la cadena literal template default para una ejecución no configurada. Después de una instalación, una ruta de pack es ~/.claude/shotkit-brand-packs/whystrohm.md; desde un clon del repositorio es brand-packs/whystrohm.md. Cualquiera de las dos pasa el validador. Los comentarios adicionales después de estos dos están bien.

validate_brand_lock.py --snapshot <ruta> verifica ambas líneas. Ejecútalo:

~/.claude/shotkit-tools/sk validate_brand_lock.py --snapshot output/brand-lock.snapshot.md
# desde un clon del repositorio:
# tools/sk validate_brand_lock.py --snapshot output/brand-lock.snapshot.md

Paso 9. Escribir run.json

Último paso, después de que los otros cuatro archivos estén finalizados. Completa templates/run.schema.json. Estos campos son obligatorios:

CampoValor
version"1.0", el formato de run.json
run_idmarca de tiempo UTC compacta, un guión, 8 caracteres hexadecimales (abajo)
created_atel mismo instante como YYYY-MM-DDThh:mm:ssZ
shotkit_versionlínea 1 de ~/.claude/shotkit-tools/VERSION; en un clon del repositorio, VERSION en la raíz
projecttitle, duration_s y aspect de shots.json, más framework y seed si se establecen
inputs.shots_ref, inputs.shots_sha256shots.json y su SHA-256
inputs.text_overlays_ref, inputs.text_overlays_sha256text-overlays.json y su SHA-256, o ambos null sin texto en pantalla
inputs.brand_lock_ref, inputs.brand_lock_sha256brand-lock.snapshot.md y su SHA-256
inputs.brand_lock_sourceel pack del que se copió, o template default

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

head -n 1 ~/.claude/shotkit-tools/VERSION     # desde un clon del repositorio: head -n 1 VERSION
shasum -a 256 output/shots.json output/text-overlays.json output/brand-lock.snapshot.md

run_id es la marca de tiempo UTC compacta, un guión, luego 8 caracteres hexadecimales, por ejemplo 20260730T142300Z-9f2c1ab4. El sufijo hexadecimal es lo que evita que dos operadores que inician una ejecución en el mismo segundo colisionen. Establece brand_lock_configured: false cuando la instantánea sea una plantilla sin completar.

Deja rounds vacío. Todo en run.json, excepto rounds, se escribe una vez y nunca se edita. rounds es de solo añadido: visual-prompt-forge añade una entrada por ronda de prompts y nunca cambia una anterior.

Formatos de salida

storyboard.md

Un encabezado por sección, en este orden: el brief tal como se dio, las suposiciones que hiciste, el marco y por qué, el bloqueo de serie, luego un bloque por toma (id, beat, tiempo, cámara, sujeto, texto en pantalla, VO, justificación), luego el guion de VO completo si lo hay. templates/storyboard.md.tpl tiene el diseño exacto si lo deseas.

shots.json

Debe validarse contra templates/shots.schema.json. La estructura es:

{
  "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": "...",
      "lighting_ref": "...",
      "on_screen_text": null,
      "vo": "...",
      "rationale": "..."
    }
  ]
}

Individual skills in this repo

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

Skills relacionados