Agent Rules (mandatory — apply across all steps)

Always:

• Confirm before acting. Every resource (source, BGM, dubbing, template) and every magic-video submission requires explicit user approval. Never auto-select, never auto-submit.
• Source data, never invent. Construct confirmed_movie_json from material list fields or task search-movie output. If neither yields it, ask the user — do not fabricate.
• Honor the language chain. The dubbing voice's language defines the writing task language param AND every magic-video text param. All three must match. → references/magic-video.md § Language Awareness
• Paginate material list to exhaustion, search programmatically. Fetch all pages until total is consumed, then grep -i or python3 -c on the JSON. Never trust truncated terminal display.
• Poll with the canonical while loop at 5-second intervals. Never use a fixed-iteration for loop. → references/operations.md § Task Polling

Never:

• Submit magic-video without showing the full request body (templates + every template_params value) and getting user confirmation. The cost is 30 pts/minute and irreversible.
• Submit Chinese default values for magic-video text params when narration language is non-Chinese. The defaults are hardcoded Chinese and will appear as Chinese text in a non-Chinese video.
• Submit .task_id (32-char hex) as order_num. Downstream tasks want .task_order_num (the prefixed string like generate_writing_xxxxx), not .task_id. Submitting the hex returns 10001 任务关联记录数据异常. The other look-alike — .results.order_info.order_num (script_xxxxx) — is also wrong; see references/operations.md § Task Query Response Shape.

Prerequisites

This skill assumes the narrator-ai-cli binary is installed and configured with a valid NARRATOR_APP_KEY. See README.md for install / setup. Agents can verify with narrator-ai-cli user balance.

Core Concepts

| Concept | Description | |---|---| | file_id | 32-char hex string for uploaded files. Via file upload or task results | | task_id | 32-char hex string returned on task creation. Poll with task query | | task_order_num | Assigned after task creation. Used as order_num for downstream tasks | | files[] | Output files in the completed task response (flat, top-level array). Each entry has file_id, file_path, suffix. Read .files[0].file_id for the next step's input | | learning_model_id | Narration style model — from a pre-built template (90+) or popular-learning result | | learning_srt | Reference SRT file_id. Mutually exclusive with learning_model_id |

Conversation Initiation

⚠️ Agent behavior — first message of a session: Before asking the user for a movie title or workflow path, proactively orient them about what the skill offers. Most users assume they need to upload their own video + SRT and don't realize a pre-built material library ships with the skill. Skipping this step often results in unnecessary uploads or aborted sessions.

Required opening (adapt to the conversation language):

1. Lead with the pre-built material library. Mention upfront that ~100 ready-to-use movies are available with video + SRT already loaded — no upload needed in most cases.
2. Offer three concrete entry points (let the user pick one):
   • "I have a specific movie in mind" → take the title, search materials first, fall back to task search-movie only if not found
   • "Show me what's available" → run material list --json and present 5–8 titles spanning varied genres; offer to filter by genre on request
   • "I'll upload my own video + SRT" → guide through file upload
3. Defer the Fast vs Standard path question until source material is confirmed. Asking both at once forces a decision the user has no context for yet.
4. Optionally share the visual resources preview link (BGM / dubbing / templates browsable visually): https://ceex7z9m67.feishu.cn/wiki/WLPnwBysairenFkZDbicZOfKnbc — but only if the user wants to browse, not as a wall of links upfront.

Example opening (Chinese conversation):

你好，欢迎使用 AI 解说大师。这个技能可以帮你生成电影/短剧解说视频。我这边内置了约 100 部电影素材（视频 + 字幕都是现成的），所以大多数情况你不需要自己上传任何文件。

你想怎么开始？

1. 直接告诉我片名 — 我先查内置素材库，没有再去外部搜
2. 让我列一些内置素材 — 你可以按类型挑（喜剧 / 动作 / 悬疑 / 科幻…）
3. 自己上传视频 + 字幕 — 我引导你完成上传流程

After source material is confirmed, walk the user through the decision sequence below — one question per turn, in order. Do NOT collapse multiple decisions into one message; users cannot reason about target_mode before they've picked a path.

Decision sequence (each step waits for explicit user confirmation):

1. Source material — covered above.
2. Workflow path — Fast (原创文案) or Standard (二创文案). See "Two Workflow Paths" below.
3. target_mode — only ask if path = Fast. Choose mode 1 / 2 / 3 (see "Fast Path internal: target_mode" below). If path = Standard, skip this question entirely — Standard Path has no target_mode.
4. BGM → Dubbing voice → Narration template — see "Resource Selection Protocol".

⚠️ Anti-pattern (do NOT do this): Asking "① 解说模式 (纯解说/原声混剪) ② 制作路线 (快速/标准)" in the same message. 纯解说 and 原声混剪 are Fast Path internal modes (target_mode 1 vs 2). They do not exist in Standard Path. Asking them alongside the path choice forces the user to make decisions in the wrong order and conflates two layers of the decision tree.

Two Workflow Paths

Two end-to-end paths produce a finished narrated video. Choose with the user before starting.

| | Fast Path (原创文案, recommended) | Standard Path (二创文案) | |---|---|---| | Pipeline | material → fast-writing → fast-clip-data → video-composing → magic-video* | material → popular-learning** → generate-writing → clip-data → video-composing → magic-video* | | Cost / speed | Faster, cheaper | Higher quality narration | | When to use | Default unless user wants adapted-style narration | When user wants narration learned from a reference style |

* magic-video is optional; only on explicit user request. ** popular-learning is skippable when using a pre-built template (recommended).

⚠️ Path is a standalone decision — ask the user "Fast or Standard?" by itself, in its own message. Do not auto-select. Do not bundle it with target_mode or any other follow-up question.

Fast Path internal: target_mode (ask only after path=Fast is confirmed)

Skip this section entirely if the user picked Standard Path — target_mode only exists inside fast-writing.

| Mode | Use when | Required input | |---|---|---| | "1" 热门影视 (纯解说) | Known movie, narration from plot only | confirmed_movie_json; no episodes_data | | "2" 原声混剪 (Original Mix) | Known movie + you have its SRT | confirmed_movie_json + episodes_data[{srt_oss_key, num}] | | "3" 冷门/新剧 (New Drama) | Obscure/new content | episodes_data[{srt_oss_key, num}]; confirmed_movie_json optional |

Resource Selection Protocol

Before any task, gather these resources in this order, with explicit user confirmation at each step:

1. Source files (video + SRT) — from material list or via file upload
2. BGM — from bgm list
3. Dubbing voice — from dubbing list
4. Narration style template — from task narration-styles

Detailed list commands, response shapes, and field mappings live in references/resources.md.

⚠️ Universal rules — apply at every resource step:

1. Pre-filter by context. Use the per-resource filter flag where supported: bgm list --search, dubbing list --lang, task narration-styles --genre. material list does NOT accept these flags — paginate the JSON and search programmatically with grep -i / python3 -c.
2. Default presentation: 5–8 options with the resource ID and key descriptive fields.
3. If the user has no preference: present 3 recommendations with a one-line reason for each. Still wait for confirmation.
4. Confirm one resource at a time. Do not advance until the current one is confirmed.

⚠️ Dubbing → writing language mismatch check: if the user pre-specified a language value that conflicts with the chosen voice, surface the mismatch and ask before proceeding. (The general language-chain rule lives in Agent Rules above.)

Fast Path — High-Level Flow

Detailed parameter tables, all target_mode cases, and full JSON examples live in references/workflows.md.

Step 0 — Find source material & determine target_mode:

1. List materials: narrator-ai-cli material list --json --page 1 --size 100. Search programmatically with grep -i or python3 -c on the JSON output — do NOT rely on the terminal display (may be truncated). Paginate (--page 2, etc.) until exhausted if total > 100.
2. Found in materials → ask user: pure narration (target_mode=1) or original mix (target_mode=2)? Construct confirmed_movie_json from material fields (mapping in references/resources.md).
3. Not found, known title → task search-movie "<name>" --json → target_mode=1 (or target_mode=2 if user uploads SRT). May take 60+ seconds (Gradio backend, results cached 24h).
4. Obscure / new content → target_mode=3 with user's uploaded SRT. confirmed_movie_json optional.

Step 1 — fast-writing: pass learning_model_id, target_mode, playlet_name, confirmed_movie_json and/or episodes_data, model (flash 5pts/char or pro 15pts/char). Save task_id from the creation response, then poll until top-level .status=2 and save .files[0].file_id from the completed task.

Step 2 — fast-clip-data: pass task_id + file_id from Step 1, plus bgm, dubbing, dubbing_type, and episodes_data with video_oss_key / srt_oss_key / negative_oss_key. Poll until top-level .status=2; read top-level .task_order_num from the response.

Step 3 — video-composing: pass order_num: <.task_order_num from Step 2>, plus bgm, dubbing, dubbing_type (re-pass the same values from Step 2 — the API does not inherit them). All four are required; submitting only order_num returns 10001 查询解说工程任务结果失败. Poll → .results.tasks[0].video_url is the finished MP4.

Step 4 (optional) — magic-video: only on explicit user request. See references/magic-video.md.

Standard Path — High-Level Flow

Detailed parameter tables and JSON examples live in references/workflows.md.

Step 0 — Source material: same material/upload flow as Fast Path. Use video_file_id as video_oss_key and negative_oss_key, and srt_file_id as srt_oss_key in episodes_data.

Step 1 — popular-learning (skip if using a pre-built template): pass video_srt_path, narrator_type, model_version. Poll until top-level .status=2, then parse .results.tasks[0].task_result JSON → agent_unique_code is the learning_model_id. Or use a pre-built template id from task narration-styles --json directly.

Step 2 — generate-writing: pass learning_model_id, playlet_name, playlet_num, episodes_data, plus three additional required fields — target_platform (e.g. "douyin"), vendor_requirements ("" if none), and target_character_name ("" if not applicable). Omitting any of these returns 10001 ... Field required. Full param table in references/workflows.md. Save task_id from the creation response.

Step 3 — clip-data: pass order_num (= top-level .task_order_num from Step 2's polled task record, e.g. generate_writing_xxxxx), plus bgm, dubbing, dubbing_type. ⚠️ Different from Fast Path's fast-clip-data, which takes task_id — clip-data takes order_num instead. Poll until top-level .status=2 (required prerequisite for Step 4) — but do not use clip-data's own task_order_num for video-composing; Step 4 keys off generate-writing's instead.

Step 4 — video-composing: pass order_num + bgm + dubbing + dubbing_type (all four required — re-pass the BGM/voice values from Step 3; the API does not inherit them, and submitting only order_num returns 10001 查询解说工程任务结果失败). ⚠️ Standard Path keys off generate-writing's task_order_num (generate_writing_xxxxx), NOT clip-data's. clip-data must reach top-level .status=2 first as a prerequisite, but its own task_order_num (generate_clip_data_xxxxx) returns 10001 任务关联记录信息缺失 when submitted. This is opposite to Fast Path (where fast-clip-data is the right anchor) — see Important Notes #4. Poll → .results.tasks[0].video_url is the finished MP4.

Step 5 (optional) — magic-video: only on explicit user request. See references/magic-video.md.

Standalone Tasks

# Voice clone — input audio_file_id, returns voice_id
narrator-ai-cli task create voice-clone --json -d '{"audio_file_id": "<file_id>"}'

# Text to speech — input voice_id + audio_text
narrator-ai-cli task create tts --json -d '{"voice_id": "<voice_id>", "audio_text": "Text to speak"}'

Both accept optional clone_model (default: pro).

Important Notes

1. confirmed_movie_json is required for target_mode=1 and 2, optional for 3. Construct from material fields when found in pre-built materials; use search-movie otherwise.
2. file_id always comes from file list or material list. Never guess.
3. search-movie may take 60+ seconds (Gradio backend, results cached 24h).
4. video-composing.order_num is path-asymmetric — which upstream task's task_order_num to use differs by path (the field-name rule — use task_order_num, not the hex order_num — is in Agent Rules above):
   • Fast Path → use fast-clip-data's task_order_num (format: fast_writing_clip_data_xxxxx).
   • Standard Path → use generate-writing's task_order_num (format: generate_writing_xxxxx). The clip-data step's own task_order_num (generate_clip_data_xxxxx) returns 10001 任务关联记录信息缺失. clip-data must still complete first as a prerequisite — but its order is not what video-composing keys off.
5. Prefer pre-built templates over popular-learning. List with task narration-styles --json; preview at the resources URL above.
6. Use -d @file.json for large request bodies to avoid shell quoting issues.
7. Use task verify before expensive tasks to catch missing/invalid materials early; task budget to estimate point cost.

Data & Privacy

• API endpoint: All requests go to https://openapi.jieshuo.cn. No third-party services.
• File upload: presigned URL → OSS PUT → callback. Files are bound to your account, not public.
• Credentials: NARRATOR_APP_KEY stored at ~/.narrator-ai/config.yaml. Keep private; do not commit.
• Scope: this skill only orchestrates the CLI; it does not access files outside what you explicitly pass as input.

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

Step 3: Install the Skill

Choose the method for your agent platform:

OpenClaw:

mkdir -p ~/.openclaw/skills/narrator-ai-cli
cp SKILL.md ~/.openclaw/skills/narrator-ai-cli/SKILL.md

WorkBuddy / QClaw (Tencent):

Upload SKILL.md through the skill management UI.

Windsurf:

cp SKILL.md /path/to/your/project/.skills/narrator-ai-cli/SKILL.md

Claude Code / Cursor:

cp SKILL.md /path/to/your/project/.skills/narrator-ai-cli/SKILL.md

Any markdown-reading agent:

cp SKILL.md /path/to/agent/skills/narrator-ai-cli/SKILL.md

💡 Tip: You can also just give the agent this repo URL — most agents can read the GitHub repo structure and auto-configure.

Step 4: Start talking!

Once installed, use natural language:

• "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"

Tested Platforms

| Platform | Setup | Status | |----------|-------|--------| | OpenClaw | Native skill loading | ✅ Verified | | Windsurf | .skills directory | ✅ Verified | | WorkBuddy (Tencent) | Upload SKILL.md | ✅ Verified | | QClaw (Tencent) | Upload SKILL.md | ✅ Verified | | Youdao Lobster | Skill loading | ✅ Verified | | Yuanqi AI | Skill loading | ✅ Verified | | Claude Code | SKILL.md in project root | ✅ Verified | | Cursor | rules/skills directory | ✅ Verified | | Any markdown-skill agent | Point to SKILL.md | ✅ Compatible |

Capabilities

| Feature | Details | |---------|---------| | Two workflow paths | Adapted Narration and Original Narration | | Three creation modes | Hot Drama / Original Mix / New Drama | | Built-in resources | 93 movies, 146 BGM tracks, 63 dubbing voices, 90+ narration templates | | Full pipeline | Script → Clip data → Video composing → Visual template | | Standalone tasks | Voice cloning, text-to-speech | | Data flow mapping | Which output feeds into which input | | Error handling | All 18 API error codes with recommended actions | | Cost estimation | Budget verification before task creation |

What's in SKILL.md

| Section | Description | |---------|-------------| | Frontmatter | Skill metadata (name, description, requirements) | | Architecture | CLI source structure and design choices | | Core Concepts | Key terms: file_id, task_id, order_num, etc. | | Workflow Paths | Two complete pipelines with step-by-step commands | | Prerequisites | How to select resources (materials, BGM, dubbing, templates) | | Fast Path | Recommended workflow: search → write → clip → compose → magic | | Standard Path | Full workflow: learn → write → clip → compose → magic | | Standalone Tasks | Voice clone and TTS | | Task Management | Query, list, budget, verify, save | | File Operations | Upload, download, list, delete | | Error Handling | All 18 API error codes with actions | | Data Flow | ASCII diagram of complete pipeline | | Important Notes | 9 critical gotchas and best practices |

Requirements

• CLI: narrator-ai-cli v0.1.0+
• Python: 3.10+
• Dependencies: typer, httpx[socks], httpx-sse, pyyaml, rich
• API key: Contact us to get one

Links

• 📦 narrator-ai-cli CLI repo
• 📖 Resource preview (Feishu Docs)
• 🦞 OpenClaw agent framework

Contact

Need an API key or help?

• 📧 Email: merlinyang@gridltd.com
• 💬 WeChat: Scan the QR code below

License

MIT