본문 바로가기
목차
개발환경

Gemini CLI: Extension, Skill, MCP, Tool (정리)

by ds31x 2026. 3. 16.
728x90
반응형

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.jsonmcpServers 설정 settings.jsondiscoveryCommand / 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.jsondiscoveryCommand / callCommand (이는 key로 값에 script의 패스가 할당됨)
모델의 인식 방식 Skill 활성화 후 run_shell_command로 실행 지시 이름·스키마를 가진 독립 Tool로 모델이 직접 호출
유효 범위 해당 Skill이 활성화된 세션 에서만 유효 항상 등록된 상태 로 상시 사용 가능
배포 방식 Skill 디렉터리와 함께 패키징 settings.json 및 스크립트 파일 별도 관리
  • Custom Tools는
    • 모델이 Tool로 인식 (/tools 명령어로 확인 가능)하고
    • 직접 호출하는 구조인 반면,
  • Skill의 scripts/
    • 모델이 Skill의 지침(SKILL.md)을 읽고
    • run_shell_command로 실행하도록 유도받는 구조임.

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을 인식하지 못함.

  • namedescription 필드는 세션 시작 시 모델에게 주입되어야 하는 meta-data임.
  • 이는 반드시 frontmatter에 존재해야함.

SKILL.mddescription
얼마나 명확하게 작성하느냐가 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단계로 이루어짐.

  1. Discovery (session시작시)
  2. Activation (사용자의 prompt에 의해 자동으로 이루어짐)
  3. 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에 국한되지 않음:

공식 튜토리얼들


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. 관련 사이트

공식 튜토리얼


3-4. Custom Tools

Custom Tools란?

Gemini CLI 전용의 로컬 실행 도구 등록 방식임.

  • settings.jsondiscoveryCommandcallCommand를 등록하면,
  • 세션 시작 시 도구가 자동으로 발견되어 항상 호출 가능한 상태가 됨.

MCP 서버 구축보다
가볍고 빠르게
로컬 기능을 연결하는 데 적합함.

단, 이 방식은 Gemini CLI에 특화되어 있어, 다른 AI 클라이언트와의 호환성은 없음.

3-4-1. 동작 방식:

다음의 2단계로 동작이 이루어짐:

  1. Discovery : discoveryCommand
  2. 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

공식 문서

튜토리얼

참고 자료

728x90