Motor de Ideas para Videos Cortos
Pipeline de investigación a guion que convierte videos excepcionales de competidores en ideas clasificadas y guiones listos para producir para tu marca.
Cuándo usarlo
Usa este skill cuando el usuario quiera un pipeline de ideas de video corto: descubrir qué está ganando en un nicho, entender por qué, generar ideas remezcladas y recibir guiones listos para grabar.
No lo uses para:
- Un video conocido que el usuario quiere decodificar: redirige a
video-decoder. - Una idea que el usuario ya tiene y quiere que se le escriba un guion: redirige a
script-writer.
Dependencias
Este es un plugin autónomo. Incluye todos los sub-skills y el script auxiliar de Gemini. No requiere un entorno de skills compartido. Los requisitos externos son tres claves API (ver sección siguiente).
| Dependencia | Rol en este skill |
|---|---|
virlo skill (incluido) | Etapa 1 modo palabra clave: descubre videos excepcionales de formato corto por palabra clave de nicho en Instagram, TikTok y YouTube |
scrape skill (incluido) | Etapa 1 modo handles, Etapa 2 y resolución de URL CDN en Etapa 4: obtiene publicaciones recientes, transcripciones, miniaturas y URLs de medios directas a través de la API de ScrapeCreators |
video-decoder skill | Etapas 3 y 4: decodifica cada video excepcional en un Registro de Decodificación completo (gancho visual, gancho escrito, gancho hablado, raíz, VV, IT, Formato) |
script-writer skill | Etapa 7: escribe un guion listo para producción por cada idea aprobada |
brand-profiler skill (incluido) | Etapa 0: construye un nuevo perfil de marca cuando no existe ninguno, recopilando todos los campos del esquema, incluyendo voice_tone |
scripts/gemini-video-analyze.js (incluido) | Etapa 4 pasada profunda: ejecuta análisis visual (ritmo, patrón de cortes, estilo visual, dispositivos de retención, cadencia de texto en pantalla) a través de OpenRouter Gemini |
Claves API y degradación elegante
Claves requeridas: VIRLO_API_KEY, SCRAPECREATORS_API_KEY, OPENROUTER_API_KEY.
Cárgalas en la Etapa 0 antes de cualquier gasto:
source .env
Reglas de degradación:
| Clave faltante | Efecto |
|---|---|
VIRLO_API_KEY | El modo palabra clave está deshabilitado. El modo handles aún funciona. Indica esto claramente en la Etapa 0. |
OPENROUTER_API_KEY | La Etapa 4 (pasada profunda) se omite por completo. Todas las decodificaciones quedan como shallow. Las ideas derivadas de decodificaciones superficiales se marcan como "shallow-decoded" en la tabla clasificada. |
SCRAPECREATORS_API_KEY | El motor no puede ejecutarse. ScrapeCreators es necesario para las transcripciones y miniaturas en todos los modos. Detente en la Etapa 0 e informa claramente al usuario. |
Pipeline
Etapa 0: Entrada de datos
Pregunta al usuario por:
- Modo: modo palabra clave (descubrir videos por palabra clave de nicho) o modo handles (analizar handles de competidores específicos).
- Ruta del perfil de marca: la ruta a un perfil de marca completo que siga
references/brand-profile-template.md. Si no existe ninguno, ofrece construir uno encadenando al skillbrand-profilerincluido, que recopila todos los campos del esquema (voice_tone,audience,positioning,content_pillars,anti_topics,forbidden_constructions,proof_credibility,format_preferences,on_camera_talent) de forma interactiva o a partir de un documento de marca existente. - Run slug: una etiqueta corta en minúsculas para esta sesión (ej.
ai-tools-keywordotechcreator-handles). Se usa para nombrar la carpeta de la ejecución. - Ruta base de la ejecución: dónde se debe escribir la carpeta de la ejecución. La base predeterminada es
./shortform-runs/relativa al directorio de trabajo actual, lo que produce./shortform-runs/YYYY-MM-DD-<slug>/. Si la sesión se ejecuta dentro de un proyecto estructurado que tiene su propia área de investigación o salida, pregunta al usuario si se debe colocar la ejecución allí en su lugar. Confirma la ruta base resuelta con el usuario antes de escribir cualquier archivo.
Verifica las tres claves API. Informa qué modos están disponibles antes de gastar créditos. Crea la carpeta de la ejecución en la ruta base confirmada (ej. <base>/YYYY-MM-DD-<slug>/) y escribe 00-intake.md con el modo, la consulta o lista de handles, el nombre del archivo de perfil de marca utilizado, la ruta base de la ejecución, las claves disponibles y cualquier anulación.
Etapa 1: Descubrimiento
Modo palabra clave. Invoca el skill virlo para descubrir videos cortos excepcionales para la palabra clave de nicho. Ejecuta el descubrimiento en los tres anillos de competidores definidos en video-decoder/references/decode-framework.md:
- Anillo directo: la palabra clave de nicho exacta tal cual.
- Anillo indirecto: frases de palabras clave adyacentes a la audiencia (misma audiencia, diferente ángulo temático).
- Anillo adyacente: frases de palabras clave adyacentes en formato (mismo formato o estilo de producción, diferente tema).
Invoca el skill virlo un anillo a la vez, pasando la etiqueta del anillo y la frase de palabra clave para ese anillo. No invoques virlo para múltiples anillos simultáneamente. El skill virlo gestiona toda la mecánica de órbita: primero verifica si existe un Comet que cubra la palabra clave del anillo y reutiliza sus datos acumulados (gratis) cuando uno está disponible, y solo lanza una Órbita nueva (costo: $0.50) para anillos sin un Comet coincidente. La responsabilidad del orquestador es la secuenciación: esperar a que virlo devuelva la lista clasificada de excepcionales para un anillo antes de invocar virlo para el siguiente anillo.
Después de que virlo devuelva resultados para un anillo, calcula la magnitud de excepcionalidad por video. Los resultados de virlo incluyen una relación de excepcionalidad a nivel de creador, pero el orquestador necesita una relación por video para la Etapa 4 y la rúbrica de clasificación de la Etapa 6. Para cada creador único que aparece en los resultados del anillo, invoca el skill scrape para obtener las publicaciones recientes de ese creador (aproximadamente las últimas 20) en la plataforma relevante. Usa las publicaciones devueltas para calcular un recuento de visitas medio de referencia para ese creador. Luego calcula la relación de excepcionalidad de cada video como video_views / creator_median_views. Guarda las respuestas JSON sin procesar en raw/ para cada anillo y para cada obtención de referencia.
Modo handles. Invoca el skill scrape para obtener las publicaciones recientes (aproximadamente las últimas 20) para cada handle en la plataforma relevante. Para cada handle, calcula el recuento de visitas medio entre las publicaciones devueltas. Conserva solo las publicaciones que superen la media de ese creador en 2x o más (umbral de excepcionalidad). Guarda el JSON sin procesar en raw/.
Si un handle produce cero publicaciones por encima del umbral de 2x (creador de baja varianza), incluye la publicación reciente de mejor rendimiento de ese creador de todos modos. Anota en 00-intake.md que el handle no tenía un excepcional claro y que se incluyó la mejor publicación como alternativa.
En ambos modos, la salida de la Etapa 1 es una lista desduplicada de videos excepcionales con su URL de origen, plataforma, handle del creador y recuento de visitas.
Etapa 2: Recopilación de datos
Para cada video excepcional, invoca el skill scrape para recopilar:
- Transcripción: para YouTube, invoca el skill
scrapepara obtener la transcripción por URL de video. Para TikTok e Instagram, intenta extraer el texto de la transcripción del payload de publicaciones ya obtenido en la Etapa 1. Si el payload de publicaciones no contiene transcripción para un video, invoca la función de transcripción del skillscrapepara esa URL de video como alternativa antes de pasar el video a la Etapa 3. - Miniatura: la URL de la miniatura devuelta en el payload de publicaciones. Para YouTube, deriva la miniatura como
https://img.youtube.com/vi/[VIDEO_ID]/hqdefault.jpg.
Guarda todas las respuestas sin procesar en raw/ nombradas por fuente y marca de tiempo (ej. scrapecreators-transcript-[video_id]-[timestamp].json). Cada recuento de visitas y cifra de participación utilizada posteriormente debe rastrearse hasta un archivo en raw/.
Etapa 3: Decodificación
Ejecuta el skill video-decoder en cada video excepcional. Pasa: el texto de la transcripción (si está disponible), la URL de la miniatura (si está disponible), el handle del creador, la plataforma, la magnitud de excepcionalidad (relación calculada en la Etapa 1) y la asignación del anillo de competidores (clasifica el anillo de cada video en relación con la marca usando las definiciones de anillo en video-decoder/references/decode-framework.md).
El skill video-decoder devuelve un Registro de Decodificación completo por video, incluyendo el gancho visual (derivado de la miniatura y cualquier texto visible en pantalla), gancho escrito y gancho hablado. Escribe cada registro en 01-decodes/[video_id].md. En este punto, todas las decodificaciones tienen decode_depth: shallow.
La falta de una transcripción por sí sola NO es una razón para saltarse un video. Muchos de los videos con mayor excepcionalidad son videos de superposición de texto o estilo POV sin contenido hablado. Si el video tiene una miniatura o un pie de foto, decodifícalo superficialmente con spoken_hook: n/a. Salta un video solo cuando no haya absolutamente nada que decodificar: sin transcripción, sin miniatura, sin pie de foto Y sin otra señal significativa (ej. un error de obtención grave sin nada recuperable). Registra cualquier video saltado como decode-failed en 00-intake.md con la URL del video y la razón exacta. Continúa procesando los videos restantes.
Etapa 4: Pasada profunda
Selecciona los 5 a 8 mejores excepcionales clasificados por magnitud de excepcionalidad (mayor relación primero).
Antes de llamar al auxiliar de Gemini para cualquier video, resuelve la URL de medios CDN directa para ese video usando el skill scrape. Una URL de página social (ej. una URL de página de TikTok o Instagram) es rechazada por Gemini. Pasa la URL de medios CDN al auxiliar, nunca la URL de la página social. El método de resolución difiere según la plataforma: consulta scrape/references/reading-scrape.md bajo "Resolviendo una URL de medios directa para video" para el enfoque por plataforma (TikTok requiere una búsqueda de información de video; las URLs de medios de Instagram están en el payload de publicaciones ya obtenido; las URLs de watch de YouTube pasan directamente). Resuelve y usa las URLs CDN rápidamente durante la ejecución, ya que las URLs CDN caducan.
Para cada video seleccionado, llama al auxiliar de Gemini y redirige stdout directamente al archivo sin procesar en un solo comando.
La ruta del auxiliar debe resolverse como una ruta absoluta desde el directorio que contiene este SKILL.md (el directorio del skill shortform-idea-engine dentro del plugin instalado). Determina ese directorio en tiempo de ejecución y construye la ruta absoluta a scripts/gemini-video-analyze.js dentro de él. La redirección de salida apunta a la carpeta de ejecución bajo la ruta base confirmada en la Etapa 0. Estas dos rutas se resuelven de forma independiente: el auxiliar desde el directorio del skill, la salida desde la ruta base de la ejecución.
OPENROUTER_API_KEY=<key> node <skill-dir>/scripts/gemini-video-analyze.js <cdnMediaUrl> "Analyze this short-form video for: pacing (average cut frequency, notable slow or fast segments), cut rhythm (pattern of cuts: cut-on-beat, reaction cuts, b-roll intercuts), visual style (color grading, background, camera movement, on-screen graphic density), text-on-screen cadence (how often captions or callouts appear relative to spoken content), and retention devices (specific hooks, pattern interrupts, cliffhangers, or loops used mid-video). Return structured notes for each dimension." > <run-base>/YYYY-MM-DD-<slug>/raw/gemini-<video_id>-<timestamp>.json
Donde <skill-dir> es la ruta absoluta al directorio del skill shortform-idea-engine (el directorio que contiene este SKILL.md) y <run-base>/YYYY-MM-DD-<slug>/ es la carpeta de ejecución confirmada en la Etapa 0.
La redirección guarda la respuesta sin procesar de Gemini en raw/gemini-<video_id>-<timestamp>.json dentro de la carpeta de ejecución para que se pueda satisfacer la trazabilidad de la Etapa 8.
Vuelve a ejecutar el skill video-decoder para cada uno de estos videos, pasando el bloque de Gemini como la entrada opcional de análisis profundo. La re-ejecución devuelve un Registro de Decodificación actualizado con decode_depth: deep y deep_notes completados. Sobrescribe el archivo 01-decodes/[video_id].md existente con el registro profundo.
Omite la Etapa 4 por completo si OPENROUTER_API_KEY no está configurada. Todas las decodificaciones permanecen como shallow y la bandera "shallow-decoded" se anota por idea en la Etapa 6.
Etapa 5: Ideación
Agrupa todos los Vectores Virales, Temas de Interés y Formatos de cada Registro de Decodificación en 01-decodes/. Genera de 10 a 15 ideas remezcladas. Cada idea debe:
- Nombrar qué Vector Viral toma prestado (etiqueta textual del Registro de Decodificación).
- Nombrar qué Tema de Interés toma prestado o adapta.
- Nombrar qué Formato utiliza.
- Indicar el ángulo de la marca: cómo el VV, IT y Formato prestados se remezclan para adaptarse a esta marca específica (usa los campos
content_pillars,audienceyproof_credibilitydel perfil de marca para anclar el ángulo). - Registrar el linaje fuente de cada elemento prestado: el
creator_handle,source_urlyvideo_iddel Registro (o Registros) de Decodificación del que se extrajo el elemento. Si un elemento aparece en más de un Registro de Decodificación, enuméralos todos. Este linaje viaja con la idea a través de la clasificación y hasta el guion.
Aquí se aplican los pesos de señal de extracción por anillo (de video-decoder/references/decode-framework.md): los VV son válidos de los cuatro anillos; los IT tienen la mayor señal de competidores indirectos; los formatos tienen la mayor señal de competidores adyacentes. Pondera tu remezcla en consecuencia, pero no excluyas ideas mecánicamente solo por el anillo.
Si el grupo de decodificación es demasiado pequeño para respaldar 10 ideas distintas sin inventar combinaciones de VV, IT o Formato que no estén presentes en el grupo, genera solo tantas ideas genuinas como el grupo pueda soportar. Anota la deficiencia y el número real al principio de 02-ideas.md. Nunca inventes extractables que no fueron decodificados.
Etapa 6: Clasificación
Puntúa cada idea usando references/ranking-rubric.md:
- Verifica cada idea contra la lista de
anti_topicsdel perfil de marca. Cualquier coincidencia es una descalificación inmediata (DQ: anti-topic). Elimina las ideas descalificadas de la tabla clasificada. Añade cada idea descalificada a una sección claramente etiquetada "Descalificadas (anti-topic)" al final de02-ideas.md, debajo de la tabla clasificada, enumerando la idea y el anti-topic específico que provocó. - Puntúa las ideas supervivientes en dos ejes:
viral_potential(promedio de cinco subfactores: fortaleza del VV, magnitud de excepcionalidad, repetibilidad del formato, frescura del tema, fortaleza del gancho) ybrand_fit(promedio de cuatro subfactores: coincidencia de voz, coincidencia de audiencia, coincidencia de pilar de contenido, credibilidad auténtica). Ambas puntuaciones usan una escala de 1 a 10. - Calcula
combined = viral_potential * (brand_fit / 10). Redondea a un decimal. - Ordena descendente por
combined. Cuando dos ideas empaten, la que tenga mayorviral_potentialse clasifica primero. - Escribe la tabla clasificada en
02-ideas.mden este orden de columnas:# | idea | raíz | VV/IT/Formato prestados | video fuente | viral | brand fit | combinado | resumen de una línea. La celdavideo fuentemuestra el video fuente principal al que se remonta la idea como@creator_handle / video_id. Si la idea toma prestado
… (continuación omitida para traducción)