Antigravity Rules, Workflows, Skills 공식 구조와 파일 위치 정리

Antigravity의 지침 체계는 Rules, Workflows, Skills로 구분해 정리할 수 있다.

Rules는 두 층으로 나뉜다

공식 문서 기준으로 Rules는 전역 규칙과 워크스페이스 규칙으로 나뉜다.¹ 이 구분이 Antigravity의 기본 구조다.

전역 Rules는 ~/.gemini/GEMINI.md에 작성되며 모든 워크스페이스에 적용된다.¹ 이 파일에는 저장소와 무관하게 유지할 개인 기본 지침을 넣는다. 예를 들면 설명 방식, 선호 도구, 작업 응답 형식 같은 공통 설정이 여기에 들어간다.

Workspace Rules는 워크스페이스 또는 git 루트의 .agents/rules 폴더에 위치한다.¹ 이 위치에는 프로젝트 전체가 따라야 하는 규칙을 둔다. 아키텍처 원칙, 테스트 정책, 디렉터리 규약, 코드 스타일처럼 저장소 차원의 기준을 여기에 정리한다.

이 분리는 규칙의 적용 범위를 명확하게 만든다. 전역 Rules는 사용자 공통 설정을 담당하고, Workspace Rules는 저장소 전용 제약을 담당한다.¹ 두 층을 나누면 개인 습관과 팀 규범이 섞이지 않고 유지된다.

Workflows는 규칙이 아니라 일의 흐름이다

공식 문서는 Antigravity의 맞춤설정 옵션을 Rules와 Workflows로 설명한다.¹ Google Codelabs의 Rules and Workflows 섹션도 같은 구성을 안내하며, Customizations 화면에서 이 둘을 관리할 수 있다고 설명한다.²

Workflows는 에이전트와 상호작용할 때 /로 필요 시 트리거하는 저장된 프롬프트다.² Workflows는 사용자가 필요할 때 선택 실행하는 절차이다.¹²

공식 문서는 Workflows를 전역 또는 워크스페이스 단위로 둘 수 있다고 명시한다.¹² 전역 Workflows 위치는 ~/.gemini/antigravity/global_workflows/<YOUR_WORKFLOW_NAME>.md이고, Workspace Workflows 위치는 your-workspace/.agents/workflows/다.¹²

정리하면 Workflows는 항상 적용되는 규칙 파일이 아니라, 필요할 때 /로 호출하는 저장된 프롬프트다.² 적용 범위는 전역과 워크스페이스 두 층으로 나뉘며, 위치도 각각 분리되어 관리된다.¹²

Skills는 특정 작업을 위한 묶음이다

공식 skills 문서 기준으로 Skill은 특정 작업에 사용할 수 있는 재사용 가능한 지식 패키지이며, SKILL.md 파일이 들어 있는 폴더다.³ 각 Skill에는 특정 유형의 작업에 접근하는 방법, 따라야 할 모범 사례와 관례, 그리고 선택적으로 사용할 수 있는 스크립트와 리소스를 담을 수 있다.³

Antigravity는 두 종류의 Skills를 지원한다.³ 워크스페이스 스킬은 <workspace-root>/.agents/skills/<skill-folder>/에 두며, 프로젝트별 워크플로, 팀 배포 절차, 테스트 관례처럼 저장소 전용 지식을 담는 데 적합하다.³ 전역 스킬은 ~/.gemini/antigravity/skills/<skill-folder>/에 두며, 모든 프로젝트에서 공통으로 쓰는 개인 유틸리티나 범용 도구 지침에 적합하다.³ 현재 기본 경로는 .agents/skills이며, .agent/skills도 하위 호환으로 지원한다.³

공식 문서의 요지는 Skill을 한 가지 일을 잘 하도록 좁게 유지하는 것이다.³ description은 어떤 상황에서 이 Skill을 써야 하는지 분명하게 드러나도록 구체적으로 작성하는 편이 좋다.³ 스크립트가 있다면 먼저 --help를 보게 유도하는 구성이 바람직하다.³ 절차가 복잡한 Skill에는 상황별 선택 기준을 함께 적어 두는 편이 안정적이다.³

Skills 작성 원칙

동작 흐름은 세 단계로 정리할 수 있다.³ Discovery 단계에서 에이전트는 대화 시작 시 사용 가능한 Skills의 이름과 설명 목록을 본다. Activation 단계에서는 현재 작업과 관련성이 있는 Skill의 SKILL.md 전체를 읽는다. Execution 단계에서는 그 지침을 실제 작업 수행에 적용한다.³ 사용자가 스킬 이름을 명시적으로 언급할 수도 있지만, 기본적으로는 문맥에 따라 관련 Skill이 선택된다.³

Skills는 이렇게 동작한다

Skill을 만들려면 스킬 디렉터리 아래에 폴더를 만들고 그 안에 SKILL.md를 둔다.³ SKILL.md 상단에는 YAML frontmatter를 둘 수 있으며 description은 필수이고, name은 선택이다. name이 없으면 폴더명을 기본값으로 사용한다.³ Skill 폴더에는 선택적으로 scripts/, examples/, resources/ 같은 하위 폴더를 둘 수 있고, 에이전트는 이 자료들도 읽을 수 있다.³

실무에서는 무엇을 어디에 쓰면 되는가

개인적으로 항상 유지할 지침은 ~/.gemini/GEMINI.md에 둔다.¹ 설명 방식, 계획 제시 방식, 선호 도구처럼 저장소가 바뀌어도 유지되는 규칙이 여기에 들어간다.

팀이나 프로젝트 전체가 따라야 하는 기준은 .agents/rules에 둔다.¹ 테스트 원칙, 브랜치 전략, 폴더 구조, 리뷰 전 확인 항목처럼 저장소 수준의 규칙은 여기서 관리한다.

반복적으로 필요하지만 항상 적용할 필요는 없는 작업은 Workflows로 정리한다.¹² 전역으로 재사용할 워크플로는 ~/.gemini/antigravity/global_workflows/<YOUR_WORKFLOW_NAME>.md에 두고, 프로젝트 전용 워크플로는 your-workspace/.agents/workflows/에 둔다.¹² 실행할 때는 채팅에서 /로 호출한다.²

특정 작업에만 필요한 전문 지침은 Skills로 분리한다.³ 프로젝트 전용 절차나 팀 관례는 <workspace-root>/.agents/skills/<skill-folder>/에 두고, 여러 저장소에서 공통으로 쓸 개인 유틸리티는 ~/.gemini/antigravity/skills/<skill-folder>/에 두면 된다.³ Skill은 SKILL.md를 중심으로 구성하고, 필요하면 scripts/, examples/, resources/를 함께 둔다.³

맺음말

Antigravity의 지침 체계는 단일 파일 하나로 설명되지 않는다.¹³ 공식 문서는 전역 Rules, Workspace Rules, Workflows, Skills를 각각 구분해 설명한다.¹³² 이 노트는 각 요소의 역할, 적용 범위, 위치를 출처 기준으로 정리한다.

~/.gemini/GEMINI.md는 모든 워크스페이스에 적용되는 전역 Rules 파일이고, .agents/rules는 Workspace Rules 위치다.¹ Workflows는 저장된 프롬프트이며 /로 호출한다.² 전역 Workflows는 ~/.gemini/antigravity/global_workflows/<YOUR_WORKFLOW_NAME>.md에 두고, Workspace Workflows는 your-workspace/.agents/workflows/에서 관리한다.¹² Skills는 SKILL.md를 포함한 폴더 단위의 재사용 가능한 지식 패키지다.³

참고

¹Google Antigravity Documentation - Rules / Workflows

²Google Antigravity 시작하기 | Google Codelabs

³Google Antigravity Documentation - Skills