Add Higgsfield skills

skills/.curated/higgsfield-generate/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Higgsfield AI
+
+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.

skills/.curated/higgsfield-generate/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: higgsfield-generate
+description: >-
+  Generate images and videos with Higgsfield AI through the Higgsfield MCP
+  server, including general generation, visual edits, image-to-video, media
+  references, Soul-aware generation, Marketing Studio ads, products, avatars,
+  hooks/settings, and ad references. Use for images, videos, animations,
+  UGC/product-demo/brand clips, or avatar/product-based ads. Not for Soul
+  training, product photoshoots, marketplace cards, chat, or TTS.
+---
+
+# Higgsfield Generate
+
+Use the Higgsfield MCP server as the primary interface for image/video generation and Marketing Studio workflows.
+
+## MCP Tools
+
+- `models_explore` — list, search, recommend, or inspect model schemas.
+- `generate_image` — submit image jobs.
+- `generate_video` — submit video jobs.
+- `show_marketing_studio` — browse/create/fetch avatars, products, webproducts, presets, hooks, settings, and ad references.
+- `show_generations`, `job_status`, `job_display` — browse, poll, and display generation results.
+- `media_upload`, `media_confirm` — prepare local image, video, or audio files for MCP generation.
+
+If MCP tools are unavailable, tell the user that the Higgsfield MCP dependency is missing or not connected. Do not silently switch to shell commands unless the user explicitly asks for them.
+
+## MCP setup
+
+If the Higgsfield MCP server is not connected, ask the user whether to add it:
+
+```bash
+codex mcp add higgsfield --url https://mcp.higgsfield.ai/mcp
+codex mcp login higgsfield
+```
+
+After successful login, the user may need to restart Codex before retrying the task.
+
+## UX Rules
+
+1. Be concise. Return ready result URLs or a short status summary.
+2. Do not expose raw JSON unless the user asks.
+3. Detect the user's language and respond in it. MCP model IDs and parameter names stay English.
+4. Ask one missing-input question at a time; otherwise pick a strong default model.
+5. Do not pre-estimate cost or optimize for cheaper models unless the user asks.
+6. For non-terminal jobs, use `job_status` with the returned job id and respect `poll_after_seconds` if present.
+
+## Generic Generation
+
+1. Pick a model. Use `models_explore` with `action: "recommend"` when uncertain, then `action: "get"` for constraints.
+
+   Image defaults:
+   - Product photoshoot / Pinterest / hero banner / ad pack / virtual try-on → use `higgsfield-product-photoshoot`, not this skill.
+   - Product concept, package, label text, graphic design, UI, banners, typography → `gpt_image_2`.
+   - Character, cartoon, stylized, or reference-driven image → `nano_banana_2`.
+   - Soul Character id from `higgsfield-soul-id` → `soul_2` for stills, `soul_cinematic` for cinematic stills.
+   - Branded ad image with avatar/product context → `marketing_studio_image`.
+   - Default general image → `gpt_image_2`.
+
+   Video defaults:
+   - Ads, UGC, product demos, unboxing, TV spots, branded product clips → `marketing_studio_video`.
+   - Serious general video, image-to-video, motion-heavy, multi-shot, 4–15s → `seedance_2_0`.
+   - Simpler single-plane video when cost matters → `kling3_0`.
+   - Highest cinema-grade video → `cinematic_studio_3_0`.
+   - Fast batch / volume → `veo3_1_lite`.
+
+2. Prepare media.
+   - For HTTPS URLs, previous job IDs, or existing media IDs, pass them in `params.medias`.
+   - For local files, call `media_upload`, upload bytes to the returned presigned URL(s), then call `media_confirm`. Use confirmed media IDs in `params.medias`.
+   - Use the model's declared roles from `models_explore`: `image`, `start_image`, `end_image`, `video`, or `audio`.
+
+3. Submit with `generate_image` or `generate_video`.
+
+```json
+{
+  "params": {
+    "model": "gpt_image_2",
+    "prompt": "neon city at dusk, cinematic reflections",
+    "aspect_ratio": "16:9"
+  }
+}
+```
+
+```json
+{
+  "params": {
+    "model": "seedance_2_0",
+    "prompt": "camera slowly dollies in, soft morning light",
+    "duration": 12,
+    "aspect_ratio": "16:9",
+    "medias": [{ "value": "<media_or_job_id>", "role": "start_image" }]
+  }
+}
+```
+
+4. Deliver the result URL when completed. If the response is pending, poll with `job_status`.
+
+## Marketing Studio
+
+Use Marketing Studio for branded ads, avatar/product campaigns, UGC clips, product demos, and Click-to-Ad flows.
+
+### Product Or Webproduct
+
+- Existing library: `show_marketing_studio` with `action: "list"`, `type: "product"` or `type: "webproduct"`.
+- Product URL: `show_marketing_studio` with `action: "fetch"` and `url`.
+- Uploaded product images: upload/confirm local media first, then `show_marketing_studio` with `action: "create"`, `type: "product"`, `title`, and `medias`.
+- App Store / Play Store / SaaS pages: use `type: "webproduct"` when the ad promotes the app/site instead of one physical item.
+
+For URL-driven Click-to-Ad, call `show_marketing_studio(action: "fetch")`, then immediately follow the returned `next_step` and call `generate_video` with those exact params.
+
+### Avatars
+
+- Presets/custom avatars: `show_marketing_studio` with `action: "list"`, `type: "avatar"`.
+- Custom avatar from local media: upload/confirm the image, then `show_marketing_studio` with `action: "create"`, `type: "avatar"`, and `avatars`.
+- For UGC modes, an avatar is optional if the brief only needs a generic person; pass one when the user wants a specific presenter.
+
+### Hooks, Settings, And Modes
+
+- Presets: `show_marketing_studio` with `action: "presets"`.
+- Hooks: `show_marketing_studio` with `action: "list"`, `type: "hook"`.
+- Settings: `show_marketing_studio` with `action: "list"`, `type: "setting"`.
+- Pass selected IDs to `generate_video` as `hook_id` and/or `setting_id`.
+- Hooks/settings are valid only for Marketing Studio modes listed in `marketing-modes.md`.
+- Do not combine `hook_id`/`setting_id` with `ad_reference_id`.
+
+### Ad References
+
+Use ad references when the user says "make a video like this", "copy this ad style", "use this clip as reference", or similar.
+
+1. For a local reference video, use `media_upload` and `media_confirm` with type `video`.
+2. Call `show_marketing_studio` with `action: "create"`, `type: "ad_reference"`, and `video_input_id`; optionally bind one avatar and/or one product.
+3. Follow the returned `next_step` when present. It includes `ad_reference_id` for `generate_video`.
+4. If the user wants to refine the extracted concept, use `show_marketing_studio` with `action: "update"`, `type: "ad_reference"`, and edited concept fields.
+
+## Errors
+
+- Missing prompt → ask for the prompt.
+- Invalid enum or unknown param → call `models_explore(action: "get", model_id: ...)` and retry with supported params.
+- Auth failure → tell the user to connect/authenticate the Higgsfield MCP server.
+- Failed generation / safety status → briefly explain and ask for a safer revision.
+- Upload issue → retry `media_upload`/`media_confirm`; local paths cannot be passed directly to generation tools.
+
+## Reference Docs
+
+Load on demand:
+
+- `references/model-catalog.md` — picking models and checking schemas.
+- `references/media-inputs.md` — MCP media upload and role handling.
+- `references/prompt-engineering.md` — prompt patterns.
+- `references/troubleshooting.md` — MCP errors and retry handling.
+- `references/marketing-avatars.md` — avatar workflows.
+- `references/marketing-products.md` — product and webproduct workflows.
+- `references/marketing-setup-items.md` — hooks/settings.
+- `references/marketing-ad-references.md` — ad reference videos.
+- `references/marketing-modes.md` — Marketing Studio modes.

skills/.curated/higgsfield-generate/agents/openai.yaml

@@ -0,0 +1,13 @@
+interface:
+  display_name: "Higgsfield Generate"
+  short_description: "Generate images, videos, and ads"
+  brand_color: "#D1FE17"
+  default_prompt: "Use $higgsfield-generate to generate an image or video with Higgsfield AI."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "higgsfield"
+      description: "Higgsfield AI MCP server for image/video generation, Marketing Studio, media, jobs, and Soul Characters"
+      transport: "streamable_http"
+      url: "https://mcp.higgsfield.ai/mcp"

skills/.curated/higgsfield-generate/references/marketing-ad-references.md

@@ -0,0 +1,71 @@
+# Marketing Studio Ad References
+
+Ad references are reusable inspiration videos for "make a video like this" workflows. They extract a reference clip's scenario, pacing, hook, narration style, and composition so `marketing_studio_video` can follow it.
+
+## When To Use
+
+Use an ad reference when the user says:
+
+- "Make a video like this."
+- "Recreate this ad."
+- "Use this clip as a reference."
+- "Copy the structure/style of this product video."
+
+Do not combine ad references with hooks/settings. Pick either:
+
+- Reference-driven: `ad_reference_id`.
+- Composed setup: `hook_id` and/or `setting_id`.
+
+## Create From Local Video
+
+1. Call `media_upload` for the local video.
+2. Upload bytes to the returned URL.
+3. Call `media_confirm` with `type: "video"`.
+4. Call `show_marketing_studio`:
+
+```json
+{
+  "action": "create",
+  "type": "ad_reference",
+  "video_input_id": "<video_media_id>"
+}
+```
+
+Optionally bind one avatar and/or one product:
+
+```json
+{
+  "action": "create",
+  "type": "ad_reference",
+  "video_input_id": "<video_media_id>",
+  "avatars": [{ "id": "<avatar_id>", "type": "preset" }],
+  "product_ids": ["<product_id>"]
+}
+```
+
+The response may include `next_step`; follow it to call `generate_video` with `ad_reference_id`.
+
+## List Or Inspect
+
+Use `show_marketing_studio`:
+
+```json
+{ "action": "list", "type": "ad_reference", "size": 20 }
+```
+
+The response includes status and processed reference metadata. A reference is usable when status is completed.
+
+## Edit Extracted Concept
+
+After analysis, the user can refine the extracted concept:
+
+```json
+{
+  "action": "update",
+  "type": "ad_reference",
+  "ad_reference_id": "<ad_reference_id>",
+  "edited_concept_text": "Keep the same pacing, but make the hook focus on battery life."
+}
+```
+
+Then call `generate_video` with the same `ad_reference_id`.

skills/.curated/higgsfield-generate/references/marketing-avatars.md

@@ -0,0 +1,59 @@
+# Avatars
+
+Marketing Studio avatars are presenters for ads and UGC-style videos.
+
+## Preset Vs Custom
+
+| | Preset | Custom |
+|---|---|---|
+| Source | Curated by Higgsfield | User uploaded |
+| Best for | Fast generic ads | Founder, employee, creator, brand-specific face |
+| Creation | Already available | Requires media upload and create step |
+
+## Listing
+
+Call `show_marketing_studio`:
+
+```json
+{ "action": "list", "type": "avatar", "size": 20 }
+```
+
+Use `search` to narrow large libraries.
+
+## Creating A Custom Avatar
+
+1. Upload/confirm one image with `media_upload` and `media_confirm`.
+2. Call `show_marketing_studio`:
+
+```json
+{
+  "action": "create",
+  "type": "avatar",
+  "avatars": [
+    {
+      "name": "Founder",
+      "medias": [
+        { "value": "<media_id>", "role": "image", "url": "<cdn_url_if_available>", "type": "media_input" }
+      ]
+    }
+  ]
+}
+```
+
+Avatar media should be an image. If the MCP response says a URL is required for a media input, include the CDN URL returned by the upload flow.
+
+## Passing To Generation
+
+For `generate_video` with `model: "marketing_studio_video"`, pass:
+
+```json
+{
+  "params": {
+    "model": "marketing_studio_video",
+    "prompt": "organic UGC product review",
+    "avatars": [{ "id": "<avatar_id>", "type": "preset" }]
+  }
+}
+```
+
+Use `type: "custom"` for user-created avatars. For UGC modes, an avatar can be omitted when a generic presenter is acceptable.

skills/.curated/higgsfield-generate/references/marketing-modes.md

@@ -0,0 +1,45 @@
+# Marketing Studio Modes
+
+Use `mode` in `generate_video` params for `marketing_studio_video`.
+
+| Mode slug | Human-readable label | Hook/setting | Best for |
+|---|---|---|---|
+| `ugc` | UGC | Yes | Default casual, organic presenter content. |
+| `ugc_how_to` | Tutorial | Yes | Explainer or "how to use this" ad. |
+| `ugc_unboxing` | Unboxing | Yes | Package opening and reveal. |
+| `product_showcase` | Product Showcase | No | Polished product-first highlight. |
+| `product_review` | Product Review | Yes | Presenter opinion/review. |
+| `tv_spot` | TV Spot | No | Broadcast-style commercial. |
+| `wild_card` | Wild Card | No | Experimental creative direction. |
+| `ugc_virtual_try_on` | UGC Virtual Try On | Yes | Organic clothing/accessory try-on. |
+| `virtual_try_on` | Pro Virtual Try On | No | Polished try-on. |
+
+Default when unspecified: `ugc`.
+
+## Picking Flow
+
+- Real-person phone-shot feel → `ugc`, `ugc_how_to`, `ugc_unboxing`, or `ugc_virtual_try_on`.
+- Polished broadcast commercial → `tv_spot`.
+- Product-first, less presenter → `product_showcase`.
+- Opinion / testimonial → `product_review`.
+- Clothing/accessory try-on → `ugc_virtual_try_on` or `virtual_try_on`.
+- Surprise / experimental → `wild_card`.
+
+## Common Params
+
+- `aspect_ratio`: `auto`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`.
+- `duration`: integer seconds; inspect current bounds with `models_explore(action: "get", model_id: "marketing_studio_video")`.
+- `resolution`: `480p` or `720p`.
+- `generate_audio`: boolean.
+- `avatars`: array of `{ "id": "...", "type": "preset" | "custom" }`.
+- `product_ids`: array of product UUIDs.
+- `hook_id`, `setting_id`: optional setup item UUIDs.
+- `ad_reference_id`: optional ad-reference UUID; do not combine with hooks/settings.
+- `medias`: optional references with role `image`, `start_image`, or `end_image`.
+- `url`: Click-to-Ad product/webproduct URL.
+
+## URL-Driven Click-To-Ad
+
+1. Call `show_marketing_studio` with `action: "fetch"` and `url`.
+2. Follow `next_step` exactly when present; it calls `generate_video` with the right URL/type params.
+3. If no `next_step` is returned, call `generate_video` with `model: "marketing_studio_video"` and the same `url`.