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.

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 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
• 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

skills.sh

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

ClawHub

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.

Cursor

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

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

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

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.

Smithery

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:

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.

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

1. 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.

2. 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.

3. 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 modellix-cli model get-schema. See 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:

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

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

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.

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. REST contract: 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.

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