Gemini Skill
⚠️ 작업 우선순위 (반드시 준수)
Gemini와의 모든 상호작용은 다음 우선순위에 따라 방식을 선택합니다:
- 🥇 최우선: MCP 도구 호출 — 본 스킬이 노출하는 MCP 도구를 직접 호출하여 작업을 완료합니다. 대부분의 시나리오를 커버합니다.
- 🥈 차선: 스킬 스크립트 실행 — MCP 도구만으로 해결되지 않는 경우, 본 스킬 프로젝트에 포함된 스크립트를 실행할 수 있습니다.
- 🥉 최후: 스킬이 관리하는 브라우저에 연결 — 앞의 두 방식으로도 해결되지 않을 때만
gemini_browser_info를 통해 CDP 연결 정보를 얻어, 스킬이 관리하는 브라우저에 직접 연결하여 작업을 수행합니다. 이 방식은 반드시 사용자 동의를 먼저 받아야 합니다.
절대 금지: 새로운 브라우저 인스턴스를 직접 실행하여 Gemini 페이지에 접속하는 행위 (OpenClaw 브라우저 사용, 별도의 Puppeteer 실행 등). 이는 세션 충돌을 유발합니다.
브라우저 Daemon이 실행 중이지 않아도 MCP 도구가 자동으로 실행하므로 별도의 수동 조작이 필요하지 않습니다.
📡 진행 동기화 & 장시간 소요 도구 규칙
MCP 도구 호출(특히 이미지 생성, 응답 대기 등)은 60~180초 정도 소요될 수 있습니다. 다음 규칙을 반드시 준수해야 합니다:
- 본 스킬의 모든 MCP 도구는 동기식 블로킹 호출이며, 최종 결과가 반환될 때까지 대기합니다. 폴링이 필요한 '중간 상태'는 존재하지 않습니다.
- 장시간 소요 도구를 호출할 때는
timeoutMs를 반드시 ≥180000(3분) 으로 설정하여 전송 계층의 조기 타임아웃을 방지하십시오. - 도구의 최종 반환을 받지 않고 대화를 종료하거나 사용자에게 "아직 실행 중입니다"/"도구 타임아웃"이라고 보고하는 것을 금지합니다.
- 15~30초마다 사용자에게 진행 메시지(예: "Gemini가 이미지를 생성 중입니다... 30초 대기 중...")를 보내 피드백을 유지합니다.
- 최종 결과를 받은 후에는 즉시 산출물(파일 경로)을 반환하거나 오류를 보고해야 하며, 누락이 없어야 합니다.
fullSize모드가 실패하면fullSize=false(미리보기 이미지 모드가 더 안정적)로 다운그레이드하여 재시도할 수 있습니다.
트리거 키워드
- 이미지 생성 작업:
생성,그려줘,이미지,포스터,nano banana,nanobanana,image generation,generate image - 요청이 모호한 경우, 사용자에게 이미지 생성이 필요한지 먼저 확인하십시오.
사용 방법
본 스킬은 MCP Server를 통해 도구를 노출하며, AI가 직접 호출하면 됩니다.
브라우저 시작, 세션 관리, 이미지 추출, 파일 저장 등의 전체 프로세스는 도구 내부에 모두 캡슐화되어 있습니다.
⚠️ 강제 규칙
AI는 반드시 MCP 도구를 통해 모든 작업을 수행해야 합니다.
MCP를 우회하여
node -e "..."와 같은 임시 스크립트를 작성하거나.js임시 파일을 생성하여import/require로 본 프로젝트의 함수(createGeminiSession,createOps등)를 호출하는 것을 금지합니다.만약 MCP 도구로 현재 요구사항을 해결할 수 없는 경우, AI는 먼저 사용자에게 이유를 설명하고 명시적인 동의를 얻어야 임시 스크립트를 작성하여 하위 API를 호출할 수 있습니다. 사용자 동의 없이는 절대 허용되지 않습니다.
사용 가능한 도구
핵심 이미지 생성 (전체 프로세스 캡슐화):
| 도구명 | 설명 | 매개변수 |
|---|---|---|
gemini_generate_image | 전체 이미지 생성 프로세스: 새 세션 생성 → 프롬프트 전송 → 대기 → 이미지 추출 → 로컬 저장 (약 60~120초 소요) | prompt, newSession(기본 false), referenceImages(참조 이미지 경로 배열), fullSize(기본 true, 고화질 원본; false시 미리보기), timeout(기본 120000ms) |
세션 관리:
| 도구명 | 설명 | 매개변수 |
|---|---|---|
gemini_new_chat | 새 빈 대화 생성 | 없음 |
gemini_temp_chat | 임시 대화 모드 진입 (기록 미저장) | 없음 |
모델 전환:
| 도구명 | 설명 | 매개변수 |
|---|---|---|
gemini_switch_model | Gemini 모델 전환 | model(pro / quick / think) |
텍스트 대화:
| 도구명 | 설명 | 매개변수 |
|---|---|---|
gemini_send_message | 텍스트 메시지 전송 후 응답 완료까지 대기, Gemini의 응답 텍스트를 직접 반환 | message, timeout(기본 120000ms) |
이미지 조작:
| 도구명 | 설명 | 매개변수 |
|---|---|---|
gemini_upload_images | 입력 상자에 이미지 업로드 (전송은 하지 않음, send_message와 함께 사용 가능) | images(경로 배열) |
gemini_get_images | 세션에 로드된 모든 이미지의 메타 정보 가져오기 | 없음 |
gemini_extract_image | 지정된 이미지의 base64 데이터를 추출하여 로컬에 저장 | imageUrl(get_images에서 획득) |
gemini_download_full_size_image | 전체 크기의 고화질 이미지 다운로드, 기본값은 가장 최신 이미지, 인덱스 지정 가능 | index(선택, 0부터 시작, 오래된 순→최신 순) |
gemini_share_latest_image | 이미지에 대한 공개 공유 링크 생성 후 바로 반환, 기본값은 가장 최신 이미지 | index(선택), timeout, copyToClipboard, closeDialog |
텍스트 응답 추출:
| 도구명 | 설명 | 매개변수 |
|---|---|---|
gemini_get_all_text_responses | 세션의 모든 텍스트 응답 가져오기 (텍스트만, 이미지 제외) | 없음 |
gemini_get_latest_text_response | 가장 최신 텍스트 응답 가져오기 | 없음 |
로그인 상태:
| 도구명 | 설명 | 매개변수 |
|---|---|---|
gemini_check_login | Google 계정에 로그인되어 있는지 확인 | 없음 |
페이지 탐색:
| 도구명 | 설명 | 매개변수 |
|---|---|---|
gemini_navigate_to | 지정된 Gemini 페이지 URL(예: 기록 대화 링크) 열기, gemini.google.com 도메인만 허용 | url(대상 URL), timeout(기본 30000ms) |
진단 & 복구:
| 도구명 | 설명 | 매개변수 |
|---|---|---|
gemini_probe | 페이지 각 요소 상태 확인 (입력 상자, 버튼, 모델 등) | 없음 |
gemini_reload_page | 페이지 새로고침 (멈춤 또는 비정상 상태 시 사용) | timeout(기본 30000ms) |
gemini_browser_info | 브라우저 연결 정보 획득 (CDP 포트, wsEndpoint 등) | 없음 |
일반적인 사용 예시
빠른 이미지 생성 (한 번에 완료):
gemini_generate_image호출, prompt 전달 → 로컬 이미지 경로 반환
이미지 생성 후 공유 링크 획득:
gemini_generate_image호출하여 이미지 생성gemini_share_latest_image호출하여 공개 링크 반환
유연한 조합 (세밀한 제어):
gemini_new_chat— 새 세션 생성gemini_switch_model→pro— 고품질 모델로 전환gemini_upload_images— 참조 이미지 업로드gemini_send_message— 설명 전송gemini_get_images→gemini_extract_image— 이미지 획득 및 저장
문제 해결:
gemini_probe— 페이지 요소가 제대로 배치되었는지 확인gemini_reload_page— 페이지가 멈추면 새로고침gemini_browser_info— CDP 정보를 얻어 직접 연결하여 디버깅
MCP 클라이언트 설정
{
"mcpServers": {
"gemini": {
"command": "node",
"args": ["<프로젝트 절대 경로>/src/mcp-server.js"]
}
}
}
npm run mcp 명령어로 수동 실행할 수도 있습니다.
실패 처리
도구 내부에 재시도 로직이 포함되어 있습니다. 그래도 실패할 경우, 반환값의 isError: true와 오류 메시지가 원인을 알려줍니다:
- 생성 시간 초과 — 사용자에게 설명을 간소화한 후 재시도하도록 권장
- Daemon 미실행 — 도구가 자동으로 실행하며, 그래도 실패하면 수동으로
npm run daemon실행 - 페이지 비정상 —
gemini_browser_info를 호출하여 브라우저 상태 확인
참고
- 상세 실행 및 대체:
references/gemini-flow.md - 키워드 및 라우팅:
references/intent-routing.md