AIBit-Descubre proyectos de código abierto AIBit-Descubre proyectos de código abierto

Narrator AI CLI Skill: permite que los AI Agent generen automáticamente vídeos de narración cinematográfica

Narrator AI CLI Skill convierte la búsqueda de películas, la generación de guiones, la locución, la música y la composición de vídeo en un flujo de trabajo de Agent invocable.

Narrator AI CLI Skill: permite que los AI Agent generen automáticamente vídeos de narración cinematográfica

Crear un vídeo de narración cinematográfica suele requerir completar múltiples etapas, como buscar material de la película, seleccionar una plantilla, redactar el texto, generar la locución, añadir música de fondo, editar el vídeo y exportar el resultado final. Para los desarrolladores, lo realmente complicado no es ejecutar cada paso por separado, sino conectar todas estas etapas de forma estable en una cadena reproducible y automatizable.

NarratorAI-Studio/narrator-ai-cli-skill ofrece una solución orientada a AI Agent: mediante las instrucciones legibles por máquina de SKILL.md y references/, expone las capacidades de narrator-ai-cli a herramientas como OpenClaw, Claude Code, Cursor, Windsurf y WorkBuddy. Una vez instalado, el usuario puede expresar sus necesidades en lenguaje natural y el Agent se encarga de invocar las herramientas de línea de comandos para completar la producción del vídeo de principio a fin.

¿Qué problema resuelve?

Este proyecto no es otro editor de vídeo independiente, sino una capa de adaptación entre el Agent y la CLI.

  • La CLI es la capa de ejecución: proporciona comandos ejecutables para buscar recursos, generar guiones, crear tareas y componer vídeos.
  • El Skill es la capa de decisión: indica al Agent cuándo debe utilizar cada comando, cómo pasar los parámetros, cómo convertir la salida de un paso en la entrada del siguiente y cómo actuar cuando se producen errores.

Se pueden entender como las herramientas y la receta de una cocina: si solo existen las herramientas, el Agent no sabe cuál es el orden correcto de las operaciones; si solo existe la receta, no hay una CLI que ejecute realmente el proceso. Al combinar ambas, el Agent puede convertir «hacer un vídeo de narración cinematográfica» en una serie de llamadas fiables a API y tareas.

Una solicitud típica puede ser muy sencilla:

Create a narration video for The Shawshank Redemption in a comedy style.

El Agent intentará completar el siguiente flujo: buscar la película, seleccionar una plantilla de narración, elegir la música de fondo y la voz, generar el guion, componer el vídeo y, finalmente, devolver un enlace de descarga.

Instalación rápida

1. Instalar la CLI

El proyecto requiere narrator-ai-cli 1.0.0 o una versión posterior. Se puede instalar directamente desde el repositorio de Git:

pip install "narrator-ai-cli @ git+https://github.com/NarratorAI-Studio/narrator-ai-cli.git"

También se necesita Python 3.10+ y las siguientes dependencias:

  • typer
  • httpx[socks]
  • httpx-sse
  • pyyaml
  • rich

2. Configurar la API Key

Después de la instalación, escribe la clave de aplicación en la configuración de la CLI:

narrator-ai-cli config set app_key <your_app_key>

También puedes configurar NARRATOR_APP_KEY según los requisitos del entorno del Agent. Para obtener la API Key, debes ponerte en contacto con los mantenedores del proyecto; el README del repositorio proporciona un correo electrónico y datos de contacto de WeChat.

3. Instalar el Skill

No basta con copiar únicamente el archivo SKILL.md. El directorio references/ contiene tablas de recursos, descripciones de flujos de trabajo, guías operativas y documentación sobre las capacidades de vídeo, por lo que debe conservarse junto con SKILL.md.

OpenClaw

mkdir -p ~/.openclaw/skills
git clone https://github.com/NarratorAI-Studio/narrator-ai-cli-skill.git \\
  ~/.openclaw/skills/narrator-ai-cli

Windsurf o Claude Code

mkdir -p /path/to/your/project/.skills
git clone https://github.com/NarratorAI-Studio/narrator-ai-cli-skill.git \\
  /path/to/your/project/.skills/narrator-ai-cli

Cursor

mkdir -p /path/to/your/project/.cursor/rules
git clone https://github.com/NarratorAI-Studio/narrator-ai-cli-skill.git \\
  /path/to/your/project/.cursor/rules/narrator-ai-cli

Otros Agent compatibles con la lectura de Skills en Markdown también pueden clonar el repositorio en su directorio de skills y hacer que el Agent apunte a SKILL.md. En WorkBuddy y QClaw es necesario subir SKILL.md junto con la carpeta completa references/ desde la interfaz de gestión de skills; no se deben aplanar los archivos de referencia en el mismo nivel.

Para actualizarlo, entra en el directorio clonado y ejecuta:

git pull

¿Qué se puede hacer después de la instalación?

Una vez completada la configuración, puedes iniciar tareas directamente en lenguaje natural, por ejemplo:

Create a narration video for The Shawshank Redemption

Show me what movies are available

Make 5 narration videos for different action movies

Use a comedy template and generate a narration

En las tareas por lotes, el valor del Skill resulta especialmente evidente: el Agent puede repetir los pasos de selección de recursos, generación de guiones y composición, en lugar de pedir al usuario que copie manualmente los parámetros de cada tarea.

Dos flujos de trabajo principales

El Skill divide el proceso creativo en dos rutas:

Fast Path: Original Narration

Está pensado para crear contenido de narración original desde cero. Normalmente, el Agent genera un nuevo guion narrativo basándose en un tema o una película y después completa la locución, la música y la composición del vídeo. Esta ruta es más adecuada para montajes originales, nuevas tramas o expresiones estilizadas.

Standard Path: Adapted Narration

Está pensada para adaptar películas o materiales existentes a una narración. El Agent primero busca películas y recursos disponibles, después genera el contenido narrativo según la plantilla seleccionada y, por último, inicia el proceso de producción del vídeo.

El SKILL.md del repositorio describe claramente los pasos, parámetros y relaciones entre las salidas de ambas rutas, y destaca especialmente detalles propensos a errores, como los parámetros de composición de vídeo y la selección de rutas en Fast Path.

Recursos y capacidades integrados

El proyecto ofrece un conjunto relativamente completo de recursos para la producción de contenido:

  • Aproximadamente 100 películas
  • 146 pistas de música de fondo
  • 63 voces de narración
  • Más de 90 plantillas de narración
  • Tres modos creativos: Hot Drama, Original Mix y New Drama
  • Flujos de trabajo de narración adaptada y narración original
  • Generación de guiones, generación de datos de fragmentos, composición de vídeos y selección de plantillas visuales
  • Tareas independientes de clonación de voz y conversión de texto a voz

Esto significa que el Agent no se limita a «llamar a una interfaz de generación de vídeos», sino que puede seguir reglas claras durante la selección de recursos. Por ejemplo, primero determina el tipo de narración, después selecciona la plantilla y la voz adecuadas, comprueba el presupuesto, crea la tarea, consulta periódicamente su estado y, finalmente, procesa el archivo de vídeo o el enlace de descarga.

¿Por qué es importante SKILL.md?

SKILL.md es el núcleo de todo el proyecto. No solo describe los nombres de los comandos, sino que también define cómo debe razonar y ejecutar las tareas el Agent. Incluye principalmente:

  • Metadatos del Skill y requisitos de ejecución
  • Índice de archivos de references/
  • Diagramas de los flujos Fast Path y Standard Path
  • Reglas de confirmación previas a la ejecución
  • Cadena de procesamiento de idiomas y patrón de consulta periódica de tareas
  • Conceptos clave como file_id, task_id y task_order_num
  • Flujo de inicio de sesión y evaluación de requisitos
  • Orden de selección de la música de fondo, la voz y las plantillas
  • Flujos independientes de clonación de voz y TTS
  • 18 códigos de error de API y recomendaciones de tratamiento correspondientes
  • Estimación de costes y validación del presupuesto antes de crear tareas
  • Consideraciones de privacidad relacionadas con el procesamiento de archivos, las direcciones de API y el alcance de las credenciales

Para los desarrolladores, esta estructura es más fiable que introducir simplemente un conjunto de comandos en el contexto del Agent. Un flujo de datos explícito reduce los problemas causados por no pasar la salida del paso anterior al siguiente, mientras que las reglas de gestión de errores permiten al Agent actuar de forma predecible cuando falla una tarea, en lugar de reintentar a ciegas.

¿Qué debe tenerse en cuenta en una ejecución fiable?

La generación de vídeo suele realizarse mediante tareas asíncronas, por lo que llamar a la interfaz de creación no significa que el vídeo ya esté terminado. Un flujo de trabajo robusto del Agent debería:

  1. Confirmar los requisitos del usuario sobre la película, el estilo, el idioma y la cantidad.
  2. Elegir Fast Path o Standard Path según el tipo de tarea.
  3. Consultar las películas, plantillas, voces y BGM disponibles.
  4. Estimar el coste y confirmar el presupuesto antes de crear la tarea.
  5. Guardar identificadores clave como file_id y task_id.
  6. Consultar el estado de la tarea a intervalos establecidos, en lugar de enviar solicitudes continuamente y a alta frecuencia.
  7. Aplicar correcciones, reintentos o solicitar confirmación manual según el código de error de la API.
  8. Devolver el archivo de vídeo o el enlace de descarga cuando finalice la tarea.

Estas reglas son especialmente importantes para la generación por lotes, ya que varias tareas de vídeo pueden estar en cola al mismo tiempo. La pérdida de cualquier identificador intermedio puede impedir que continúe la composición posterior.

Compatibilidad con plataformas

Las plataformas verificadas o declaradas como compatibles por el repositorio incluyen:

  • OpenClaw
  • Windsurf
  • WorkBuddy
  • QClaw
  • Youdao Lobster
  • Yuanqi AI
  • Claude Code
  • Cursor
  • Otros Agent capaces de leer Skills en Markdown

La ubicación de instalación varía según la plataforma, pero el principio fundamental es el mismo: permitir que el Agent encuentre SKILL.md y conservar sin cambios la estructura de directorios relativa de references/.

¿Para qué escenarios es adecuado?

Narrator AI CLI Skill resulta especialmente adecuado para los siguientes escenarios de desarrollo y producción de contenido:

  • Crear cuentas automatizadas de narración cinematográfica
  • Generar vídeos cortos por lotes con distintos estilos
  • Añadir capacidades de producción de vídeo a un Agent
  • Validar flujos de trabajo multimedia de API con varios pasos
  • Integrar herramientas de línea de comandos con Claude Code u OpenClaw
  • Integrar la clonación de voz, el TTS y la composición de vídeo en un mismo flujo

También puede servir como caso práctico de ingeniería de Agent Skill: separa las capacidades de las herramientas, los índices de recursos, las descripciones de parámetros, la gestión de errores y las consideraciones de seguridad en una capa documental mantenible, en lugar de escribir toda la lógica en un único prompt.

Conclusión

El valor principal de Narrator AI CLI Skill reside en organizar las complejas API de producción de vídeo en un flujo de trabajo que los Agent pueden comprender y ejecutar. narrator-ai-cli se encarga de la ejecución real, mientras que SKILL.md proporciona el contexto, las reglas de decisión y la descripción del flujo de datos. Al combinar ambos, el usuario solo tiene que describir el objetivo y el Agent puede completar una tarea de varios pasos, desde la selección del material hasta la entrega del vídeo final.

El proyecto utiliza la licencia MIT y actualmente ofrece la versión inicial v1.0.0. Para los desarrolladores que quieran dotar a Claude Code, OpenClaw, Cursor u otros Agent basados en Markdown de capacidades de creación de vídeo, se trata de una solución de integración de código abierto que merece la pena estudiar y probar.

Fuente

NarratorAI-Studio/narrator-ai-cli-skill: AI 解说大师 — Agent skill；封装 narrator-ai-cli 供 Claude/Codex 等工具调用