요약 (TL;DR): omni-skill-agy는 Google의 gemini-omni-flash-preview 모델 (Omni Flash)을 아주 작은 FastMCP 서버로 래핑(wrap)하여 Antigravity CLI 스킬로 패키징합니다. Antigravity에 "눈 속을 달리는 여우의 비디오를 생성해줘"라고 입력하면, 모델이 그냥... 해냅니다. 그다음 "눈이 내리는 밤으로 만들어줘"라고 말하면, 전체 장면을 다시 프롬프트로 입력할 필요 없이 동일한 비디오를 편집합니다. 또한 정지 이미지를 애니메이션화하거나, 두 키프레임 사이를 보간(interpolate)하거나, 이미 가지고 있는 비디오의 스타일을 변경할 수도 있습니다. 그리고 결과가 마음에 들면 터미널을 떠나지 않고도 YouTube에 바로 업로드할 수 있습니다.

배경: 왜 또 다른 비디오 도구가 필요한가?

대부분의 비디오 생성 워크플로우는 상태 비저장(stateless) 방식입니다. 프롬프트를 보내면 프레임을 돌려받고, 모델은 즉시 모든 것을 잊어버립니다. 결과를 수정하고 싶나요? 그러면 전체 장면을 다시 설명해야 하며, 캐릭터, 조명, 카메라 워크가 그 과정에서도 유지되기를 기도해야 합니다. (해설: 유지되지 않습니다.)

Google의 Omni Flash — gemini-omni-flash-preview — 는 다른 접근 방식을 취합니다. 이는 Google의 Gemini "Omni" 라인업에 포함된 비디오 생성 모델로, 빠르고 고충실도(high-fidelity)의 클립을 위해 구축되었으며, 핵심 기능은 상태 유지(stateful) Interactions API에 연결되어 있다는 점입니다. 이를 통해 모델이 서버 측에서 시각적 문맥(visual context)을 유지하는 동안 여러 턴에 걸쳐 비디오를 반복적으로 수정할 수 있습니다.

Omni Flash가 실제로 하는 일

"Omni"라는 부분은 단순한 브랜딩 수식어가 아닙니다. 이 모델은 진정한 의미의 혼합 멀티모달(multimodal) 입력을 수용합니다. 단일 요청의 input은 일반 문자열이거나, 타입이 지정된 파트(parts)의 리스트일 수 있습니다: text 파트, base64로 인코딩된 image 파트, 그리고 Gemini File API를 통해 업로드한 비디오를 가리키는 document 파트입니다. 모델은 사용자가 전달하는 무엇이든 하나의 클립으로 구성합니다. 이 단일 메커니즘은 비디오를 만드는 다섯 가지의 뚜렷한 방식을 모두 포괄합니다:

1. Text → video (텍스트 → 비디오). 프롬프트를 입력하면 .mp4 파일이 출력됩니다. 생성 시점에 가로형 16:9 또는 세로형 9:16을 선택할 수 있습니다.
2. One image + a motion prompt (이미지 1장 + 모션 프롬프트) → animation (애니메이션). 정지 영상이 생동감 있게 움직입니다 ("그룹이 웃으며 카메라를 향해 손을 흔듭니다").
3. Two images + a transition prompt (이미지 2장 + 트랜지션 프롬프트) → keyframe interpolation (키프레임 보간). 모델이 프레임 A에서 프레임 B 사이의 중간 영상을 만들어냅니다 ("일출에서 일몰까지 이어지는 부드러운 타임랩스").
4. Reference images + a scene prompt (참조 이미지 + 장면 프롬프트) → subject-consistent generation (피사체 일관성 생성). 참조 사진 속의 인물이나 사물이 프롬프트의 지시에 따라 생성된 장면 속에 그대로 등장합니다.
5. An uploaded video + an edit prompt (업로드된 비디오 + 편집 프롬프트) → restyling (스타일 재구성). 모델이 생성하지 않은 기존 영상을 다시 렌더링합니다 ("Pixar 애니메이션 스타일로 만들어줘").

그리고 이 다섯 가지 방식 위에 상태 유지(stateful) 레이어가 놓여 있습니다. store=True 옵션으로 호출된 모든 요청은 interaction ID를 반환하며, 이후 모든 결과물은 점진적인 편집 프롬프트를 통해 차례대로 정교화할 수 있습니다. 모델이 사용자가 다시 설명할 필요 없이 저장된 시각적 컨텍스트 (visual context)를 검색하기 때문에 동일한 캐릭터, 동일한 조명, 동일한 카메라 언어를 유지할 수 있습니다.

시작하기 전에 알아두어야 할 세 가지 실질적인 사항이 있습니다: 생성 과정은 동기적(synchronous)이며 느립니다 (비디오가 준비될 때까지 호출이 차단됩니다), 생성당 비용이 청구되며, 출력 파일의 크기가 빠르게 커집니다. 약 4MB를 넘어가면 인라인 base64 방식 대신 File-API 전달 방식을 사용해야 합니다. 아래의 서버와 스킬은 이러한 현실적인 문제들을 대신 처리하기 위해 존재합니다.

이 리포지토리는 이 모든 것을 Antigravity CLI로 결합하여, 여러분의 코딩 에이전트(coding agent)가 세션의 자연스러운 일부로서 비디오를 생성하고 반복적으로 개선할 수 있도록 합니다. 이 리포지토리는 두 가지 구성 요소로 제공됩니다:

1. 정확히 8개의 도구(tools)를 노출하는 Model Context Protocol (MCP) 서버 (server.py에 포함된 단일 파일 FastMCP 앱인 omni-video-agent).
2. 에이전트에게 해당 도구들을 언제 그리고 어떻게 잘 사용할지를 가르치는 Antigravity 스킬 (omni-video).

Interactions API: 기억력을 가진 비디오

Interactions API는 Gemini의 상태 유지(stateful) 엔드포인트입니다. 핵심 루프는 다음과 같습니다:

1. 프롬프트와 store=True 옵션을 포함하여 client.interactions.create(...)를 호출합니다.
2. 응답에는 **interaction_id**가 포함됩니다. 이는 Google 서버에 저장되어 해당 턴의 시각적 컨텍스트(visual context)를 가리키는 핸들(handle) 역할을 합니다.
3. 다음 호출 시 previous_interaction_id를 전달하면, 모델은 _기존 비디오_를 편집합니다. 이 과정에서 장면, 캐릭터, 조명 및 스타일의 연속성(continuity)이 유지됩니다.

따라서 다음과 같은 방식(상태 비저장(stateless) 방식의 고통) 대신:

"골든 아워에 신선한 눈 속을 달리는 붉은 여우의 트래킹 샷, 자작나무, 낮은 태양, 얕은 피사체 심도, 그리고 이제는 또한 폭설이 내리는 밤"

...이렇게 작성하면 됩니다:

"폭설이 내리는 밤으로 만들어줘."

그게 전부입니다. 저장된 컨텍스트가 나머지를 처리합니다.

서버가 대신 처리해 주는 몇 가지 실질적인 세부 사항은 다음과 같습니다:

• 매 턴마다 새로운 interaction ID가 반환됩니다. 가장 최신의 ID를 체이닝(chain)하세요. 오래된 ID로 편집하면 세션이 이전 상태에서 조용히 분기(fork)됩니다 (이를 수동으로 구현할 경우 매우 미묘하고 짜증 나는 버그가 됩니다).
• 종횡비(Aspect ratio)는 생성 시점에 결정되며 (16:9 가로형 또는 9:16 세로형), 상태 유지 편집 시 이를 상속(inherited) 받습니다. 따라서 편집 도구는 의도적으로 종횡비를 입력받지 않습니다.
• 전송 모드(Delivery modes): inline (기본값 — 비디오가 base64로 반환되며, 짧은 클립에 적합함) 또는 uri — uri 방식은 출력이 Google File API에 저장되며, 서버는 준비될 때까지 폴링(poll)한 후 다운로드합니다. 비디오는 크기가 빠르게 커집니다. 약 4MB를 넘어가면, uri 방식은 직접 겪어보기 전에는 알기 어려운 페이로드 제한(payload-limit) 오류로부터 여러분을 보호해 줍니다.

MCP란 무엇인가, 1분 요약

**Model Context Protocol (MCP)**는 AI 어시스턴트를 도구 및 데이터와 연결하기 위한 개방형 표준입니다. MCP가 등장하기 전에는 모델에 특정 서비스에 대한 접근 권한을 부여하려면 각 어시스턴트마다 맞춤형 통합(bespoke integration) 코드를 작성해야 했습니다. 즉, N개의 어시스턴트 × M개의 서비스만큼, 모두가 동일한 배관 작업을 매번 새로 만들어야 했습니다. MCP는 이를 하나로 통합합니다. 도구 제작자가 타입이 지정된 도구(typed tools)를 노출하는 하나의 **MCP 서버 (MCP server)**를 작성하면, MCP를 지원하는 모든 클라이언트(Claude Code, Claude Desktop 및 점점 늘어나는 기타 클라이언트들)가 클라이언트별 접착 코드(glue code) 없이도 해당 도구들을 발견하고 호출할 수 있습니다.

MCP 서버는 일반적으로 stdio를 통해 JSON-RPC를 사용하는 작은 로컬 프로세스입니다. 클라이언트가 이를 실행하고 "어떤 도구들을 가지고 있나요?"라고 물으면, 그 이후부터 모델은 이 도구들을 함수처럼 호출할 수 있습니다.

omni-video-agent 서버는 정확히 8개의 도구를 노출합니다:

오류는 프로토콜 오류가 아닌 🔴 ... 텍스트 문자열로 반환되므로, 에이전트가 이를 읽고 대응할 수 있습니다.

8가지 함수 호출 상세 정보

전체 인터페이스를 관통하는 두 가지 규칙이 있습니다. 모든 비디오 도구는 delivery 파라미터를 받습니다. 'inline'(기본값; 비디오가 응답 내 base64로 반환됨) 또는 'uri'(출력이 Google File API에 저장되며, 서버가 ACTIVE 상태가 될 때까지 폴링한 후 다운로드함 — 약 4MB를 초과하는 모든 작업에 사용하십시오) 중 하나를 선택합니다. 그리고 모든 비디오 도구는 저장된 로컬 경로와 다음 편집으로 체이닝(chain)하기 위한 **상호작용 ID (interaction ID)**를 포함하는 텍스트 보고서를 반환합니다. 비디오는 각 도구별 접두사(prefix)와 함께 <prefix>_<unix-timestamp>.mp4 형식으로 디스크에 저장됩니다.

generate_video — 텍스트 → 비디오

generate_video(prompt: str, aspect_ratio: str = "16:9", delivery: str = "inline") -> str

시작점입니다. aspect_ratio는 '16:9' (가로형) 또는 '9:16' (세로형)입니다. 상태 유지(stateful) 편집은 이 값을 상속받기 때문에, 이 값을 허용하는 유일한 도구입니다. 그 외의 다른 값을 입력하면 모델의 기본값으로 조용히 대체됩니다. 내부적으로는 store=True 옵션이 포함된 단일 client.interactions.create(...) 호출로 이루어지므로, 결과물은 즉시 편집 가능한 상태가 됩니다. gen_*.mp4로 저장됩니다.

edit_video — 상태 유지(stateful) 편집

edit_video(previous_interaction_id: str, edit_prompt: str, delivery: str = "inline") -> str

전체 아키텍처의 중심이 되는 도구입니다. 최신 턴의 상호작용 ID(interaction ID)를 전달하고 변경 사항만 설명하세요. 나머지 정보는 저장된 컨텍스트(context)가 유지합니다. 각 호출은 새로운 ID를 반환하며, 다음 호출 시 이 ID를 체이닝(chain)해야 합니다. 오래된(stale) ID로 편집을 시도하면 세션이 이전 상태에서 조용히 분기(fork)되기 때문입니다. 의도적으로 aspect_ratio 파라미터는 포함하지 않았습니다. 해당 값은 상속됩니다. edit_*.mp4로 저장됩니다.

animate_image — 정지 이미지 → 움직임

animate_image(image_path: str, motion_prompt: str, delivery: str = "inline") -> str

로컬 이미지(png/jpg/jpeg/webp — 확장자로부터 MIME 타입을 추론하며, 그 외의 형식은 png로 전송됨)를 읽어 base64로 인코딩한 후, [image, text]를 멀티모달(multimodal) 입력으로 전송합니다. animated_*.mp4로 저장됩니다.

interpolate_images — 두 개의 키프레임 → 그 사이의 영상

interpolate_images(start_image_path: str, end_image_path: str, prompt: str, delivery: str = "inline") -> str

animate_image와 동일한 인코딩 방식을 사용하지만, 입력값은 [start_image, end_image, text]이며 프롬프트는 전환 과정(예: "일출부터 일몰까지의 부드러운 타임랩스")을 설명합니다. interpolation_*.mp4로 저장됩니다.

generate_with_subjects — 참조 이미지를 활용한 디렉팅 생성

generate_with_subjects(subject_image_paths: list[str], prompt: str, delivery: str = "inline") -> str

리스트 내의 모든 경로는 이미지 파트로 변환되며, 장면(scene) 프롬프트는 마지막에 배치됩니다. 모델은 해당 피사체(subjects)들이 등장하는 영상을 생성합니다. subject_*.mp4로 저장됩니다.

edit_user_video — 이미 보유한 푸티지(footage)를 리스타일링(restyle)하기

edit_user_video(video_path: str, edit_prompt: str, delivery: str = "inline") -> str

입력 시 Gemini File API를 사용하는 유일한 도구입니다. 로컬 비디오를 업로드하고, 처리가 완료될 때까지 폴링(polling)하며(최대 5분), 완료되면 URI로 참조된 업로드된 비디오와 편집 지침이 포함된 [document, text]를 전송합니다. 결과물은 user_edit_*.mp4로 저장됩니다.

upload_to_youtube — 최종 편집본 게시하기

upload_to_youtube(video_path: str, title: str, description: str,
                  category_id: str = "22", privacy_status: str = "private") -> str

YouTube Data API v3를 사용합니다. 일회성 OAuth 설정이 필요합니다 (server의 작업 디렉토리에 client_secrets.json 필요; 첫 실행 시 브라우저가 열리고 token.pickle이 캐시됨). category_id의 기본값은 '22'(인물 및 블로그)이며, privacy_status는 'private', 'public', 또는 'unlisted' 중 하나를 선택할 수 있습니다. 기본값은 'private'이므로 실수로 영상이 공개되는 일은 없습니다. 오류 발생 시 🔴 ... 대신 ❌ ...를 사용하며, 추가 종속성(dependencies)은 선택 사항입니다. 종속성이 누락된 경우 도구가 정확한 pip install 명령어를 보고합니다.

get_help — 내장 매뉴얼

get_help() -> str

매개변수가 없습니다. 전체 도구 카탈로그, 전달 모드(delivery-mode) 안내, 그리고 시네마틱 프롬프팅 가이드를 반환합니다. 이를 통해 에이전트(또는 궁금한 사용자)가 세션을 벗어나지 않고도 방향을 잡을 수 있습니다.

그렇다면 Antigravity _스킬(skill)_이란 무엇인가?

MCP가 손(에이전트가 물리적으로 호출할 수 있는 도구들)이라면, **스킬(skill)**은 _근육 기억(muscle memory)_입니다. 즉, 에이전트의 컨텍스트(context)에 로드되어 워크플로우를 가르쳐주는 마크다운 파일(SKILL.md)과 번들된 리소스들의 집합입니다. 어떤 도구를, 어떤 순서로, 어떤 제약 조건 하에 사용해야 하는지를 알려줍니다.

omni-video의 경우, 스킬은 다음과 같은 사항들을 인코딩합니다:

• 시네마틱하게 (cinematically) 프롬프트 작성: 장면 레이아웃(scene layout), 피사체의 동작(subject action), 카메라 움직임(camera motion) (트래킹 샷(tracking shot), 슬로우 줌(slow zoom)), 조명(lighting), 스타일(style). 구체적인 비트(beats)는 모호하게 작성.
• 편집 프롬프트는 점진적으로 (incremental) 유지: 장면이 아닌 '변화'를 설명할 것.
• 항상 최신 (latest) 인터랙션 ID(interaction ID)를 체이닝(chain)할 것.
• 내용이 길거나 움직임이 많은 경우에는 delivery='uri' 방식을 선호할 것.
• 비디오 생성은 준비될 때까지 블록(block)되며 비용이 발생합니다 — 관련 편집 사항들을 하나의 잘 정의된 프롬프트로 배치(batch) 처리하고, YouTube에 public으로 업로드하기 전에는 반드시 확인을 거치세요.

이 스킬은 MCP 서버 자체(mcp/server.py), 요구 사항(requirements), 설치 스크립트(installer script), 그리고 Interactions API 비디오 가이드를 함께 묶어 제공하므로 자급자족(self-contained)이 가능합니다. 즉, 스킬을 설치하기만 하면 서버를 구축하는 데 필요한 모든 것을 갖추게 됩니다.

설치 방법: "그냥 바로 작동하길 원하는" 버전

세 가지가 필요합니다: Python 3.10+, Antigravity CLI (또는 Claude Code), 그리고 Gemini API 키 (Google AI Studio에서 무료로 발급 가능)). 아래 경로 중 _하나_를 선택하세요.

경로 A: 플러그인 마켓플레이스 (가장 적은 키 입력)

에이전트 CLI 내부에서 다음과 같이 입력합니다:

/plugin marketplace add xbill9/omni-skill-agy
/plugin install omni-video@omni-skill-agy

이렇게 하면 스킬이 설치됨과 동시에 MCP 서버가 자동으로 등록됩니다. 플러그인 매니페스트(manifest)에는 API 키가 포함되지 않으며(당연히 그래야 합니다!), 서버는 환경 변수에서 GEMINI_API_KEY를 읽어오므로, 세션을 시작하기 전에 해당 변수가 내보내기(export) 되었는지 확인하세요.

경로 B: 클론 및 부트스트랩 (이 리포지토리)

# 1. 코드 가져오기
git clone https://github.com/xbill9/omni-skill-agy.git
cd omni-skill-agy
...

정말로 이게 전부입니다. 무언가 잘못된 것 같다면 init.sh를 다시 실행해도 안전합니다.

경로 C: 본인의 프로젝트에 설치

리포지토리를 클론한 상태에서 다음과 같이 실행합니다:

make init TARGET=/path/to/your/project