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 total | Sí | Preguntar |
| Relación de aspecto | Sí | Preguntar (16:9, 9:16, 1:1) |
| Marco de beats | No | Sugerir según el brief |
| Ruta del archivo de bloqueo de marca | No | Usar ~/.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) | No | Preguntar si no está claro |
| Generador(es) objetivo para prompts posteriores | No | Anotar como "por especificar" |
Hallazgos de auditoría, brand/audit-findings.json de whystrohm-audit | No | Omitir 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.mdpara un marco que no conozcas de memoria,references/timing-rules.mdcuando el brief y la duración no coincidan,references/on-screen-text.mdcuando 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_gapses candidata para el beat de dolor o del mundo: el problema que responde el vídeo. rewrite.afteres 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_aten la sección de Brief destoryboard.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 tomastart/end, marcas de tiempo en segundos, se permite decimal.enddebe ser posterior astartframing, ECU / CU / MCU / MS / MLS / WS / EWSangle, eye-level / high / low / overhead / dutchmotion, 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 yreferences/shot-grammar.mdexplica cuándo cada uno vale la penadepth_of_field, opcional, shallow / deep / racksubject, lo que está en el encuadre, estructuradoenvironment_ref, referencia al lenguaje del bloqueo de serie, por defectoseries_lock.environmentlighting_ref, referencia al lenguaje del bloqueo de serie, por defectoseries_lock.lightingon_screen_text, nulo, un id de superposición de texto, O un array de ids cuando una toma lleva más de una superposiciónvo, línea de voz en off, o nulorationale, 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 superponecontent, el texto realfont, referencia a la tipografía del bloqueo de marcaposition,center,lower-third,upper-third,left-third,right-third, o{x, y}porcentajessize,display,headline,body,captionweight,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 unkickero unlockup, y usa unplatedonde el encuadre esté ocupado. Los campos y cuándo usar cada uno están enreferences/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.mdde 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:
| Campo | Valor |
|---|---|
version | "1.0", el formato de run.json |
run_id | marca de tiempo UTC compacta, un guión, 8 caracteres hexadecimales (abajo) |
created_at | el mismo instante como YYYY-MM-DDThh:mm:ssZ |
shotkit_version | línea 1 de ~/.claude/shotkit-tools/VERSION; en un clon del repositorio, VERSION en la raíz |
project | title, duration_s y aspect de shots.json, más framework y seed si se establecen |
inputs.shots_ref, inputs.shots_sha256 | shots.json y su SHA-256 |
inputs.text_overlays_ref, inputs.text_overlays_sha256 | text-overlays.json y su SHA-256, o ambos null sin texto en pantalla |
inputs.brand_lock_ref, inputs.brand_lock_sha256 | brand-lock.snapshot.md y su SHA-256 |
inputs.brand_lock_source | el 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": "..."
}
]
}