Narrator AI CLI Skill: Teaching an Agent to Run the narrator-ai-cli Video Pipeline

What the skill actually adds on top of narrator-ai-cli

The repository is not a video tool. It is a capability description: a SKILL.md file plus a references/ directory that an AI agent reads so it knows which narrator-ai-cli commands to run, in what order, with which parameters. The README draws the line plainly, calling the CLI the hands and the skill the brain. The CLI works alone in a terminal; the skill does not work without the CLI.

That framing matters for who this is for. If you already run narrator-ai-cli by hand, the skill removes the part where you memorize the sequence from movie search to template selection to BGM and voice choice to script generation to composing. The README's worked example is a single sentence from the user, "Create a narration video for Pegasus in a comedy style", expanded into that full chain. The audience is therefore narrow and specific: people using an agent that reads markdown skill files, and who have already cleared the API key requirement. Everyone else gets a document, not a tool.

How SKILL.md and references/ divide the work

The skill is split across two locations, and the README states both are required. SKILL.md holds the frontmatter, a reference index, an ASCII diagram of the Fast Path and Standard Path, mandatory agent rules, prerequisites, core concepts, and the step-by-step Fast Path and Standard Path procedures. The references/ directory holds the lookup tables the index points to: resources, workflows, magic-video and operations.

The division is deliberate. SKILL.md stays short enough to sit in context, and the agent pulls a lookup table only when the task needs it. The README warns against flattening the structure during upload: references/ must remain a subfolder alongside SKILL.md. That warning is the tell that the design depends on relative paths rather than a single concatenated prompt.

Two workflow paths run through the same data chain. Fast Path is Original Narration, Standard Path is Adapted Narration. Both end in script, clip data, video composing and visual template. The skill also documents which output feeds which input, and it carries all 18 API error codes with recommended actions plus a cost estimation step that checks budget before a task is created. That last item is the most operationally interesting part of the file: it is the skill's attempt to stop an agent from spending money before the user has agreed to the spend.

Installing narrator-ai-cli and the skill in Claude Code or Cursor

The skill is useless until the CLI exists on the machine and an app key is configured. Install the CLI from the git URL the README gives, then set the key with the config subcommand.

pip install "narrator-ai-cli @ git+https://github.com/NarratorAI-Studio/narrator-ai-cli.git"
narrator-ai-cli config set app_key <your_app_key>

The README says to email [email protected] for a key, so there is no self-service signup documented. Next, clone the skill into the folder your agent reads. For Claude Code the README points at the project .skills directory; for Cursor it points at .cursor/rules.

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

For Cursor, swap the destination for /path/to/your/project/.cursor/rules/narrator-ai-cli. OpenClaw uses ~/.openclaw/skills. WorkBuddy and QClaw do not take a clone at all: the README says to upload SKILL.md and the entire references/ folder through the skill management UI, keeping the directory structure intact.

After that, drive it in natural language. The README's examples include "Show me what movies are available" and "Make 5 narration videos for different action movies". The README also notes that the skill assumes narrator-ai-cli is installed and NARRATOR_APP_KEY is set, which is the environment variable the agent looks for. To update later, run git pull inside the cloned directory.

The API key is the real dependency, and the README does not hide it

Everything in this repository routes to a hosted service. The README's Data & Privacy section names an API endpoint and describes file handling and credential scope, so the pipeline is not local: script generation, clip data, composing and the visual template all run against the vendor's API. The built-in resources (roughly 100 movies, 146 BGM tracks, 63 dubbing voices, 90 or more narration templates) live on that side too.

The practical consequence is that the MIT licence covers the instruction files, not the service. Cloning the repo grants you no rendering capability. The README documents no offline mode, no local renderer and no way to point the CLI at your own backend. If the API key is missing or revoked, the agent reads SKILL.md, forms a plan, and fails at the first call. The skill's error handling covers the 18 API error codes, which is useful, but error handling is not a fallback path.

Cost estimation deserves the same scrutiny. The README lists budget verification before task creation as a feature, which implies tasks consume a metered budget. It does not document what happens when the estimate is wrong, and it does not document rollback. The README is silent on both.

What the skill does not solve

The skill is an instruction file, so its failure modes are agent failure modes. An agent that ignores the mandatory rules, or that does not confirm before acting, will run the pipeline with wrong parameters. The README's Agent Rules section exists precisely because the sequence is not self-correcting: language chain, polling pattern and confirmation are listed as mandatory, which means they are things an agent can get wrong.

Polling is the other sharp edge. The pipeline is asynchronous, with task_id and task_order_num as core concepts, so the agent has to poll until composing finishes. If your agent framework truncates long tool loops or drops context between turns, the skill's step ordering will not save you.

This is also the wrong tool for anyone who wants a general AI video generator. It produces narration videos from a fixed resource catalogue, and the README describes two narration paths and three creation modes (Hot Drama, Original Mix, New Drama). It is not a timeline editor, and nothing in the repository suggests you can compose arbitrary footage. If your source material is not in the catalogue and you are not using the original narration path, the skill has little to offer.

How this differs from running a general agent video workflow

The nearest comparison is against a general AI video generator, the kind that takes a prompt and returns a clip. The difference is the shape of the input. A prompt-to-clip tool treats the model as the producer. This repository treats the model as an operator: the creative decisions are constrained to selecting from a catalogue of movies, BGM tracks, voices and templates, and the agent's job is to make those selections in the right order and pass the right identifiers between steps.

That is a real trade-off, not a marketing distinction. You give up open-ended generation and get a repeatable pipeline with a documented data flow, error codes and a pre-flight budget check. The output is a narration video in a known format rather than whatever the model invents. If you want the model to decide what the video is, this is the wrong layer. If you want the model to execute a fixed production line without a human typing each command, it is the right one.

The skill layer itself has no real equivalent in prompt-to-clip tools: there is no separate artifact that teaches an agent how to operate the generator. That separation is the interesting design choice here, and it is also why the repository is tiny.

Maintenance, licensing and upgrade cost

The repository is not archived. The last push was on 2026-07-05, and the only release listed is v1.0.0 from 2026-04-02. That is a young project with a single tagged release, so treat the interface as unsettled. Upgrades are cheap by construction: the skill is a git clone, and the README says to run git pull inside the cloned directory to update. No build step, no package manager.

The CLI is the part that moves. The skill requires narrator-ai-cli v1.0.0 or later and Python 3.10 or higher, with typer, httpx[socks], httpx-sse, pyyaml and rich as dependencies. If the CLI changes a command or a parameter, the skill's step-by-step instructions are what go stale, and a git pull is the fix. There is no version pinning documented between the skill and the CLI beyond that v1.0.0 floor.

The licence is MIT for the repository contents. That covers SKILL.md, the references/ directory and the packaging files. It does not cover the hosted API, the app key, or the resource catalogue, none of which are distributed here. Read the service terms separately; this article is not legal advice and the repository does not restate them.

Editorial conclusion

Adopt it if you already have a narrator-ai-cli API key and an agent that reads markdown skills, because the skill adds no runtime of its own and the whole install is a git clone into the right folder. Do not adopt it if you want a self-contained open source video pipeline: without a key and the CLI, SKILL.md is inert text, and the README documents no offline mode, no local rendering and no rollback. Verify first that your agent reads SKILL.md and the references/ subfolder together, that NARRATOR_APP_KEY is set in the environment the agent runs in, and that the CLI is at v1.0.0 or later, since the skill assumes both.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. NarratorAI-Studio/narrator-ai-cli-skill on GitHub
4. README
5. Releases