oil-motion

무엇인가

oil-motion은 AI 코딩 에이전트에 인터랙티브 웹 애니메이션 제작 절차를 주입하는 스킬 팩이다. 규율하는 영역은 CSS·SVG·Lottie로 처리하는 인터페이스 전환이 아니라, 주체 자체가 변형되어야 하는 애니메이션—캐릭터의 고개 돌림, 제품 분해도, 재질 변화, 카메라 관통—이다. 사용자는 무엇을 표현할지, 어떤 소재를 제공할지, 어떤 입력(스크롤·마우스·드래그·터치·기기 방향)에 반응시킬지만 진술한다. 생성·검수·압축·프런트엔드 구현은 전부 에이전트가 맡는다. 즉 영상을 한 번 뽑아 붙이는 방식이 아니라, 키프레임 확정 → 연속 동작 생성 → 프레임 검수 → 실제 표시 크기 기준 압축 → 입력값과 애니메이션 진행률 매핑이라는 고정 파이프라인을 따른다. 배경을 영상에 굽는지 여부와 시간 제어 방식(연속 스크럽·구간 재생·자율 재생)도 이 절차 안에서 결정된다.

어떻게 동작하나

이 절차가 없을 때의 실패는 구체적이다. 에이전트는 보통 전체 영상을 한 번에 생성하려 하고, 그 결과 모델이 도중에 제품 구조나 캐릭터 비율을 바꾸고, 로고가 뭉개지고, 팔다리가 복제되거나, 하드 컷과 플래시 프레임, 의미 없는 정지 구간이 섞인 결과물을 낸다. 끝 프레임이 시작 프레임과 어긋나 왕복 재생이 튀고, 표시 영역이 작은데도 고해상도 원본을 그대로 실어 모바일에서 끊긴다. 마우스의 수평·수직 위치가 모두 자세를 바꾸는 상황에 좌우 왕복 영상 한 편을 붙여 상하·원근 변화를 표현하지 못하고, 스크롤할 때마다 영상을 다시 생성해 같은 입력에 다른 결과가 나온다. 로딩 실패 시 대체 정지 화면이 없고, 사용자가 동적 효과를 끈 경우의 대안도 빠진다.

무엇과 다른가

규칙이 하드 제약인 이유는 영상 생성이 비결정적이고 유료이기 때문이다. 그래서 Concept Contract로 주체·스타일·동작·배경 귀속·상호작용 입력·시간 제어·연속성 요구를 먼저 잠그고 임의 확장을 금지한다. 배경 귀속은 장면을 영상에 구울지 먼저 정하게 하고, 예산 스크립트는 가장 적합한 주 자원 형식 하나를 채택해 두 가지를 중복 구현하지 못하게 한다. 양산 전에는 키프레임 한 쌍과 짧은 영상으로 Pilot을 완료하고, 실제 페이지에 붙여 검수한 뒤 아티팩트 해시가 담긴 승인 파일을 만든다. 이후 생성 스크립트는 승인 파일이 없거나 앞뒤 프레임 SHA-256이 불일치하면 네트워크 접속 전에 차단한다. 압축은 페이지 내 실제 표시 크기를 기준으로 하며, 파일 크기와 선명도가 충돌하면 화면에서의 실제 인상을 우선한다.

어떻게 쓰나

적용 경로는 저장소 주소를 에이전트에 넘겨 설치하거나 npx skills add oil-oil/oil-motion을 실행한 뒤 에이전트가 스킬을 다시 로드하는 방식이다. 규칙 본문은 SKILL.md에, 세부 파라미터·자원 처리·웹 런타임 로직은 references/에 두며, 에이전트가 애니메이션 작업을 다룰 때 이 문서를 참조한다. 로컬에서 기존 영상과 시퀀스 프레임을 처리하는 데는 Python 3.10+와 FFmpeg만 있으면 된다. AI 생성이 필요하면 기본적으로 ZenMux를 통해 이미지·영상 모델을 호출하고, 첫 생성 전에 로컬 설정 페이지를 열어 API 키를 직접 입력하게 한다. 키는 시스템 자격 증명 저장소(macOS 키체인, Windows 자격 증명 관리자, Linux Secret Service)에 저장되고 채팅으로 전송되지 않는다. 설정 페이지는 Node.js 22.18+가 필요하며, 자격 증명 서비스를 쓸 수 없으면 평문 저장으로 대체하지 않고 중단한다.

전제와 한계

내부 구성은 절차 단계와 산출물로 나뉜다. 입력은 참조 소재·표현 목적·제어 방식이고, 첫 산출물은 Concept Contract다. 주체·스타일·동작·배경 귀속·상호작용 입력·시간 제어·연속성 요구를 항목별로 확정하고 임의 확장을 금지한다. 이어 예산 스크립트가 파라미터 공간·접근 방식·기기 예산을 계산해 주 자원 형식 하나를 채택한다. 키프레임 한 쌍과 짧은 영상으로 Pilot을 수행하고 실제 페이지 검수를 거쳐 아티팩트 해시가 담긴 승인 파일을 만들며, 양산 생성은 승인 파일 존재와 앞뒤 프레임 SHA-256 일치를 확인한 뒤에만 네트워크를 호출한다. 프레임 검수 단계는 정지 구간·근사 중복 프레임·플래시·구조 변화를 제거하고 페이지 내 실제 표시 크기에 맞춰 압축한다. 마지막으로 스크롤·마우스·드래그·터치·기기 방향 입력을 애니메이션 진행률에 매핑하는 인터랙션 코드를 작성한다. 산출물은 확정 키프레임과 생성 프롬프트, 원본 영상, 정리된 애니메이션 자원, 데스크톱·모바일용 아틀라스 또는 비디오, 인터랙션 코드, 전체 화면과 현재 프레임·입력값을 함께 보여주는 프리뷰 페이지, 자원·상호작용 범위·로딩 방식 설정 파일이다.

프롬프트를 직접 쓰는 방식과의 차이는 검증 자산이 남는지에 있다. 프롬프트는 매 요청마다 지시를 다시 진술해야 하고, 결과가 좋았는지 판단한 근거가 파일로 축적되지 않는다. CLAUDE.md 같은 단일 규칙 파일은 상시 로드되어 짧은 금지·선호를 강제하는 데 적합하지만, 스크립트·승인 파일·해시 검증 같은 실행 자산을 담지 못한다. oil-motion은 규칙 본문과 참조 자료, 예산·생성·검수 스크립트를 저장소 단위로 함께 두어 절차가 파일로 남는다. 같은 저장소 계열의 oil-ui가 UI 스타일을 여러 안으로 탐색하고 병렬 비교하는 단계에 집중한다면, oil-motion은 소재를 조작 가능한 모션 자원으로 바꾸는 파이프라인에 집중한다. Lottie나 실시간 3D 라이브러리와의 차이도 분명하다. 그쪽은 런타임에 장면을 계산하고, oil-motion은 미리 만들어 둔 연속 프레임에서 위치를 찾거나 구간을 재생한다. 그래서 입력에 대한 응답이 즉시 나오고 같은 입력에 같은 화면이 나온다. 반대로 프레임 자원 자체가 결과물이므로 표시 크기와 기기 예산에 맞춘 압축이 품질을 좌우한다.

설치 후 에이전트가 스킬을 다시 로드하면 이후 애니메이션 요청에서 절차가 발동한다. 첫 요청에서 확인할 항목은 표현하려는 내용과 페이지에서의 역할, 주체의 불변 요소, 제어 입력의 종류, 동작이 하나의 경로인지 수평·수직 동시 반응인지, 페이지 내 실제 표시 크기, 데스크톱과 모바일 자원 분기 여부, 로딩 전·실패 시·동적 효과 비활성 시 표시할 대체 화면이다. 동작 방향이 정해지지 않았으면 방향 세 안을 먼저 받아 표현 내용·따라가는 방식·구현 비용을 비교한 뒤 하나를 고른다. Pilot 승인 전에 양산을 요청하지 않는 편이 비용과 재작업을 줄인다. 검수는 프리뷰 페이지에서 현재 프레임과 입력값을 함께 보며 하고, 실제 페이지에서는 빠른 스크롤·빠른 역방향·잦은 마우스 이동에서 끊김이나 튐, 경계 이탈이 없는지, 페이지 확대나 기기 회전 후에도 입력 위치와 애니메이션 방향이 맞는지 확인한다.

이 스킬은 Claude Code를 주 대상으로 하고 Codex에서도 쓸 수 있는 형식으로 배포된다. 로컬 영상·시퀀스 처리에는 Python 3.10+와 FFmpeg가 필요하고, AI 생성 설정 페이지에는 Node.js 22.18+가 필요하다. 현재 실기 검증은 macOS에서 끝난 상태다. 프로그램이 처리할 수 있는 것은 경미한 드리프트, 색 차이, 중복 프레임, 인코딩 문제다. 반대로 주체 구조, 사지 관계, 동작 방향 자체가 잘못 설계된 경우는 복구하지 못하고 키프레임을 다시 잡거나 영상을 재생성해야 한다. 범위 밖도 명시되어 있다. 독립된 영상 편집과 단일 정지 이미지 제작은 다루지 않고, CSS·JS·SVG·Lottie·실시간 3D만으로 되는 인터페이스 전환·버튼 피드백·레이아웃 모션은 일반 프런트엔드 구현에 맡긴다. 생성은 호출마다 과금되므로 시행 횟수가 곧 비용이다.

주체 자체가 변형되어야 하는지가 첫 분기다. 캐릭터의 고개 돌림, 제품 분해, 재질 변화, 카메라 관통처럼 프레임 사이의 형태 변화가 필요한 경우에는 oil-motion을 쓴다. 인터페이스 전환, 버튼 피드백, 레이아웃 모션처럼 요소의 위치·크기·투명도만 바뀌면 일반 프런트엔드로 충분하다. 마우스의 수평·수직 위치가 모두 자세를 바꾸는 경우에는 2차원 방향 자원을 준비해야 하고, 좌우 왕복 영상 한 편으로는 대응할 수 없다. 이미 녹화한 그린스크린 영상이나 스프라이트 시트를 조작 가능한 웹 자원으로 바꾸는 작업에도 맞는다. 소재만 있고 동작 방향이 없으면 설계를 먼저 위임하고, 최종 결과가 단일 이미지나 독립 영상 파일이면 다른 도구를 쓴다. 표시 영역이 작고 기기 예산이 빡빡하면 압축 기준을 화면 인상에 두고 자원 형식을 낮춘다.