Gemini CLI Skills 도입 및 사용법: SKILL.md 템플릿과 베스트 프랙티스

Gemini CLI의 “Skills(Agent Skills)”는 무엇인가요?
Gemini CLI의 Skills는 “자주 반복되는 작업/전문 도메인 지식/운영 절차”를 재사용 가능한 지침(Instruction) 패키지로 만들어, CLI 에이전트가 상황에 맞게 호출·적용하도록 하는 실험적(Experimental) 기능입니다. Skills는 구조화된 마크다운 파일로 정의되며, YAML 프론트매터에 name, description 같은 메타데이터를 두고 본문에 실제 수행 지침을 작성하는 형태입니다. 

실험 기능 활성화

아래처럼 .gemini/settings.json에 실험 기능 플래그를 켜서 사용할 수 있습니다.

{
  "experimental": {
    "skills": true
  }
}

참고로 Gemini CLI 설정 파일은 여러 레벨(예: 사용자 전역 ~/.gemini/settings.json)로 둘 수 있습니다.

Skills의 구성 방식(파일/구조/로드 개념)

핵심 구조

• Skill은 “하나의 폴더” + 그 안의 SKILL.md로 구성됩니다.
• CLI 시작 시(또는 리로드 시) Skills를 발견(discover) → 메모리 로드 → 활성/비활성 상태를 설정으로 관리하는 형태로 설계되어 있습니다.

📝 SKILL.md의 일반 형태(예시 템플릿)
(공식 문서가 GitHub UI 제약으로 본문을 그대로 인용하긴 어렵고, 아래는 공개 설명(설계 요약)에 맞춘 실무 템플릿 예시입니다. 필드명은 구현/버전에 따라 달라질 수 있어요.)

---
name: log-triage
description: 보안 로그를 빠르게 분류하고 IOC/의심행위를 요약합니다.
---

# 목적
- 운영 중 유입되는 로그를 신속히 요약/분류하여 초동 대응 품질을 높인다.

# 입력(사용자가 주는 것)
- 로그 원문(또는 파일 경로)
- 시간 범위/서비스/호스트/사용자 식별자(가능한 경우)

# 절차
1) 로그에서 시간축/주체(IP, 계정, host)/행위(URI, 프로세스, 쿼리)를 추출
2) 실패/에러/권한거부/비정상 빈도/새로운 User-Agent 등 의심패턴 체크
3) IOC 후보(IP/도메인/해시)가 있으면 표로 정리
4) “추가 확인 질문 3개”와 “즉시 차단/완화 옵션”을 제시

# 출력 형식
- 5줄 요약
- IOC 표
- 위험도(상/중/하) + 근거
- 다음 액션(차단, 관찰, 티켓 발행 등)

Skills는 “Custom Commands / GEMINI.md / Tools(MCP 포함)”와 뭐가 달라요?

혼동이 가장 많은 부분이라, 운영 관점으로 정리해볼게요.

1. GEMINI.md(메모리/규칙)

• 프로젝트/디렉터리별 “상시 적용되는” 지침을 적어두는 방식입니다.
• CLI에는 메모리 관리 명령(/memory ...)도 있고, 어떤 GEMINI.md가 로드되었는지 확인/리프레시가 가능합니다.

2. Custom Commands(슬래시 커맨드 단축키)

• 반복 프롬프트를 “내 명령어”로 만드는 기능입니다.

3. Tools(로컬 파일/쉘/웹 fetch 등) & MCP 서버

• 모델이 실제 행동을 하도록 “기능”을 제공하는 영역입니다. Gemini CLI는 파일 시스템 작업, 쉘 실행, 웹 fetch 같은 내장 도구를 갖고, MCP로 확장합니다.

4. Skills(Agent Skills)

• “특정 도메인/업무의 전문 절차”를 재사용 가능한 패키지로 만들어, 상황에 맞춰 적용되도록 한다는 점이 포인트입니다.

관리/명령 체계는 어떻게 되나요?

현재 Skills는 “실험 기능”이고, 관리용 gemini skills 같은 상위 커맨드를 넣는 작업이 진행 이슈로 잡혀 있습니다. (즉, 버전에 따라 UX가 바뀔 수 있습니다)
또한 Skills 문서/튜토리얼을 더 보강하려는 문서화 이슈도 별도로 트래킹되고 있어, 지금은 ‘진행형 기능’이라고 보는 게 안전합니다.

300x250

실무적으로는

• Skills 폴더/파일을 준비하고
• CLI를 재시작(또는 기능이 제공되면 reload)해서 반영
  하는 흐름이 일반적입니다. (Skills를 공유하기 위해 ~/.claude/skills 등을 심볼릭 링크로 연결하는 커뮤니티 예시도 있습니다. 다만 이건 서드파티 패턴이므로 조직 표준으로 채택할 땐 내부 검증을 권장드립니다.)

구체 예시 3가지

“IR 초동대응(티켓 템플릿 자동화)” Skill

목적: 사건 발생 시 “누락 없는 질문/증적/조치”를 자동으로 밀어주기

• 입력: 알람 내용(탐지 룰명/호스트/계정/타임라인), 관련 로그 파일 경로
• 출력
  • 사건 요약(5줄)
  • 증적 체크리스트(로그/프로세스/네트워크/계정)
  • 즉시조치(차단/격리/권한회수)
  • 커뮤니케이션 템플릿(내부 공지/협업 요청 문구)

프롬프트 사용 예(개념)

@alerts/2026-01-09-sev.txt 이 알람을 기준으로 IR 초동대응 플랜과 티켓 템플릿을 만들어줘.

@...는 파일/디렉터리 내용을 프롬프트에 주입하는 CLI 기능입니다.

“로그 요약 + IOC 테이블화 + 차단 후보 추출” Skill

목적: 대량 로그에서 사람 눈으로 보기 전에 “정리된 표”를 먼저 얻기

• 규칙 예
  • 새로 등장한 외부 IP/ASN/국가
  • 인증 실패 폭증
  • 특정 URI/파라미터 반복
  • 프로세스 트리 상의 수상한 실행(EDR 로그라면)

“보안 점검(구성/권한/네트워크) 체크리스트 실행” Skill

목적: 점검 항목을 표준화하고, 결과를 동일 포맷으로 남기기

• 예: “서버 계정/권한 점검”, “쿠버네티스 RBAC 점검”, “Nginx/WAF 설정 점검” 등
• 출력
  • PASS/FAIL/NA
  • 근거(어떤 설정/로그 라인에서 판단했는지)
  • 개선 권고(우선순위/리스크/대안)

보안 관점 가이드 & 점검 포인트

Gemini CLI는 로컬 파일 접근/쉘 실행 등 “행동 가능한 도구”를 포함합니다.
따라서 Skills를 도입하면 에이전트가 더 ‘잘’ 움직이는 만큼, 위험도 같이 커질 수 있어요.

“신뢰 경계(Trusted / Untrusted)”를 먼저 정하세요

• 신뢰된 레포/디렉터리에서만 Skills 사용
• 외부에서 받은 PoC/샘플 코드/압축 해제 폴더는 격리 환경에서만 실행
• “프로덕션 키/토큰/인증서”가 있는 경로는 기본적으로 접근 금지

Sandbox 실행을 기본값으로 권장

Gemini CLI는 보안/격리를 위해 컨테이너 기반 샌드박스 실행 옵션을 공식적으로 안내합니다.

• 운영 정책 예: “업무용 표준은 샌드박스 모드만 허용, 로컬 직접 실행은 예외 승인”

“자동 실행/허용 목록(allowlist)” 류는 특히 경계

과거 Gemini CLI에서 허용된 명령이 악용되어 코드 실행/정보 유출로 이어질 수 있는 취약점이 보고된 바 있습니다.

• CLI 버전 최신 유지
• Skills 작성 시 “자동으로 쉘 명령을 실행” 같은 패턴은 금지
• 실행 전 사용자 확인(대화형 승인)을 강제하는 운영 규칙 권장

Skills 자체에 대한 보안 리뷰 체크리스트

• Skill이 어떤 입력을 받는지(파일/경로/환경변수/네트워크)
• Skill이 어떤 출력/행동을 유도하는지(파일 수정, 명령 실행, 외부 전송)
• “비밀정보 다루지 말 것” 같은 금지 규칙이 본문에 명시되어 있는지
• 로그/결과물에 개인정보/접근토큰이 포함되지 않게 마스킹 규칙이 있는지
• Skill 배포/변경 관리(코드리뷰, 서명/해시, 승인자) 체계가 있는지

운영에 바로 쓰는 “도입 로드맵”

1. PoC(로컬/샌드박스): 개인용 Skills 몇 개로 효과 검증
2. 팀 공용 Skills 레포: “IR/점검/로그분석” 3종만 먼저 표준화
3. 보안 가드레일: 샌드박스 강제 + 신뢰 폴더 정책 + 변경관리
4. 품질 관리: Skill별 출력 포맷 표준 + 케이스 기반 리그레션 테스트(샘플 로그 세트)