AI 에이전트에 전문 지식을 더하는 Antigravity Agent Skills 개발 방법

지난주, 팀원이 몇 번째인지도 모르게 제게 물었습니다. “이 API의 인증 절차가 정확히 어떻게 되나요?”

한동안 열어 보지 않았던 Confluence 페이지를 확인해 보니 마지막 업데이트는 6개월 전이었습니다. 문서와 코드는 또 어긋나 있었습니다. 한숨을 쉬고 이미 수도 없이 설명했던 내용을 다시 직접 입력하기 시작했습니다.

그날 저녁 Antigravity를 이것저것 만지다가 우연히 Skills 시스템을 발견했습니다. 간단히 말하면 AI Agent에 “전문 두뇌”를 심어 특정 지식을 기억하고, 정해진 절차를 실행하며, 필요한 도구를 호출하게 만드는 기능입니다.

두 시간 정도 들여 사내 API용 Skill을 하나 만들었습니다. 다음 날 신입 팀원이 같은 질문을 하자 Antigravity에 한 문장만 입력했습니다. “사용자 서비스의 인증 절차를 확인해 줘.”

Agent는 제가 만든 Skill을 호출했고, 30초 뒤 정확한 설명과 코드 예제를 내놓았습니다. 신입 팀원은 내용을 확인한 뒤 스스로 작업을 이어 갔습니다.

그 순간 깨달았습니다. Skill 시스템은 단순한 확장 기능이 아니라 팀의 협업 방식을 바꾸는 도구입니다.

여기서는 Antigravity용 커스텀 Skills를 작성하는 방법을 다룹니다. 기본 개념부터 외부 API 연동과 사설 지식 베이스 연결까지 실제 사례를 따라가며 살펴보겠습니다.

Antigravity Skills란 무엇인가

먼저 개념부터 정리해 보겠습니다.

Antigravity의 Skill 시스템은 가볍고 개방적인 확장 형식입니다. AI Agent에 설치하는 “앱”이라고 생각하면 이해하기 쉽습니다. 각 Skill은 특정 기능 묶음을 정의해 필요한 상황에서 Agent가 더 전문적으로 작업하도록 합니다.

Google Codelabs의 설명에 따르면 Skills는 디렉터리 구조로 구성된 패키지이며, 표준 형식을 통해 Agent가 안정적으로 해석하고 실행할 수 있습니다. 일반적인 Skill에는 다음 항목이 포함됩니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

• skill.yaml: Skill의 메타데이터, 기능 설명, 사용 상황을 정의합니다.
• README.md: Skill의 기능과 사용법을 자세히 설명합니다.
• scripts/: 실제 실행할 스크립트(Python, Bash 등)를 둡니다.
• templates/: Prompt 템플릿이나 출력 템플릿을 둡니다.

Skills는 두 가지 범위에 정의할 수 있습니다.

• 전역 범위(~/.gemini/antigravity/skills/): “JSON 포맷팅”, “일반 코드 리뷰”처럼 여러 프로젝트에서 사용할 기능을 둡니다.
• 프로젝트 범위(.agent/skills/): “우리 팀의 API 규칙”, “특정 비즈니스용 코드 템플릿”처럼 현재 프로젝트에서만 사용할 기능을 둡니다.

이 계층 구조는 꽤 실용적입니다. 범용 기능은 전역에, 비즈니스와 관련된 기능은 프로젝트에 둘 수 있습니다.

첫 번째 Skill 작성하기

이제 직접 만들어 보겠습니다.

간단한 예제로 시작합니다. Git commit message를 자동으로 정리하는 Skill입니다.

1단계: 디렉터리 구조 만들기

mkdir -p ~/.gemini/antigravity/skills/git-commit-formatter

2단계: skill.yaml 작성하기

name: git-commit-formatter
description: Format Git commit messages following Conventional Commits spec
version: 1.0.0
author: your-name
triggers:
  - commit
  - git message
  - format commit
actions:
  - name: format_commit
    description: Format a raw commit message to Conventional Commits format
    input:
      raw_message: string
      type: enum[feat, fix, docs, style, refactor, test, chore]
    output:
      formatted_message: string

이 YAML은 Skill의 기본 정보, 실행 키워드, 입력 및 출력 형식을 정의합니다.

3단계: 실행 스크립트 작성하기

디렉터리 안에 scripts/format_commit.py를 만듭니다.

#!/usr/bin/env python3
import sys
import re

def format_commit(raw_message, commit_type):
    # 원본 메시지 분석
    scope_match = re.search(r'\(([^)]+)\)', raw_message)
    scope = f"({scope_match.group(1)})" if scope_match else ""

    # 설명 추출
    desc = re.sub(r'\([^)]+\):?\s*', '', raw_message).strip()

    # 포맷 적용
    formatted = f"{commit_type}{scope}: {desc}"
    return formatted

if __name__ == "__main__":
    raw = sys.argv[1]
    ctype = sys.argv[2]
    print(format_commit(raw, ctype))

4단계: 테스트하기

Antigravity를 다시 시작한 뒤 다음과 같이 입력합니다.

“git-commit-formatter로 이 커밋 메시지를 정리해 줘: 사용자 로그인 버그를 수정했습니다.”

정상적으로 작동하면 Agent가 Skill을 호출해 fix(auth): 사용자 로그인 버그를 수정했습니다와 같은 결과를 출력합니다.

간단하죠? 이것이 Skill의 기본 골격입니다.

외부 API 연동: GitHub + Jira 실전

로컬에서만 동작하는 Skill은 활용 범위가 제한적입니다. 외부 시스템과 연결될 때 진짜 쓸모가 생깁니다.

Jira 이슈를 자동으로 처리하는 Skill을 하나 만들어 보겠습니다.

상황: 팀은 매일 Jira에서 상태를 바꾸고 작업 시간을 기록하는 데 많은 시간을 씁니다. 이런 반복 작업을 Agent에 맡기는 것이 목표입니다.

1단계: API 인증 준비하기

Jira API token과 도메인이 필요합니다. 민감한 정보는 환경 변수에 저장하는 것이 좋습니다.

export JIRA_API_TOKEN="your-token"
export JIRA_DOMAIN="your-domain.atlassian.net"
export JIRA_EMAIL="[email protected]"

2단계: Skill 설정 작성하기

name: jira-assistant
description: Automate Jira workflows - search issues, update status, add worklogs
triggers:
  - jira
  - ticket
  - issue
  - worklog
actions:
  - name: search_issues
    description: Search Jira issues by JQL query
  - name: add_worklog
    description: Add time spent to an issue
  - name: transition_issue
    description: Move issue to a different status

3단계: 핵심 스크립트 작성하기

#!/usr/bin/env python3
import os
import requests
from base64 import b64encode

class JiraClient:
    def __init__(self):
        self.domain = os.getenv('JIRA_DOMAIN')
        self.email = os.getenv('JIRA_EMAIL')
        self.token = os.getenv('JIRA_API_TOKEN')
        self.auth = self._get_auth()

    def _get_auth(self):
        credentials = f"{self.email}:{self.token}"
        return b64encode(credentials.encode()).decode()

    def search(self, jql):
        url = f"https://{self.domain}/rest/api/2/search"
        headers = {
            "Authorization": f"Basic {self.auth}",
            "Content-Type": "application/json"
        }
        response = requests.get(url, headers=headers, params={"jql": jql})
        return response.json()

    def add_worklog(self, issue_key, time_spent, comment):
        url = f"https://{self.domain}/rest/api/2/issue/{issue_key}/worklog"
        headers = {
            "Authorization": f"Basic {self.auth}",
            "Content-Type": "application/json"
        }
        data = {
            "timeSpent": time_spent,
            "comment": comment
        }
        return requests.post(url, headers=headers, json=data)

# CLI 진입점
if __name__ == "__main__":
    import sys
    client = JiraClient()

    if sys.argv[1] == "search":
        result = client.search(sys.argv[2])
        for issue in result.get('issues', []):
            print(f"{issue['key']}: {issue['fields']['summary']}")

    elif sys.argv[1] == "worklog":
        client.add_worklog(sys.argv[2], sys.argv[3], sys.argv[4])
        print(f"Worklog added to {sys.argv[2]}")

4단계: 사용하기

이제 Antigravity에서 다음과 같이 말할 수 있습니다.

“내가 담당한 In Progress 상태의 Jira ticket을 모두 찾아 줘.”

“PROJ-123에 작업 시간 2시간을 기록하고 메모에는 ‘사용자 모듈 리팩터링 완료’라고 적어 줘.”

“PROJ-456의 상태를 Done으로 바꿔 줘.”

Agent가 Jira API를 자동으로 호출하므로 느린 Jira 화면을 다시 열 필요가 없습니다.

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

GitHub 연동도 비슷합니다. PyGithub 라이브러리나 requests를 사용해 GitHub API를 직접 호출하면 됩니다. PR 자동 생성, CI 상태 확인, 코드 리뷰까지 처리하는 Skill을 만들 수 있습니다.

사설 지식 베이스 연결: NotebookLM + Antigravity

제가 가장 흥미롭게 본 부분입니다.

XDA Developers에 흥미로운 사례가 하나 있습니다. 작성자는 프로젝트 문서를 NotebookLM에 넣고 기술 사양을 생성한 다음, 이를 Antigravity Skill로 변환했습니다. 그 결과 Agent가 프로젝트 문서를 근거로 직접 코드를 작성할 수 있었습니다.

구현 방식:

NotebookLM은 대화를 구조화된 문서로 내보내는 기능을 제공합니다. 다음과 같이 활용할 수 있습니다.

1. NotebookLM에 프로젝트 지식 베이스를 만듭니다(설계 문서, API 규칙, 아키텍처 결정 사항).
2. NotebookLM의 질의응답 기능으로 “지식 요약”을 정리합니다.
3. 요약을 Skill의 context 또는 templates로 변환합니다.

더 직접적인 방법은 MCP(Model Context Protocol)로 NotebookLM과 Antigravity를 연결하는 것입니다.

GitHub의 오픈 소스 프로젝트 notebooklm-antigravity-skill은 nlm CLI로 이 연동을 구현합니다.

name: notebooklm-knowledge
description: Query project knowledge from NotebookLM
triggers:
  - 문서 검색
  - 규칙 확인
  - 프로젝트 지식
actions:
  - name: query_knowledge
    description: Query NotebookLM for project-specific knowledge

NotebookLM API를 호출하는 스크립트를 결합하면 Agent가 사설 지식 베이스를 실시간으로 질의할 수 있습니다.

다음 상황을 상상해 보세요.

신입 팀원: “우리 프로젝트의 오류 처리 규칙은 무엇인가요?”
당신: (Antigravity에서) “NotebookLM에 있는 오류 처리 규칙을 확인해 줘.”
Agent: “프로젝트 문서에 따르면 오류 처리 규칙은 다음과 같습니다. 1. 커스텀 예외 클래스를 사용합니다… 2. 로그에 traceback을 반드시 포함합니다… 3. 사용자에게 표시되는 오류는 국제화해야 합니다…”

묻혀 있던 문서가 Agent의 “전문 두뇌”로 바뀝니다.

고급 활용: Rules와 Skill 조합하기

Antigravity에는 Skills 외에도 “Rules” 시스템이 있습니다. 두 기능을 함께 사용하면 더 강력합니다.

Rules는 전역 또는 프로젝트 수준에서 적용되는 행동 제약 조건입니다. 예를 들면 다음과 같습니다.

# .agent/rules/code-review.md

코드 리뷰 시:
1. 단위 테스트 커버리지가 충분한지 확인합니다.
2. 민감한 정보가 하드코딩되지 않았는지 확인합니다.
3. 오류 처리가 충분한지 검증합니다.
4. 팀의 TypeScript 규칙을 준수하는지 확인합니다.

Rule은 “언제 어떻게 해야 하는지”를 정의하고 Skill은 “구체적으로 어떻게 실행할지”를 정의합니다.

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

Atlassian 개발자는 블로그에서 실제 활용 사례를 공유했습니다. Antigravity에 app-deployment 규칙을 정의하고 Jira Skills와 결합해 배포 절차를 자동화한 사례입니다.

Agent가 코드가 main 브랜치에 병합된 것을 감지하면 다음 순서로 동작합니다.

1. Rule 실행: “배포 전 검사를 수행합니다.”
2. Skill 호출: Jira에서 연결된 ticket의 상태를 확인합니다.
3. Skill 호출: 테스트 스위트를 실행합니다.
4. Skill 호출: 테스트를 통과하면 Jira 상태를 업데이트하고 배포 로그를 기록합니다.

이 조합을 적용하면 원래 사람이 열 단계 넘게 처리해야 했던 절차를 이제 한 문장으로 실행할 수 있습니다.

마무리

핵심은 한 문장으로 정리할 수 있습니다. Skills는 Antigravity를 ‘범용 도구’에서 ‘전문 어시스턴트’로 바꿉니다.

범용 AI는 코드를 작성할 수 있지만 사용자의 비즈니스까지 이해하지는 못합니다. Skills를 사용하면 비즈니스 지식, 팀 규칙, 내부 도구를 Agent에 연결해 실제 팀원처럼 일하게 만들 수 있습니다.

첫 Git commit formatter를 만든 뒤 지금까지 저희 팀에는 사내용 Skills가 20개 넘게 쌓였습니다. API 문서 검색, 코드 규칙 검사, Jira 이슈 처리, 신입 사원 onboarding까지 반복 작업을 조금씩 Agent에 넘기고 있습니다.

게을러진 것이 아닙니다. 더 가치 있는 일에 집중할 시간을 되찾은 것입니다. 아키텍처 설계, 어려운 문제 해결, 새로운 제품 개발처럼 사람이 해야 할 일에 집중할 수 있습니다. 반복되는 지식 검색과 절차 실행은 Agent에 맡기면 됩니다.

직접 시도하고 싶다면 작은 불편부터 시작해 보세요. 팀에서 계속 반복되는 질문이나 매일 열 번씩 되풀이하는 절차를 찾아 Skill 하나로 해결하는 겁니다.

곧 Agent가 단순한 도구가 아니라 팀의 확장이라는 점을 알게 될 것입니다.

Skills는 Agent에 전문 역량을 부여하는 열쇠입니다.