SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsmedia-higgsfield-core

media-higgsfield-core

Agents & models

View repository

Updated 10-15 21:36

About this skill

Higgsfield Core (media-higgsfield-core)

moai-media | Shared SSOT for image/video skills (reference-only core)

Overview

This skill is media-higgsfield-image와 media-higgsfield-videois the core commonly referenced by. The two consuming skills take the call contract, lookup order, and common rules from here. Core design principle: parameters (model id, enum, aspect, duration, media role, cost) are never hardcoded and are retrieved at runtime via models_exploreOnly prompt craft is statically curated and sourced.

This design is necessary because the two axes have different sources of truth:

축 Source of truth How the skill obtains it
Parameters Live MCP models_explore / show_marketing_studio / presets_show / get_cost (at call time)
Prompt craft Official model vendor documentation By family prompt-craft/*.md (fixed at authoring time, with source and Evidence tier noted)

Core reference files

File Role
references/call-schema.md Nested params{} shape contract, medias[].role/.value rules, namespace runtime resolution, anti-patterns for nonexistent parameters
references/catalog-protocol.md models_explore live lookup tools and standard order (REQ-010), out-of-scope model fallback
references/universal-rules.md R1–R5 vendor cross-common rules
references/interview-schema.md Collection slots consumed by craft files
references/job-lifecycle.md get_cost preflight, credits rules, adjustments readback, polling/error classification, balance halt

Orchestration contract (REQ-010 flow)

Consuming skills follow this order:

  1. Intent → narrowing candidates — narrow family candidates from the user request (see craft notes). Only narrow candidates; do not assert parameters.
  2. Live lookup — models_explore(action:'get')to fetch actual constraints. If it is the Marketing Studio family, show_marketing_studio.
  3. cost preflight — get_cost: true로 credits check (0 credits). adjustments secure.
  4. Approval gate — the final stop line before credits are spent. See §Paid generation approval gate below.
  5. Generation — call only with approved values.
  6. Polling/readback — job_status로 completedup to, adjustmentsreport to the user.

Paid generation approval gate

If you check the cost in step 3 and immediately move to step 4, the user only finds out how much was spent after being billed. preflight does not obtain approval, it only looks upthe cost. This gate fills that gap.

  • [HARD] Always obtain approval before any call that consumes credits. preflight (get_cost: true, credits 0) and query-type tools are not gate targets — only calls that spend money are.
  • [HARD] Approval is obtained through the path in the §Approval Request Contract. This skill and the consuming skill do not ask the user directly (§Interview Boundary), so when they reach the gate they return a blocker and the orchestrator asks on their behalf. It is the same path as slot collection.
  • [HARD] Do not summarize; show exactly what is actually being passed:
What to show Why it is needed
Prompt full text This sentence is what the user is paying for
Model id and family The same request costs and results differently depending on the model
Input media (media_id / job_id list and role) Which images go in as materials
Options confirmed by query (aspect ratio, resolution, duration, etc.) Confirm that these are queried values, not hardcoded
Number of generations The count is directly the multiplier on cost
adjustments — values the server silently changed The difference between what the user requested and what will actually run
get_costreturned by estimated creditsand the current balance How much goes out and how much remains

The approval options are composed like this:

Options 뜻
Generate as is (recommended) Call with exactly the values shown
Fix and re-quote Change the prompt, model, or count and restart from step 3
Cancel Exit without calling. No credits spent
  • [HARD] adjustmentsis shown before approval. Reporting back via leadback after generation finishes (step 6) is correct in itself, but the fact that the server changed the request must be known before money goes out so it can be canceled. Do not omit this item just because there is a step 6 report.
  • [HARD] Do not create a new job even if it fails. If the generation call fails ambiguously (timeout, no response), do not re-call. The absence of a success signal is not evidence that no job was created, and a blind retry spends credits twice. If there is a returned job/request ID, first check that job's status with job_status, and if there is not even an ID, first check whether a tool for querying generation history is actually exposed — the core catalog-protocol.mdtreats only job_status·job_displayas the contract, and the history query tool is not in that list. If it is exposed, check with it, and if it is not, ask the user to check directly in the Higgsfield dashboard. Retries are always tied to the existing job ID — create a new one only after it is confirmed that none exists.
  • [HARD] Batch batches are approved per batch unit. When one request creates multiple jobs (multiple variants, block assembly, etc.), instead of asking for each job, the overall plan + maximum total creditsis approved at once. Additional generation beyond the approved plan requires a new approval.

namespace runtime resolution

The namespace prefix of the Higgsfield tool is, depending on the registration method, mcp__higgsfield__ or mcp__claude_ai_higgsfield__. The skill checks the actually exposed namespace at runtime immediately before invocation and uses that prefix. It does not hardcode either one as the sole correct answer. For details, see references/call-schema.md §3.

interview boundary

This skill (and subagents) do not ask the user directly. It only documents the slots to be collected, and the orchestrator conducts the actual questions. If a slot is empty, it returns a structured blocker report. For details, see references/interview-schema.md.

approval request contract (runtime-neutral)

[HARD] This skill's gate is not tied to a specific tool name. AskUserQuestionis merely a means in the Claude runtime, and other runtimes including Codex do not have that tool. If the contract is written in terms of tool names, then in runtimes lacking that tool the gate becomes a permanent blocker, and every task requiring approval simply stops. That is not safety but breakage.

Approval is obtained in the following order. From the top, the first actually possibleis used.

The definition of approval is the result, not the means: showing the approval form to the user as-is and receiving an explicit response to it. Below are the paths that produce that result, and the first possible one from the top is used.

Rank Path Condition
1 The runtime's structured question tool (AskUserQuestion 등) When that tool is exposed in the current session
2 Present the approval form in normal conversation and receive the response on the next turn When conversing directly with the user. Even without the tool, this path is always open
3 Return a structured blocker → the parent orchestrator asks When running as a subagent

[HARD] The runtime's tool execution permission prompt is not approval. That prompt only asks "may this tool be called", and does not display the arguments, estimate, and consent questions that the gate is supposed to show. Only when the entire approval form and the options are actually displayed is it recognized as path 2.

[HARD] Because path 2 exists, the situation of "having no means to ask" effectively does not exist. Wherever conversation is possible, the approval form can always be presented in writing. fail-closed applies only to fully unattended execution where neither conversation nor blocker return is possible— only in that case does it stop without executing.

[HARD] When using path 3, the blocker must itself be an approval request form. If the higher level does not know what to ask, it cannot ask back, and then there is a deadlock. Include all of the following:

  • Action to be approved action one line (what is irreversible / how much is going out)
  • All arguments required by the gate (values not summarized)
  • List of options — in a form the higher level can present directly to the user
  • How to resume — what to continue executing upon receiving which answer

[HARD] In unattended execution where all three paths are impossible, do not execute (fail-closed). The absence of a means to ask does not mean approval was obtained. In this case, record "could not proceed because there is no approval means" and stop — do not proceed silently. Conversely, stopping because there is no tool even though conversation is possible is also wrong. Use path 2.

This contract is CLAUDE.local.md the gate-side application of §Generality Principle (same behavior across 2 OS types × 2 runtime types). A gate that runs on only one runtime is considered incomplete.

Related skills

Skill Relationship
moai-media:media-higgsfield-image Consumes: image generation
moai-media:media-higgsfield-video Consumes: video generation
moai-media:media-higgsfield-identity Consumes: Soul·Element consistency reference
moai-media:media-higgsfield-assets Consumes: 3D·audio·video analysis·post-processing
moai-media:media-higgsfield-explainer Consumes: block-assembly explanatory video
moai-media:media-higgsfield-product Consumes: 10 modes of product shooting
moai-designer:design-brand-visual Consumes (cross-plugin): brand-consistent visuals
moai-story:story-* Consumes (cross-plugin): artwork·storyboard·cover·characters

Source