Noureddine RAMDI / how narratorai cli skill orchestrates ai agents for automated movie narration

Created Sat, 23 May 2026 20:41:14 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
1008 Words
github-stars ai cli automation video-narration ai-agents markdown

NarratorAI-Studio/narrator-ai-cli-skill

NarratorAI CLI Skill is an interesting example of how AI agents can be taught to orchestrate complex multimedia workflows through a simple, machine-readable skill definition. Instead of embedding logic directly into agents or software, this repo defines a SKILL.md file that acts as a “recipe book” for AI coding assistants like Claude Code, OpenClaw, Windsurf, Cursor, and others, enabling them to use the narrator-ai-cli tool to create automated movie narration videos.

what narratorai cli skill does and how it’s structured

At its core, the NarratorAI CLI Skill is a markdown-based skill file (SKILL.md) that encodes detailed workflow instructions, resource selection protocols, and error handling procedures for the narrator-ai-cli command-line tool. This tool automates the production of narrated movie videos by combining text-to-speech (TTS), background music (BGM), dubbing voices, and narration templates.

The repo embodies a “CLI is the hands, Skill is the brain” architecture: the CLI tool is the executor that performs video narration tasks, while the skill file contains the high-level workflow logic and resource management. This separation allows the skill to be portable and compatible with multiple AI agent platforms.

The skill supports two main narration pipelines:

  • Fast Path: For original narration videos, optimized for speed.
  • Standard Path: For adapted narration videos, which might include additional processing.

To support these pipelines, the SKILL.md file includes definitions and protocols to handle 18 different API error codes, ensuring robust error handling during video generation.

Additionally, the repo ships with a rich set of media resources:

  • References to about 100 movies
  • 146 background music tracks
  • 63 dubbing voices
  • Over 90 narration templates

These resources enable diverse and customizable narration experiences.

Compatibility is broad, with the skill verified to work across at least eight AI agent platforms, including OpenClaw, Windsurf, WorkBuddy, QClaw, and Claude Code. Installation is straightforward by cloning the repo directly into the agent’s skills directory.

technical strengths and design tradeoffs

The main strength lies in treating the skill file as a machine-readable instruction set that decouples workflow logic from the CLI implementation. This design allows AI agents to interpret and orchestrate complex narration workflows without embedding specialized code.

The skill’s explicit handling of many API error codes improves robustness, which is critical for automated video production pipelines where failures can be subtle and costly.

By providing two distinct pipeline paths, the repo addresses performance tradeoffs between fast, original narration and more complex adapted narration, allowing users to choose according to their needs.

The code and markdown workflow definitions are surprisingly clean and well structured, considering the complexity of the task. The use of markdown for defining workflows may feel unconventional, but it provides a human- and machine-readable format that fits well in a multi-agent environment.

A tradeoff is the reliance on the narrator-ai-cli tool and the skill format itself, which means users need to operate within the supported AI agent platforms and follow the skill conventions closely. This limits flexibility somewhat but enhances portability and consistency.

quick start

Step 1: Install the CLI tool

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

See narrator-ai-cli for detailed installation options.

Step 2: Configure API key

narrator-ai-cli config set app_key <your_app_key>

📧 Need an API key? Email merlinyang@gridltd.com or scan the QR code at the bottom of this page.

Step 3: Install the Skill

The skill consists of SKILL.md and the references/ directory — both are required. Clone the repo directly into your agent’s skills folder:

OpenClaw:

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

Windsurf / 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

Any markdown-reading agent:

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

WorkBuddy / QClaw (Tencent):

Upload SKILL.md and the entire references/ folder through the skill management UI, keeping the directory structure intact (references/ must remain a subfolder alongside SKILL.md — do not flatten the files).

💡 Tip: To update the skill later, just run git pull inside the cloned directory.

Step 4: Start talking!

Once installed, you can interact with the skill using natural language commands like:

  • “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”

verdict

NarratorAI CLI Skill is a practical demonstration of the “skills as software” paradigm, showing how a markdown skill file can turn a CLI tool into a multi-platform AI-powered video narration pipeline. It’s particularly relevant for developers building AI agents that need modular, reusable skills to orchestrate complex media workflows.

The architecture balances portability and robustness by handling many API edge cases and supporting multiple narration pipelines. However, its reliance on the narrator-ai-cli tool and adherence to a specific skill format means it fits best in environments where these tools and conventions are already adopted.

If you work with AI agents like Claude Code or OpenClaw and want to integrate automated movie narration into your workflows, this skill offers a clean, extensible starting point. The rich media references and templates also make it useful for experimenting with different narration styles and voices.

Overall, the repo offers a well-structured approach to combining AI agents, CLI tooling, and markdown-defined workflows for real-world automation in video narration.

→ GitHub Repo: NarratorAI-Studio/narrator-ai-cli-skill ⭐ 637