컨텍스트 윈도우 낭비는 그만, Gemini CLI '스킬'로 온디맨드 전문성 구축하기

모든 지식을 프롬프트에 넣지 마세요. 필요한 순간에만 활성화되는 Agent Skills의 메커니즘과 구현 전략을 다룹니다.

에이전트를 개발하다 보면 컨텍스트 관리라는 현실적인 벽에 부딪히게 됩니다. 보안 가이드라인, 복잡한 배포 절차, 프로젝트 고유의 코딩 컨벤션 등을 모두 프롬프트에 포함하면, 정작 중요한 질문을 했을 때 모델이 핵심을 놓치거나 불필요한 토큰 소모로 인해 비용과 속도 면에서 손해를 보기 때문입니다. 실제로 많은 개발자가 모든 지식을 하나의 거대한 컨텍스트 파일에 몰아넣는 방식을 사용하지만, 이는 효율적인 전략이 아닙니다.

Gemini CLI의 ‘에이전트 스킬(Agent Skills)’은 단순한 코드 실행기가 아닙니다. 이는 AI가 필요할 때만 읽고 따르는 텍스트 기반의 지침서(SKILL.md)에 가깝습니다 [1, 2]. 덕분에 모델의 즉각적인 컨텍스트 윈도우를 어지럽히지 않고도 방대한 전문 라이브러리를 유지할 수 있습니다.

결국 Gemini CLI의 ‘스킬’은 정적인 컨텍스트 파일과 달리, 필요한 시점에만 전문 지식을 주입하는 시스템입니다. 모델의 효율성을 극대화하면서 복잡한 워크플로우를 표준화하는 ‘온디맨드 전문성’ 시스템이라고 이해하시면 좋습니다.

왜 GEMINI.md만으로는 부족할까: 정적 컨텍스트 vs 온디맨드 스킬

보통 Gemini CLI를 사용하면 GEMINI.md 파일을 만들어 워크스페이스 전체에 적용되는 배경 지식을 제공합니다. 이는 마치 신입 사원에게 “우리 회사는 이런 곳이야”라고 알려주는 오리엔테이션 자료와 같습니다. 항상 기억하고 있어야 하는 기본 상식인 셈이죠.

하지만 모든 전문 지식을 여기에 넣으면 문제가 생깁니다. 보안 감사, 클라우드 배포, 코드베이스 마이그레이션 같은 특수 작업 지침까지 모두 포함되어 있다고 가정해 보세요. 모델은 지금 당장 단순한 오타 수정 중인데도 머릿속에 ‘보안 감사 체크리스트’를 계속 띄워놓고 있어야 합니다. 이것이 바로 컨텍스트 윈도우 오염과 토큰 낭비의 주범입니다.

반면 ‘스킬’은 특정 작업이 필요할 때만 호출되는 전문성입니다.

“Unlike general context files, which provide persistent workspace-wide background, Skills represent on-demand expertise.” [2]

일반적인 컨텍스트 파일이 워크스페이스 전체에 지속적인 배경 지식을 제공한다면, 스킬은 필요할 때만 사용하는 전문 지식을 의미합니다.

즉, 평소에는 가볍게 유지하다가 “이제 보안 감사 시작해줘”라고 요청하는 순간에만 관련 지침을 주입하는 방식입니다. 모델이 현재 작업에 가장 적합한 지침만 선택적으로 수용하게 함으로써, 훨씬 더 정확하고 효율적인 답변을 끌어낼 수 있습니다 [2].

Gemini CLI 스킬의 작동 원리: 발견에서 실행까지

스킬은 단순히 파일을 읽는 것을 넘어 체계적인 라이프사이클을 가지고 작동합니다. 크게 5단계의 프로세스로 나눌 수 있습니다 [2].

1. 발견(Discovery): 세션을 시작하면 Gemini CLI는 설정된 티어(사용자 수준이나 워크스페이스 수준)를 스캔합니다. 이때 모든 내용을 읽는 것이 아니라, 스킬의 ‘이름’과 ‘설명’만 추출하여 시스템 프롬프트에 등록합니다. “나에게 이런 능력이 있다”라는 목록만으로 인지하는 단계입니다. 2. 활성화(Activation): 사용자가 “이 코드의 보안 점검을 수행해줘”라고 요청하면, 모델은 등록된 목록 중 ‘보안 감사 스킬’이 적합하다고 판단하고 activate_skill이라는 도구를 호출합니다. 3. 동의(Consent): AI가 임의로 파일을 읽는 것을 방지하기 위해 사용자 확인 절차를 거칩니다. “이 스킬을 활성화하여 특정 경로의 파일에 접근해도 되겠습니까?”라는 확인을 통해 보안성을 확보합니다. 4. 주입(Injection): 승인이 나면 비로소 SKILL.md의 상세 내용과 폴더 구조가 대화 기록(Context)에 추가되고, 해당 폴더에 대한 파일 접근 권한이 부여됩니다. 5. 실행(Execution): 모델은 이제 주입된 전문 지식을 바탕으로 구체적인 작업을 수행합니다.

실전: 나만의 커스텀 스킬 설계하고 배포하기

스킬을 구현할 때 가장 중요한 핵심은 스킬이 ‘자기 완결적 디렉토리’여야 한다는 점입니다. 지침이 담긴 SKILL.md 파일과 그 지침을 수행하는 데 필요한 에셋(템플릿, 스크립트 등)이 하나의 폴더에 묶여 있어야 합니다 [2].

설치 범위 및 경로 설정

설치 범위는 두 가지로 나뉩니다.

글로벌 설정: 모든 프로젝트에서 범용적으로 쓰고 싶다면 --scope user로 설정합니다.
로컬 설정: 특정 프로젝트 팀원들과만 공유하고 싶다면 --scope workspace로 설정합니다.

경로 설정 시 팁을 드리자면, .gemini/skills/보다 .agents/skills/라는 별칭(alias)을 사용하는 것이 좋습니다. 이 경로가 업계의 일종의 표준처럼 쓰이고 있어, 향후 다른 AI 도구를 도입하더라도 호환성을 유지하기 유리하기 때문입니다 [2].

구현 예시

가장 빠르게 만드는 방법은 내장된 skill-creator 도구를 사용하는 것입니다 [3]. 아래는 보안 감사 스킬을 구성했을 때의 예시 구조입니다.

# 스킬 디렉토리 구조 예시
my-project/
└── .agents/
    └── skills/
        └── security-audit/
            ├── SKILL.md          # AI가 읽을 상세 지침 (레시피)
            └── templates/
                └── audit-report.md # 결과물 작성을 위한 템플릿 파일

실제 SKILL.md 파일은 다음과 같이 구체적인 단계와 체크리스트를 포함하여 작성할 수 있습니다.

# Security Audit Skill

## Description
이 스킬은 프로젝트의 소스 코드를 분석하여 OWASP Top 10 취약점을 점검하고 보고서를 작성합니다.

## Instructions
1. 먼저 `src/` 디렉토리의 모든 파일을 스캔하여 하드코딩된 비밀번호나 API 키가 있는지 확인하세요.
2. 입력값 검증이 누락된 엔드포인트를 찾아내어 리스트업하세요.
3. 발견된 취약점은 `templates/audit-report.md` 양식에 맞춰 정리하세요.
4. 각 취약점마다 수정 제안 코드를 반드시 포함하세요.

## Assets
- templates/audit-report.md: 보고서 표준 양식

이렇게 설정해두면, 모델은 평소에는 이 내용을 모르고 있다가 “보안 감사 시작해”라는 요청을 받는 순간에만 위 지침을 읽고 정확하게 작업을 수행합니다.

MCP(Model Context Protocol)와의 비교 분석: 무엇을 선택할 것인가?

많은 분이 스킬과 MCP를 혼동하시는데, 이 둘은 보완 관계이지 대체 관계가 아닙니다.

1. 스킬(Skills): 지식의 레시피 스킬은 기본적으로 ‘텍스트 지침’입니다. SKILL.md에 “파이썬 스크립트를 실행해”라고 적는다고 해서 AI가 갑자기 마법처럼 바이너리를 실행하는 것이 아닙니다 [1].

“No. Skills are just text instructions — the AI reads and follows them like a recipe.” [1]

즉, 스킬은 AI에게 ‘어떻게 행동해야 하는지’ 알려주는 매뉴얼 역할을 합니다.

2. MCP: 실행의 손발 반면 MCP는 AI가 외부 데이터베이스에 쿼리를 날리거나, 실제 API를 호출하고, 로컬 파일을 수정하는 등의 ‘실제 동작’을 가능하게 하는 프로토콜입니다.

결론적으로, 스킬이 ‘어떻게 해야 하는지’ 알려주는 매뉴얼이라면, MCP는 ‘실제로 움직이는’ 손발입니다. 최적의 에이전트를 구축하려면 스킬로 전문적인 절차를 정의하고, MCP로 실제 실행력을 부여하는 조합 전략이 필요합니다 [4].

또한, CLI 기반 스킬은 팀원 모두가 동일한 파일을 동기화해야 하는 유지보수 부담이 있습니다 [4]. 조직 규모가 커져 중앙 집중식 관리가 필요하다면, 서버 업데이트만으로 모든 팀원에게 적용되는 MCP 방식이 훨씬 효율적일 수 있습니다 [4].

핵심 요약

컨텍스트 최적화: 상시 필요한 배경 지식은 GEMINI.md에, 특정 상황에만 필요한 전문 지식은 Skills로 분리하여 토큰 낭비를 줄이세요.
텍스트 레시피: 스킬은 SKILL.md 중심의 지침서입니다. 실제 시스템 제어력이 필요하다면 MCP 서버와 조합하여 사용하세요.
표준 경로 사용: .agents/skills/ 경로를 사용해 다른 에이전트 도구와의 호환성을 확보하세요.
규모에 따른 선택: 개인이나 소규모 팀은 CLI 스킬로 빠르게 구축하고, 전사적 배포와 중앙 관리가 필요하다면 MCP 전환을 검토하세요.

AI에게도 ‘집중력’이 필요합니다. 모든 정보를 한꺼번에 쏟아붓는 것이 아니라, 상황에 맞는 ‘도구 상자(Skill Box)’를 스스로 열어보게 만드는 설계, 그것이 진정한 에이전트 최적화의 시작입니다.

참고 자료 (References)

1. [github.com] awesome-agent-skills: Tutorials, Guides and … — https://github.com/heilcheng/awesome-agent-skills 2. [geminicli.com] Agent Skills – Gemini CLI — https://geminicli.com/docs/cli/skills 3. [github.com] gemini-cli/docs/cli/creating-skills.md — https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/creating-skills.md 4. [levelup.gitconnected.com] MCP vs CLI: Stop Over-Engineering Your AI Agent Tooling — https://levelup.gitconnected.com/mcp-vs-cli-stop-over-engineering-your-ai-agent-tooling-1860023c567b

FAQ

GEMINI.md와 에이전트 스킬의 차이점은 무엇인가요?

GEMINI.md는 워크스페이스 전체에 적용되는 상시 배경 지식(오리엔테이션 자료와 같은 기본 상식)을 제공하는 반면, 스킬은 특정 작업이 필요할 때만 호출되어 주입되는 온디맨드 전문 지식입니다.

Gemini CLI 스킬은 어떤 단계로 작동하나요?

스킬은 발견(이름과 설명 추출) → 활성화(도구 호출) → 동의(사용자 확인) → 주입(상세 내용 및 권한 추가) → 실행의 5단계 프로세스로 작동합니다.

커스텀 스킬을 설계할 때 주의할 점과 추천 경로는 무엇인가요?

스킬은 지침이 담긴 SKILL.md와 필요한 에셋이 하나의 폴더에 묶인 '자기 완결적 디렉토리' 구조여야 합니다. 경로는 향후 다른 AI 도구와의 호환성을 위해 .agents/skills/를 사용하는 것이 좋습니다.

스킬과 MCP(Model Context Protocol)의 결정적인 차이는 무엇인가요?

스킬은 AI에게 '어떻게 행동해야 하는지'를 알려주는 텍스트 기반의 지침서(레시피)이며, MCP는 외부 데이터베이스 쿼리나 API 호출 등 '실제 동작'을 가능하게 하는 실행 인터페이스입니다.

스킬의 설치 범위(scope)는 어떻게 설정할 수 있나요?

모든 프로젝트에서 범용적으로 사용하려면 –scope user(글로벌 설정)로, 특정 프로젝트 팀원들과만 공유하려면 –scope workspace(로컬 설정)로 설정할 수 있습니다.

정보로부자되세요(정보부자:Infobuza.com)

컨텍스트 윈도우 낭비는 그만, Gemini CLI ‘스킬’로 온디맨드 전문성 구축하기