Agent Skills

技能包是一份给 AI 编程助手的「说明书」。安装后，Claude Code 等 AI agent 在遇到音频相关任务时，会自动知道该调用哪些 VoxFlow CLI 命令。

什么是 Agent Skills？

Agent Skills 是安装在你项目里的 SKILL.md 文件。它告诉 AI agent：

VoxFlow CLI 有哪些命令（say、podcast、dub、asr...）
每个命令怎么用、参数是什么
常见工作流怎么组合（视频翻译 = ASR + translate + dub）
登录和配额怎么管理

Skills vs MCP： Skills 教 AI 用 CLI（本地执行，支持 FFmpeg/视频），MCP 让 AI 直接调 API（云端执行，对话式交互）。两者互补。

AI 一键安装（推荐）

把下面这段 prompt 整段复制给 Claude Code / Codex / Cursor / Gemini CLI / WorkBuddy / OpenClaw 任意一个 agent，全程不用开终端、不用粘贴 token——它自己跑命令、自己处理登录、自己装好 5 个 skill：

✨ 复制给 AI

请帮我把 VoxFlow 装好并跑通验证。VoxFlow 是一个语音工作流 CLI（npm 包名 voxflow），
首页 https://voxflow.studio。装好后你能用自然语言帮我合成语音 / 做播客 / 翻译视频。

⚠️ 重要：登录步骤不要让我去开新终端！按下面的"AI agent 非交互登录"模式做。
每一步先告诉我你在做什么；遇到失败先 dump 错误再排查，不要静默重试；全程中文回复。

═══ 步骤 1：装 CLI ═══
node --version    # 要求 >=20.19 或 >=22.12
npm install -g voxflow@latest

═══ 步骤 2：登录（device-flow，零粘贴）═══

(2a) 你跑：voxflow login
(2b) CLI 会打印两行关键信息：
       Pairing code: VF-XXXX
       Verify at:    https://voxflow.studio/device?code=VF-XXXX
     把这两行原样发给我，告诉我："请打开上面的链接，确认网页上的配对码
     与终端的 VF-XXXX 完全一致后，点「授权此设备」。"
(2c) CLI 在后台每 5 秒轮询。我授权完成后你会看到 "✓ Authorized (邮箱)" —
     全程零 JSON 粘贴。
(2d) 如果 CLI 一直显示 "Unexpected poll response" 或超过 5 分钟没动静，
     先 dump 完整输出，再让我重新跑。不要静默重试。

═══ 步骤 3：TTS 链路验证 ═══
voxflow say "你好 VoxFlow" -o hello.mp3
告诉我 hello.mp3 的绝对路径和文件大小。

═══ 步骤 4：装 5 个 skill 到所有 AI agent ═══
voxflow skills install -y
（底层跑：npx -y skills add VoxFlowStudio/skills --all --yes --global，
  装到 ~/.agents/skills/ 并 symlink 到 Claude Code / Cursor / Codex /
  Gemini / OpenClaw 等 agent 的标准 skills 目录。）

═══ 步骤 5：报告 ═══
全部跑完，告诉我：
  a) 装了哪些组件、版本号
  b) hello.mp3 路径和大小
  c) ~/.agents/skills/ 下有哪几个目录
  d) 我现在可以用哪些自然语言指令调用 VoxFlow（举 3 个例子）

═══ 约束 ═══
- 沙箱不能 npm install -g 的话告诉我具体限制，改用 https://voxflow.studio 网页版
- 步骤 2 严禁让我开新终端 — 把 verifyUrl + 配对码直接发我，让我在浏览器完成

手动安装

想自己跑命令？三步：

# 1. 装 CLI（需要 Node 20.19+ 或 22.12+）
npm install -g voxflow

# 2. 浏览器扫码登录（只需一次）
voxflow login
voxflow status

# 3. 装 5 个 skill（自动探测 50+ 种 agent 并 symlink 到各自标准目录）
voxflow skills install -y

底层等价于 npx -y skills add VoxFlowStudio/skills --all --yes --global，技能文件落到 ~/.agents/skills/voxflow/ 并 symlink 到 Claude Code / Cursor / Codex / Gemini / Cline / Amp / OpenClaw 等 agent 的标准目录。几个有用 flag：--dry-run 只打印不执行、voxflow skills detect 只看检测结果、voxflow skills list 列全部支持的 agent。

安装后的效果

AI agent 遇到音频任务时，会自动使用 VoxFlow CLI：

› “帮我把这段文字合成语音”

AI 自动执行 voxflow say "..." -o output.mp3

› “把这个视频翻译成日语”

AI 自动执行 voxflow video-translate video.mp4 --to ja

› “生成一个关于 AI 的播客”

AI 自动执行 voxflow podcast "AI的未来" --duration 3

Skills 包含的内容

~/.agents/skills/voxflow/      # 全局安装位置，symlink 到各 agent 标准目录
  ├── hub/SKILL.md             # 入口技能 — TTS、音色搜索、安装/登录/配额
  ├── podcast/SKILL.md         # 多说话人播客（主题 / URL / 脚本 → MP3/WAV）
  ├── transcribe/SKILL.md      # ASR + 字幕翻译 + SRT 配音 + 端到端视频翻译
  ├── slice/SKILL.md           # 长文转 1080×1920 竖版卡片视频（6 套主题）
  └── video/SKILL.md           # 短视频 — 小红书 / TikTok / Reels 知识卡

创意工作流

安装 Skill 后，AI 会自动组合 CLI 命令完成复杂创作。这些都写在 SKILL.md 里，AI 照着做。

有声绘本

AI 写故事 + 生成 SVG 插画 + voxflow say 逐页配音 → 单个离线 HTML 文件

有声演示文稿

AI 做 slide + 写旁白 + voxflow say 逐页配音 → HTML 演示文稿

文档朗读 / 文章有声摘要

voxflow narrate README.md 或 AI 总结网页 + voxflow say → mp3

多语言合成 / Git 日报 / PR 讲解 / 模拟面试

AI 翻译/总结/出题 + voxflow say 多段合成 → 自动播放

在 OpenClaw 中使用

OpenClaw 有自己的官方 skill 注册表，OpenClaw bot 出于供应链安全只信任这条路径。VoxFlow 在两个 OpenClaw 注册表都已上架（slug 都是 voxflow）：海外 / 全球用 ClawHub（`clawhub install voxflow`），中国 / 腾讯内部 OpenClaw（如 chico-claw-win）用 SkillHub.cn（`skillhub install voxflow`，knot_skills 工具默认查这里）。不要对 OpenClaw bot 跑 voxflow skills install——那条是给 Claude Code / Cursor / Codex / Gemini CLI 等通用 agent 用的，OpenClaw 会（正确地）拒绝。完整指南见 /docs/openclaw。

Skills vs MCP vs CLI — 什么时候用什么？

	Skills	MCP	CLI
执行方式	AI 调 CLI（本地）	AI 调 API（云端）	你手动执行
适合	需要 FFmpeg/视频/本地文件的任务	纯语音任务、对话式交互	脚本、CI/CD、批量处理
依赖	Node.js + CLI + ffmpeg	无（纯网络）	Node.js + CLI
视频处理	✓	✗	✓
安装	`voxflow skills install`	`claude mcp add`	`npm i -g voxflow`

推荐组合：同时安装 Skills + MCP。AI 会根据任务自动选择：需要视频处理用 CLI（通过 Skills），纯语音用 MCP API。

更新

# 重新跑安装命令即可，会拉最新版覆盖
voxflow skills install -y

CLI 文档 → · MCP 文档 → · 所有文档 →