공식 레퍼런스: Sub-agents · Skills · CLI Commands · Extensions 개요
학습 경로
- Gemini CLI 시작하기 — 설치, 인증, 메모리 기초
- 100만 토큰의 장점 — 전체 코드베이스로 작업하기 — 저장소 단위 분석을 낭비 없이
- Gemini Extensions & MCP — 커스텀 워크플로 만들기 — 명령, MCP, 스킬 패키징
- Gemini CLI MCP 연동 — 외부 도구와 데이터 연결하기
- Trusted Folders, Sandboxing, 그리고 Restore — 신뢰, 격리, 복구
- Gemini Task Decomposition — 복잡한 작업을 성공적으로 완수하기
- Gemini CLI Headless Automation — 스크립트, CI, 구조화 출력
- Gemini Git Worktrees — 병렬 작업 최적화
- 서브 에이전트와 스킬 오케스트레이션 — 위임과 전문가 워크플로 ← 현재 문서
- GEMINI.md Mastery — 계층적 컨텍스트 설계
- Gemini 첫날 안전 루프
- Multi-Agent Orchestration — 서브 에이전트와 스킬 조합
- Gemini 주간 단위 딜리버리 플레이북
- Gemini GitHub Actions — CI 자동화와 리뷰
- Gemini 고위험 변경 통제 모델
- Gemini Effective Prompting — 100만 토큰을 지배하는 프롬프팅
- Gemini 운영 매뉴얼 — 팀 단위 CLI 딜리버리 리듬
- Gemini Hooks Automation — 로컬 자동화의 방패
- Gemini 사고 복구 플레이북
- Mid-size Refactor Playbook — 중규모 리팩터링
- Gemini 사고 후 하드닝 루프
- Gemini 카오스 복원력 드릴
- Human-Agent Handoffs — 인간과 AI의 릴레이
- Ralph Persistence Loops — 끝까지 물고 늘어지는 자가 치유
- Gemini 복원력 지표와 SLO
- Release Readiness Automation — 배포 자동화
- ADR Automation — 아키텍처 결정 기록 자동화
이 문서에서 참고한 공식 문서
- 내장 / 커스텀 sub-agent 모델 — Sub-agents
- skills 발견 계층, 활성화, 작성 원리 — Skills
- extension이 전문가 워크플로를 배포하는 방식 — Extensions 개요
Gemini는 메인 스레드에서 모든 걸 다 할 때보다, 덜 할 때 더 강해진다
연구, 탐색, 구현, 리뷰, 정리까지 전부 메인 대화 하나에서 처리하고 싶은 유혹이 있습니다. 작은 작업에서는 괜찮지만, 큰 작업으로 갈수록 이 방식은 비효율적입니다.
Gemini CLI를 제대로 쓰려면 두 개념을 분리해서 봐야 합니다.
- Sub-agent는 내 대신 일을 해 주는 작업자
- Skill은 현재 에이전트의 행동 규칙을 바꾸는 전문가 모드
이 차이를 이해하면 오케스트레이션이 훨씬 명확해집니다.
sub-agent는 "시끄러운 작업"을 메인 이력 밖으로 밀어낸다
sub-agent가 유용한 경우는 보통 셋 중 하나입니다.
- 범위가 넓다
- 반복이 많다
- 메인 컨텍스트를 지나치게 소모할 가능성이 크다
공식 문서의 built-in sub-agent 목록만 봐도 의도가 보입니다.
codebase_investigator— 넓은 아키텍처 탐색, 원인 분석- general-purpose / generalist 계열 — 반복적이고 시끄러운 대량 작업
- CLI help 계열 — Gemini 사용법 자체를 조사할 때
- browser 계열 — 로컬 파일이 아니라 웹 인터랙션이 필요할 때
즉 sub-agent는 “이 noisy한 탐색은 밖에서 끝내고, 요약만 가져와”라는 요청에 가깝습니다.
skill은 "일꾼 추가"가 아니라 "두뇌 포맷 변경"이다
skill은 별도 작업자를 만드는 것이 아니라, 현재 에이전트가 따라야 할 절차와 판단 기준을 바꿉니다.
그래서 skill은 이런 작업에 특히 잘 맞습니다.
- 코드 리뷰
- 보안 리뷰
- 마이그레이션 체크리스트 실행
- release 준비
- 사내 규정 준수 점검
sub-agent가 계약직 전문가라면, skill은 현재 에이전트에게 새로운 직업 윤리를 입히는 것에 가깝습니다.
언제 sub-agent를 쓰고, 언제 skill을 켤까
| 상황 | sub-agent | skill |
|---|---|---|
| 작업이 넓고 시끄럽다 | 적합 | 경우에 따라 |
| 더 엄격한 절차가 필요하다 | 경우에 따라 | 적합 |
| 메인 컨텍스트를 아끼고 싶다 | 적합 | 아님 |
| 현재 에이전트가 전문 체크리스트를 따르길 원한다 | 아님 | 적합 |
실전에서는 둘을 같이 쓰는 경우가 많습니다.
- discovery는 sub-agent에 위임하고
- 구현이나 리뷰 단계에서 skill을 활성화하는 방식입니다.
실전 오케스트레이션 패턴
1) 큰 저장소 조사
- Plan Mode로 시작
codebase_investigator에게 구조 파악 위임- 리스크와 영향 범위를 요약
- 변경 경계가 명확해졌을 때만 기본 모드로 복귀
2) 반복 정리 작업
- 대량 수정은 worker 성격의 sub-agent에 맡기고
- 메인 세션은 diff 검토와 우선순위 판단에 집중
3) 전문 리뷰
- 작업은 메인 세션에 유지
code-review나 커스텀 skill을 활성화- 결과는 일정한 형식으로 보고하게 설계
핵심은 noisy search는 밖으로 보내고, 판단이 중요한 리뷰는 가까이에 두는 것입니다.
skill 발견 계층은 팀 운영 모델을 만들 수 있게 해 준다
공식 문서는 skills가 여러 계층에서 발견된다고 설명합니다. user-level, workspace-level, extension-provided, built-in처럼 출처가 나뉘기 때문에 팀은 “어디에 어떤 전문성을 둘지”를 설계할 수 있습니다.
예를 들어:
- user-level — 개인 습관
- workspace-level — 저장소 공통 규칙
- extension-level — 팀 배포용 전문가 워크플로
- built-in — 일반적인 고급 절차
이 구조는 Gemini CLI의 숨은 강점입니다. ad-hoc prompt 문화에서 벗어나, 문서화된 운영 모델로 진화할 수 있게 해 주기 때문입니다.
커스텀 skill은 체크리스트가 안정됐을 때만 만들자
모든 영리한 프롬프트를 skill로 만들 필요는 없습니다. 아래 조건을 만족할 때가 좋습니다.
- 자주 반복된다
- 사람마다 빠뜨리기 쉽다
- 일관되지 않으면 리스크가 생긴다
- 실행 후 검증이 가능하다
좋은 예:
- locale parity 감사
- release 체크리스트 강제
- API contract review
- localization QA
- 문서 배포 전 점검
나쁜 skill은 막연하고 추상적입니다. 좋은 skill은 done condition이 반복 가능하게 정의돼 있습니다.
AI Native Notes에 적용하면 이런 그림이 나온다
이 저장소라면 오케스트레이션을 대략 이렇게 가져갈 수 있습니다.
- 아키텍처 질문이 생기면
codebase_investigator가 routing, i18n, content loading을 먼저 맵핑 locale-review같은 커스텀 skill이ko / en / es패리티를 점검content-releaseskill이 배포 전 업데이트 요약, broken link, metadata를 다시 확인
이 조합이면 메인 세션은 전략과 판단에 집중하고, 지루한 검증은 재사용 가능한 전문가 경로로 밀어낼 수 있습니다.
가장 흔한 실패는 "보여주기식 오케스트레이션"이다
sub-agent와 skill이 재미있다고 해서 남발하면 오히려 느려집니다.
위험 신호는 이렇습니다.
- 사소한 작업에도 sub-agent를 띄운다
- 검증 로직 없는 긴 프롬프트를 그냥 skill이라 부른다
- 메인 스레드가 즉시 알아야 하는 작업까지 밖으로 보낸다
- 사실
GEMINI.md한 줄이면 되는 규칙에 자산 다섯 개를 만든다
오케스트레이션은 소음을 줄여야지, 의식을 늘리면 안 됩니다.
다음에 읽으면 좋은 글
- 복잡한 팀 워크플로 설계는 Multi-Agent Orchestration
- CI 환경에서의 자동화 리뷰는 Gemini GitHub Actions
- 반복 가능한 전문가 행동을 패키징하는 법은 Gemini Extensions & MCP