---
title: MetaDig Skill 使用指南：让 Cursor、Claude Code 这类 Agent 直接帮你出图出片
section: MetaDig Skills
source: https://waytometa.cn/docs/skills/agent-skill
summary: MetaDig Skill 是给 AI Agent 用的能力包：装好它，Agent 就知道怎么用 metadig 命令行查模型、报价、生成图片视频配音并把产物落到你的画布。这篇讲它是什么、去哪拿、装到哪、怎么用，以及它和「命令行」栏目、和画布「Skill 广场」的区别。
updated: 2026-09-03
---
MetaDig Skill 是一份**写给 AI Agent 看的操作手册**。它告诉 Agent 怎么通过 `metadig` 命令行调用 MetaDig 的图片、视频、语音和音乐生成能力，什么时候该先查模型、什么时候该先向你报价、失败了该不该重试，并约束 Agent 只走稳定的命令行入口，不去拼接网页内部接口。

如果你在用 Cursor、Claude Code、Codex、OpenClaw、Kimi、Trae 这类支持 Agent Skill 的工具，可以把它理解成「给 Agent 装一个 MetaDig 插件」：装好 Skill、登录一次，之后直接对 Agent 说"帮我出三张 16:9 的秋天海报"或"给这篇文章配一条 5 秒的片头"，它自己去跑命令，产物出现在你的网页画布上。

> [!NOTE] 先分清两个「Skill」
> 本站有两套叫 Skill 的东西。**画布 Skill 广场**（`/skills`）里的 Skill 是你写给画布内 Agent 的创作套路文档，只在网页画布里生效；**本文说的 MetaDig Skill** 是给 Cursor、Claude Code 这类站外 Agent 用的，让它们学会用命令行调用 MetaDig。两者互不依赖。画布 Skill 的用法见同栏目的《Skill 完全指南》。

## 相关地址

- GitHub 仓库：[github.com/pythonthink/metadig-skills](https://github.com/pythonthink/metadig-skills)（`git clone` 后把 `metadig/` 放进 Skills 目录即可）
- Skill 包下载：`https://waytometa.cn/cli-dist/latest/metadig-cli-skill.zip`（解压得到 `metadig/` 目录，与仓库同内容）
- 在线阅读 Skill 正文：`https://waytometa.cn/cli-dist/latest/skill/metadig/SKILL.md`
- CLI 落地页（含一键复制的安装提示词）：[/cli](/cli)
- CLI 安装脚本：`https://waytometa.cn/cli/install.sh`（macOS / Linux）、`https://waytometa.cn/cli/install.ps1`（Windows）
- Skill 格式遵循开放规范 [Agent Skills](https://agentskills.io)，所以任何支持该规范的 Agent 都能直接读取。

## 你可以用它做什么

- 用一句话让 Agent 生成单张或多张图片，指定比例、分辨率、张数，或带参考图改图。
- 文生视频、首帧生视频、首尾帧、参考生视频四种方式出片，Agent 按你给的素材自动选方式。
- 文字转语音（多种音色）和 AI 音乐（带歌词或纯音乐）。
- 查询当前可用的模型、积分价格和参数档位——Agent 生成前会先查一遍，不会凭记忆写过时的模型 ID。
- 批量生成前先报方案和预计积分，你点头它才跑；任务失败不扣积分，它也不会原样重提。
- 产物自动落到你的网页画布项目（提交即出现「生成中」节点，完成自动回填），也可以顺手下载到本地目录。
- 在 Agent 工作流里统一用 `metadig` 命令和 `--json` 输出，稳定、可脚本化。

## 五步开始

1. 准备一个支持 Agent Skill 的工具（Cursor、Claude Code、Codex、OpenClaw 等）。
2. 拿到 Skill：`git clone https://github.com/pythonthink/metadig-skills.git`，或下载上面的 zip 并解压，都会得到 `metadig/` 目录。
3. 把 `metadig/` 放进你的 Skills 目录（见下一节），重开一次 Agent 会话让它发现新 Skill。
4. 让 Agent 安装 CLI 并登录：`metadig login` 会打开浏览器，你在网页上点一下「授权登录」就行。CLI 登录和网页登录并存，不会互相顶掉。
5. 直接对 Agent 说需求，例如「用 metadig 给 ./photos 里的 6 张产品图各出一张 16:9 的白底电商主图，先告诉我大概要多少积分」。

**更省事的做法**：打开 [/cli](/cli)，复制「发给 AI 助手的提示词」发给 Agent，它会自己下载、解压、放进 Skills 目录并完成安装登录——上面五步它一次做完。

## 装到哪个目录

Skill 就是一个包含 `SKILL.md` 的文件夹，放进 Agent 会扫描的目录即可。常见位置：

| 工具 | 项目级（只对当前仓库生效） | 用户级（本机所有项目） |
| --- | --- | --- |
| 通用约定（多数 Agent 都认） | `.agents/skills/metadig/` | `~/.agents/skills/metadig/` |
| Cursor | `.cursor/skills/metadig/` | `~/.cursor/skills/metadig/` |
| Claude Code | `.claude/skills/metadig/` | `~/.claude/skills/metadig/` |
| Codex | `.codex/skills/metadig/` | `~/.codex/skills/metadig/` |
| OpenClaw 等其他工具 | 按其文档的 skills 目录放置 | — |

放好后在对话里输入 `/metadig`（Cursor / Claude Code 支持斜杠直接调用）或直接描述需求，Agent 会按 Skill 的 `description` 自动判断何时启用。

> [!TIP] 不想装 Skill 也能用
> 直接把 `SKILL.md` 的内容或链接丢给 Agent 读一遍，效果一样，只是下次新会话要再给一次。装进 Skills 目录的好处是一次安装、以后每个会话自动可用。

## Skill 文件在哪里、长什么样

Skill 目录结构：

```text
metadig/
├── SKILL.md                         # 主文档：安装登录、命令速查、关键工作流、重要规则
└── references/
    ├── cli-command-guide.md         # 每个命令的完整参数、环境变量、配置文件、JSON 输出字段
    ├── generation-guide.md          # 选模型、估积分、视频方式与参数约束、音色清单、产物落画布
    └── common-pitfalls.md           # 报错对照表：登录 / 超时 / 积分 / 模型不可用 / 上传下载
```

`SKILL.md` 顶部是一段 YAML 元信息（`name: metadig` 和一段说明「做什么、什么时候用」），Agent 启动时只加载这几十个字来判断相关性；真正用到时才读正文；`references/` 里的细节只在需要时按需读取。这就是规范里说的「渐进式加载」——装十几个 Skill 也不会把 Agent 的上下文撑爆。

主文档明确要求 Agent 优先使用这些公开命令：

```bash
metadig models            # 查模型与价格（生成前必查）
metadig gen image         # 图片
metadig gen video         # 视频
metadig gen speech        # 语音
metadig gen music         # 音乐
metadig status            # 查任务 / 等待 / 下载
metadig history           # 任务记录
```

## 和 Agent 怎么说话

装好之后像跟同事交代一样说就行：

> 用 metadig 出一张竖屏 9:16 的秋日海报，2K，写实风格，出好后下载到 ./exports。

> 先查一下现在哪个视频模型支持首帧生视频、10 秒多少积分，报个价给我；我点头后用 ./cover.png 做首帧出一条。

> 把 ./script.txt 里的旁白用成熟女声配音，落到「秋日短片」这个项目里。

Agent 会先跑 `metadig models` 查最新目录和价格，再决定用哪个模型、要不要先向你确认，然后提交、等待、把链接和落画布的节点整理给你。

## 积分与安全

- Skill 本身免费。花积分的只有 Agent 提交的生成任务，价格与网页端同价同折扣；任务失败、取消、超时都不扣。
- Skill 里写死了几条保护你的规则：视频和批量任务先报价再跑、积分不足就停下来提醒、提交超时先查状态不重复提交、失败不原样重试。
- 登录走浏览器授权，终端和 Agent 都不经手你的密码。凭证存在本机 `~/.metadig/credentials.json`，约 30 天有效。
- 只在自己的设备上点授权链接；别人发来的授权链接一律别点——点了就等于把账号交给对方的终端。

## 和「命令行」栏目的区别

「命令行」栏目面向**人**，逐条解释 `metadig` 的每个命令和参数，适合你自己在终端里敲。「MetaDig Skill」面向 **Agent**，重点是安装位置、授权方式、推荐工作流和禁止事项，让 Agent 替你敲命令。两边描述的是同一个工具，命令行栏目的内容也是 Skill 里 `references/cli-command-guide.md` 的人类可读版。

## 和画布「Skill 广场」的区别

| | 画布 Skill 广场 | MetaDig Skill（本文） |
| --- | --- | --- |
| 谁读 | 网页画布里的 Agent | Cursor / Claude Code 等站外 Agent |
| 内容 | 你写的创作套路（风格、分镜流程、产出要求） | 官方维护的 `metadig` 命令行操作手册 |
| 在哪用 | 网页画布对话框里启用 | 你自己的编辑器 / 终端 / Agent 工具里 |
| 谁来写 | 你或社区作者，可发布到广场 | MetaDig 官方，随 CLI 一起更新 |
| 怎么拿 | 广场里点「使用」 | 下载 zip 放进 Skills 目录 |

两者可以一起用：先在画布里用 Skill 广场的套路把风格跑顺，再让站外 Agent 用命令行批量产出同一画布里的素材。

## 常见问题

**Agent 说找不到 metadig 命令。** CLI 还没装或刚装完 PATH 没刷新。让 Agent 重跑安装脚本，然后重开一个终端；`~/.metadig/metadig --version` 能跑说明装好了。

**Agent 装了 Skill 但没有自动用。** 确认目录名是 `metadig`、里面有 `SKILL.md`，并且重开过一次会话；也可以在对话里直接 `/metadig` 手动调用。还不行就把 `SKILL.md` 内容贴给它。

**能不能不装 CLI，让 Agent 直接调 MetaDig 的接口？** 不建议，Skill 里也明确禁止。命令行是稳定的公开入口，内部接口随时会变；命令行缺功能时升级 CLI 即可。

**Skill 会自动更新吗？** 不会。Skill 随 CLI 版本一起发布，重新下载 zip 覆盖 `metadig/` 目录即可；`SKILL.md` 与 CLI 命令一一对应，旧 Skill 配新 CLI 一般也能用。

**在服务器或没有浏览器的环境怎么登录？** `metadig login --no-open` 只打印授权链接，你在任何已登录网页的设备上打开它授权即可；再不行就设置 `METADIG_TOKEN` 环境变量。细节见 Skill 的 `references/common-pitfalls.md` 或命令行栏目。