Gemini CLI 확장 프로그램 시작하기 (Getting started with Gemini CLI extensions)

이 가이드는 첫 번째 Gemini CLI 확장 프로그램을 만드는 과정을 안내합니다. 새로운 확장 프로그램을 설정하고, MCP 서버를 통해 사용자 정의 도구를 추가하고, 사용자 정의 명령을 만들고, GEMINI.md 파일을 사용하여 모델에 컨텍스트를 제공하는 방법을 배우게 됩니다.

전제 조건 (Prerequisites)

시작하기 전에 Gemini CLI가 설치되어 있고 Node.js에 대한 기본적인 이해가 있는지 확인하세요.

기능별 사용 시기 (When to use what)

확장 프로그램은 Gemini CLI를 사용자 정의하는 다양한 방법을 제공합니다.

1단계: 새 확장 프로그램 만들기 (Create a new extension)

가장 쉬운 시작 방법은 내장 템플릿 중 하나를 사용하는 것입니다. 여기서는 mcp-server 예제를 기본으로 사용하겠습니다.

다음 명령을 실행하여 템플릿 파일이 포함된 my-first-extension이라는 새 디렉터리를 만드세요.

gemini extensions new my-first-extension mcp-server

그러면 다음과 같은 구조의 새 디렉터리가 생성됩니다.

my-first-extension/
├── example.js
├── gemini-extension.json
└── package.json

2단계: 확장 프로그램 파일 이해하기 (Understand the extension files)

새 확장 프로그램의 주요 파일을 살펴보겠습니다.

gemini-extension.json

이것은 확장 프로그램의 매니페스트 파일입니다. Gemini CLI에 확장 프로그램을 로드하고 사용하는 방법을 알려줍니다.

{
  "name": "mcp-server-example",
  "version": "1.0.0",
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["${extensionPath}${/}example.js"],
      "cwd": "${extensionPath}"
    }
  }
}

• name: 확장 프로그램의 고유 이름입니다.
• version: 확장 프로그램의 버전입니다.
• mcpServers: 이 섹션에서는 하나 이상의 MCP(Model Context Protocol) 서버를 정의합니다. MCP 서버는 모델이 사용할 새로운 도구를 추가하는 방법입니다.
  • command, args, cwd: 이 필드는 서버를 시작하는 방법을 지정합니다. ${extensionPath} 변수를 사용하는 것에 주목하세요. Gemini CLI는 이를 확장 프로그램의 설치 디렉터리 절대 경로로 대체합니다. 이렇게 하면 확장 프로그램이 어디에 설치되든 작동할 수 있습니다.

example.js

이 파일에는 MCP 서버의 소스 코드가 포함되어 있습니다. @modelcontextprotocol/sdk를 사용하는 간단한 Node.js 서버입니다.

/**
 * @license
 * Copyright 2025 Google LLC
 * SPDX-License-Identifier: Apache-2.0
 */
 
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';
 
const server = new McpServer({
  name: 'prompt-server',
  version: '1.0.0',
});
 
// Registers a new tool named 'fetch_posts'
server.registerTool(
  'fetch_posts',
  {
    description: 'Fetches a list of posts from a public API.',
    inputSchema: z.object({}).shape,
  },
  async () => {
    const apiResponse = await fetch(
      'https://jsonplaceholder.typicode.com/posts',
    );
    const posts = await apiResponse.json();
    const response = { posts: posts.slice(0, 5) };
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(response),
        },
      ],
    };
  },
);
 
// ... (prompt registration omitted for brevity)
 
const transport = new StdioServerTransport();
await server.connect(transport);

이 서버는 공개 API에서 데이터를 가져오는 fetch_posts라는 단일 도구를 정의합니다.

package.json

Node.js 프로젝트의 표준 구성 파일입니다. 종속성과 스크립트를 정의합니다.

3단계: 확장 프로그램 연결하기 (Link your extension)

확장 프로그램을 사용하려면 먼저 로컬 개발을 위해 Gemini CLI 설치에 연결해야 합니다.

1. 종속성 설치:

   cd my-first-extension
   npm install

2. 확장 프로그램 연결:

   link 명령은 Gemini CLI 확장 프로그램 디렉터리에서 개발 디렉터리로 심볼릭 링크를 생성합니다. 즉, 변경 사항이 재설치 없이 즉시 반영됩니다.

   gemini extensions link .

이제 Gemini CLI 세션을 다시 시작하세요. 새로운 fetch_posts 도구를 사용할 수 있습니다. "fetch posts"라고 요청하여 테스트해 볼 수 있습니다.

4단계: 사용자 정의 명령 추가하기 (Add a custom command)

사용자 정의 명령은 복잡한 프롬프트에 대한 단축키를 만드는 방법을 제공합니다. 코드에서 패턴을 검색하는 명령을 추가해 보겠습니다.

1. commands 디렉터리와 명령 그룹을 위한 하위 디렉터리를 만드세요.

   mkdir -p commands/fs

2. commands/fs/grep-code.toml 파일을 만드세요.

   prompt = """
   Please summarize the findings for the pattern `{{args}}`.
    
   Search Results:
   !{grep -r {{args}} .}
   """

   이 명령 /fs:grep-code는 인수를 받아 grep 쉘 명령을 실행하고, 결과를 요약 프롬프트로 파이프합니다.

파일을 저장한 후 Gemini CLI를 다시 시작하세요. 이제 /fs:grep-code "some pattern"을 실행하여 새 명령을 사용할 수 있습니다.

5단계: 사용자 정의 GEMINI.md 추가하기 (Add a custom GEMINI.md)

확장 프로그램에 GEMINI.md 파일을 추가하여 모델에 지속적인 컨텍스트를 제공할 수 있습니다. 이는 모델의 행동 지침이나 확장 프로그램 도구에 대한 정보를 제공하는 데 유용합니다. 명령과 프롬프트만 노출하는 확장 프로그램의 경우 항상 필요한 것은 아닙니다.

1. 확장 프로그램 디렉터리의 루트에 GEMINI.md 파일을 만드세요.

   # My First Extension Instructions
    
   You are an expert developer assistant. When the user asks you to fetch
   posts, use the `fetch_posts` tool. Be concise in your responses.

2. gemini-extension.json을 업데이트하여 CLI가 이 파일을 로드하도록 설정하세요.

   {
     "name": "my-first-extension",
     "version": "1.0.0",
     "contextFileName": "GEMINI.md",
     "mcpServers": {
       "nodeServer": {
         "command": "node",
         "args": ["${extensionPath}${/}example.js"],
         "cwd": "${extensionPath}"
       }
     }
   }

CLI를 다시 시작하세요. 이제 확장이 활성화된 모든 세션에서 모델은 GEMINI.md 파일의 컨텍스트를 갖게 됩니다.

(선택 사항) 6단계: 에이전트 스킬 추가하기 (Add an Agent Skill)

에이전트 스킬을 사용하면 전문적인 지식과 절차적 워크플로우를 번들로 묶을 수 있습니다. 지속적인 컨텍스트를 제공하는 GEMINI.md와 달리, 스킬은 필요할 때만 활성화되어 컨텍스트 토큰을 절약합니다.

1. skills 디렉터리와 스킬을 위한 하위 디렉터리를 만드세요.

   mkdir -p skills/security-audit

2. skills/security-audit/SKILL.md 파일을 만드세요.

   ---
   name: security-audit
   description:
     Expertise in auditing code for security vulnerabilities. Use when the user
     asks to "check for security issues" or "audit" their changes.
   ---
    
   # Security Auditor
    
   You are an expert security researcher. When auditing code:
    
   1. Look for common vulnerabilities (OWASP Top 10).
   2. Check for hardcoded secrets or API keys.
   3. Suggest remediation steps for any findings.

확장 프로그램에 번들로 제공되는 스킬은 세션 중에 모델이 관련 작업을 식별할 때 자동으로 검색되고 활성화될 수 있습니다.

7단계: 확장 프로그램 배포하기 (Release your extension)

확장 프로그램이 만족스럽다면 다른 사람들과 공유할 수 있습니다. 확장 프로그램을 배포하는 두 가지 주요 방법은 Git 리포지토리를 통하거나 GitHub 릴리스를 통하는 것입니다. 공개 Git 리포지토리를 사용하는 것이 가장 간단한 방법입니다.

두 방법에 대한 자세한 내용은 확장 프로그램 배포 가이드를 참조하세요.

결론 (Conclusion)

성공적으로 Gemini CLI 확장 프로그램을 만들었습니다! 다음 내용을 배웠습니다.

• 템플릿에서 새 확장 프로그램 부트스트랩하기.
• MCP 서버로 사용자 정의 도구 추가하기.
• 편리한 사용자 정의 명령 만들기.
• 모델에 지속적인 컨텍스트 제공하기.
• 전문적인 에이전트 스킬 번들링하기.
• 로컬 개발을 위해 확장 프로그램 연결하기.

이제 더 고급 기능을 탐색하고 Gemini CLI에 강력한 새 기능을 구축할 수 있습니다.