핵심 요약
- 커스텀 에이전트는 마크다운 파일 하나입니다: YAML 프론트매터(name, description, model, tools)에 시스템 프롬프트 본문 — 반복되는 전문가를 한 번만 저장하면 매 세션마다 다시 설명할 필요가 없습니다.
- 워크스페이스 에이전트는 .agents/agents/<이름>.md에 두고 저장소와 함께 배포합니다. 개인용은 ~/.gemini/config/agents/에 두면 머신의 모든 프로젝트에 적용됩니다.
- tools는 Antigravity의 실제 도구 이름만 받습니다 — view_file, grep_search, list_dir — 잘못된 이름이면 시작 시 실패합니다. subagent: true는 위임 가능하게, mainAgent: true는 입력 선택기에 나타나게 합니다.
- IDE 선택기에서 "What are your tools?"로 스모크 테스트하고, 메인 채팅에서 위임하거나, CLI에서 /agents와 Alt+J로 점검 — 이후 규칙·워크플로·스킬을 층층이 더하세요.
Google Antigravity Livestream: Remote Control and Custom Agents
채널:Google Antigravity47:43
Antigravity Customization Features That 10X Your Coding Speed
채널:Code A Program11:02
Defining Custom Subagents (.md) — Antigravity Docs
공식 문서:antigravity.googleDocs
스크린샷은 Code A Program의 화면 녹화에서 추출한 정지 화면입니다(위에서 표기). 커스텀 에이전트 파일 작성 흐름 자체는 Google 공식 라이브 스트림과 Antigravity subagents 문서를 기준으로 정리했습니다 — 이 흐름을 다룬 깨끗한 제3자 녹화는 아직 없습니다.
사실 확인에 Use AI with Tech Dad와 AI with Surya의 커스텀 에이전트 해설 영상도 참고했습니다. 모든 상표는 Google에 귀속되며, 이 튜토리얼은 Google과 제휴되지 않은 독립 콘텐츠입니다.
빈 폴더에서 믿을 수 있는 전문가까지
1 · 전문가의 범위 정하기
- 1
저장할 가치가 있는 역할 찾기
같은 작업이 반복된다면 커스텀 에이전트의 파일을 만들 자리입니다: 고정 체크리스트를 가진 코드 리뷰어, 의존성 업데이트 담당, 테스트 실행 담당, 문서 관리 담당. 지시 사항이 안정적이고, 범용 어시스턴트와 뚜렷이 다르며, 도구 상자를 미리 열거할 수 있다면 역할을 저장하세요. 일회성 요청은 평범한 프롬프트로 충분합니다.
- 2
서브에이전트·스킬과의 차이 알기
서브에이전트는 '일하는 자리'입니다: 메인 에이전트가 작업을 위임하는 세션이죠. 커스텀 에이전트는 그 자리에 앉을 수 있는 저장된 프로필이며, 직접 대화할 수도 있습니다. 스킬은 또 다른 층으로, 어떤 에이전트든 가져다 쓸 작업 지식을 패키징하는 반면 커스텀 에이전트는 핵심 지시와 도구 접근을 바꿉니다. 일회용 작업자에게는 파일이 필요 없습니다 — Antigravity는 세션 중 define_subagent 도구로 임시 서브에이전트를 만들 수 있습니다.
- 3
범위 선택: 저장소 아니면 머신
Antigravity는 세 곳에서 커스텀 에이전트 .md 파일을 발견합니다. 워크스페이스 설정은 .agents/agents/<이름>.md(또는 .agents/agents/<이름>/agent.md)에 두고 저장소와 함께 이동 — 팀 규칙에 적합합니다. 전역 설정은 ~/.gemini/config/agents/<이름>.md에 두면 머신의 모든 프로젝트에 적용 — 개인 전문가용입니다. 플러그인은 plugins/<플러그인명>/agents/ 아래에 에이전트를 포함할 수 있습니다.
Antigravity 문서의 Rules 페이지: 전역 규칙은 ~/.gemini/GEMINI.md에 두어 모든 워크스페이스에 적용하고, 워크스페이스 규칙은 .agents 폴더에 둡니다 — 커스텀 에이전트 파일도 같은 구분을 따릅니다.영상 0:30 지점
2 · 에이전트 파일 작성하기
- 4
에이전트 파일 만들기
프로젝트 안에서 폴더와 파일을 한 번에 만드세요 — 파일명이나 폴더명이 에이전트의 식별자가 되므로 소문자와 하이픈으로: .agents/agents/codereviewer/agent.md. Antigravity 에이전트에게 시켜도 됩니다: 공식 워크스루에서는 "I have an idea for a custom agent" 한마디로 전체 경로 undefined/.agents/agents/codereviewer/agent.md와 바로 편집 가능한 정의를 돌려받았습니다.
- 5
YAML 프론트매터 채우기
프론트매터는 전문가의 신원과 경계를 선언합니다. name은 고유해야 합니다 — 멘션할 때 쓰는 이름입니다. description은 Antigravity에게 언제 이 전문가를 부를지 알려주므로 채용 공고처럼 쓰세요. model: inherit은 부모의 모델 등급을 유지하고, tools는 이 역할이 쓸 수 있는 것을 정확히 나열합니다. 자격 플래그 두 개로 마무리: subagent는 기본 true(위임 가능), mainAgent는 기본 false(true로 바꾸면 입력 선택기에서 바로 선택 가능).
- 6
시스템 프롬프트 본문 쓰기
프론트매터 구분선 아래의 모든 내용이 에이전트의 시스템 지시가 됩니다. 공식 예제는 페르소나로 시작하고("You are an expert, meticulous Code Reviewer"), 핵심 책임 — 정확성, 보안, 성능, 스타일 — 을 나열한 뒤 엄격한 출력 형식으로 끝납니다: Summary 판정, 줄 번호가 있는 차단급 Critical findings, 그리고 비차단 Suggestions. 안정적인 보고 형식이 전문가의 결과를 신뢰하게 만듭니다.
---
name: codereviewer
description: >-
Code review specialist that analyzes diffs, inspects code for bugs,
architectural issues, performance bottlenecks, and style compliance.
model: inherit
tools:
- view_file
- grep_search
- list_dir
subagent: true
---
# Code Reviewer Persona & Instructions
You are an expert, meticulous Code Reviewer. Inspect proposed changes,
pull requests, and codebase files for correctness, security, performance,
and style.
## Review Output Format
- **Summary**: high-level assessment (LGTM / Changes Requested)
- **Critical findings**: blocking issues with line references and fixes
- **Suggestions & Improvements**: non-blocking refactors3 · 확장하고 제한하기
- 7
실제 도구 이름으로 도구 상자 한정하기
tools 프론트매터는 명시적 허용 목록을 받으며, 이름은 Antigravity의 실제 도구와 일치해야 합니다. 공식 워크스루에서 생성된 파일은 read를 나열했다가 — "Agent execution terminated due to error"로 즉사하고 view_file로 고쳐진 후에야 살아났습니다. view_file, grep_search, list_dir 같은 실제 이름만 쓰고, 역할에 필요한 최소한만 주세요. 리뷰어에게 쓰기 권한은 거의 필요 없습니다.
에이전트가 호출할 수 있는 도구 이름을 나열한 워크스페이스 설정 파일 — view_file, grep_search, read_file — 커스텀 에이전트의 tools 목록이 기대하는 어휘 그 자체입니다.영상 4:44 지점 - 8
언제 움직이는지 정하기
subagent: true(기본값)이면 전문가를 위임할 수 있습니다: 메인 에이전트에게 작업을 설명하면 경계가 분명한 과업이 전문가에게 넘어가고, 보고서가 메인 대화로 돌아옵니다. 위임된 서브에이전트는 부모의 권한 경계를 상속합니다 — 명령 허용 범위, 파일 스코프, 샌드박스 설정 — 사용자 승인이 필요한 요청은 메인 인터페이스로 올라옵니다. mainAgent도 true로 바꾸면 입력 선택기에도 나타나 직접 대화할 수 있습니다.
- 9
Customizations 열고 규칙 이름 짓기
하우스 룰을 더하면 커스텀 에이전트가 빠르게 똑똑해집니다. IDE에서 에이전트 패널 상단의 "..." 드롭다운을 열고 Customizations를 선택하세요 — Rules와 Workflows가 같은 패널에 있습니다. Rules 아래에서 새 규칙을 만드세요: 전역 규칙은 ~/.gemini/GEMINI.md에 있어 모든 워크스페이스에 적용되고, 워크스페이스 규칙은 워크스페이스 또는 git 루트의 .agents 폴더에 있습니다. 규칙 파일은 12,000자로 제한됩니다.
Antigravity 에이전트 패널의 Customizations 패널: Rules 탭이 활성화되고 새 규칙 이름을 입력하는 중, 플레이스홀더는 e.g. code-style-guide.영상 0:56 지점 - 10
활성화 모드 고르기
모든 규칙은 하나의 질문에 답합니다: 언제 적용되는가? Always On은 모든 대화에 주입되고, Manual은 입력창에서의 @멘션을 기다리며, Model Decision은 규칙의 자연어 설명을 보고 에이전트가 판단하고, Glob은 *.test.ts 같은 패턴에 맞는 파일에만 적용됩니다. 가장 좁은 모드를 고르세요 — diff에서만 발동하는 리뷰 규칙이야말로 집중을 유지합니다.
Antigravity 규칙 편집기의 Activation Mode 드롭다운, 네 옵션이 모두 보입니다 — Always On, Manual, Model Decision, Glob.영상 1:04 지점 - 11
규칙 내용 쓰기
규칙은 일반적인 Markdown 제약입니다: "주석은 코드가 무엇을 하는지가 아니라 왜 그렇게 쓰였는지 설명한다", "함수에는 JSDoc을 쓴다", "TODO를 남기지 않는다". 규칙 하나에는 하나의 목적만 — 에이전트는 해당하는 모든 대화에서 문자 그대로 읽어들입니다. 규칙은 전문가의 일하는 방식을 만들고, 다음 두 층이 절차와 지식을 줍니다.
Antigravity 편집기의 comments.md 규칙 파일, Activation Mode는 Always On, 모든 대화가 따라야 할 Markdown 지시를 기다리는 중.영상 1:02 지점 - 12
반복 절차를 워크플로로 패키징하기
전문가가 여러 단계 절차를 반복해야 한다면 — 병합된 브랜치 정리, 릴리스 컷, API 문서 재생성 — 단계를 다시 타이핑하지 말고 워크플로로 저장하세요. 워크플로는 프론트매터에 YAML description을 가진 마크다운 파일이고 슬래시 명령으로 호출합니다: /cleanup-branches를 입력하면 에이전트가 나열된 각 단계를 실행합니다.
Antigravity 문서의 Workflows 섹션: 워크플로 파일은 .agent의 workflows 폴더에 있으며 채팅에서 슬래시 명령으로 호출합니다.영상 5:40 지점 - 13
워크플로 파일 만들기
에이전트에게 시키거나 직접 하세요: mkdir -p .agent/workflows 후 짧은 description 프론트매터와 번호 매긴 단계 목록을 갖춘 cleanup-branches.md를 만듭니다. 녹화된 예제의 단계는 git fetch --prune부터 병합된 브랜치 삭제까지 이어집니다 — 각 단계가 명시적이기에 파괴적 작업 앞에서 에이전트는 멈춰 물어봅니다.
Antigravity 대화 장면: 에이전트가 mkdir -p .agent/workflows와 nano를 실행하고, 저장할 워크플로 마크다운 — description 프론트매터와 10단계 git 정리 체크리스트 — 를 받습니다.영상 6:20 지점
4 · 테스트, 배포, 계층 정리
- 14
가드레일이 작동하는 모습 보기
녹화된 워크플로 실행은 에이전트가 가져온 브랜치를 보고하고, feature/about-page를 병합 완료·삭제 안전으로 지목한 뒤, 무언가에 손대기 전에 "Would you like me to proceed with deleting these?"라고 묻는 장면으로 끝납니다. 이 승인 습관은 위임된 커스텀 에이전트에도 적용됩니다: 사용자 승인이 필요한 작업은 메인 인터페이스로 올라오므로 전문가가 조용히 경계를 넘는 일이 없습니다.
에이전트의 워크플로 보고: feature/about-page는 병합되어 안전하게 삭제 가능하며, git branch -d와 git gc를 실행하기 전에 "Would you like me to proceed?"라고 묻습니다.영상 7:46 지점 - 15
스킬 하나 가르치기
규칙은 행동을, 스킬은 지식을 더합니다. 스킬은 SKILL.md 파일을 담은 폴더입니다 — 워크스페이스 스킬은 .agents/skills/<스킬명>/ 아래에, 개인 스킬은 ~/.gemini/skills 아래에. 프론트매터의 name과 description이 언제 관련 있는지 에이전트에게 알리고, 본문이 전체 지시·스크립트·참고자료를 담습니다. 커스텀 에이전트와 스킬은 조합됩니다: codereviewer에 nextjs-reviewer 스킬을 붙여 프레임워크 전용 점검을 보완하세요.
Antigravity 문서의 Agent Skills 섹션: 스킬 디렉터리 중 하나에 폴더를 만들고 YAML 프론트매터가 있는 SKILL.md 파일을 추가하는 절차.영상 8:42 지점 - 16
SKILL.md 프론트매터 작성하기
description은 트리거처럼 쓰세요: "Reviews Next.js and TypeScript code for critical issues only — types, performance, security, and App Router patterns". 요청이 일치하면 에이전트가 스킬 전체를 로드하고, 아니면 스킬은 방해하지 않습니다. 이 점진적 로딩이야말로 깊은 참고 자료를 에이전트의 시스템 프롬프트가 아니라 스킬에 두어야 하는 이유입니다.
Antigravity 편집기의 nextjs-reviewer SKILL.md: YAML 프론트매터에 스킬 이름과 설명이 있습니다 — Reviews Next.js and TypeScript code for critical issues only.영상 9:16 지점 - 17
실제 리뷰에서 스킬이 발동되는 장면 보기
녹화된 세션에서 Next.js 코드 리뷰를 요청하자 에이전트는 리뷰어 스킬을 로드하고 페이지를 분석한 뒤 구조화된 리뷰로 답했습니다: Project Strengths에서 타입 유틸리티와 폰트 최적화를 짚었고, 편집 전에 "Would you like me to apply these fixes for you?"라고 물었습니다. 프롬프트에 같은 출력 형식을 요구하면 여러분의 커스텀 에이전트도 이 규율을 상속합니다.
리뷰어 에이전트의 실전: 프로젝트의 강점 — 타입 유틸리티, next/image, App Router 패턴 — 을 나열하고 수정 적용 여부를 묻습니다.영상 10:15 지점 - 18
IDE와 CLI 양쪽에서 테스트하기
mainAgent: true로 두면 선택기에 전문가가 나타납니다 — 선택하고 "What are your tools?"라고 물어 도구 상자 연결을 확인하세요. 깨진 tools 목록은 즉시 실행 오류로 실패하니 그것이 가장 빠른 스모크 테스트입니다. CLI에서는 /agents 명령으로 발견된 에이전트를 나열하고, Alt+J로 서브에이전트 패널을 열어 위임 작업을 실시간으로 볼 수 있습니다.
- 19
폴더를 커밋해 팀 전체가 같은 전문가를 쓰게 하기
전문가에게 필요한 모든 것이 이제 저장소에 있습니다: 에이전트 정의는 .agents/agents/, 그리고 rules·skills·workflows를 담은 .agent 폴더가 소스 옆에 있습니다. 커밋하면 모든 팀원과 모든 CI 실행이 같은 경계를 가진 같은 전문가를 발견합니다. ~/.gemini의 개인 정의는 저장소에 넣지 마세요 — 머신 전역의 취향입니다.
Antigravity 탐색기에서 펼쳐진 .agent 폴더 — agent, rules, skills, workflows가 소스 옆에 나란히 있어 커밋할 준비가 되어 있습니다.영상 9:04 지점 - 20
어느 층이 무엇을 하는지 알기
세 커스터마이즈 층은 에이전트 파일을 대체하지 않고 보완합니다: Rules는 항상 켜진(또는 패턴 발동) 코딩 표준, Workflows는 슬래시 명령 절차, Skills는 자동 발견되는 전문 지식입니다. 커스텀 에이전트는 이들을 묶는 정체성 — 반복되는 직무에 이름과 도구 상자와 기억을 주는 마크다운 파일 하나입니다.
Rules vs Workflows vs Skills 비교표: 코딩 표준은 자동 적용, 작업 자동화는 슬래시 명령, 전문 지식은 필요할 때 자동 발견됩니다.영상 10:20 지점