에이전트 스킬이란 무엇인가 — 공식 정의부터

Gemini CLI 에이전트 스킬(Agent Skills)은 AI 에이전트에게 특정 전문 지식과 절차를 “on-demand”로 주입할 수 있는 폴더 단위 모듈입니다. 공식 오픈 표준 사이트(agentskills.io)에서 정의하는 방식으로 보면, 스킬은 지침(SKILL.md), 스크립트, 참조 자료를 하나의 폴더에 묶어 에이전트가 필요할 때 꺼내 쓰도록 한 구조입니다.

이게 기존의 GEMINI.md 컨텍스트 파일과 다른 핵심적인 차이가 하나 있습니다. GEMINI.md는 세션 시작부터 전체 내용이 컨텍스트 창에 올라가지만, 스킬은 에이전트가 관련 작업을 감지했을 때만 activate_skill 도구를 호출해 로드합니다. (출처: Gemini CLI 공식 문서)

즉, 이론상 스킬은 컨텍스트 창을 아끼면서도 전문 지식을 쓸 수 있는 구조입니다. 문제는 “에이전트가 필요하다고 인식할 때만”이라는 조건이 붙는다는 점인데, 이게 실제로 어떤 결과를 낳는지는 섹션 4에서 수치로 확인해봅니다.

▲ 목차로 돌아가기

설치 방법 3가지 — 명령어 그대로 따라하기

스킬을 가져오는 방법은 크게 세 가지입니다. 아래 명령어는 Gemini CLI 공식 문서(geminicli.com/docs/cli/skills)에 그대로 나와 있습니다.

① Git 저장소에서 직접 설치

gemini skills install https://github.com/user/repo.git

기본 설치 범위는 사용자 홈(~/.gemini/skills/)입니다. 모든 프로젝트에서 공통으로 쓸 스킬에 적합합니다.

② 로컬 폴더를 워크스페이스 범위로 연결

gemini skills link /path/to/my-skills-repo --scope workspace

팀 단위로 공유하는 스킬은 --scope workspace 옵션을 붙이면 프로젝트 루트의 .gemini/skills/에 심링크로 연결됩니다. 버전 관리 시스템(Git)에 같이 커밋해두면 팀원 전체가 동일한 스킬 환경을 씁니다.

③ 인터랙티브 세션 내에서 관리

/skills list       # 현재 발견된 스킬 전체 목록
/skills enable 스킬명   # 비활성화된 스킬 재활성화
/skills disable 스킬명  # 특정 스킬 일시 비활성화
/skills reload     # 디스커버리 캐시 새로고침

Gemini CLI 안에서 /skills 명령어로 바로 확인할 수 있습니다. 설치 직후 스킬이 안 보인다면 /skills reload를 먼저 실행하는 것이 빠릅니다.

▲ 목차로 돌아가기

SKILL.md 직접 만드는 법 — 최소 구조만 이해하면 끝

스킬의 핵심은 SKILL.md 파일 하나입니다. Agent Skill 스펙(agentskills.io/specification)에 따르면, YAML 프론트매터에 name과 description 두 가지만 있으면 유효한 스킬이 됩니다. 나머지 본문은 에이전트가 실행할 절차를 Markdown으로 기술합니다.

---
name: code-reviewer
description: >
코드 리뷰를 수행할 때 사용하는 스킬. 사용자가 PR 번호나
로컬 변경사항 검토를 요청하면 자동으로 활성화됩니다.
# Code Reviewer
## 워크플로
1. PR 번호나 로컬 diff를 먼저 확인합니다.
2. 보안 취약점 · 성능 · 가독성 순으로 검토합니다.
3. 각 항목에 Before/After 코드 예시를 포함합니다.

폴더 구조는 아래처럼 단순합니다. scripts/·references/·assets/는 선택 사항이고, 필요에 따라 스크립트나 참조 파일을 넣으면 됩니다.

code-reviewer/
├── SKILL.md          # 필수
├── scripts/          # 선택: 실행 스크립트
├── references/       # 선택: 참조 문서
└── assets/           # 선택: 템플릿 등

Gemini CLI에는 skill-creator라는 내장 스킬도 있어서 “create a new skill called code-reviewer”처럼 자연어로 요청하면 스킬 폴더 전체를 자동으로 생성해줍니다. (출처: Gemini CLI 공식 문서)

여기서 description 필드가 생각보다 훨씬 중요합니다. 에이전트가 스킬을 발동시킬지 판단할 때 이 설명만 보고 결정하기 때문입니다. “코드 관련 작업에 쓰세요”처럼 막연하게 쓰면 에이전트가 정작 필요할 때 스킬을 불러오지 않는 상황이 생깁니다.

▲ 목차로 돌아가기

스킬만 깔면 된다는 생각이 문제인 이유

Vercel이 2026년 1월에 발표한 에이전트 평가 연구(출처: vercel.com, 2026.01.27)에서 확인된 수치입니다. Next.js 16의 신규 API를 에이전트가 올바르게 처리하는지를 기준으로 측정했습니다.

스킬을 설치했는데도 기준값과 동일한 53%에 머문 이유는 단순합니다. 에이전트가 56%의 경우에서 스킬을 아예 불러오지 않았기 때문입니다. 스킬이 있다는 것은 알지만, 지금 이 작업에 그 스킬이 필요하다는 판단을 에이전트 스스로 내리지 못했습니다.

Vercel은 이 결과를 바탕으로 AGENTS.md에 8KB로 압축한 독스 인덱스를 삽입하는 방식을 택했고, 같은 테스트에서 100% 통과율을 기록했습니다. 컨텍스트 창이 넉넉한 Gemini 3.1 Pro(200만 토큰) 기준이라 8KB는 전체의 0.4%도 안 됩니다. 스킬의 “on-demand 로드”라는 장점보다 “항상 꺼내놓기”의 확실성이 현재 모델에서는 더 강했습니다.

▲ 목차로 돌아가기

GEMINI.md와 SKILL.md, 무엇을 어디에 쓸 것인가

Google 공식 개발자 포럼에서 나온 구분 기준(출처: Google AI 개발자 포럼, 2026.03.16)을 실제 사용 패턴과 함께 정리하면 다음과 같습니다.

Google 포럼의 요약 문장을 그대로 빌리면, GEMINI.md는 “누구인지, 어떻게 일하는지”를 정의하고 SKILL.md는 “특정 도구를 어떻게 쓰는지”를 담습니다. 모노레포처럼 서브 프로젝트가 많은 환경에서는 스킬이 더 적합한데, 각 서브 프로젝트에 맞는 스킬을 워크스페이스 범위로 따로 두면 됩니다.

▲ 목차로 돌아가기

Claude, Cursor에서도 그대로 쓸 수 있는 이유

에이전트 스킬 포맷을 처음 제안한 곳은 Anthropic입니다. Anthropic이 SKILL.md 명세를 오픈 표준으로 공개했고, 이후 Google Gemini CLI, GitHub Copilot, Cursor가 이 표준을 채택했습니다. (출처: agentskills.io 공식 페이지)

Gemini CLI 공식 문서에서는 이 호환성을 명시적으로 인정합니다. “Agent Skills는 오픈 포맷이기 때문에 Gemini CLI, Claude Code, GitHub Copilot, Cursor에서 모두 동작한다”고 적혀 있습니다. (출처: Google Cloud Medium 블로그, Daniel Strebel, 2026.02.02)

단, 각 도구마다 스킬 파일을 찾는 기본 경로가 다릅니다. Gemini CLI는 .gemini/skills/와 .agents/skills/를 동시에 인식하고, Claude Code는 .claude/skills/를 씁니다. 공통으로 쓸 스킬은 .agents/skills/에 두고 각 도구별 경로에서 심링크로 연결하는 방식이 실무에서 많이 쓰입니다.

▲ 목차로 돌아가기

Q&A 5가지

▲ 목차로 돌아가기

마치며

Gemini CLI 에이전트 스킬은 구조 자체는 단순합니다. SKILL.md 파일 하나에 이름과 설명, 절차를 적으면 끝입니다. 그런데 막상 쓰다 보면 “분명히 설치했는데 왜 에이전트가 쓰지 않지?”라는 상황을 자주 만납니다.

Vercel의 데이터가 그 이유를 수치로 설명해줬습니다. 기본 상태에서 스킬 발동 실패율 56%는 현재 LLM의 구조적 한계이고, GEMINI.md에 스킬 경로와 실행 순서 지시문을 넣는 것이 현재 가장 확실한 보완책입니다. 스킬을 “설치하면 알아서 쓰는 자동 모듈”로 이해하면 기대와 결과 사이에 간격이 생깁니다. “에이전트에게 올바른 절차를 주입하는 레시피 카드”로 보면, 무엇을 어떻게 준비해야 할지가 더 명확해집니다.

스킬 생태계 자체는 빠르게 성장 중입니다. skills.sh에서 커뮤니티가 공유한 스킬을 바로 설치해볼 수 있고, Google의 Gemini CLI 확장 갤러리에도 스킬 번들 확장이 계속 추가되고 있습니다.

▲ 목차로 돌아가기

본 포스팅 참고 자료

1. Gemini CLI 공식 문서 — Agent Skills
2. Agent Skills 오픈 표준 공식 사이트 (agentskills.io)
3. Vercel 에이전트 평가 연구 — AGENTS.md vs Skills (2026.01.27)
4. Google Cloud Medium — Beyond Prompt Engineering: Using Agent Skills (2026.02.02)
5. Google Codelabs — Gemini CLI Agent Skills 사용 방법
6. Google AI 개발자 포럼 — GEMINI.md vs Skills 모범 사례 (2026.03.16)