> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modellix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Install the Modellix Agent Skill

> Install the Modellix Agent Skill so coding agents in Cursor, Claude Code, and other hosts can discover models, inspect request schemas, and generate images, videos, and speech.

<Note>
  Agent Skills are folders of instructions, scripts, and resources that agents discover and load on demand to work more accurately. For background, see [Agent Skills](https://agentskills.io/home).
</Note>

The official Modellix Skill teaches your coding agent how to generate images, videos, and speech audio with [Modellix](https://modellix.ai). It ships as `skills/modellix` inside the [modellix-plugin](https://github.com/Modellix/modellix-plugin) repository and installs into any Agent Skills host.

<Info>
  The skill previously lived in a separate `modellix-skill` repository. That repository is now `modellix-plugin`, and the skill is maintained at `skills/modellix`. Old URLs still redirect, but update your install commands to the new repository.
</Info>

## Skill or Plugin

| Install shape | What you get | When to use it |
| - | - | - |
| **Skill** | Only `skills/modellix` | Any Agent Skills host, or when you do not want a full plugin install |
| **Plugin** | Repository root: plugin manifests plus the skill | Your host has a plugin marketplace (Claude Code, Codex, Cursor, OpenClaw, Pi) |

See the [Plugin](/ways-to-use/plugin) guide for marketplace installs. Both shapes deliver the same skill and behave the same at runtime.

## What the Skill Gives Your Agent

* A CLI-first workflow: `modellix-cli doctor` → `model get-schema` when the body is non-trivial → `model run --wait` → `task download`
* REST fallback with submit-and-poll logic when the CLI is unavailable
* Default models for each task type, so simple prompts do not require a catalog scan
* Model discovery through `model list` and `model describe`, plus live request schemas from `model get-schema`
* An API key lifecycle policy: discover an existing key before asking, prefer session-only keys, and persist only on request
* Retry rules mapped to HTTP status codes and CLI exit codes, including a hard rule against blindly re-running paid submissions

## Requirements

* A Modellix API key from the [Modellix Console](https://www.modellix.ai/console/api-key)
* Recommended: [`modellix-cli`](https://www.npmjs.com/package/modellix-cli) on Node.js 18.17 or later

```bash theme={null}
npm install --global modellix-cli@latest
modellix-cli doctor --json
```

The skill works without the CLI by calling the [REST API](/ways-to-use/api), but the CLI gives your agent single-command waiting, safer downloads, and local task history.

## Install

<Tabs>
  <Tab title="skills.sh">
    Works with any Agent Skills host:

    ```bash theme={null}
    npx skills add https://github.com/Modellix/modellix-plugin --skill modellix
    ```

    Target one agent:

    ```bash theme={null}
    npx skills add https://github.com/Modellix/modellix-plugin --skill modellix --agent cursor
    ```

    Update:

    ```bash theme={null}
    npx skills update
    ```
  </Tab>

  <Tab title="ClawHub">
    Install from [ClawHub](https://clawhub.ai/Modellix/modellix) with the slug `modellix`:

    ```bash theme={null}
    clawhub install modellix
    ```

    Or through OpenClaw:

    ```bash theme={null}
    openclaw skills install modellix
    ```

    Update:

    ```bash theme={null}
    clawhub update modellix
    clawhub update --all
    ```

    <Note>
      The skill slug `modellix` is separate from the OpenClaw bundle package `@modellix/modellix-plugin`, which is covered in the [Plugin](/ways-to-use/plugin) guide.
    </Note>
  </Tab>

  <Tab title="Cursor">
    ```bash theme={null}
    npx skills add https://github.com/Modellix/modellix-plugin --skill modellix --agent cursor
    ```

    Update:

    ```bash theme={null}
    npx skills update
    ```

    You can also set the key as the `MODELLIX_API_KEY` plugin variable if you install the full [plugin](/ways-to-use/plugin) instead.
  </Tab>

  <Tab title="OpenCode">
    OpenCode [plugins](https://opencode.ai/docs/plugins/) are JavaScript event hooks, which Modellix does not use. Install the [Agent Skill](https://opencode.ai/docs/skills/) instead:

    ```bash theme={null}
    npx skills add https://github.com/Modellix/modellix-plugin --skill modellix
    ```

    Or symlink the skill from a clone:

    ```bash theme={null}
    # Global
    mkdir -p ~/.config/opencode/skills
    ln -sfn /path/to/modellix-plugin/skills/modellix ~/.config/opencode/skills/modellix

    # Project-local
    mkdir -p .opencode/skills
    ln -sfn /path/to/modellix-plugin/skills/modellix .opencode/skills/modellix
    ```

    Load it in a session with `skill({ name: "modellix" })`.
  </Tab>

  <Tab title="Pi">
    [Pi](https://github.com/badlogic/pi-mono) can load the repository as a package, which is the preferred path documented in the [Plugin](/ways-to-use/plugin) guide. For a skill-only install:

    ```bash theme={null}
    npx skills add https://github.com/Modellix/modellix-plugin --skill modellix
    ```

    Pi also scans `~/.agents/skills/`. To symlink the skill tree directly:

    ```bash theme={null}
    mkdir -p ~/.pi/agent/skills
    ln -sfn /path/to/modellix-plugin/skills/modellix ~/.pi/agent/skills/modellix
    ```
  </Tab>

  <Tab title="Hermes">
    [Hermes](https://hermes-agent.nousresearch.com/) uses Agent Skills rather than plugins:

    ```bash theme={null}
    hermes skills install Modellix/modellix-plugin/skills/modellix
    ```

    Or symlink into the Hermes skills tree:

    ```bash theme={null}
    mkdir -p ~/.hermes/skills
    ln -sfn /path/to/modellix-plugin/skills/modellix ~/.hermes/skills/modellix
    ```

    To reuse a shared Agent Skills directory, add it to `~/.hermes/config.yaml`:

    ```yaml theme={null}
    skills:
      external_dirs:
        - ~/.agents/skills
    ```

    Start a new session after installing, then invoke `/modellix`. Hermes may prompt securely for `MODELLIX_API_KEY` on first load because the skill declares it as a required environment variable.
  </Tab>

  <Tab title="Smithery">
    ```bash theme={null}
    npx @smithery/cli@latest skill add modellix/modellix-skill
    npx @smithery/cli@latest skill add modellix/modellix-skill --agent cursor
    ```

    To update, run the same `skill add` command again.
  </Tab>
</Tabs>

## Configure Your API Key

```bash theme={null}
export MODELLIX_API_KEY="your_api_key"
```

The skill follows a `discover → request → use for the session → optionally persist` policy:

1. It first checks the session environment for `MODELLIX_API_KEY`.
2. It then checks for a saved CLI profile through `modellix-cli auth status` or `doctor`.
3. Only when neither exists does it ask you for a key.

The CLI resolves keys in this order: `--api-key`, then `MODELLIX_API_KEY`, then the selected saved profile.

<Warning>
  The skill does not persist your key automatically. Ask for persistence explicitly, and prefer `modellix-cli auth login` or `modellix-cli init` so the CLI validates and stores the profile. Never commit an API key or print it in logs.
</Warning>

## Verify the Install

<Steps>
  <Step title="Check the Environment">
    ```bash theme={null}
    modellix-cli doctor --json
    ```

    `doctor` reports the Node.js version, the API-key source, API connectivity, and your team balance without printing the key.
  </Step>

  <Step title="Prompt Your Agent">
    ```text theme={null}
    Generate an image of a cinematic sunset over a futuristic city skyline.
    ```

    The skill picks a default model, submits the task, waits for it, and downloads the result.
  </Step>

  <Step title="Compare with the Manual Flow">
    ```bash theme={null}
    modellix-cli model run \
      --model-slug google/nano-banana-2-lite \
      --body '{"prompt":"A cinematic sunset over a futuristic city skyline"}' \
      --wait --timeout 5m --json

    modellix-cli task download <task_id> --output-dir ./outputs --json
    ```
  </Step>
</Steps>

## Supported Task Types

| Type | Required body fields |
| - | - |
| `text-to-image` | `prompt` |
| `image-to-image` | `prompt` and an `image` array |
| `text-to-video` | `prompt` |
| `image-to-video` | At least one of `first_frame_image`, `last_frame_image`, or `reference_images` |
| `video-to-video` | A `video_urls` array |

Exact schemas come from `modellix-cli model get-schema`. See [Inspect a Request Schema](#inspect-a-request-schema).

## Default Models

When you do not name a model, the skill uses these defaults immediately instead of scanning the catalog:

| Task type | Default model slug |
| - | - |
| Text-to-image | `google/nano-banana-2-lite` |
| Image editing / image-to-image | `google/nano-banana-2-lite-edit` |
| Text-to-video | `bytedance/seedance-2.0-mini-t2v` |
| Image-to-video | `bytedance/seedance-2.0-fast-i2v` |
| Video-to-video | `bytedance/seedance-2.0-fast-v2v` |

Name any other model in your prompt to override the default:

```bash theme={null}
modellix-cli model list --type text-to-image --output slugs
modellix-cli model describe google/nano-banana-2 --json
modellix-cli model get-schema google/nano-banana-2
```

<Tip>
  Model slugs are exact, and decimals matter. Use `bytedance/seedance-2.0-mini-t2v`, not a slug guessed from a documentation filename.
</Tip>

## Inspect a Request Schema

The skill reads the live OpenAPI-style request and response contract with `modellix-cli model get-schema <provider/model>`. The endpoint is public and does not need an API key. JSON is the default.

```bash theme={null}
modellix-cli model get-schema alibaba/qwen-image-3.0-pro
modellix-cli model get-schema alibaba/qwen-audio-3.0-tts-flash --output human
```

Command details: [CLI schema command](/ways-to-use/cli#get-a-model-api-schema). REST contract: [Get Schema](/api/get-schema).

The agent calls `get-schema` when:

* you named a model that is not a skill default
* the body needs fields beyond the documented examples
* a previous submit returned HTTP `400`
* it needs to report required fields, such as TTS voices

It skips `get-schema` when the skill default plus the example already lists the required fields, or you supplied a complete body.

If the CLI is unavailable, the skill falls back to Docs MCP when connected, then `docs_url` from `model describe`, or the model page in [llms.txt](https://docs.modellix.ai/llms.txt).

## What Is Inside the Skill

| Path | Purpose |
| - | - |
| `SKILL.md` | Execution policy, default models, credential lifecycle, error and retry rules |
| `references/cli-playbook.md` | Install, auth, get-schema, run, wait, download, batch, and recovery commands |
| `references/rest-playbook.md` | REST submit-and-poll flow when the CLI is unavailable |
| `references/capability-matrix.md` | CLI to REST mapping and fallback rules |
| `scripts/preflight.py` | Optional environment check that wraps `doctor` and recommends CLI or REST |
| `scripts/invoke_and_poll.py` | Optional wrapper around submit, wait, and download |
| `assets/output/task-result.schema.json` | Schema for task result payloads |

Your agent loads references progressively, reading only the files a task needs.

## Error Handling the Skill Follows

| Situation | Skill behavior |
| - | - |
| `400` | Does not retry. Fixes parameters or the request body first, using `model get-schema` when the contract is unclear. |
| `401` | Does not retry. Repairs auth with `doctor` or `auth login`. |
| `402` | Does not retry. Reports insufficient balance. |
| `404` | Does not retry. Verifies the task ID or model slug. |
| `429` or read-only `5xx` | Relies on CLI retries for safe GET requests, and never re-POSTs a paid submission blindly. |
| Unknown paid submission outcome | Checks `modellix-cli task history` and console activity before submitting again. |
| Exit code `124` | Treats it as a local wait timeout and recovers with `task wait` or `task get`. |
| Exit code `2` | Treats it as an argument or safety-guard rejection and fixes the flags. |

## Troubleshooting

| Problem | What to do |
| - | - |
| The agent ignores the skill | Confirm the skill is installed and enabled, then start a new session. Skills load on demand, so mention Modellix or image, video, or speech generation in your prompt. |
| A model schema is unavailable | Confirm the slug with `model list --output slugs`, then retry `model get-schema`. If the CLI is missing, use Docs MCP or [llms.txt](https://docs.modellix.ai/llms.txt). |
| The agent asks for a key you already set | Export `MODELLIX_API_KEY` in the shell that launched the agent, or save a profile with `modellix-cli auth login`. |
| `task download` fails with a private or reserved network error | Local proxies sometimes map CDN hosts such as `file.modellix.ai` into `198.18.0.0/15`. Retry with `--allow-private-network` for trusted Modellix CDN hosts, or download the resource URL with `curl`. |
| A result URL no longer works | Resource URLs expire after roughly 24 hours. Download results promptly. |
| A bundled helper script fails | Fall back to the direct CLI commands. The scripts are optional. |

## Next Steps

<CardGroup cols={2}>
  <Card title="Plugin" icon="puzzle" href="/ways-to-use/plugin">
    Install the full plugin from a host marketplace.
  </Card>

  <Card title="CLI" icon="terminal" href="/ways-to-use/cli">
    Learn the `modellix-cli` commands the skill runs.
  </Card>

  <Card title="REST API" icon="code" href="/ways-to-use/api">
    Call Modellix directly without the CLI.
  </Card>

  <Card title="Pricing" icon="credit-card" href="/get-started/pricing">
    Review model pricing before running paid tasks.
  </Card>
</CardGroup>