Communitygithub.com

TheMattBerman/shortform-idea-engine

Motor de ideación de videos cortos de principio a fin. Descubre videos cortos excepcionales por palabra clave de nicho o handles de competidores, los decodifica, los remezcla en ideas que encajan con la marca, las clasifica por potencial viral y ajuste a la marca, y escribe los guiones de las mejores.

¿Qué es shortform-idea-engine?

Este skill es un pipeline completo de investigación a guion para la creación de contenido de video corto. Su propósito es ayudar a creadores y marcas a descubrir qué tipo de videos cortos están funcionando excepcionalmente bien en un nicho específico, entender por qué funcionan, y generar ideas propias que se puedan grabar de inmediato. El skill funciona en múltiples etapas: primero descubre videos excepcionales de competidores usando palabras clave o handles (identificadores de usuario) en plataformas como Instagram, TikTok y YouTube; luego extrae sus transcripciones y miniaturas; después decodifica los elementos que los hacen virales (gancho visual, gancho escrito, gancho hablado, vector viral, tema de interés, formato); realiza un análisis profundo opcional usando Gemini de OpenRouter para evaluar ritmo, estilo visual y dispositivos de retención; genera entre 10 y 15 ideas remezcladas que se alinean con la marca; las clasifica usando una rúbrica que combina potencial viral y ajuste a la marca; y finalmente escribe guiones listos para producción. Este skill es ideal para sesiones de brainstorming de contenido, análisis de competidores y creación de un pipeline de ideas para Reels, TikTok o Shorts. Requiere tres claves API: VIRLO_API_KEY, SCRAPECREATORS_API_KEY y OPENROUTER_API_KEY, y maneja la degradación elegante si alguna falta.

Compatible con✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/TheMattBerman/shortform-idea-engine/tree/HEAD/skills/shortform-idea-engine

Preguntar en tu IA favorita

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

Documentación

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).

DependenciaRol 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 skillEtapas 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 skillEtapa 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 faltanteEfecto
VIRLO_API_KEYEl modo palabra clave está deshabilitado. El modo handles aún funciona. Indica esto claramente en la Etapa 0.
OPENROUTER_API_KEYLa 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_KEYEl 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:

  1. Modo: modo palabra clave (descubrir videos por palabra clave de nicho) o modo handles (analizar handles de competidores específicos).
  2. 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 skill brand-profiler incluido, 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.
  3. Run slug: una etiqueta corta en minúsculas para esta sesión (ej. ai-tools-keyword o techcreator-handles). Se usa para nombrar la carpeta de la ejecución.
  4. 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 scrape para 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 skill scrape para 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, audience y proof_credibility del perfil de marca para anclar el ángulo).
  • Registrar el linaje fuente de cada elemento prestado: el creator_handle, source_url y video_id del 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:

  1. Verifica cada idea contra la lista de anti_topics del 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 de 02-ideas.md, debajo de la tabla clasificada, enumerando la idea y el anti-topic específico que provocó.
  2. 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) y brand_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.
  3. Calcula combined = viral_potential * (brand_fit / 10). Redondea a un decimal.
  4. Ordena descendente por combined. Cuando dos ideas empaten, la que tenga mayor viral_potential se clasifica primero.
  5. Escribe la tabla clasificada en 02-ideas.md en este orden de columnas: # | idea | raíz | VV/IT/Formato prestados | video fuente | viral | brand fit | combinado | resumen de una línea. La celda video fuente muestra 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)

Skills relacionados