메인 콘텐츠로 건너뛰기
TilnoteAI 스퀘어

Antigravity Agent Skills 사용법 및 SKILL.md 작성 가이드

R
roy
•조회수 8
요약

Antigravity Agent Skills 사용 가이드

Generated image

개요

Antigravity에서 이제 에이전트용 “스킬(Skill)”을 정식으로 지원합니다.

Agent Skill은 에이전트가 따라야 할 작업 방식, 기준, 도구 사용법을 하나의 패키지로 정리한 확장 포맷입니다. 팀이나 개인이 평소에 해오던 업무 절차를 그대로 문서화해 두면, 에이전트가 그 방식을 따라 실행하는 구조입니다.

코드 리뷰 스타일, 릴리스 체크리스트, 문서 작성 규칙처럼 반복해서 설명해야 했던 내용을 스킬로 묶어두면, 에이전트가 항상 같은 기준으로 답변하고 작업을 진행하게 만들 수 있습니다.

즉, “우리 팀이 일하는 방식”을 에이전트에게 이식하는 수단이라고 이해하시면 됩니다.

빠른 시작(Quick Start)

이 섹션은 “새 워크스페이스에서 처음으로 스킬 하나를 만들어 쓰고 싶은 사람”을 위한 최소 단계 가이드입니다.

아래 네 단계만 순서대로 따라 하면 됩니다.

1. 스킬 디렉토리 위치 만들기

워크스페이스 전용 스킬은 프로젝트 루트에 있는 .agent/skills 아래에 둡니다.

<workspace-root>/
  .agent/
    skills/

처음이라면 .agent와 skills 폴더가 없을 가능성이 큽니다. 이때는 직접 생성하면 됩니다.

mkdir -p .agent/skills

이제 이 skills 폴더 안에 각 스킬별로 하위 폴더를 만들게 됩니다.

2. 최소 폴더 구조 생성

가장 단순한 스킬은 “폴더 1개 + SKILL.md 1개”만 있으면 됩니다.

예를 들어 기본 코드 리뷰 스킬을 만든다고 하면 다음과 같습니다.

.agent/skills/
  code-review-basic/
    SKILL.md

여기서는 code-review-basic이 스킬 폴더 이름입니다. 실제 이름은 팀 규칙에 맞게 정해도 됩니다.

처음에는 이 구조만 있어도 충분합니다. 나중에 필요해지면 scripts/, examples/ 같은 하위 폴더를 추가해 확장할 수 있습니다.

3. 최소 예제 SKILL.md 작성

이제 code-review-basic/SKILL.md 파일을 만들고 아래 내용을 붙여 넣습니다.

---
name: basic-code-review
description: 작은 규모의 코드 변경에 대해 간단하고 일관된 코드 리뷰를 수행하는 스킬입니다.
---

# Basic Code Review

## Purpose

작은 변경에 대해 빠르고 안정적으로 피드백을 제공하기 위한 코드 리뷰 기준을 정의합니다.

## When to use this skill

- 사용자가 "코드 리뷰해줘", "이 PR 어때?"처럼 리뷰를 요청했을 때  
- 변경 범위가 크지 않고 구현 디테일 위주의 검토가 필요할 때

## How to use it

1. 변경된 파일과 설명(커밋 메시지, PR 설명 등)을 함께 확인합니다.  
2. 버그 가능성, 스타일, 가독성, 유지보수성 관점에서 차례대로 살펴봅니다.  
3. 문제가 되는 부분은 구체적인 코드 위치와 함께 지적합니다.  
4. 가능하다면 개선 예시 코드를 함께 제안합니다.

여기까지 완료하면 형식적으로 유효한 스킬 하나가 준비된 상태입니다.

4. 에이전트가 스킬을 인식하고 사용하는 흐름

별도 설치나 빌드 과정은 없습니다. 워크스페이스 루트에서 Antigravity를 열고 에이전트를 사용하면, 에이전트가 자동으로 .agent/skills/**/SKILL.md를 스캔해 스킬을 발견합니다.

사용 예시는 다음과 같습니다.

에이전트에게 다음과 같이 요청합니다.

이 PR 코드 리뷰해줘. 구현 디테일 위주로 확인해줘.

에이전트는 현재 워크스페이스의 스킬 목록을 살펴본 뒤, basic-code-review가 상황에 맞다고 판단되면 이 스킬에 정의된 절차를 참고해 답변을 구성합니다.

사용자 입장에서는 “스킬을 따로 호출한다”는 느낌보다는, “설명을 잘 해뒀더니 에이전트가 그 기준을 자연스럽게 따라준다”에 가깝다고 이해하면 됩니다.

워크스페이스 스킬 vs 글로벌 스킬

Antigravity의 스킬은 크게 두 위치에 둘 수 있습니다.

프로젝트에 종속된 “워크스페이스 스킬”과, 모든 프로젝트에서 공통으로 쓰는 “글로벌 스킬”입니다.

워크스페이스 스킬

워크스페이스 스킬은 현재 프로젝트에서만 유효한 스킬입니다. 경로는 다음과 같습니다.

<workspace-root>/.agent/skills/<skill-folder>/

이 위치의 스킬은 해당 저장소의 맥락과 규칙을 강하게 반영할 때 좋습니다.

예를 들어 다음과 같은 경우입니다.

  • 특정 저장소에만 존재하는 디렉터리 구조와 레이어 규칙

  • 이 프로젝트 전용 테스트 전략, 브랜치 전략, 배포 절차

  • 레포지토리별로 다른 코드 스타일 가이드, 리뷰 체크리스트

실무에서는 “이 저장소만의 개발 규칙, 체크리스트, 온보딩 문서”를 워크스페이스 스킬로 두고, 새로 합류한 팀원이 에이전트를 통해 자연스럽게 그 규칙을 따르게 만드는 용도로 많이 쓰입니다.

글로벌 스킬

글로벌 스킬은 Antigravity를 사용하는 모든 워크스페이스에서 공통으로 사용되는 스킬입니다. 경로는 다음과 같습니다.

~/.gemini/antigravity/skills/<skill-folder>/

이 위치의 스킬은 여러 프로젝트에서 반복해서 쓰는 “개인/팀 공통 도구” 성격일 때 유용합니다.

예를 들어 다음과 같은 스킬을 여기에 두면 좋습니다.

  • 본인이 선호하는 일반적인 코드 리뷰 스타일

  • 글쓰기 보정, 톤/스타일 정리, 문장 다듬기 가이드

  • 일상적인 작업 템플릿(회의록 정리, 이메일 작성, 회고 문서 구조 등)

실제로는 “개인 작업 습관이나 모든 프로젝트에 공통으로 적용하는 팀 규칙”은 글로벌 스킬로, “레포지토리마다 달라지는 구현 디테일”은 워크스페이스 스킬로 나누는 패턴이 가장 관리하기 쉽습니다.

에이전트 관점에서의 동작 흐름

에이전트는 대화 한 번마다 “어떤 스킬을 쓸지, 쓴다면 어떻게 적용할지”를 내부적으로 결정합니다.

이 과정은 크게 Discovery, Activation, Execution 세 단계로 이해할 수 있습니다.

Discovery: 스킬 찾기

에이전트는 먼저 사용 가능한 스킬 목록을 빌드합니다. 워크스페이스 스킬과 글로벌 스킬의 SKILL.md를 읽고, name, description, 본문 내용을 기반으로 어떤 작업에 적합한지 이해합니다.

예를 들어 사용자가 “테스트 코드 작성 가이드 알려줘”라고 요청하면, 에이전트는 설명과 본문에 “테스트”, “테스트 코드”, “작성 가이드” 같은 단어가 포함된 스킬을 우선 후보로 올립니다.

Activation: 언제 스킬을 켤지 결정

Discovery 단계에서 찾은 여러 스킬 중, 현재 대화에 실제로 도움이 되는 스킬만 활성화합니다.

사용자의 요청 내용, 현재 보고 있는 파일, 이전 대화 맥락 등을 고려해 “지금 이 상황에 이 스킬을 적용하는 게 맞는지”를 판단합니다.

예를 들어 같은 코드 리뷰 스킬이라도, 사용자가 “코드를 설명만 해줘”라고 말한 경우에는 활성화하지 않고, “코드 리뷰해줘”라고 명시적으로 말한 경우에만 적용할 수 있습니다.

Execution: 스킬을 따라 답변 구성

활성화된 스킬은 에이전트가 답변을 작성할 때 “업무 매뉴얼”처럼 참조됩니다. 스킬 본문에 있는 섹션(예: Purpose, How to use it, Checklist)을 읽고, 그 순서와 체크 항목을 실제 답변에 녹여냅니다.

예를 들어 코드 리뷰 스킬에 “1) 버그 가능성, 2) 스타일, 3) 가독성 순으로 확인”이라고 적혀 있다면, 에이전트는 답변에서 이 순서대로 코드를 검토한 결과를 정리하려고 시도합니다.

SKILL.md 작성 가이드

SKILL.md는 “YAML Frontmatter + Markdown 본문” 구조를 따릅니다.

Frontmatter에는 스킬 메타데이터를, 본문에는 실제 작업 절차와 기준을 적습니다.

필수 필드

가장 기본적으로 다음 두 필드는 항상 넣는 것을 권장합니다.

  1. name 스킬의 기술적인 식별자입니다. 영어 소문자, 하이픈 조합처럼 단순하게 짓는 편이 좋습니다. 예: basic-code-review, release-checklist, docs-style-guide

  2. description 스킬이 어떤 상황에서 어떤 일을 하는지 한두 문장으로 요약합니다. 에이전트가 스킬을 고를 때 매우 중요한 힌트가 됩니다.

간단한 예시는 다음과 같습니다.

---
name: basic-code-review
description: 작은 규모의 코드 변경에 대해 빠르고 일관된 코드 리뷰를 수행하는 스킬입니다.
---

자주 쓰는 필드

필수는 아니지만, 다음 필드를 함께 적어두면 스킬 관리에 도움이 됩니다.

  • version: 스킬 버전(예: 1.0.0, 0.1)

  • author: 작성자 이름이나 팀 이름

  • tags: 스킬 분류용 키워드 배열(예: ["code-review", "backend"])

  • language: 주로 사용하는 언어(예: ko, en)

예시:

---
name: basic-code-review
description: 작은 규모의 코드 변경에 대해 빠르고 일관된 코드 리뷰를 수행하는 스킬입니다.
version: 1.0.0
author: backend-team
tags:
  - code-review
  - quality
language: ko
---

좋은 name/description을 짓기 위한 팁

  1. name은 “무엇을 하는지”가 드러나게 짓습니다. 예: api-contract-review, frontend-release-checklist 처럼 작업 유형이 명확한 이름이 좋습니다.

  2. description은 “언제 / 무엇을 / 어떻게”까지 포함해 한두 문장으로 씁니다. 예: description: 프론트엔드 배포 전, 주요 기능과 UI를 빠르게 점검하기 위한 체크리스트입니다. 처럼 트리거 상황과 목적이 함께 드러나면 에이전트가 선택하기 쉬워집니다.

  3. 너무 포괄적인 설명은 피합니다. “코드를 도와주는 스킬입니다”보다는 “리액트 컴포넌트 리팩토링 아이디어를 제안하는 스킬입니다”처럼 구체적으로 적는 것이 좋습니다.

본문 템플릿 제안

SKILL.md의 본문은 결국 “에이전트가 따라야 할 업무 매뉴얼”입니다. 구조가 일정할수록 에이전트가 이해하고 따르기 쉬워집니다.

아래와 같은 섹션 구성을 추천합니다.

  • Purpose

  • When to use this skill

  • How to use it

  • Checklist

  • Examples (선택)

  • Notes / Caveats (선택)

간단한 샘플을 보며 필요한 부분만 가져다 쓰면 됩니다.

---
name: basic-code-review
description: 작은 규모의 코드 변경에 대해 빠르고 일관된 코드 리뷰를 수행하는 스킬입니다.
version: 1.0.0
author: backend-team
tags:
  - code-review
  - quality
language: ko
---

# Basic Code Review

## Purpose

작은 규모의 코드 변경에 대해, 버그 가능성과 유지보수성을 빠르게 확인하기 위한 리뷰 기준을 제공합니다.

## When to use this skill

- 변경된 파일 수가 많지 않고, 기능 영향 범위가 제한적일 때  
- 사용자가 "간단히 코드 리뷰해줘"라고 요청할 때

## How to use it

1. 변경된 파일과 관련 설명(이슈, PR 설명, 커밋 메시지)을 모두 확인합니다.  
2. 아래 Checklist 순서대로 코드를 검토합니다.  
3. 각 항목에서 발견한 사항은 구체적인 코드 위치와 함께 피드백합니다.

## Checklist

- 기능이 요구사항대로 동작하지 않을 위험이 있는 부분은 없는가?  
- 명확하지 않은 변수명, 함수명, 매직 넘버가 있는가?  
- 중복 코드나 불필요한 복잡도가 있는가?  
- 팀 코딩 컨벤션(포맷팅, 네이밍, 파일 구조 등)을 위반하는 부분이 있는가?

## Examples

- 좋은 피드백 예시:  
  - "user_service.py의 42번째 줄에서 직접 SQL을 작성하고 있는데, 기존 레포지토리에서는 ORM을 사용하는 패턴을 따릅니다. ORM을 사용하도록 수정하는 것이 어떨까요?"

## Notes

- 이 스킬은 작은 변경을 전제로 합니다. 대규모 리팩토링이나 설계 변경이 포함된 경우, 별도의 아키텍처 리뷰 스킬을 우선 고려합니다.

실무에서는 위 템플릿을 복사해 이름과 설명, 체크리스트만 바꿔서 “테스트 작성 가이드”, “릴리스 체크리스트”, “문서 작성 가이드” 등 다양한 스킬을 빠르게 만들어 쓸 수 있습니다.

참고

1Antigravity Agent Skills 내부 가이드(예시 링크) — 실제 링크는 팀 내 공식 문서를 사용하세요. (https://antigravity-docs.example.com/agent-skills)

#Antigravity#Agent#Skills#Gemini#google#에이전트 스킬#업무 자동화#코드 리뷰#워크스페이스 관리