Gemini CLI Skills: 터미널 에이전트에게 사고하는 법 가르치기

개요 (Overview)

안녕하세요 여러분 👋

Gemini CLI를 한동안 사용해 오셨다면, 이 에이전트가 일반적인 작업에는 뛰어나지만 때로는 특정 워크플로우(workflows)를 위한 가이드가 필요하다는 점을 눈치채셨을 것입니다. 그것이 바로 **Skills (기술)**가 필요한 이유입니다.

Skills는 Gemini CLI에서 가장 과소평가된 기능 중 하나이며, 일단 사용하기 시작하면 이전에는 어떻게 사용했는지 의문이 들 정도일 것입니다. 오늘은 Skills가 무엇인지, 어떻게 만드는지, 그리고 즉시 활용할 수 있는 실제 사례를 안내해 드리겠습니다.

시작해 봅시다! 🤙

시작하기 전 짧은 참고 사항 📢

Google은 6월 18일부터 무료 티어 및 Google One 사용자들을 대상으로 Gemini CLI가 Antigravity CLI로 전환될 것이라고 발표했습니다. 좋은 소식은? Skills는 두 도구 모두에서 동일한 방식으로 작동하므로, 여기서 배우는 모든 내용은 Antigravity CLI에 직접 적용됩니다. 이미 마이그레이션(migration) 기간에 있다면, 머릿속으로 "Gemini CLI"를 "Antigravity CLI"로 바꾸기만 하면 됩니다.

Skills란 무엇인가? 🤔

제너럴리스트(generalist, 다방면의 지식을 가진 사람)와 스페셜리스트(specialist, 전문가)의 차이를 생각해 보세요. 제너럴리스트는 모든 것에 대해 조금씩 알지만 특정 분야에 대한 깊은 전문 지식은 부족합니다. 스페셜리스트는 자신의 도메인(domain)에 대한 깊은 지식을 가지고 있으며, 해당 분야의 문제에 어떻게 접근해야 하는지 정확히 알고 있습니다.

기본적으로 Gemini CLI는 제너럴리스트입니다. 많은 것을 알고 있지만, 여러분의 특정 프로젝트, 팀의 컨벤션(conventions), 또는 배포 파이프라인(deployment pipeline)이 요구하는 정확한 단계는 알지 못합니다.

Skills는 제너럴리스트를 스페셜리스트로 바꿔줍니다.

Skill은 특화된 지침(instructions)과 컨텍스트(context)를 하나의 발견 가능한 능력으로 패키징한 독립된 디렉토리(directory)입니다. 항상 컨텍스트에 로드되는 GEMINI.md 파일과 달리, Skills는 에이전트가 현재 작업과 관련이 있다고 판단할 때만 **온 디맨드(on demand, 필요 시)**로 로드됩니다.

이러한 차이는 매우 중요합니다. 만약 모든 내용을 GEMINI.md에 넣는다면, 대부분의 작업과 관련 없는 정보들로 인해 모델의 컨텍스트 윈도우 (context window)가 금방 포화될 것입니다. Skills는 점진적 공개 (Progressive Disclosure) 방식을 통해 이 문제를 해결합니다. 에이전트는 모든 Skill의 짧은 설명을 확인하고, 실제로 해당 Skill이 필요할 때만 전체 지침을 로드합니다.

그 결과: 컨텍스트를 어지럽히지 않으면서, 적절한 시점에 적절한 지식을 제공합니다.

Skill의 구조 🏗️

Skill은 특정 구조를 가진 폴더일 뿐입니다:

.gemini/skills/
└── my-skill/
    ├── SKILL.md          # 메인 정의 파일 (필수)
...

유일하게 필수적인 파일은 SKILL.md입니다. 그 외의 모든 것은 Skill이 활성화되었을 때 에이전트가 참조할 수 있는 보조 자료입니다.

SKILL.md 파일

이것은 모든 Skill의 핵심입니다. 두 부분으로 구성됩니다: 프론트매터 (frontmatter) 헤더와 지침이 담긴 본문입니다.

---
name: your-skill-name
description: 이 Skill이 하는 일. ...이 필요할 때 사용하세요.
...

프론트매터는 매우 중요합니다. description 필드는 에이전트가 매 세션 시작 시 이 Skill을 로드할지 결정하기 위해 읽는 내용입니다. 이를 명확하고 구체적으로 작성하십시오. 모호한 설명은 Skill이 잘못된 시점에 활성화되거나(또는 전혀 활성화되지 않거나) 하는 원인이 됩니다.

좋은 설명:

"보안 취약점, 성능 문제 및 프로젝트 컨벤션(conventions) 준수 여부에 대해 코드 변경 사항을 검토합니다. PR을 검토하거나 병합 전 코드를 확인할 때 사용하세요."

나쁜 설명:

"코드 리뷰 관련 사항."

Skill을 어디에 두어야 하는가 📁

Gemini CLI는 두 위치에서 Skill을 발견하며, 어떤 것을 사용할지는 범위(scope)에 따라 달라집니다:

프로젝트 Skill (your repo 내의 .gemini/skills/):
이것들은 특정 프로젝트에 종속됩니다. 이를 버전 관리 시스템에 커밋하면 팀 전체가 동일한 특화된 동작을 얻을 수 있습니다. 배포 단계, 프레임워크 컨벤션, 또는 코드베이스 특화 검토 가이드라인과 같은 프로젝트별 워크플로우에 완벽합니다.

Global Skills (홈 디렉토리 내 ~/.gemini/skills/):
이 스킬들은 모든 프로젝트에 걸쳐 작동합니다. 개인적인 워크플로우 (Workflows), 일반적인 코딩 표준 (Coding standards), 또는 어디서나 사용하는 도구에 완벽합니다.

멘탈 모델 (Mental model): 만약 어떤 스킬이 팀과 프로젝트에 유용하다면, 리포지토리 (Repo)에 넣으세요. 만약 개인적인 생산성 (Productivity)을 위한 것이라면, 전역 (Globally)으로 설정하세요.

첫 번째 스킬 만들기: 단계별 가이드 🔧

코드 리뷰 (Code review)를 위한 실용적인 스킬을 만들어 보겠습니다. 전체 과정은 다음과 같습니다:

1단계: 디렉토리 생성

프로젝트 스킬의 경우:

mkdir -p .gemini/skills/code-review

전역 스킬의 경우:

mkdir -p ~/.gemini/skills/code-review

2단계: SKILL.md 작성

.gemini/skills/code-review/SKILL.md 파일을 생성합니다:

---
name: code-review
description: 버그, 보안 문제, 성능 문제 및 스타일 일관성을 위해 코드 변경 사항을 검토합니다. PR을 검토하거나, diff를 확인하거나, 머지 (Merge) 전 코드 품질을 감사할 때 사용하세요.
...

3단계: 스킬 인식 여부 확인

프로젝트 디렉토리에서 Gemini CLI를 시작하고 다음을 실행합니다:

/skills

code-review 스킬이 목록에 표시되어야 합니다. 만약 보이지 않는다면, 디렉토리 구조와 파일 이름을 다시 확인하세요.

4단계: 사용하기

평소처럼 작업하면 됩니다. 코드 리뷰를 요청할 때:

Review the changes in auth.js before I merge this PR

Gemini CLI는 요청을 확인하고, 이를 스킬 설명 (Skill description)과 매칭하며, 전체 SKILL.md를 로드한 뒤 귀하의 체크리스트 (Checklist)를 체계적으로 따릅니다. 스킬을 명시적으로 호출할 필요는 없으며, 자동으로 수행됩니다.

실용적인 예시: Conventional Commits 스킬 📝

제가 모든 프로젝트에서 Conventional Commits 형식을 강제하기 위해 끊임없이 사용하는 또 다른 스킬을 공유하겠습니다.

.gemini/skills/conventional-commits/SKILL.md를 생성합니다:

---
name: conventional-commits
description: Conventional Commits 사양을 따르는 커밋 메시지 (Commit messages)를 생성합니다. git 커밋 메시지를 생성, 검토 또는 제안할 때 사용하세요.
...

이제 Gemini CLI에 커밋 관련 도움을 요청할 때마다:

방금 인증 모듈(authentication module)에 적용한 변경 사항에 대한 커밋 메시지를 작성해줘

에이전트는 해당 스킬을 로드하고, 전체 컨벤션(convention)을 이해하며, 올바른 타입(type), 범위(scope), 그리고 설명 스타일(description style)을 갖춘 적절한 형식의 메시지를 생성합니다.

Skills vs. GEMINI.md: 무엇을 언제 사용할 것인가 🔄

자주 나오는 질문입니다: 무엇을 스킬(Skill)로 만들고, 무엇을 GEMINI.md에 넣어야 할까요?

GEMINI.md를 사용하는 경우:

에이전트가 항상 필요로 하는 정보 (프로젝트 이름, 기술 스택 (tech stack), 폴더 구조)
모든 작업에 적용되는 일반적인 코딩 표준 (coding standards)
절대 누락되어서는 안 되는 중요한 컨텍스트 (context)

스킬(Skill)을 사용하는 경우:

가끔씩만 실행되는 특화된 워크플로우 (배포 (deployments), 코드 리뷰 (code review), 테스트 (testing))
특정 도메인에 대한 깊은 전문 지식 (보안 감사 (security auditing), 접근성 점검 (accessibility checking))
필요하지 않을 때 컨텍스트를 낭비하게 만드는 복잡한 체크리스트
가끔 필요하지만, 필요할 때는 깊이 있는 정보가 필요한 모든 것

판단 기준: 만약 에이전트가 관련 없는 작업에서 이 지식을 사용하여 당신을 짜증 나게 할 것 같다면, 그것은 스킬입니다. 반대로 에이전트가 이 지식을 갖추지 못했을 때 당신이 짜증이 날 것 같다면, 그것은 GEMINI.md에 속해야 합니다.

좋은 스킬을 작성하기 위한 팁 💡

여러 개의 스킬을 만든 후, 실제로 효과가 있었던 방법들은 다음과 같습니다:

좁은 범위의 설명을 작성하세요. 설명은 에이전트가 스킬을 활성화할지 여부를 결정하는 기준입니다. 광범위한 것보다 좁은 범위가 더 좋습니다. "코딩 작업에 사용"보다는 "PR을 리뷰하거나 코드 품질을 확인할 때 사용"이 더 좋습니다.

필요할 때 명시적인 "사용 금지" 힌트를 추가하세요. 스킬이 과도하게 활성화될 가능성이 있다면 명확성을 더하세요: "일반적인 코딩 질문이나 기능 구현에는 사용하지 마세요."

SKILL.md를 집중력 있게 유지하세요. 상세한 예시와 템플릿은 examples/ 또는 resources/ 하위 디렉토리에 두세요. 핵심 SKILL.md는 훑어보기 쉽고 간결해야 합니다.

하나의 스킬에는 하나의 책임만 부여하세요.

활성화 테스트 (Test activation). 스킬을 생성한 후에는 해당 스킬이 활성화되어야 하는 프롬프트와 활성화되지 않아야 하는 프롬프트를 모두 시도해 보세요. 만약 활성화되지 않아야 할 때 활성화된다면, 설명을 더 엄격하게(tighten) 수정하세요.

마치며 🌟

스킬은 적은 투자로 큰 효과를 얻을 수 있는 방법입니다. SKILL.md를 작성하는 데 단 10~15분만 투자하면, 에이전트는 그 시점부터 당신의 정확한 워크플로우 (workflow)를 일관되게 따르게 됩니다.

더 큰 관점에서 보자면, 스킬은 Gemini CLI (또는 Antigravity CLI)를 일반적인 AI 어시스턴트에서 당신의 팀, 관례(conventions), 그리고 프로세스(processes)를 이해하는 도구로 변모시키는 방법입니다. 더 많은 스킬을 구축할수록, 에이전트는 단순한 도구가 아닌 팀원처럼 느껴질 것입니다.

코드 리뷰 스킬이나 커밋 메시지 스킬처럼 작은 것부터 시작하여 점차 확장해 나가세요. 에이전트가 당신이 무엇을 필요로 하는지 "그냥 아는" 순간들을 빠르게 발견하게 될 것이며, 바로 그때 모든 것이 맞아떨어지는 경험을 하게 될 것입니다.

즐거운 코딩 되세요! ✨

안녕하세요 👋🏻
제 이름은 Domenico이며, 오픈 소스 (Open Source)에 열정을 가진 소프트웨어 개발자입니다. 지식과 경험을 공유하기 위해 관련 글을 작성하고 있습니다.
제 링크들을 확인하시려면 Linktree를 방문해 주시고, 저의 오픈 소스 프로젝트들을 확인하시려면 Domenico Tenace Open Labs를 확인해 주세요! 🫰🏻

🌲 Linktree: https://linktr.ee/domenicotenace
🐙 Domenico Tenace Open Labs: https://github.com/Domenico-Tenace-Open-Labs

더 많은 글을 보시려면 dev.to에서 저를 팔로우해 주세요 👇

[

](/dvalin99)

]

Domenico Tenace 팔로우

제 콘텐츠가 마음에 들거나 제 작업을 지원하고 싶으시다면, 소액의 기부로 저를 후원하실 수 있습니다. 정말 감사하겠습니다 🥹