higgsfield · aeonfun — Claude Code skill: what it does, how to install

---
name: higgsfield
description: Generate images and video through the Higgsfield MCP - text-to-image, text-to-video, and image-to-video with motion control across 100+ models. Generation draws real credits from the connected Higgsfield account; OAuth Connect via the dashboard MCP panel.
metadata:
  title: Higgsfield
  mode: read-only
  category: productivity
  var: ""
  tags:
    - content
    - media
    - mcp
  mcp:
    - higgsfield
  capabilities:
    - external_api
    - writes_external_host
    - sends_notifications
---
> **${var}** — the generation request. **Required.** Prefix picks the mode:
> - `image: <prompt>` (or a bare `<prompt>`) → text-to-image
> - `video: <prompt>` → text-to-video
> - `animate: <image-url> | <motion prompt>` → image-to-video (motion control)
>
> Optional trailing hints are honoured when the server supports them: `--ar 16:9` / `--ar 9:16` (aspect ratio), `--seconds N` (video duration), `--n K` (output count, capped below), `--model <name>`. If empty, log `HIGGS_NO_PROMPT` and exit cleanly — **no notify**. This skill spends credits, so it never fires on a blank/default run.

Generate visual media through the **Higgsfield** MCP server (`mcp.higgsfield.ai/mcp`): text-to-image, text-to-video, and image-to-video with motion control, across Higgsfield's library of 100+ generative models. **Every generation consumes real credits from the operator's Higgsfield account** — spend is irreversible, so the run is prompt-gated and bounded.

## Detection & auth

The server is wired by the dashboard MCP panel's one-click **Connect** (OAuth, Authorization Code + PKCE with `offline_access`; tokens stored as `MCP_HIGGSFIELD_TOKEN` + `MCP_HIGGSFIELD_OAUTH`, refreshed each run by `scripts/mcp-oauth-refresh.sh`). Its tools surface as `mcp__higgsfield__*` — discover them from the server; the tool descriptions are the source of truth, don't assume a fixed list or invent model names.

- **No `mcp__higgsfield__*` tool callable** → the server isn't connected (or its secrets are missing, in which case the workflow logged a `::warning::` and skipped MCP). Log `HIGGS_NOT_CONNECTED`, notify once pointing the operator at the dashboard → MCP → Connect Higgsfield, and exit. Don't try to reach the API with curl — there is no static key.
- **Tools exist but return 401/invalid-token** → the OAuth refresh failed (rotating refresh tokens need `GH_SECRETS_PAT` — see `docs/mcp-oauth.md`). Log `HIGGS_AUTH_STALE`, notify the operator to re-connect the server once in the dashboard, and exit. Don't retry the same call more than twice.
- **Payment-required / insufficient-credits errors** → log `HIGGS_NO_CREDITS`, notify the operator to top up their Higgsfield account, and exit with any partial output already returned (clearly marked partial).

## Steps

### 1. Parse the request

From `${var}`, resolve:
- **Mode** — image / video / animate (from the prefix; default `image` when none given).
- **Prompt** — the descriptive text. For `animate:`, split on `|` into the source image URL and the motion prompt.
- **Params** — aspect ratio, duration, count, model from the `--` hints. Only pass params the chosen tool actually accepts (read its schema); drop the rest silently.

Pick the model/tool that fits the mode. When several fit, prefer the tool's default or the one the server marks recommended — don't guess an exotic model.

**Spend budget:** **one** generation per run by default; `--n K` may request more only up to a hard cap of **2** outputs total per run. Never loop "one more" generation beyond the cap. This is a hard limit (STRATEGY: stay within configured spend limits).

### 2. Generate

Call the generation tool with the resolved prompt + params. Higgsfield generation is **asynchronous** — most tools return a job/prediction id rather than the finished asset. If the server exposes a status/result tool, poll it until the job reports complete, **failed**, or you hit a bound of ~20 polls (stop and report a timeout rather than polling forever). If the tool blocks until done and returns assets directly, use that.

- Submit as the **final substantive action** of the run (fail-closed: parsing, budget checks, and log prep happen first, so a generation failure surfaces in this run).
- One retry at most on a transient error; never re-submit a job that already succeeded (that double-charges).
- Capture the server's response verbatim: job id, status, output asset URL(s), and any cost/credit figure it returns.

### 3. Collect output

Gather the finished asset URL(s) and the model actually used. If the job failed or timed out, capture the server's error/status — **never** fabricate an asset URL or claim a generation that has no URL back.

### 4. Notify

This skill is on-demand — a completed run always notifies. Deliver via `./notify -f` (ordinary Markdown), **exactly one `./notify` call per run** (each call overwrites `$AEON_PENDING_DIR/.pending-higgsfield.md`, the chain artifact `consume:` steps and the feed read — a second ping would clobber the result):

- **Success:** the mode + model used, the prompt (trimmed), and each output asset as a clickable URL. Include the credit/cost figure if the server returned one, and the job id. Severity `success`.
- **Failure / refusal / no-credits:** exactly what happened (auth stale, no credits, content rejected, timeout) and the one action the operator can take. Severity `warn`.

Note assets may be time-limited signed URLs — say so and suggest the operator save anything they want to keep.

### 5. Log

This skill is `read-only`, so the workflow's read-only guard writes its `### higgsfield` log entry from your captured output; a self-written entry would be a duplicate. Don't append to `memory/logs/` yourself - put this record in your **final output**:

```
### higgsfield
- Request: <${var}, truncated>
- Result: HIGGS_OK | HIGGS_NO_PROMPT | HIGGS_NOT_CONNECTED | HIGGS_AUTH_STALE | HIGGS_NO_CREDITS | HIGGS_FAILED
- Mode: image | video | animate | model: <name> | outputs: N (cap 2)
- Assets: <url(s) or "none">
- Cost: <credits/USD if returned, else "unknown">
```

## Constraints

- **Credits are real and irreversible.** One generation per run by default, ≤2 outputs total, ever. A `${var}` asking for a batch is capped, not honoured in full — say what was capped in the notify.
- **Content policy.** Refuse prompts for a real, identifiable person's likeness without a clear consent signal in the request, sexual content involving anyone who could be a minor, or other content the platform disallows — log `HIGGS_FAILED` reason=`content-refused`, notify why, and exit. When Higgsfield itself rejects a prompt, relay its reason; don't retry with a reworded prompt to route around a safety refusal.
- **Every asset URL traces to a tool response.** Never estimate, guess, or reconstruct an output that the server didn't return.
- The operator owns every generation this agent triggers — when the request is ambiguous about what to make, refuse and ask rather than spend credits on a guess.