Gemini CLI 확장하기: Extension, Agent Skills, MCP, Custom Tools 완전 정리
Gemini CLI는 기본 제공 기능 외에도,
사용자가 직접 기능을 확장할 수 있는
여러 메커니즘을 제공함.
대표적으로 다음 4가지가 있음:
- Extensions,
- (Agent) Skills,
- MCP Servers,
- Custom Tools.
이 4가지는 서로 대등한 병렬 관계는 아니나 그렇다고 엄격한 계층구조도 아님.
각각 유래·목적·동작 구조가 차이를 가짐.
이 문서는 이들의 정의와 관계를 간단히 정리해 봄:
0. 각 확장 방식의 유래 (Origins)
4가지 개념은
- 서로 다른 배경에서 등장하였으며,
- Gemini CLI 는 이들을 받아들이거나 정의하여 통합하고 있음.
| 개념 | 유래 및 표준 여부 |
| MCP (Model Context Protocol) | Anthropic이 2024년 11월 공개한 open standard protocol. 이후 Google, OpenAI, Microsoft 등이 채택하여 사실상 AI-외부서비스 연결의 산업 표준 이 됨. |
| Agent Skills | Anthropic이 2025년 10월 Claude 전용 기능으로 도입 후, 2025년 12월 18일 open standard 로 공개. 이후 Claude Code, GitHub Copilot, Cursor, Gemini CLI 등 다수의 AI 클라이언트가 공통 채택함. |
| Custom Tools | Gemini CLI 고유의 로컬 실행 도구 등록 방식. settings.json 기반으로 동작하며 Gemini CLI에 특화됨. |
| Extensions | Gemini CLI의 공식 패키징 및 해당 패키지 배포 시스템 . MCP 설정, 컨텍스트 파일, 커스텀 명령어 등을 하나의 설치 가능한 단위로 묶어 공유하기 위한 구조. |
주의할 점은 다음을 참고:
- MCP와 Agent Skills는 Gemini CLI에 종속되지 않는 범용 오픈 표준임.
- Custom Tools와 Extensions는 Gemini CLI에 특화된 구조임.
이 차이는 단순한 분류가 아니라 실용적 의미를 가짐.
MCP 서버나 Agent Skill을 한 번 만들어두면,
Gemini CLI 외에도 지원 클라이언트 어디서든 재사용 가능함.
1. 관계 구조 (Relationship)
이들 4가지 개념은 포함 관계와 독립 관계가 혼재함.
- 우선 Extension이 필수적인 상위 컨테이너가 아니라는 점 임:
- Gemini CLI에선 상위 컨테이너는 맞음.
- 그러나 모든 요소를 필수적으로 요구하진 않음.
Extension은
- 각 요소들을 묶어 배포하는 선택적 패키지 단위이며,
- Extension 없이도 각각이 독립적으로 등록하고 공유할 수 있음.
[ Extension ] ← 선택적 배포 패키지.
| 아래 요소들 중 일부 또는 전부를 묶어 설치·공유하는 단위.
| 반드시 모든 요소를 포함할 필요 없음.
|
├── MCP Server 설정 (포함 가능, 선택)
├── Context File/GEMINI.md (포함 가능, 선택)
├── Custom Commands/.toml (포함 가능, 선택)
├── Agent Skills (포함 가능, 선택)
└── excludeTools 설정 (포함 가능, 선택)
[ Agent Skills ] ← Extension 없이 독립 설치·공유 가능한 오픈 표준 포맷.
└── SKILL.md (필수)
scripts/ (선택 — Skill 활성화 시 run_shell_command로 실행)
references/ (선택 — 참조 문서, 예시 파일)
assets/ (선택 — 템플릿, 바이너리 리소스)
※ scripts/의 스크립트는 Custom Tool과 유사하게 동작하지만,
등록·호출 방식이 근본적으로 다른 별개 개념임 (2-2절 참고).
[ MCP Servers ] ← Extension 없이 settings.json으로 직접 등록 가능.
└── Tools (MCP 서버가 노출하는 named 함수 — 모델이 직접 호출)
Resources (MCP 서버가 노출하는 데이터 소스 — @ 문법으로 참조)
Prompts (MCP 서버가 노출하는 프롬프트 템플릿)
[ Custom Tools ] ← Extension 없이 settings.json으로 직접 등록 가능.
항상 등록된 상태. 모델이 언제든 직접 호출 가능.
2. 기술적 비교 분석
2-1. 비교
| 비교 항목 | Extensions | Agent Skills | MCP Servers | Custom Tools |
| 정의 방식 | gemini-extension.json 포함 디렉터리 |
SKILL.md 포함 디렉터리 |
settings.json의 mcpServers 설정 |
settings.json의 discoveryCommand / callCommand |
| 주된 역할 | 여러 요소를 묶어 설치·배포하는 패키지 단위 | on-demand 지침·리소스 패키지 | 외부 시스템의 도구·리소스·프롬프트 연결 | 로컬 실행 가능 도구 상시 등록 |
| 활성화 방식 | gemini extensions install로 설치, 시작 시 자동 로드 |
세션 시작 시 name·description만 주입, 매칭 시 activate_skill로 on-demand 활성화 |
설정된 서버에서 tools·resources·prompts 자동 discovery | 설정 시 도구로 등록, 항상 호출 가능 |
| 범용성 | Gemini CLI 전용 | 오픈 표준 (Claude Code, Copilot, Cursor 등 호환) | 오픈 표준 (MCP 지원 모든 클라이언트 호환) | Gemini CLI 전용 |
| 단독 공유 | gemini extensions install <url> |
gemini skills install <url|path|.skill> |
settings.json 공유 |
settings.json + 스크립트 공유 |
| 복잡도 | 높음 (여러 요소 통합) | 중간 | 중간 이상 | 낮음 |
2-2. Skill 내 scripts/ vs Custom Tools
Skill 와 Custom Tools 모두 스크립트 실행이 가능하나
구조와 목적이 차이가 있음.
| 구분 | Skill 내 scripts/ |
Custom Tools |
| 등록 방식 | Skill 디렉터리에 파일로 번들 | settings.json의 discoveryCommand / callCommand (이는 key로 값에 script의 패스가 할당됨) |
| 모델의 인식 방식 | Skill 활성화 후 run_shell_command로 실행 지시 |
이름·스키마를 가진 독립 Tool로 모델이 직접 호출 |
| 유효 범위 | 해당 Skill이 활성화된 세션 에서만 유효 | 항상 등록된 상태 로 상시 사용 가능 |
| 배포 방식 | Skill 디렉터리와 함께 패키징 | settings.json 및 스크립트 파일 별도 관리 |
- Custom Tools는
- 모델이 Tool로 인식 (
/tools명령어로 확인 가능)하고 - 직접 호출하는 구조인 반면,
- 모델이 Tool로 인식 (
- Skill의
scripts/는- 모델이 Skill의 지침(
SKILL.md)을 읽고 run_shell_command로 실행하도록 유도받는 구조임.
- 모델이 Skill의 지침(
3. 핵심 구성 요소 (Components)
3-1. Extension
Extension이란?
Extension은
gemini-extension.json파일을
포함하는 디렉터리임.
다음의 다양한 요소를 하나의 패키지로 묶어 설치·배포·공유할 수 있는 단위임:
- MCP 서버 설정,
- 컨텍스트 파일,
- 커스텀 명령어,
- Agent Skills,
- 도구 제한 등
단, Extension은
이 모든 요소를 반드시 포함할 필요 없음.
예를 들어,
- MCP 서버 설정만 번들한 Extension도 유효하며,
GEMINI.md와 Custom Commands만 묶은 Extension도 가능함.
목적에 따라
필요한 요소만 선택하여 구성함.
중요한 것은 gemini-extension.json 파일은 필수이며,
해당 파일이 있는 디렉터리가 바로 Extension이라고 볼 수 있음
3-1-1. gemini-extension.json 구조:
{
"name": "my-python-extension",
"version": "1.0.0",
"mcpServers": {
"my-python-server": {
"command": "python",
"args": ["server.py"],
"env": {
"DB_PATH": "${DB_PATH}"
}
}
},
"contextFileName": "GEMINI.md",
"excludeTools": ["run_shell_command"]
}
name: Extension의 고유 식별자. 디렉터리 이름과 일치해야 함.version: Extension의 버전 (gemini extensions update시 참조).mcpServers: 번들할 MCP 서버 설정 (선택).settings.json의 MCP 설정과 동일한 형식.- 주의할 점은, command로 지정한 실행 파일이 Extension을 설치하는 각 사용자의 환경에 반드시 존재해야 함.
contextFileName: 컨텍스트로 주입할 파일명 (선택). 기본값은GEMINI.md.
해당 파일이 Extension 디렉터리에 있으면 이 필드 없이도 자동 로드 됨.excludeTools: 특정 빌트인 도구 비활성화 (선택).
예:["run_shell_command(rm -rf)"]로 특정 명령만 제한 가능.
Extension에 포함되는 Agent Skills는
- Extension 디렉터리 내
.gemini/skills/경로에 배치하면 자동으로 번들됨. gemini-extension.json에 별도 필드는 없는 점에 주의할 것.
3-1-2. Extension 설치·관리 명령:
Extension은 Gemini-CLI에서 처음부터 배포 및 공유를 염두에 둔 확장방식임.
때문에 설치, 업데이트, 목록 확인등을 위한 명령어가 지원됨.
Extension 관련 명령어는 /extensions 를 공통으로 사용하며 이에 대한 인자로 구분됨.
다음을 참고:
# GitHub URL 또는 로컬 경로로 설치
gemini extensions install https://github.com/user/my-extension
gemini extensions install ./my-extension
# 업데이트 (gemini-extension.json의 version 필드 기준)
gemini extensions update my-extension
# 설치된 Extension 목록 확인 (CLI 내부)
/extensions list
3-1-3. Extension 갤러리 (커뮤니티 공개 목록):
공개된 Extensions는 다음의 URL에서 확인 가능(설치법 및 관련 URL등이 표시되어있음)함.
https://geminicli.com/extensions/
이는 Gemini CLI의 /extensions explore 명령어로도 이동 가능함.
3-1-4. Extension 을 학습하기 좋은 사이트:
공식 튜토리얼
3-2. Agent Skills
Agent Skills란?
Anthropic이 처음 제안한 오픈 표준 포맷,
- AI 에이전트에게 특정 도메인의 전문 지식·절차·리소스를
- on-demand로 제공하기 위한 자기 완결적(self-contained) 디렉터리 패키지임.
Global Context인 GEMINI.md 와 달리,
- Agent Skills는 필요한 순간에(on-demand)만 불러오는 Lazy Loading 방식.
- 이 덕분에 Context를 읽기 위한 Token 소모를 줄이고 응답 정확도와 속도를 높일 수 있음.
Skills는 Claude Code, GitHub Copilot, Cursor 등에서 사용가능!
MCP 와 Skills는
여러 AI 클라이언트 간에 이식 가능한
open standard임.
3-2-1. SKILL.md 구조 — YAML frontmatter + Markdown 본문의 이중 구조가 필수:
SKILL.md에선 frontmatter 없이는 Gemini CLI가 해당 Skill을 인식하지 못함.
name과description필드는 세션 시작 시 모델에게 주입되어야 하는 meta-data임.- 이는 반드시 frontmatter에 존재해야함.
SKILL.md의description을
얼마나 명확하게 작성하느냐가 Skill 자동 활성화 정확도를 결정지음.
다음의 예제 SKILL.md를 참고:
---
name: api-auditor
description: >
Expertise in auditing and testing API endpoints.
Use when the user asks to "check", "test", or "audit"
a URL or API endpoint for availability and correctness.
---
# API Auditor Instructions
You act as a QA engineer specialized in API reliability.
When this skill is active, you MUST follow this procedure:
1. **Audit**: Use the bundled `scripts/audit.js` utility to check the
status of the provided URL (status codes, latency, response body).
2. **Report**: Analyze the output and explain any failures in plain English.
3. **Recommend**: Suggest concrete remediation steps if the endpoint fails.
3-2-2. 권장 디렉터리 구조:
Skills는 open standard로 배포 및 패키징을 염두에 두고 만들어짐.
일반적으로 다음과 같은 구조의 디렉토리가 Skills임:
.gemini/skills/api-auditor/
├── SKILL.md (필수 — YAML frontmatter + 지침 본문)
├── scripts/ (선택 — 활성화 후 run_shell_command로 실행할 스크립트)
│ └── audit.js
├── references/ (선택 — 정적 참조 문서, 예시 파일)
│ └── error-codes.md
└── assets/ (선택 — 템플릿, 바이너리 리소스)
3-2-3. Skills의 3단계 Progressive Disclosure:
Skills의 동작은 다음 3단계로 이루어짐.
- Discovery (session시작시)
- Activation (사용자의 prompt에 의해 자동으로 이루어짐)
- Execution (사용자의 승인 이후,
SKILL.md가 로딩)
[1. Discovery]
세션 시작 시 name + description만 시스템 프롬프트에 주입.
전체 지침과 리소스는 아직 로드되지 않음 → 토큰 절약.
↓ 요청 내용이 description과 매칭될 때
[2. Activation]
모델이 activate_skill 도구를 자동 호출.
UI에 동의 프롬프트 표시 (Skill 이름, 목적, 접근 경로).
사용자 승인 후 진행.
↓ 승인 완료
[3. Execution]
SKILL.md 본문 전체를 대화 히스토리에 주입.
Skill 디렉터리 전체가 에이전트의 허용 파일 경로에 추가됨.
모델이 Skill 지침을 우선 적용하여 작업 수행.
3-2-4. Skill 탐색 경로 및 우선순위:
Skills 의 디렉토리가 놓일 수 있는 곳은 아래와 같음:
Workspace Skills: <project>/.gemini/skills/ 또는 <project>/.agents/skills/
User Skills: ~/.gemini/skills/ 또는 ~/.agents/skills/
Extension Skills: <extension-dir>/.gemini/skills/
우선순위: Workspace > User > Extension
같은 계층 내에서는 .agents/skills/ > .gemini/skills/
Skills는
Extension에 포함될 수 있음을 기억할 것.
3-2-5. Skill 독립 설치·관리 명령:
앞서 말한대로, Skills도 배포 및 공유를 염두에 두고 설계됨.
Gemini CLI에선 \skills 명령어를 통해 설치 및 관리가 가능함:
# Git 저장소로부터 설치
gemini skills install https://github.com/user/repo.git
# 로컬 디렉터리로부터 설치
gemini skills install /path/to/local/skill
# .skill 번들 파일로부터 설치
gemini skills install /path/to/my-expertise.skill
# 로컬 개발 디렉터리를 심볼릭 링크로 연결 (개발 시 편리)
gemini skills link /path/to/my-skills-repo --scope workspace
# 설치된 Skill 목록 확인
gemini skills list
# Skill 활성화/비활성화 (기본 scope: user)
/skills enable api-auditor
/skills disable api-auditor --scope workspace
3-2-6. 관련 사이트들
Skills는 open standard이므로 Gemini에 국한되지 않음:
공식 튜토리얼들
- Agent Skills 입문 실습 (공식 Getting Started)
- Agent Skills 작성 가이드 (공식 Creating Skills)
- Agent Skills 실습 (Google Codelabs)
- Agent Skills 개요 (공식 문서)
3-3. MCP Servers & Tools
MCP란?
Model Context Protocol(MCP)은
Anthropic이 2024년 11월 공개한
AI 에이전트와 외부 서비스 간의 표준 통신 프로토콜임.
- 기존에는 AI 툴마다 외부 서비스 연결 방식이 제각각이었으나,
- MCP가 이를 표준화하여 MCP를 지원하는 어떤 AI 클라이언트든
- 동일한 서버를 연결해 사용할 수 있게 됨.
MCP 서버는 세 가지 유형의 기능을 노출할 수 있음:
- Tools: 모델이 직접 호출하는 함수 단위. 데이터 조회, 외부 API 호출, 파일 조작 등.
- Resources:
@문법으로 참조 가능한 데이터 소스. 파일, API 응답, 보고서 등. - Prompts: 재사용 가능한 프롬프트 템플릿.
discovery된 MCP Tool은 빌트인 도구와 동일하게 모델이 자동으로 사용 가능함.
서버 이름이 충돌할 경우 auto prefixing 으로 이름이 구분됨.
3-3-1. settings.json 으로 MCP 서버 등록 예시:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
},
"sqlite": {
"command": "uvx",
"args": ["mcp-server-sqlite", "--db-path", "./mydb.sqlite"]
}
}
}
3-3-2. Tool Definition (Schema) 예시 — 서버가 노출하는 도구 정의 구조:
{
"name": "list_issues",
"description": "GitHub 저장소의 이슈 목록을 가져옵니다.",
"inputSchema": {
"type": "object",
"properties": {
"owner": { "type": "string", "description": "저장소 소유자" },
"repo": { "type": "string", "description": "저장소 이름" },
"state": { "type": "string", "enum": ["open", "closed", "all"] }
},
"required": ["owner", "repo"]
}
}
3-3-3. MCP 서버 상태 확인 명령 (CLI 내부):
Gemini CLI가 지원하는 MCP 명령어는 다음과 같음:
/mcp # 연결된 모든 MCP 서버, Tools, Resources, Prompts 목록 확인
3-3-4. 관련 사이트
공식 튜토리얼
- MCP 서버 설정 및 사용 가이드 (공식 문서)
- MCP 서버 실습 (Google Codelabs — Hands-on with Gemini CLI)
- MCP 서버 GitHub 공식 문서
3-4. Custom Tools
Custom Tools란?
Gemini CLI 전용의 로컬 실행 도구 등록 방식임.
settings.json에discoveryCommand와callCommand를 등록하면,- 세션 시작 시 도구가 자동으로 발견되어 항상 호출 가능한 상태가 됨.
MCP 서버 구축보다
가볍고 빠르게
로컬 기능을 연결하는 데 적합함.
단, 이 방식은 Gemini CLI에 특화되어 있어, 다른 AI 클라이언트와의 호환성은 없음.
3-4-1. 동작 방식:
다음의 2단계로 동작이 이루어짐:
- Discovery :
discoveryCommand - Call :"
callCommand
[Discovery]
세션 시작 시 discoveryCommand를 실행.
실행 결과로 FunctionDeclaration JSON 배열을 반환.
이 배열이 모델에게 사용 가능한 도구 목록(스키마)으로 제공됨.
[Call]
모델이 도구 호출을 결정하면 callCommand를 실행.
첫 번째 인자: 도구 이름
stdin: 도구에 전달할 JSON 인자
stdout: 도구 실행 결과 (모델에게 반환됨)
3-4-2. settings.json 등록 예시:
{
"tools": {
"discoveryCommand": "node tools/index.js list",
"callCommand": "node tools/index.js call"
}
}
3-4-3. discoveryCommand가 반환해야 하는 JSON 형식 예시:
[
{
"name": "get_weather",
"description": "특정 도시의 현재 기온을 반환합니다.",
"parameters": {
"type": "object",
"properties": {
"city_name": {
"type": "string",
"description": "날씨를 조회할 도시 이름"
}
},
"required": ["city_name"]
}
}
]
3-4-4. 관련 사이트
다음의 URL에서 보다 자세히 다룸:
Custom Tool 실습)
공식 튜토리얼
4. 선택 기준
상황에 따른 적합한 메커니즘 선택 기준을 정리하면 다음과 같음.
| 상황 | 적합한 메커니즘 |
| 단일 로컬 스크립트를 항상 사용 가능하게 등록하고 싶을 때 | Custom Tools |
| 특정 작업의 절차·지침·스크립트를 묶어 필요할 때만 활성화하고 싶을 때 | Agent Skills |
| GitHub, DB, 외부 API 등 외부 서비스와 표준 방식으로 연결하고 싶을 때 | MCP Servers |
| 위 요소 중 일부를 조합해 팀·커뮤니티에 한 번에 배포하고 싶을 때 | Extensions |
| 작업 지식을 Claude Code, Copilot 등 다른 AI 클라이언트와도 공유하고 싶을 때 | Agent Skills (오픈 표준) |
| 외부 서비스 연결 설정을 여러 AI 클라이언트와 공유하고 싶을 때 | MCP Servers (오픈 표준) |
5. 종합 흐름 예시
다음의 예를 들어서 파악해 볼 것:
사용자: "내 GitHub에서 오늘 올라온 Issue를 분석해서 우선순위를 정리해줘"
① Extension 로드 (시작 시 자동)
└─ gemini-extension.json → MCP 서버 설정 + GEMINI.md 컨텍스트 주입
② MCP Server 연결
└─ GitHub MCP 서버와 통신 채널 수립
└─ list_issues, get_issue, add_label 등 Tool을 모델에 노출
└─ 저장소 정보(Resources)를 @ 문법으로 참조 가능
③ Agent Skill 활성화 (on-demand)
└─ "이슈 우선순위 분석" Skill의 description과 요청 매칭 감지
└─ activate_skill 호출 → 사용자 동의 프롬프트 표시
└─ SKILL.md 본문 + references/priority-criteria.md 컨텍스트 주입
④ MCP Tool 실행
└─ list_issues 도구로 오늘 이슈 목록 수집
└─ get_issue로 각 이슈 상세 내용 조회
└─ Skill 지침의 우선순위 기준에 따라 분석·정렬하여 응답
- 이 예시는 Extension + MCP + Skill을 함께 사용하는 통합 시나리오임.
실제로는 각 메커니즘을 단독으로 사용하거나 일부만 조합하는 경우가 더 많음.
예를 들면 다음과 같음:
- MCP 서버만 단독으로 등록해 GitHub에 연결하거나,
- Skill만 단독으로 설치해 코드 리뷰 절차를 표준화하는 것도 완전히 유효함.
References
공식 문서
- Gemini CLI 전체 문서 홈
- Extension 작성 가이드
- Extension 갤러리 (커뮤니티)
- Agent Skills 개요
- Agent Skills 작성 가이드
- MCP Server 가이드
- Tools 레퍼런스 (Custom Tools 포함)
- Tools API 심화 (내부 구조)
튜토리얼
- Extension 입문 실습 (Google Codelabs)
- Agent Skills 입문 실습 (공식 Getting Started)
- Agent Skills 실습 (Google Codelabs)
- Gemini CLI 종합 실습 (Google Codelabs — MCP 포함)
- Custom Tool 실습 (ds31x 블로그)
참고 자료
'개발환경' 카테고리의 다른 글
| Install the WARP of Cloudflare (0) | 2026.03.12 |
|---|---|
| Cloudflare WARP: Secure Internet Routing and Network Optimization (0) | 2026.03.12 |
| npm install 과 npm ci 의 차이 (0) | 2026.01.27 |
| Emacs vs vi 단축키 비교 (주요내용) (0) | 2026.01.07 |
| 아웃바운드 터널을 이용한 SSH 접속: Colab과 cloudflared 사례 (0) | 2026.01.05 |