| name | media-higgsfield-core |
| description | Higgsfield MCP 이미지·영상 생성의 공유 코어. media-higgsfield-image / media-higgsfield-video가
로드하는 SSOT(single source of truth)로, 호출 스키마·라이브 카탈로그 조회 프로토콜·공통 크래프트
규칙(R1–R5)·인터뷰 슬롯·잡 수명주기를 정의합니다.
다음과 같은 상황에서 로드됩니다:
- media-higgsfield-image 또는 media-higgsfield-video가 호출 계약을 참조할 때
- Higgsfield 모델의 파라미터를 하드코딩하지 않고 런타임 조회해야 할 때
- namespace(mcp__higgsfield__ vs mcp__claude_ai_higgsfield__)를 런타임 해석해야 할 때
이 스킬은 단독 실행 스킬이 아니라 두 소비 스킬이 참조하는 공유 코어입니다.
|
| version | 1.2.0 |
Higgsfield 코어 (media-higgsfield-core)
moai-media | 이미지·영상 스킬의 공유 SSOT (참조 전용 코어)
개요
이 스킬은 media-higgsfield-image와 media-higgsfield-video가 공통으로 참조하는 코어다. 두 소비 스킬은 호출 계약·조회 순서·공통 규칙을 여기서 가져온다. 핵심 설계 원칙: 파라미터(모델 id·enum·aspect·duration·media role·비용)는 절대 하드코딩하지 않고 런타임에 models_explore로 조회한다. 프롬프트 크래프트만 정적으로 큐레이션하고 출처를 단다.
이 설계가 필요한 이유는 두 축이 서로 다른 진실원을 갖기 때문이다:
| 축 | 진실원 | 스킬이 얻는 방법 |
|---|
| 파라미터 | 라이브 MCP | models_explore / show_marketing_studio / presets_show / get_cost (호출 시점) |
| 프롬프트 크래프트 | 모델 벤더 공식 문서 | 계열별 prompt-craft/*.md (저술 시점 고정, 출처·Evidence tier 표기) |
코어 참조 파일
| 파일 | 역할 |
|---|
references/call-schema.md | 중첩 params{} 형태 계약, medias[].role/.value 규칙, namespace 런타임 해석, 존재하지 않는 파라미터 안티패턴 |
references/catalog-protocol.md | models_explore 등 라이브 조회 도구와 표준 순서(REQ-010), 범위 밖 모델 폴백 |
references/universal-rules.md | R1–R5 벤더 교차 공통 규칙 |
references/interview-schema.md | 크래프트 파일이 소비하는 수집 슬롯 |
references/job-lifecycle.md | get_cost 프리플라이트, credits 규칙, adjustments 리드백, 폴링·오류 분류, 잔액 정지 |
오케스트레이션 계약 (REQ-010 흐름)
소비 스킬은 다음 순서를 따른다:
- 의도 → 후보 좁히기 — 사용자 요청에서 계열 후보를 추린다(크래프트 노트 참조). 후보를 좁힐 뿐 파라미터를 단정하지 않는다.
- 라이브 조회 —
models_explore(action:'get')로 실제 제약을 가져온다. Marketing Studio 계열이면 show_marketing_studio.
- 비용 프리플라이트 —
get_cost: true로 credits 확인(크레딧 0). adjustments 확보.
- 승인 게이트 — 크레딧이 나가기 전 마지막 정지선. 아래 §유료 생성 승인 게이트.
- 생성 — 승인된 값으로만 호출.
- 폴링·리드백 —
job_status로 completed까지, adjustments를 사용자에게 보고.
유료 생성 승인 게이트
3단계에서 비용을 확인해놓고 곧바로 4단계로 넘어가면, 사용자는 얼마가 나갔는지 청구된 뒤에 안다. 프리플라이트는 비용을 조회할 뿐 승인을 받지 않는다. 이 게이트가 그 사이를 메운다.
- [HARD] 크레딧이 소진되는 호출 전에는 반드시 승인을 받는다. 프리플라이트(
get_cost: true, 크레딧 0)와 조회 계열 도구는 게이트 대상이 아니다 — 돈이 나가는 호출만이다.
- [HARD] 승인은 §승인 요청 계약의 경로로 받는다. 이 스킬과 소비 스킬은 사용자에게 직접 묻지 않으므로(§인터뷰 경계), 게이트에 도달하면 blocker로 반환하고 오케스트레이터가 대신 묻는다. 슬롯 수집과 같은 경로다.
- [HARD] 요약하지 말고 실제로 넘어가는 것을 그대로 보여준다:
| 보여줄 것 | 왜 필요한가 |
|---|
| 프롬프트 전문 | 사용자가 돈을 내는 대상이 이 문장이다 |
| 모델 id와 계열 | 같은 요청도 모델에 따라 비용·결과가 다르다 |
입력 미디어 (media_id / job_id 목록과 role) | 어떤 이미지가 재료로 들어가는지 |
| 조회로 확정된 옵션 (비율·해상도·길이 등) | 하드코딩이 아니라 조회값임을 확인 |
| 생성 개수 | 개수가 곧 배수 비용이다 |
adjustments — 서버가 조용히 바꾼 값 | 사용자가 요청한 것과 실제 실행될 것의 차이 |
get_cost가 돌려준 견적 크레딧과 현재 잔액 | 얼마가 나가고 얼마가 남는지 |
승인 선택지는 이렇게 구성한다:
| 선택지 | 뜻 |
|---|
| 이대로 생성 (권장) | 보여준 값 그대로 호출 |
| 고쳐서 다시 견적 | 프롬프트·모델·개수를 바꿔 3단계부터 다시 |
| 취소 | 호출하지 않고 종료. 크레딧 소진 없음 |
- [HARD]
adjustments는 승인 전에 보여준다. 생성이 끝난 뒤 리드백으로 보고하는 것(6단계)은 그 자체로 옳지만, 서버가 요청을 바꿨다는 사실은 돈이 나가기 전에 알아야 취소할 수 있다. 6단계 보고가 있다고 해서 이 항목을 생략하지 않는다.
- [HARD] 실패해도 새 잡을 만들지 않는다. 생성 호출이 애매하게 실패하면(타임아웃·응답 없음) 재호출하지 않는다. 성공 신호가 없다는 것은 잡이 만들어지지 않았다는 증거가 아니며, 블라인드 재시도는 크레딧을 두 번 쓴다. 반환된 job/request ID가 있으면
job_status로 그 잡의 상태를 먼저 확인하고, ID조차 없으면 생성 이력을 조회할 도구가 실제로 노출돼 있는지 먼저 확인한다 — 코어 catalog-protocol.md가 계약으로 두는 것은 job_status·job_display뿐이고, 이력 조회 도구는 그 목록에 없다. 노출돼 있으면 그것으로 확인하고, 없으면 사용자에게 Higgsfield 대시보드에서 직접 확인해 달라고 요청한다. 재시도는 언제나 기존 잡 ID에 묶인다 — 없다는 것이 확인된 뒤에만 새로 만든다.
- [HARD] 대량 배치는 배치 단위로 승인한다. 한 요청이 여러 잡을 만들면(다중 변형·블록 조립 등) 잡마다 묻지 않고 전체 계획 + 최대 총 크레딧을 한 번에 승인받는다. 승인된 계획을 넘는 추가 생성은 새 승인을 받는다.
namespace 런타임 해석
Higgsfield 도구의 namespace 접두사는 등록 방식에 따라 mcp__higgsfield__ 또는 mcp__claude_ai_higgsfield__다. 스킬은 호출 직전 실제 노출된 namespace를 런타임에 확인하고 그 접두사를 쓴다. 어느 하나를 유일 정답으로 하드코딩하지 않는다. 상세는 references/call-schema.md §3.
인터뷰 경계
이 스킬(및 서브에이전트)은 사용자에게 직접 질문하지 않는다. 수집할 슬롯을 문서화할 뿐이며, 실제 질문은 오케스트레이터가 진행한다. 슬롯이 비면 구조화된 blocker 보고를 반환한다. 상세는 references/interview-schema.md.
승인 요청 계약 (런타임 중립)
[HARD] 이 스킬의 게이트는 특정 도구 이름에 묶이지 않는다. AskUserQuestion은 Claude 런타임의 수단일 뿐이고, Codex를 비롯한 다른 런타임에는 그 도구가 없다. 도구 이름으로 계약을 쓰면 그 도구가 없는 런타임에서 게이트가 영구 blocker가 되어, 승인이 필요한 모든 작업이 그냥 멈춘다. 그건 안전이 아니라 고장이다.
승인은 아래 순서로 구한다. 위에서부터 실제로 가능한 첫 번째를 쓴다.
승인의 정의는 수단이 아니라 결과다: 승인서를 사용자에게 그대로 보여주고, 그에 대한 명시적 응답을 받는 것. 아래는 그 결과를 만드는 경로들이며, 위에서부터 가능한 첫 번째를 쓴다.
| 순위 | 경로 | 조건 |
|---|
| 1 | 런타임의 구조화 질문 도구 (AskUserQuestion 등) | 그 도구가 현재 세션에 노출돼 있을 때 |
| 2 | 일반 대화로 승인서를 제시하고 다음 턴에서 응답을 받는다 | 사용자와 직접 대화 중일 때. 도구가 없어도 이 경로는 언제나 열려 있다 |
| 3 | 구조화 blocker 반환 → 상위 오케스트레이터가 물어봄 | 서브에이전트로 실행 중일 때 |
[HARD] 런타임의 도구 실행 권한 프롬프트는 승인이 아니다. 그 프롬프트는 "이 도구를 호출해도 되는가"를 물을 뿐, 게이트가 보여주기로 한 인자·견적·동의 문항을 표시하지 않는다. 승인서 전체와 선택지를 실제로 표시하는 경우에만 2번 경로로 인정한다.
[HARD] 2번 경로가 있으므로 "물을 수단이 없다"는 상황은 사실상 없다. 대화가 가능한 곳에서는 언제나 승인서를 글로 제시할 수 있다. fail-closed는 대화도 blocker 반환도 불가능한 완전 무인 실행에만 해당한다 — 그 경우에만 실행하지 않고 멈춘다.
[HARD] 3번을 쓸 때 blocker는 그 자체로 승인 요청서여야 한다. 상위가 무엇을 물어야 할지 모르면 되물을 수 없고, 그러면 교착된다. 다음을 모두 담는다:
- 승인받을 행위 한 줄 (무엇이 되돌릴 수 없는지 / 얼마가 나가는지)
- 게이트가 요구하는 인자 전부 (요약하지 않은 값)
- 선택지 목록 — 상위가 그대로 사용자에게 제시할 수 있는 형태
- 재개 방법 — 어떤 답을 받으면 무엇을 이어서 실행하는지
[HARD] 세 경로가 모두 불가능한 무인 실행에서는 실행하지 않는다(fail-closed). 물을 수단이 없다는 것은 승인을 받았다는 뜻이 아니다. 이때는 "승인 수단이 없어 진행하지 못했다"고 기록하고 멈춘다 — 조용히 진행하지 않는다. 반대로 대화가 가능한데 도구가 없다는 이유로 멈추는 것도 잘못이다. 2번 경로를 쓴다.
이 계약은 CLAUDE.local.md §범용성 원칙(OS 2종 × 런타임 2종에서 동일 동작)의 게이트 쪽 적용이다. 한 런타임에서만 도는 게이트는 미완성으로 본다.
관련 스킬
| 스킬 | 관계 |
|---|
moai-media:media-higgsfield-image | 소비: 이미지 생성 |
moai-media:media-higgsfield-video | 소비: 영상 생성 |
moai-media:media-higgsfield-identity | 소비: Soul·Element 일관성 참조 |
moai-media:media-higgsfield-assets | 소비: 3D·오디오·영상 분석·후처리 |
moai-media:media-higgsfield-explainer | 소비: 블록 조립형 설명 영상 |
moai-media:media-higgsfield-product | 소비: 제품 촬영 10모드 |
moai-designer:design-brand-visual | 소비(교차 플러그인): 브랜드 정합 비주얼 |
moai-story:story-* | 소비(교차 플러그인): 작화·콘티·표지·캐릭터 |
출처
