@assemblyline-agents/higgsfield 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenEve contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# @assemblyline-agents/higgsfield
+
+Official Assembly Line connection plugin for Higgsfield's CLI-first coding-agent
+workflow. Higgsfield remains a normal developer-selectable connection; its
+transport runs the official CLI inside the active agent sandbox rather than
+launching a process on the Assembly Line gateway.
+
+## Install and select
+
+```sh
+assembly-line add higgsfield agent
+```
+
+This creates `connections/higgsfield.ts`:
+
+```ts
+import { defineHiggsfieldConnection } from "@assemblyline-agents/higgsfield";
+
+export default defineHiggsfieldConnection({
+  access: {
+    read: true,
+    write: false
+  }
+});
+```
+
+Enable generation and editing only after choosing an approval policy:
+
+```ts
+write: { approval: "always" }
+```
+
+The connection exposes `higgsfield__read` for discovery, status, cost, history,
+and polling, plus `higgsfield__write` for upload, generation, training,
+editing, reframing, and assembly. The write operation can create remote assets
+and consume account credits.
+
+Assign it to a subagent with the same connection abstraction:
+
+```ts
+export default defineSubagent({
+  description: "Create and edit social video.",
+  connections: ["higgsfield"]
+});
+```
+
+`assembly-line add` also copies the bundled `higgsfield-generate`,
+`higgsfield-soul-id`, and `higgsfield-product-photoshoot` skills.
+
+## Why the transport is a sandbox CLI
+
+The connection definition compiles as `protocol: "cli"` and
+`transport: "sandbox"`. Tool discovery, subagent scoping, access policy,
+approval, tracing, and developer selection stay in the connection layer. At
+execution time, Assembly Line invokes the reviewed command in the active run
+sandbox, where it can consume `/files/...` attachments and write results to
+`/workspace`.
+
+Model-authored shell source is never accepted. The plugin validates the
+official command surface, Assembly Line shell-quotes each argument, hydrates logical
+input paths, and adds `--json --no-color`.
+
+## Sandbox setup
+
+Install the official CLI in the sandbox image or template:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh
+```
+
+Then authenticate interactively inside the persistent sandbox belonging to
+that user:
+
+```sh
+higgsfield auth login
+```
+
+Do not bake CLI credentials into a shared image or reuse one authenticated
+sandbox across unrelated users. Higgsfield's current CLI login is
+browser-based OAuth with a loopback callback, so sandbox provisioning must
+make that login reachable. If the sandbox is ephemeral, retain the user's
+authenticated CLI home with a user-scoped snapshot or persistent volume.
+
+The plugin rejects auth-token, website repository-token, and secret-management
+commands.
+
+Official references:
+
+- https://higgsfield.ai/cli
+- https://higgsfield.ai/skills
+- https://github.com/higgsfield-ai/cli
+- https://github.com/higgsfield-ai/skills

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { type ConnectionDefinition, type ConnectionPluginAccessSelection } from "@assemblyline-agents/core";
+export interface HiggsfieldConnectionOptions {
+    /** Executable path only. Shell fragments and extra arguments are not accepted. */
+    command?: string;
+    description?: string;
+    access: ConnectionPluginAccessSelection;
+    readTimeoutMs?: number;
+    writeTimeoutMs?: number;
+    maxOutputChars?: number;
+    required?: boolean;
+    subject?: ConnectionDefinition["subject"];
+}
+export interface HiggsfieldToolInput {
+    /** Official Higgsfield CLI arguments, excluding the `higgsfield` executable. */
+    args: string[];
+}
+export declare function defineHiggsfieldConnection(options: HiggsfieldConnectionOptions): import("@assemblyline-agents/core").SandboxCliConnectionDefinition;
+export declare const openevePlugin: import("@assemblyline-agents/core").PluginModule;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,+BAA+B,EAGrC,MAAM,2BAA2B,CAAC;AAgEnC,MAAM,WAAW,2BAA2B;IAC1C,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,+BAA+B,CAAC;IACxC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,oBAAoB,CAAC,SAAS,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,2BAA2B,sEAuB9E;AAED,eAAO,MAAM,aAAa,kDAA0C,CAAC"}

package/dist/index.js

@@ -0,0 +1,185 @@
+import { connectionPluginMetadata, definePlugin, defineSandboxCliPluginConnection } from "@assemblyline-agents/core";
+const PLUGIN = connectionPluginMetadata("higgsfield");
+const DEFAULT_READ_TIMEOUT_MS = 10 * 60_000;
+const DEFAULT_WRITE_TIMEOUT_MS = 30 * 60_000;
+const MAX_ARGUMENTS = 160;
+const MAX_ARGUMENT_LENGTH = 32_000;
+const READ_COMMANDS = new Set([
+    "account:status",
+    "account:transactions",
+    "generate:cost",
+    "generate:get",
+    "generate:list",
+    "generate:wait",
+    "model:get",
+    "model:list",
+    "preset:list",
+    "soul-id:get",
+    "soul-id:list",
+    "soul-id:wait",
+    "upload:list",
+    "voices:get",
+    "voices:list",
+    "workflow:get",
+    "workflow:list",
+    "workspace:list",
+    "workspace:status"
+]);
+const MARKETING_READ_RESOURCES = new Set([
+    "ad-formats",
+    "ad-references",
+    "avatars",
+    "brand-kits",
+    "hooks",
+    "products",
+    "settings",
+    "webproducts"
+]);
+const WRITE_COMMANDS = new Set([
+    "generate:create",
+    "generate:workflow",
+    "marketplace-cards:create",
+    "preset:resolve",
+    "product-photoshoot:create",
+    "soul-id:create",
+    "upload:create",
+    "workspace:set",
+    "workspace:unset"
+]);
+const MARKETING_WRITE_COMMANDS = new Set([
+    "ad-references:create",
+    "avatars:create",
+    "brand-kits:fetch",
+    "dtc-ads:generate",
+    "products:create",
+    "products:fetch",
+    "webproducts:create",
+    "webproducts:fetch"
+]);
+export function defineHiggsfieldConnection(options) {
+    return defineSandboxCliPluginConnection(PLUGIN, {
+        ...(options.command ? { command: options.command } : {}),
+        ...(options.description ? { description: options.description } : {}),
+        access: options.access,
+        tools: [
+            higgsfieldTool("read", "Inspect Higgsfield models, workflows, jobs, media, account state, and generation cost.", validateReadCommand, options.readTimeoutMs ?? DEFAULT_READ_TIMEOUT_MS),
+            higgsfieldTool("write", "Create, upload, train, edit, reframe, or assemble media with Higgsfield.", validateWriteCommand, options.writeTimeoutMs ?? DEFAULT_WRITE_TIMEOUT_MS)
+        ],
+        ...(options.maxOutputChars !== undefined ? { maxOutputChars: options.maxOutputChars } : {}),
+        ...(options.required !== undefined ? { required: options.required } : {}),
+        ...(options.subject ? { subject: options.subject } : {})
+    });
+}
+export const openevePlugin = definePlugin({ connections: [PLUGIN] });
+function higgsfieldTool(name, description, validateCommand, timeoutMs) {
+    return {
+        name,
+        description,
+        inputSchema: higgsfieldInputSchema(),
+        build(input) {
+            const args = validatedArguments(input);
+            validateCommand(args);
+            return {
+                args: [...args, "--json", "--no-color"],
+                cwd: "/workspace",
+                timeoutMs,
+                hydratePaths: sandboxInputPaths(args)
+            };
+        }
+    };
+}
+function higgsfieldInputSchema() {
+    return {
+        type: "object",
+        properties: {
+            args: {
+                type: "array",
+                description: "Canonical Higgsfield CLI arguments. Do not include the executable, --json, or --no-color.",
+                items: { type: "string" },
+                minItems: 1,
+                maxItems: MAX_ARGUMENTS
+            }
+        },
+        required: ["args"],
+        additionalProperties: false
+    };
+}
+function validatedArguments(input) {
+    const argsValue = input && typeof input === "object" && !Array.isArray(input)
+        ? input.args
+        : undefined;
+    if (!Array.isArray(argsValue) || argsValue.length === 0) {
+        throw new Error("Higgsfield requires a non-empty args array.");
+    }
+    if (argsValue.length > MAX_ARGUMENTS) {
+        throw new Error(`Higgsfield accepts at most ${MAX_ARGUMENTS} arguments per call.`);
+    }
+    const args = argsValue.map((argument) => {
+        if (typeof argument !== "string")
+            throw new Error("Every Higgsfield argument must be a string.");
+        if (argument.includes("\0"))
+            throw new Error("Higgsfield arguments cannot contain NUL bytes.");
+        if (argument.length > MAX_ARGUMENT_LENGTH) {
+            throw new Error(`A Higgsfield argument exceeded ${MAX_ARGUMENT_LENGTH} characters.`);
+        }
+        return argument;
+    });
+    if (args.includes("--json") || args.includes("--no-color")) {
+        throw new Error("OpenEve adds --json and --no-color automatically; omit them from args.");
+    }
+    return args;
+}
+function validateReadCommand(args) {
+    if (args.includes("--help") || args.includes("-h"))
+        return;
+    if (args[0] === "version")
+        return;
+    const command = `${args[0] ?? ""}:${args[1] ?? ""}`;
+    if (READ_COMMANDS.has(command))
+        return;
+    if (args[0] === "marketing-studio"
+        && MARKETING_READ_RESOURCES.has(args[1] ?? "")
+        && (args[2] === "list" || args[2] === "get"))
+        return;
+    throw new Error(`Higgsfield read tool does not allow "${args.slice(0, 3).join(" ")}". Use the write tool for approved mutations.`);
+}
+function validateWriteCommand(args) {
+    if (args[0] === "auth") {
+        throw new Error("Higgsfield auth commands are never exposed to agents. Authenticate the user-scoped sandbox interactively.");
+    }
+    if (args[0] === "website" && (args[1] === "repo-access" || args[1] === "secrets")) {
+        throw new Error("Credential-returning Higgsfield website commands are not exposed to agents.");
+    }
+    const command = `${args[0] ?? ""}:${args[1] ?? ""}`;
+    if (WRITE_COMMANDS.has(command))
+        return;
+    if (args[0] === "marketing-studio"
+        && MARKETING_WRITE_COMMANDS.has(`${args[1] ?? ""}:${args[2] ?? ""}`))
+        return;
+    throw new Error(`Higgsfield write tool does not allow "${args.slice(0, 3).join(" ")}".`);
+}
+function sandboxInputPaths(args) {
+    const paths = new Set();
+    for (const argument of args) {
+        const candidates = [argument];
+        const equals = argument.indexOf("=");
+        if (equals >= 0)
+            candidates.push(argument.slice(equals + 1));
+        for (let candidate of candidates) {
+            if (candidate.startsWith("@"))
+                candidate = candidate.slice(1);
+            if (candidate === "/files"
+                || candidate.startsWith("/files/")
+                || candidate === "/memory"
+                || candidate.startsWith("/memory/")
+                || candidate === "/skills"
+                || candidate.startsWith("/skills/")
+                || candidate === "/history"
+                || candidate.startsWith("/history/")) {
+                paths.add(candidate);
+            }
+        }
+    }
+    return [...paths];
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@assemblyline-agents/higgsfield",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@assemblyline-agents/core": "0.1.0"
+  },
+  "description": "Official OpenEve sandbox CLI connection and skills for Higgsfield creative media workflows.",
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jasonbadeaux/openeve.git",
+    "directory": "packages/higgsfield"
+  },
+  "bugs": {
+    "url": "https://github.com/jasonbadeaux/openeve/issues"
+  },
+  "homepage": "https://github.com/jasonbadeaux/openeve#readme",
+  "author": "OpenEve contributors",
+  "keywords": [
+    "openeve",
+    "ai",
+    "agents",
+    "higgsfield",
+    "video",
+    "creative",
+    "media",
+    "plugin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/skills/higgsfield-generate/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: higgsfield-generate
+description: Generate, analyze, transform, or reframe images, video, 3D assets, and audio with the official Higgsfield CLI. Use for image or video generation, image-to-video, existing-video analysis, Draw to Edit, vertical reframing, Marketing Studio ads, 3D creation, or generated audio. Do not use for local cutting or stitching when FFmpeg or Remotion is the better tool.
+---
+
+# Higgsfield Generate
+
+Use the reviewed `higgsfield__read` and `higgsfield__write` connection tools. They run the
+official `higgsfield` CLI inside the same sandbox that owns `/files` and
+`/workspace`.
+
+Pass CLI arguments as an array without the executable:
+
+```json
+{"args":["model","list"]}
+```
+
+Assembly Line adds `--json --no-color`. Never include either flag yourself. Never use
+Higgsfield auth commands; if the CLI reports an expired or missing session, ask
+the user to run `higgsfield auth login` interactively in their persistent
+sandbox.
+
+## Operating rules
+
+1. Use `higgsfield__read` for discovery, account status, cost, job history, and
+   polling.
+2. Use `higgsfield__write` for uploads, generation, workflows, and training.
+   These calls require approval because they create remote state or
+   consume credits.
+3. Pass `/files/...` or `/workspace/...` media paths directly. The CLI
+   auto-uploads supported local files; do not pre-upload unless a later step
+   needs a reusable upload ID.
+4. Prefer `--wait` for generation so one call returns the completed job. Use
+   `--wait-timeout 20m` when a longer job needs it.
+5. Return result URLs and a concise summary. Do not dump raw job IDs or large
+   JSON unless the user asks.
+6. Do not silently replace video understanding with random or sparse frame
+   sampling. Use Virality Predictor for supported creative analysis, or state
+   the limitation.
+
+## Discover before generating
+
+Start with the full catalog when the exact model or feature is uncertain:
+
+```json
+{"args":["model","list"]}
+```
+
+Then inspect the chosen model:
+
+```json
+{"args":["model","get","seedance_2_0"]}
+```
+
+Workflows are separate:
+
+```json
+{"args":["workflow","list"]}
+{"args":["workflow","get","reframe"]}
+```
+
+Do not conclude that a feature is unavailable from a filtered or semantic
+search alone. Check the unfiltered model or workflow list.
+
+## Current quality defaults
+
+- General images, graphic design, typography, and on-image text: GPT Image 2.
+- Serious video, multi-shot motion, image-to-video, and video references:
+  Seedance 2.0.
+- Character, cartoon, stylized, or reference-driven images: Nano Banana 2;
+  Lite for speed, Pro for harder briefs.
+- Ads, UGC, product demos, unboxing, presenters, and brand workflows:
+  Marketing Studio.
+- Text-to-audio, sound effects, ambience, foley, and music-like audio:
+  Seed Audio 1.0.
+
+Resolve the current CLI ID with `model list`; model availability changes.
+
+## Generation
+
+Examples below are `args` for `higgsfield__write`:
+
+```json
+{"args":["generate","create","gpt_image_2","--prompt","neon city at dusk","--aspect_ratio","16:9","--resolution","2k","--wait"]}
+```
+
+```json
+{"args":["generate","create","seedance_2_0","--prompt","camera dollies in","--start-image","/files/first.png","--duration","12","--resolution","4k","--wait"]}
+```
+
+```json
+{"args":["generate","create","seed_audio","--prompt","cinematic rain ambience with distant thunder","--wait"]}
+```
+
+For a prior job, use `higgsfield__read`:
+
+```json
+{"args":["generate","get","<job_id>"]}
+{"args":["generate","wait","<job_id>"]}
+```
+
+## Existing video
+
+Read [references/workflows.md](references/workflows.md) before editing or
+reframing an existing video. Read
+[references/media-inputs.md](references/media-inputs.md) before passing video,
+image, or audio references.
+
+Higgsfield currently provides:
+
+- `draw_to_video` for editing a source video from an edited/sketched frame at a
+  timestamp.
+- `reframe` for converting a source video to a new aspect ratio.
+- `brain_activity`, customer-facing name Virality Predictor, for finished-video
+  hook, attention, retention, and virality analysis.
+
+Higgsfield is not a general timeline editor. Use sandbox FFmpeg or Remotion for
+precise cuts, concatenation, audio replacement, captions, or deterministic
+stitching; use Higgsfield for generative transformations and supported
+server-side assembly.
+
+## Errors
+
+- `Session expired` or `Not authenticated`: ask the user to authenticate the
+  same persistent, user-scoped sandbox.
+- `Missing required params`: ask only for the missing user input.
+- `Unknown params`: inspect the live model or workflow schema.
+- Timeout: rejoin the existing job with `generate wait`; do not submit a
+  duplicate.
+
+Source contract: Higgsfield's official CLI and skills documentation at
+https://github.com/higgsfield-ai/cli and
+https://github.com/higgsfield-ai/skills.

package/skills/higgsfield-generate/references/media-inputs.md

@@ -0,0 +1,34 @@
+# Higgsfield Media Inputs
+
+Pass local sandbox paths or existing Higgsfield UUIDs directly. The CLI
+auto-uploads local paths and detects upload IDs versus completed job IDs.
+
+Supported local extensions include:
+
+- Images: PNG, JPEG, WebP, GIF
+- Video: MP4, MOV, WebM
+- Audio: MP3, WAV, M4A, OGG
+
+Common flags:
+
+- `--image`: image reference
+- `--start-image`: first-frame reference
+- `--end-image`: last-frame reference
+- `--video`: video reference or analyzed video
+- `--audio`: audio reference
+- `--image-references`, `--video-references`, `--audio-references`: repeated
+  reference-array inputs when exposed by the model schema
+
+Inspect `model get <model_id>` before assuming a media role. Important current
+contracts:
+
+- `seedance_2_0` accepts image, start image, end image, video, and audio.
+- `brain_activity` accepts exactly one video and returns a text analysis report.
+- `grok_video_v15` requires one start image.
+- `gemini_omni` accepts up to seven image references or one video reference,
+  with lower image limits when video is also present.
+- `multi_image_to_3d` accepts one to four images.
+- `seed_audio` may use audio or image references, but not both together.
+
+Do not pass `--generate-audio` to Seedance 2.0. Use `--audio` for its reference
+audio.

package/skills/higgsfield-generate/references/workflows.md

@@ -0,0 +1,41 @@
+# Higgsfield Video Workflows
+
+Inspect the live workflow before submission:
+
+```json
+{"args":["workflow","get","draw_to_video"]}
+{"args":["workflow","get","reframe"]}
+```
+
+## Draw to Video
+
+Use when the user supplies a source video, an edited or sketched frame, its
+timestamp, and an edit instruction:
+
+```json
+{"args":["generate","workflow","draw_to_video","--video","/files/source.mp4","--sketch","/files/frame.png","--timestamp","3.2","--prompt","make the jacket red","--wait"]}
+```
+
+`--image` is an alias for `--sketch`.
+
+## Reframe
+
+Use for aspect-ratio conversion:
+
+```json
+{"args":["generate","workflow","reframe","--video","/files/source.mp4","--aspect-ratio","9:16","--resolution","720p","--wait"]}
+```
+
+Optional parameters include `--mode std|pro`, `--start-image`, image references
+for Pro mode, and `--folder-id`.
+
+## Cost and results
+
+Cost uses `generate cost workflow`:
+
+```json
+{"args":["generate","cost","workflow","reframe","--duration","7.1","--resolution","1080p"]}
+```
+
+Workflow jobs are normal generation jobs. Retrieve them with `generate get` or
+`generate wait`, not `workflow get`.

package/skills/higgsfield-product-photoshoot/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: higgsfield-product-photoshoot
+description: Generate brand-quality Higgsfield product photography through the official product-photoshoot prompt enhancer. Use for studio shots, lifestyle scenes, hero banners, Pinterest pins, social carousels, ad creative packs, virtual try-on, conceptual product visuals, or restyling an existing product image.
+---
+
+# Higgsfield Product Photoshoot
+
+Use the approval-gated `higgsfield__write` connection tool with
+`product-photoshoot create`. Do not bypass the backend prompt enhancer with a
+generic GPT Image command.
+
+Choose the most specific mode:
+
+- `product_shot`: neutral, studio, catalog, or storefront image
+- `lifestyle_scene`: product in a real environment
+- `closeup_product_with_person`: hands, partial face, or demonstration
+- `moodboard_pin`: vertical Pinterest-native visual
+- `hero_banner`: wide website or campaign header
+- `social_carousel`: connected multi-slide set
+- `ad_creative_pack`: coordinated paid-social variants
+- `virtual_model_tryout`: product worn or used by a generated model
+- `conceptual_product`: surreal, floating, splash, or CGI-style visual
+- `restyle`: change an existing image's mood or season while preserving subject
+
+Ask only for unresolved essentials: product/reference image, use case or mode,
+count, and desired mood. Pass `/files/...` paths directly:
+
+```json
+{"args":["product-photoshoot","create","--mode","lifestyle_scene","--prompt","cold-brew bottle on a sunlit kitchen counter for Instagram","--image","/files/bottle.jpg","--count","3"]}
+```
+
+Use `--count 1..10` for variants. Let the backend choose aspect ratio unless
+the user explicitly requests one; supported overrides are `1:1`, `4:5`,
+`5:4`, `3:4`, `4:3`, `2:3`, `3:2`, `9:16`, and `16:9`.
+
+Return the image URLs as a short list. Do not expose the enhanced prompt, raw
+job JSON, or internal model IDs.

package/skills/higgsfield-soul-id/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: higgsfield-soul-id
+description: Train and reuse a Higgsfield Soul Character from a person's photos for identity-consistent image or cinematic generation. Use when the user asks to train their face, create a digital twin, build a reusable personal avatar, or preserve identity across generated media.
+---
+
+# Higgsfield Soul Character
+
+Use `higgsfield__read` for account and Soul lookup. Use the approval-gated
+`higgsfield__write` connection tool for training.
+
+Before submission:
+
+1. Check account status; Soul training requires a paid Higgsfield plan.
+2. Collect a name and 5–20 well-lit face photos with varied angles.
+3. Choose `--soul-2` for image generation or `--soul-cinematic` for cinematic
+   use. Default to `--soul-2`.
+
+Pass `/files/...` paths directly; the CLI auto-uploads them:
+
+```json
+{"args":["soul-id","create","--name","Alice","--soul-2","--image","/files/alice-1.jpg","--image","/files/alice-2.jpg","--image","/files/alice-3.jpg","--image","/files/alice-4.jpg","--image","/files/alice-5.jpg"]}
+```
+
+Wait without duplicating the training job:
+
+```json
+{"args":["soul-id","wait","<soul_id>"]}
+```
+
+Use the resulting reference in generation:
+
+```json
+{"args":["generate","create","text2image_soul_v2","--prompt","cinematic portrait at dusk","--soul-id","<reference_id>","--quality","2k","--wait"]}
+```
+
+Do not expose raw IDs in normal chat unless needed. Respect likeness consent;
+never infer permission to train or reuse another person's identity.