Skills Atlas · Narrator AI CLI Skill 使用說明書

Single-Repo Deep Dive · NarratorAI-Studio · 2026 Q2

Skills Atlas — 使用說明書把自然語言變成
影片解說生產線。
narrator-ai-cli-skill 完整拆解。

Tenten 拆解 NarratorAI-Studio／narrator-ai-cli-skill — 一個用 SKILL.md 教 AI 代理把「幫我做一支《刺激 1995》的解說片」翻譯成素材確認 → 文案生成 → 切片資料 → 影片合成完整管線的開源契約。內建 100+ 部影片、146 BGM、63 配音與 90+ 解說範本，Claude Code、Cursor、Windsurf、OpenClaw 一份 SKILL.md 通用。

GitHub Stars

231 ★

v1.0.0 於 2026 年 4 月初首發後迅速被多平台代理收錄。

工作流路徑

2 Paths

Fast Path 原創文案／ Standard Path 二創文案，按授權與品質取捨。

內建素材

100+

影片 + SRT 字幕現成可用，146 BGM 與 63 配音聲線跨 11 語系。

授權與更新

MIT · 2026

SKILL.md 與底層 Python CLI 同為 MIT，由 Grid Ltd 維護。

01 / 編者手記 FROM THE EDITOR · APRIL 2026

這份 SKILL.md 是一條合約，不是一份 README。

編者手記 EDITOR'S NOTE

narrator-ai-cli-skill 把「影片解說」這件高度依賴經驗的事，拆成七個 task type、兩條工作流路徑與一組嚴格的代理行為守則。它不是教 Claude 寫旁白，是把整條製作流的 SOP 灌進代理腦中。

影片製作流，第一次被寫成代理可遵守的契約。

過去把影片需求交給代理，會卡在「要哪部片」「用什麼配音」「合成到哪一步」的反覆來回。這份 SKILL.md 把素材確認 → 路徑選擇 → target_mode → BGM／配音／範本的決策順序明確寫死，並要求每一步都有使用者顯式確認 — 把「能不能交付」變成可重複的工程問題。

兩條路徑，反映了現實世界的版權與品質取捨。

Fast Path（原創文案）用fast-writing＋fast-clip-data，便宜、快、不需學習素材；Standard Path（二創文案）多了popular-learning，先吃熱門解說的風格，再生成更高品質的旁白。一個倉庫同時容納「成本敏感」與「精品產出」兩種團隊。

SKILL.md 一份，跨平台代理通用。

README 同時列出 OpenClaw、Windsurf、WorkBuddy、QClaw、Cursor、Youdao Lobster、Yuanqi AI、Claude Code 八種代理的安裝方式 — 同一份 markdown 契約在哪裡都能跑。這正是 2026 年 SKILL.md 取代 prompt 範本成為主流的原因：可移植、可審查、可版本化。

02 / 功能總覽 FEATURES · PIPELINE · RESOURCES · UPDATED APR 2026

功能 Capabilities

兩條工作流路徑、三種創作模式、七個 task type，加上內建 100+ 部影片素材與 11 語系配音的完整生產線。

5 Entries
2 Paths · 3 Modes · 7 Tasks
v1.0.0 · Apr. 2026

01^/05

NarratorAI-Studio / narrator-ai-cli-skill

兩條工作流路徑，分別對應原創與二創

Fast Path 走 fast-writing；Standard Path 走 popular-learning + generate-writing

Fast Path（原創文案）序列為 material → fast-writing → fast-clip-data → video-composing → magic-video，便宜、快、適合默認案例；Standard Path（二創文案）插入 popular-learning 先學習熱門解說風格，再走 generate-writing → clip-data → video-composing，旁白品質更高。SKILL.md 明確要求代理不得自動切換路徑，每次都要使用者顯式選擇。

✓ 代理行為契約 Fast Path Standard Path popular-learning video-composing

Paths 2 Task Types 7 Final Output MP4

NarratorAI-Studio / narrator-ai-cli-skill

Fast Path 的三種 target_mode

熱門影視／原聲混剪／冷門新劇各對應不同輸入要求

target_mode="1" 熱門影視：純解說，需 confirmed_movie_json，無需上傳字幕。target_mode="2" 原聲混剪：需 confirmed_movie_json + episodes_data（含 SRT）。target_mode="3" 冷門／新劇：需 episodes_data，confirmed_movie_json 可選。SKILL.md 規定路徑與模式不能寫在同一輪訊息，避免兩層決策被混淆。

熱門影視原聲混剪冷門新劇

Modes 1 / 2 / 3 Required JSON

NarratorAI-Studio / narrator-ai-cli（底層 CLI）

內建素材庫 — 大多數情況不需上傳

100+ 影片 + SRT、146 BGM 軌、63 配音聲線、90+ 解說範本

底層 narrator-ai-cli（Python，MIT）內建涵蓋 11 個語系的配音與 12 種解說題材的範本（learning_model_id）。SKILL.md 要求代理在會話開場就告知使用者素材庫存在，並提供「直接給片名／列出內建／自己上傳」三個入口，省去無謂的檔案上傳。

100+ 影片 146 BGM 63 配音 11 語系

Movies 100+ Templates 90+

NarratorAI-Studio / narrator-ai-cli-skill

七個 task type 構成完整製作管線

writing → clip-data → composing → magic-video，外加學習與獨立任務

管線含 popular-learning、generate-writing、fast-writing、clip-data、fast-clip-data、video-composing、magic-video。magic-video 是視覺範本層，按分鐘計費（30 pts／分鐘），依路徑接在不同 task_order_num 之後。

7 Task Types magic-video 分鐘計費

Tasks 7 Magic Cost 30 pts／min

NarratorAI-Studio / narrator-ai-cli-skill

獨立任務：聲音複製與 TTS

脫離影片管線單獨運作的兩個 task type

voice-clone 吃 audio_file_id，產出可重複使用的 voice_id；tts 吃 voice_id + audio_text，產出純音訊檔。兩者都接受可選的 clone_model（預設 pro），可在不啟動完整影片合成的情況下用於 podcast、有聲書等場景。

voice-clone TTS 獨立執行

Tasks 2 Standalone Default pro model

03 / 安裝與設定 PIP · CONFIG · MULTI-AGENT · DISCOVERY

安裝 Setup

底層 Python CLI、SKILL.md 跨代理部署、API 端點與認證、資源探索與成本驗證指令一次到位。

5 Entries
CLI · API · Multi-Agent
MIT License

01^/05

NarratorAI-Studio / narrator-ai-cli

一行 pip 安裝，一條指令設好金鑰

底層 Python CLI 與 SKILL.md 同源，MIT 授權

CLI 安裝：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>。完成後就有完整的 config、user、task、file、material、bgm、dubbing 指令樹可用。

✓ MIT 授權 Python pip install git+https

Stack Python License MIT Maintainer Grid Ltd

NarratorAI-Studio / narrator-ai-cli-skill

八個代理平台共用同一份 SKILL.md

OpenClaw、Windsurf、WorkBuddy、QClaw、Cursor、Youdao Lobster、Yuanqi AI、Claude Code

README 提供逐平台的安裝指引。OpenClaw 範例：mkdir -p ~/.openclaw/skills 後 git clone https://github.com/NarratorAI-Studio/narrator-ai-cli-skill.git ~/.openclaw/skills/narrator-ai-cli。對 Claude Code 而言，把整個 repo clone 到 ~/.claude/skills/ 即可載入。

8 Agent 平台 git clone SKILL.md

Platforms 8 Format SKILL.md

NarratorAI-Studio / narrator-ai-cli（API 端點）

API 端點與本機認證路徑

NARRATOR_APP_KEY 寫入 ~/.narrator-ai/config.yaml

底層 API 為 https://openapi.jieshuo.cn。檔案上傳走預簽 URL → OSS PUT → callback 三步驟，產出 file_id 後綁定到帳號。金鑰存於 ~/.narrator-ai/config.yaml，列入 .gitignore 是基本紀律。

openapi.jieshuo.cn OSS 預簽 config.yaml

Auth App Key Storage OSS Presign

NarratorAI-Studio / narrator-ai-cli

資源探索：先列出，再選擇

material list ／ search-movie ／ bgm list ／ dubbing list

素材：narrator-ai-cli material list --json --page 1 --size 100，必要時用 task search-movie "<title>" --json 查找未在內建庫的片名。BGM 用 bgm list --search "<keyword>"；配音用 dubbing list --lang "<language>"；解說範本用 task narration-styles --genre "<genre>" --json。SKILL.md 強調全部需窮盡分頁、程式化搜尋 JSON，不要靠終端機輸出截斷的結果判斷。

--json 分頁查詢先列再選

Listing 4 Surfaces Pagination Required

NarratorAI-Studio / narrator-ai-cli

提交前的預算驗證三件套

task budget ／ task verify ／ user balance

narrator-ai-cli user balance 查帳戶餘額；task budget 對待提交的任務做成本估算；task verify 確認 payload 結構正確再提交。SKILL.md 將「提交前檢查」列為強制流程，特別是 magic-video 必須先把完整 request body 給使用者看過再 submit。

budget verify balance

Pre-submit 3 Checks Magic-Video Confirm

04 / 進階用法 POWER-USER PATTERNS · AGENT RULES · CHAIN-WITH

SKILL.md 已經把易踩的雷列成代理鐵則。

代理鐵則 · task_id ≠ task_order_num

下游 task 一律用 task_order_num

32 字元 hex 是用來 polling 的，不是串接管線用的

task_id 為 32-char hex，僅供 task query ／ task polling 使用。串接 video-composing 等下游任務必須用建立後回傳的 task_order_num（如 generate_writing_xxxxx 或 fast_writing_clip_data_xxxxx）。代理錯把 hex 丟進 order_num 是最常見的失敗模式。

✓ 鐵則 task_order_num order_num

Anti-pattern hex as order

代理鐵則 · 5 秒 while-loop 輪詢

永遠用 while-loop，不用固定迭代

task polling 是長尾任務，固定 for 範圍會在合成時提早爆掉

SKILL.md 規定使用標準 while 迴圈、5 秒間隔進行 task polling，禁用 for i in range(N) 之類的固定上限。video-composing 與 magic-video 的耗時依素材長度差異甚大，固定迴圈幾乎必定錯過完成事件。

while-loop 5s 間隔禁用 fixed for

Interval 5 sec

代理鐵則 · 語言鏈一致性

配音語系必須與文案 language 完全相同

non-Chinese 解說搭中文 magic-video 預設，是常見的語系錯位

writing 任務的 language 參數、dubbing list --lang 篩出的 voice_id、以及 magic-video 內所有文字欄位，必須使用同一語系。SKILL.md 將語言錯位列為禁止行為 — 英文解說配中文視覺範本會被靜默套用預設值，產出無法使用的成片。

11 語系語言鏈 ✓ 三點對齊

Aligned Surfaces 3

CLI 模式 · --json 串接

所有資源指令都加 --json

截斷的終端機輸出不能用來搜素材

material list --json --page 1 --size 100 才能讓代理程式化搜尋。SKILL.md 明確要求窮盡分頁後再對 JSON 結構做篩選 — 直接讀終端機文字會漏掉超過視窗的素材。task create 系列也都用 -d '<params>' --json 取得結構化回傳。

--json --page --size 100

Pagination Exhaustive

代理鐵則 · magic-video 提交前確認

提交前必須展示完整 request body

magic-video 是分鐘計費，誤交會直接燒積分

magic-video 為 30 pts／分鐘，且文字欄位若用錯語系會被靜默替換為預設。SKILL.md 將「未顯示完整 payload 直接提交」列為禁止行為 — 代理必須印出組好的 JSON，等使用者顯式 confirm 才執行 task create magic-video。

30 pts／min payload 確認 ✓ 防誤計費

Cost 30 pts/min

05 / 實戰應用 REAL-WORLD WORKFLOWS · TARGET MODES · BATCH

實戰 Workflows

把 SKILL.md 的契約套到五種真實情境，從熱門電影解說、原聲混剪、新劇試水、二創精修到聲音複製。

5 Entries
Modes · Standard · Standalone
Production Ready

01^/05

NarratorAI-Studio / narrator-ai-cli-skill

情境一：熱門影視解說（target_mode "1"）

「幫我做一支《刺激 1995》的 5 分鐘解說」

最常見的入口。代理會先 material list 確認內建素材中有無《刺激 1995》，沒命中就 task search-movie；確認後組出 confirmed_movie_json，走 Fast Path 的 fast-writing → fast-clip-data → video-composing。不需上傳字幕，因為熱門片內建素材含 SRT，且 mode 1 為純解說型，不需逐字 timing 對應。

✓ 最低門檻 target_mode 1 Fast Path 無需上傳

Input 片名 Output 解說 MP4 Cost Tier Low

NarratorAI-Studio / narrator-ai-cli-skill

情境二：原聲混剪（target_mode "2"）

保留原片台詞，剪出精華段落並穿插旁白

適合對台詞、節奏要求高的內容。需提供 confirmed_movie_json + episodes_data（包含 SRT），讓 fast-clip-data 在原聲節點切出片段。fast-clip-data 在混剪模式下計費為 40 pts／1k chars，明顯高於純解說 — SKILL.md 要求代理在路徑展示完整成本估算。

target_mode 2 原聲 SRT 必備 40 pts／1k

Input 片 + SRT Cost Tier High

NarratorAI-Studio / narrator-ai-cli-skill

情境三：冷門新劇（target_mode "3"）

內建庫沒有的小眾片源、新上檔劇集

走自上傳流程：narrator-ai-cli file upload <path> 取得 file_id 後組出 episodes_data。confirmed_movie_json 此時為可選 — 若代理沒有可信片名資訊，不應該硬填。SKILL.md 的禁止項就包含「在沒有確定來源時偽造 confirmed_movie_json」。

target_mode 3 file upload ✓ 不偽造

Input 使用者素材 Mode 3

NarratorAI-Studio / narrator-ai-cli-skill

情境四：Standard Path 二創精修

先學熱門解說的風格，再產出更高品質旁白

走 popular-learning → generate-writing → clip-data → video-composing。代理需先選一支熱門解說作為風格樣本，generate-writing 會產生 task_order_num，下游 video-composing 鎖在這個 order_num（不是 clip-data 的）。適合 MCN、品牌頻道對品質要求高、願意多花一輪計費的場景。

Standard Path popular-learning 高品質旁白

Steps 4 + 1 Best For MCN／品牌

NarratorAI-Studio / narrator-ai-cli-skill

情境五：聲音複製＋ TTS 獨立鏈路

不啟動影片管線，純做語音資產

task create voice-clone --json -d '{"audio_file_id":"<id>"}' 將 30 秒參考音檔產出 voice_id；接著用 task create tts --json -d '{"voice_id":"<id>","audio_text":"…"}' 批量輸出旁白檔。適用於 podcast、有聲書、IVR、品牌語音 — 與影片管線完全解耦，無需任何素材。

voice-clone TTS 無需影片

Inputs audio_file_id Outputs voice_id

想把 narrator-ai-cli-skill 接進你的內容流程？

SKILL.md 已經開源。
接上生產環境這一段，
是 Tenten 在做的事。

Tenten 是 AI-First 設計與技術顧問公司。我們把 Claude、MCP、Agentic Commerce 接進 Headless CMS、Webflow、Shopify Plus 的企業級交付 — 讓 narrator-ai-cli-skill 這類開源契約，能真正跑在你正式上線的內容生產線上。

預約 30 分鐘諮詢 → Tenten Awesome List

Tenten 如何部署這些 Skills

Skills 架構諮詢

依團隊與堆疊選出適配 skills，建立 OpenClaw 路由與 CI/CD 部署流程。

Claude Design System Sprint

兩週固定價格，接上 frontend-design + brand-guidelines 到 production。

Agentic Commerce Build

Shopify Plus / Webflow / Headless 遷移，搭配 Claude + MCP 營運層。

這份 SKILL.md 是一條合約，不是一份 README。

影片製作流，第一次被寫成代理可遵守的契約。

兩條路徑，反映了現實世界的版權與品質取捨。

SKILL.md 一份，跨平台代理通用。

功能 Capabilities

兩條工作流路徑，分別對應原創與二創

Fast Path 的三種 target_mode

內建素材庫 — 大多數情況不需上傳

七個 task type 構成完整製作管線

獨立任務：聲音複製與 TTS

安裝 Setup

一行 pip 安裝，一條指令設好金鑰

八個代理平台共用同一份 SKILL.md

API 端點與本機認證路徑

資源探索：先列出，再選擇

提交前的預算驗證三件套

SKILL.md 已經把易踩的雷列成代理鐵則。

下游 task 一律用 task_order_num

永遠用 while-loop，不用固定迭代

配音語系必須與文案 language 完全相同

所有資源指令都加 --json

提交前必須展示完整 request body

實戰 Workflows

情境一：熱門影視解說（target_mode "1"）

情境二：原聲混剪（target_mode "2"）

情境三：冷門新劇（target_mode "3"）

情境四：Standard Path 二創精修

情境五：聲音複製＋ TTS 獨立鏈路

依團隊規模，選你的起跑點

用 Fast Path + 內建素材跑單人頻道

用 Standard Path 學習風格、批量精修

63 配音 × 11 語系同片多語發行

把 SKILL.md 部署成中央生產線

SKILL.md 已經開源。 接上 生產環境這一段， 是 Tenten 在做的事。

SKILL.md 已經開源。
接上生產環境這一段，
是 Tenten 在做的事。