Install the Modellix Agent Skill

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.

The official Modellix Skill teaches your coding agent how to generate images, videos, and speech audio with Modellix. It ships as skills/modellix inside the modellix-plugin repository and installs into any Agent Skills host.

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.

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 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 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 the live model index at llms.txt
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
Recommended: modellix-cli on Node.js 18.17 or later

npm install --global modellix-cli@latest
modellix-cli doctor --json

The skill works without the CLI by calling the REST API, but the CLI gives your agent single-command waiting, safer downloads, and local task history.

Install

Works with any Agent Skills host:

npx skills add https://github.com/Modellix/modellix-plugin --skill modellix

Target one agent:

npx skills add https://github.com/Modellix/modellix-plugin --skill modellix --agent cursor

Update:

npx skills update

Install from ClawHub with the slug modellix:

clawhub install modellix

Or through OpenClaw:

openclaw skills install modellix

Update:

clawhub update modellix
clawhub update --all

The skill slug modellix is separate from the OpenClaw bundle package @modellix/modellix-plugin, which is covered in the Plugin guide.

npx skills add https://github.com/Modellix/modellix-plugin --skill modellix --agent cursor

Update:

npx skills update

You can also set the key as the MODELLIX_API_KEY plugin variable if you install the full plugin instead.

OpenCode plugins are JavaScript event hooks, which Modellix does not use. Install the Agent Skill instead:

npx skills add https://github.com/Modellix/modellix-plugin --skill modellix

Or symlink the skill from a clone:

# 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" }).

Pi can load the repository as a package, which is the preferred path documented in the Plugin guide. For a skill-only install:

npx skills add https://github.com/Modellix/modellix-plugin --skill modellix

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

mkdir -p ~/.pi/agent/skills
ln -sfn /path/to/modellix-plugin/skills/modellix ~/.pi/agent/skills/modellix

Hermes uses Agent Skills rather than plugins:

hermes skills install Modellix/modellix-plugin/skills/modellix

Or symlink into the Hermes skills tree:

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:

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.

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.

Configure Your API Key

export MODELLIX_API_KEY="your_api_key"

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

It first checks the session environment for MODELLIX_API_KEY.
It then checks for a saved CLI profile through modellix-cli auth status or doctor.
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.

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.

Verify the Install

Check the Environment

modellix-cli doctor --json

doctor reports the Node.js version, the API-key source, API connectivity, and your team balance without printing the key.

Prompt Your Agent

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.

Compare with the Manual Flow

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

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 each model’s documentation. The skill reads the docs_url returned by model describe, or follows the links in llms.txt.

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:

modellix-cli model list --type text-to-image --output slugs
modellix-cli model describe google/nano-banana-2 --json

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

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, 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.
`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.
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

Plugin

Install the full plugin from a host marketplace.

CLI

Learn the modellix-cli commands the skill runs.

REST API

Call Modellix directly without the CLI.

Pricing

Review model pricing before running paid tasks.

Getting Started

Ways to Use

Team

Install the Modellix Agent Skill

Skill or Plugin

What the Skill Gives Your Agent

Requirements

Install

Configure Your API Key

Verify the Install

Supported Task Types

Default Models

What Is Inside the Skill

Error Handling the Skill Follows

Troubleshooting

Next Steps

Plugin

CLI

REST API

Pricing

​Skill or Plugin

​What the Skill Gives Your Agent

​Requirements

​Install

​Configure Your API Key

​Verify the Install

​Supported Task Types

​Default Models

​What Is Inside the Skill

​Error Handling the Skill Follows

​Troubleshooting

​Next Steps

Plugin

CLI

REST API

Pricing

Skill or Plugin

What the Skill Gives Your Agent

Requirements

Install

Configure Your API Key

Verify the Install

Supported Task Types

Default Models

What Is Inside the Skill

Error Handling the Skill Follows

Troubleshooting

Next Steps