Claude Code 스킬을 Gemini로 이전 2026: SKILL.md를 Gem으로 원클릭
Claude Code 스킬을 Gemini로 이전 2026: SKILL.md를 Gem으로 원클릭
결론부터: Claude Code에서 코드 리뷰, commit 메시지, 블로그 작성, AEO 감사 등 30개 스킬을 축적했다면, Gemini로 옮길 때 다시 쓸 필요도, 복붙할 필요도 없습니다. GeminiDesktop이 ~/.claude/skills와 project/.claude/skills 두 경로를 자동으로 스캔해, 각 SKILL.md의 YAML frontmatter와 본문을 Gem (Gemini의 커스텀 Agent 컨테이너)의 name, description, system_prompt로 1:1 매핑합니다.
한 줄 요약: SKILL.md를 “여러 Agent가 공유하는 프롬프트 소스 코드”로 취급. Claude Code / Cursor / Gemini가 같은 파일을 소비합니다.
이미 30개 스킬을 썼다 —— Gemini로 가도 다시 쓸 필요 없다
2024년 후반 Anthropic이 Agent Skills 사양을 공개한 이후, Claude Code 사용자의 커스텀 스킬 축적 속도가 빨라졌습니다. /commit, /review-pr, /blog-writer, /improve-aeo-geo…… 30개를 넘기면 “Agent 바꾸면 모든 프롬프트 다시 쓰기”가 실제 전환 비용이 됩니다.
하지만 스킬의 본질적 가치는 특정 Agent 런타임에 묶여 있는 게 아닙니다. 반복해서 다듬어 실행 가능한 운영 매뉴얼이 된 Markdown 텍스트 에 있습니다. 그 텍스트는 Claude Code에서 slash command로 호출할 수 있고, Cursor에서 .cursorrules에 붙여 넣을 수 있으며, 원칙적으로는 Gemini에서도 Gem의 system_prompt로 주입할 수 있습니다.
문제는 “중간에 수동 번역이 얼마나 필요한가”뿐. Gemini Desktop에서는 자동 스캔 + 자동 매핑으로 이 부분을 제로 설정, 제로 복붙으로 만들었습니다.
Claude Code 스킬 구조 복습
Anthropic 공식 사양 (2024년 8월 확정) 레이아웃을 빠르게 복습합니다:
---
name: review-commit-push
description: Review code, commit with context, and push with type-check auto-fix
allowed-tools: Bash, Edit, Read, Grep
---
# Review Commit Push
When the user asks to commit, follow this procedure:
1. Run `git status` and `git diff --staged`
2. Analyze changes and draft a conventional commit message
3. ...핵심 필드:
| 필드 | 소스 | 의미 | Gem 매핑 |
|---|---|---|---|
name |
YAML frontmatter | slash command 이름 + Agent 내부 ID | Gem name |
description |
YAML frontmatter | 트리거 + 한 줄 설명 | Gem description |
allowed-tools |
YAML frontmatter | 허용 도구 화이트리스트 | 현재는 기록만, 자동 포워딩 없음 (아래 상세) |
| 본문 Markdown | frontmatter 이후 | 운영 매뉴얼, 규칙, 예시 | Gem system_prompt |
본문은 보통 500~3,000자의 프롬프트 텍스트로 체크리스트, 의사결정 트리, 코드 템플릿이 들어갑니다. Agent 경계를 넘을 때 가장 자동화할 가치가 큰 부분입니다.
GeminiDesktop 스캔 경로: ~/.claude/skills + project/.claude/skills
시작 시 GeminiDesktop은 다음 순서로 스캔합니다 (2단계 fallback):
- 글로벌:
~/.claude/skills/*/SKILL.md—— 개인 범용 스킬 (/commit,/review등) - 프로젝트:
<cwd>/.claude/skills/*/SKILL.md—— 프로젝트 고유 스킬 (BibiGPT의/topic-finder,/blog-writer등)
병합 시 같은 이름이면 프로젝트 레벨 우선 —— Claude Code 본체와 동일한 동작입니다. 스캔은 증분 방식으로, 각 SKILL.md의 mtime을 기억해 변경된 파일만 재인포트합니다.
인포트된 Gem은 Gemini 채팅창의 “/” 드롭다운에 원래 Gem과 나란히 나타나며, 시각적 차이는 없습니다.
인포트 규칙: name / description / body → Gem system_prompt
매핑 규칙 상세:
| SKILL.md 필드 | Gem 필드 | 변환 |
|---|---|---|
name: review-commit-push |
Gem name: review-commit-push |
그대로 |
description: ... |
Gem description | 그대로, 최대 512자 |
| 본문 Markdown | Gem system_prompt | UTF-8-safe 32KB 절단, 멀티바이트 문자 중간에서 안 자름 |
allowed-tools |
Gem metadata tags | 태그 표시만, MCP tool 자동 바인딩 없음 |
32KB 이유: Gemini 2.5 Pro의 systemInstruction 상한이 32KB. 99% 스킬에는 충분 (SKILL.md 중앙값 6~8KB)하지만, 프롬프트에 대량 예시를 욱여넣은 스킬은 초과할 수 있습니다. GeminiDesktop은 절단 시 끝에 [...truncated at 32KB, original file at /path/to/SKILL.md]를 삽입해 절단 사실을 명시합니다. 수동으로 줄이는 판단 근거가 됩니다.
UTF-8-safe 절단: CJK 문자는 UTF-8에서 3바이트를 차지하므로, 무식한 바이트 절단은 문자를 반으로 쪼개 디코드 오류를 냅니다. GeminiDesktop의 절단기는 가장 가까운 유효 코드포인트 경계까지 되돌아가, 항상 유효한 UTF-8 출력을 보장합니다.
MCP tool 자동 포워딩을 뺀 이유
기술적으로는 allowed-tools: Bash, Edit, Read를 Gemini의 MCP tool 바인딩으로 변환할 수 있습니다. 의도적으로 하지 않았습니다. 두 가지 이유:
이유 1: 대부분 스킬이 shell/git 환경에 암묵적으로 의존
review-commit-push는 cwd가 git 저장소임을 전제로 하고, commit은 husky hook을 전제로 하며, topic-finder는 gcloud와 GSC CLI 로그인 완료를 전제로 합니다. 이 암묵적 전제는 Claude Code의 로컬 shell에서는 기본 성립하지만, Gemini의 실행 샌드박스 (특히 웹 UI)에서는 완전히 다를 수 있습니다.
Bash tool을 무식하게 포워딩하면, 사용자가 Gem에서 스킬을 호출했을 때 git status가 실패하는 걸 보게 됩니다. “참조 문서로 읽기”보다 나쁜 경험입니다.
이유 2: 보안 경계가 모호
Claude Code의 allowed-tools는 느슨한 화이트리스트일 뿐 강제 샌드박스가 아닙니다. Gemini가 실행을 맡는다면 각 스킬이 정말 화이트리스트 내 작업만 하는지 재감사해야 합니다 —— 그렇지 않으면 데이터 유출이나 파괴적 작업 위험이 있습니다. 이 감사 작업은 필드 매핑보다 훨씬 큰 작업량입니다.
현재 동작: SKILL.md 본문은 system_prompt에 전체 주입되므로, Gem은 스킬이 “무엇을 해야 하는지” 알고 있습니다. 실제 실행은 사용자가 수동으로 호출하거나 MCP server를 명시적으로 바인딩할 때 일어납니다. 다음 단계는 opt-in 자동 브리지 —— SKILL.md에 gemini-bridge: auto를 선언한 스킬만 자동 배선됩니다.
크로스 Agent 재사용 베스트 프랙티스
위의 매핑 규칙을 바탕으로, Agent를 넘나드는 스킬을 쓰는 습관을 정리합니다:
- 도구 의존 최소화. 순수 프롬프트로 해결 가능한 로직에 bash 스크립트 의존 추가 금지. “git diff 분석 후 commit 메시지 작성”은 프롬프트로 규칙 기술이 가능하므로 실제
git diff실행 불필요 - 자기 완결적 프롬프트 블록으로 작성. “당연히 리포지토리 구조를 안다”고 가정하지 말고, 핵심 컨텍스트는 프롬프트 내부에 다 적기
- 도구명은 구체 명령이 아닌 의미 기술로.
bun test가 아닌 “리포지토리의 테스트 스위트 실행”. 후자는 Cursor, Gemini에서도 성립 allowed-tools필드는 자동 포워딩 안 돼도 유지. “이 스킬이 뭘 건드리는가”의 기계 판독 가능 선언으로 남고, 미래의 브리지 도구가 활용
MCP server 설정 상세에서 Claude Code / Cursor / Gemini 삼단이 같은 MCP server 풀을 공유하는 방법을 설명했습니다. 스킬 재사용과 조합하면 Agent 전환 비용을 거의 0에 가깝게 압축할 수 있습니다.
시나리오: Claude Code로 코딩하며 Gemini가 video-summary 재사용
실제 사례: BibiGPT의 bibigpt-skill 패키지는 Agent Native “영상 요약” 능력을 제공하며, SKILL.md에는 “URL 종류 판별, API 선택, 프롬프트 조립” 전체 운영 매뉴얼이 담겨 있습니다.
Claude Code 내: 코딩 중 YouTube 튜토리얼에서 구현 아이디어를 뽑고 싶어 /video-summary https://youtube.com/... 한 줄로 해결.
GeminiDesktop 내: 동일한 SKILL.md가 자동으로 Gem이 되고, 브라우저로 튜토리얼 영상을 보며 /video-summary 현재 탭으로 요약 생성. 출력 포맷, 인용 스타일, 톤이 두 환경에서 완전 일치 —— system_prompt가 문자 그대로 같은 파일이기 때문입니다.
이것이 “스킬을 Agent 간 프롬프트 소스 코드로 취급”의 가치입니다. SKILL.md 하나 유지하면, 모든 Agent에서 소비 가능.
다음: 역방향 익스포트 + 삼단 동기화
단방향 Claude Code → Gemini는 오늘 작동합니다. 다음 단계는 역방향 익스포트 —— Gemini에서 먼저 Gem을 설계한 뒤, SKILL.md로 덤프해 Claude Code가 받을 수 있게 하는 것?
기술적으로는 간단합니다: Gem의 name/description/system_prompt를 YAML frontmatter와 본문으로 되돌리기만 하면 됩니다. Cursor의 .cursorrules 포맷도 관찰 중이며, “하나의 SKILL.md를 삼단 동기화” 목표입니다.
관련 글: Gemini Mac 앱에 빠진 6가지 기능에서 Claude Code 대비 현재 데스크톱 스토리의 로컬 워크플로 갭을 정리했습니다. 스킬 이전은 그중 한 조각에 불과합니다.
마무리
Agent 스킬은 런타임 고유 포맷이어선 안 됩니다. SKILL.md는 지식의 축적물 —— 몇 시간 공들여 다듬은 “리뷰 규범” “블로그 집필 매뉴얼” “AEO 감사표”가 Agent 바꾸면 폐기되는 건 잘못입니다. GeminiDesktop의 자동 스캔 + 매핑은 첫걸음이며, 목표는 스킬 라이브러리를 진정 “Agent runtime 독립”으로 만드는 것입니다.