Skills

The five Windpaint agent skills: what each one teaches an agent, and how to install them.

Skills are short instruction files (SKILL.md) an agent loads when a request matches. The Windpaint skills teach an agent how to use Windpaint well: read models and prices from the API instead of guessing, estimate before spending, wait on long jobs instead of resubmitting them, and chain outputs into inputs by asset id.

They live in the public repo windpaint-ai/skills, packaged as a plugin for Claude Code, Codex and Cursor. The plugin also connects the MCP server.

Install

/plugin marketplace add windpaint-ai/skills
/plugin install windpaint@windpaint

Cursor installs from its plugin marketplace; see Cursor. All of them need your key in the environment:

export WINDPAINT_API_KEY=aak_...

npx skills add copies only the SKILL.md files into your agent’s skills directory. It doesn’t connect the MCP server. Add that separately (MCP server), or let the agent work through the CLI or the REST API, which the windpaint skill falls back to when no MCP tools are present.

The skills

In Claude Code they’re namespaced by the plugin: /windpaint:windpaint, /windpaint:windpaint-image, and so on. You rarely need to call them by name; the agent picks them up from the request.

windpaint

The base skill every other one builds on. It tells the agent to:

• Pick a surface: MCP tools when connected, else the windpaint CLI if installed, else curl against the REST API.
• Check WINDPAINT_API_KEY is set without printing it, and never ask you to paste a key into the chat.
• Call list_capabilities first and never rely on model names or prices from memory. A capability with no available model can’t run, and the agent says so.
• Check list_products before chaining capabilities by hand.
• Estimate every video job, product run and batch, and report the credits and your available balance before running.
• On 402 billing.insufficient_credits, offer a cheaper option rather than retry.
• Treat jobs as async, and never resubmit because a wait timed out. Resubmit only after a terminal failed, once.
• Put inputs in named slots by asset id, upload external URLs first, and keep work in one project.
• Report back what ran, the credits charged, and where the output is, without dumping raw JSON.

windpaint-image

Text to image with image.generate:

• Pick aspect_ratio and resolution from what the catalog lists (for example 16:9 for a future video start frame, 9:16 for a vertical post). Leave model unset unless there’s a reason.
• Set seed when you want to reproduce or vary a result.
• Skip the estimate for a single image; for a batch, estimate once, multiply, and tell you the total first.
• Generate with wait=true, download the output, and report the path, model, resolution and credits.
• Prompting: subject first, then setting, composition, lighting and style; change one thing per attempt and keep the seed.

It also covers image.edit (sources in the images slot, an optional mask), which only runs once a model for it is live.

windpaint-video

Animate an image into a clip with video.generate:

• Read each model’s slots: a start_frame with min: 1 means a start image is required.
• Get the start frame from an upload, an existing asset id, or a still generated first at the same aspect ratio. If you only gave a prompt, check for the text-to-clip product first.
• Estimate, tell you the credits and balance, and wait for approval unless you’ve already approved spending.
• Submit with wait=false, then wait_for_job with timeout_s=600, calling it again while the job runs.
• Prompting: describe what moves and how the camera moves, not the image again. One action per clip.
• On failed, retry once only if it looks transient. On nsfw, tell you.

windpaint-products

Run products, multi-step workflows with a small input form:

• list_products, then read each product’s inputs, outputs, available and unavailable_reasons, and credits_estimate.
• Fill the form (text and choices as strings, media as one asset id), estimate_product, and report the cost.
• run_product with wait=false, then get_run with wait=true until it finishes. Never start a second run because a wait timed out.
• Download the named outputs (for text-to-clip: video, still, cover).
• Credits are checked at the start but held per step, so a run can fail midway if the balance drops. Credits for steps that completed are not returned.

windpaint-api

For building Windpaint into an app, backend or script, in any language:

• The endpoints, base URL, Authorization: Bearer auth, and which responses are bare versus wrapped in {"data": ...}.
• Submit and poll with backoff; handle every terminal status, including nsfw and canceled.
• Per-job webhooks are unsigned, sent once, and not retried, so treat them as a hint and re-fetch the status with your key.
• Keep the key server-side. Store asset ids, not signed URLs, and fetch content through your backend.
• Branch on error.code, log error.request_id, and don’t retry 4xx errors.
• No idempotency keys: before resubmitting after a timeout, list recent requests and look for the job you meant to create.

This skill doesn’t need the MCP server. The cookbook has the same patterns as runnable code.

Next steps