Antigravity에서 스킬을 만들려면 결국 SKILL.md 파일을 어떻게 작성하느냐가 핵심이에요. 이 파일 하나가 에이전트의 행동 방식을 결정짓기 때문에, 구조를 제대로 이해하고 작성하는 게 스킬 품질을 좌우해요.
SKILL.md가 필요한 이유
Antigravity의 스킬은 디렉토리 기반 패키지로 구성돼요. 이 패키지 안에서 SKILL.md는 필수 정의 파일 역할을 하고, 스크립트나 템플릿 같은 부가 자산은 선택적으로 함께 넣을 수 있어요.
대화가 시작되면 에이전트는 등록된 스킬들의 이름과 설명을 먼저 훑어봐요. 그러다 현재 작업과 관련 있어 보이는 스킬을 발견하면 그 SKILL.md 전체 내용을 읽어들여서 지침으로 삼아요. 즉 SKILL.md는 에이전트와 사람 사이의 약속 문서인 셈이에요.
기본 디렉토리 구조
Antigravity 스킬은 보통 .agent/skills/ 디렉토리 아래에 스킬별로 폴더를 만들어 관리해요. 각 폴더의 전형적인 구성은 다음과 같아요.
- SKILL.md – 스킬의 핵심 지침이 담긴 필수 파일이에요. 이름, 설명, 실행 절차가 이 안에 들어가요.
- scripts/ – 스킬 실행에 필요한 보조 스크립트를 넣는 선택적 폴더예요.
- examples/ – 참고할 만한 구현 예시를 모아두는 폴더예요.
- resources/ – 템플릿이나 기타 참고 자산을 담는 폴더예요.
SKILL.md 안에 들어가야 할 필수 항목
SKILL.md는 마크다운 형식으로 작성하되, 에이전트가 명확히 해석할 수 있도록 몇 가지 핵심 요소를 포함하는 게 좋아요.
가장 먼저 스킬의 이름과 한두 문장짜리 설명이 상단에 들어가야 해요. 이 설명은 에이전트가 현재 작업과 스킬의 관련성을 판단하는 근거가 되기 때문에 최대한 구체적으로 적는 게 중요해요.
그다음으로는 실제 작업 절차를 단계별로 서술해요. 막연한 지침보다는 “1단계에서 무엇을 확인하고, 2단계에서 무엇을 실행한다”는 식으로 순서를 명확히 밝히는 것이 에이전트의 작업 정확도를 높여줘요.
컨텍스트 최적화를 위한 설계 원칙
SKILL.md의 중요한 특징 중 하나는 필요할 때만 로드된다는 점이에요. 대화 시작 시에는 스킬 이름과 짧은 설명만 에이전트에게 노출되고, 실제로 관련 작업이 발생했을 때에만 전체 SKILL.md 내용이 컨텍스트에 로드돼요.
이런 구조 덕분에 여러 개의 스킬을 등록해둬도 에이전트가 불필요한 정보에 방해받지 않고, 컨텍스트 윈도우를 효율적으로 사용할 수 있어요. 따라서 SKILL.md를 작성할 때는 설명 부분은 짧고 명확하게, 본문 지침은 상세하게 작성하는 균형이 필요해요.
agents.md와의 관계
Antigravity의 자율 개발 파이프라인 구축 사례를 보면 agents.md와 skills.md를 함께 사용하는 패턴이 자주 등장해요. agents.md가 프로젝트 전반의 에이전트 동작 방식을 정의한다면, skills.md는 특정 작업에 특화된 세부 절차를 담당해요.
두 파일을 함께 활용하면 프로젝트 전체의 큰 그림과 개별 작업의 디테일을 모두 관리할 수 있어서, 복잡한 자율 파이프라인을 구축할 때 특히 유용해요.
실전 작성 팁
SKILL.md를 작성할 때는 실제 예시 코드나 명령어를 함께 넣어주는 것이 좋아요. 텍스트로만 설명하는 것보다 구체적인 예시가 있을 때 에이전트가 지침을 정확히 따르는 경향이 있어요.
- 구체적 예시 포함 – 실제 코드 스니펫이나 명령어를 함께 제시해요.
- 예외 상황 서술 – 일반적인 경우뿐 아니라 예외 케이스에 대한 처리 방법도 적어둬요.
- 간결한 설명 필드 – 상단 설명은 검색 및 매칭에 쓰이므로 핵심만 담아요.
SKILL.md는 결국 사람이 매번 반복 설명해야 했던 지침을 문서화해서 에이전트에게 위임하는 도구예요. 처음에는 작은 스킬부터 만들어보면서 구조에 익숙해지고, 점차 팀의 핵심 워크플로우로 확장해나가는 것을 추천해요.