1. Skills란?

Skills는 Agent의 기능을 확장하는 재사용 가능한 지식 패키지입니다.

특정 작업에 대한 지침, 모범 사례, 스크립트 등을 담아 Agent에게 제공합니다.

1.1 쉽게 이해하기

Skills를 전문가의 노하우를 담은 매뉴얼이라고 생각하면 됩니다.

예를 들어, "코드 리뷰를 어떻게 해야 하는지" 정리해둔 문서가 있다면, Agent가 그 문서를 읽고 동일한 방식으로 코드 리뷰를 수행합니다.

1.2 Rules vs Workflows vs Skills 비교

Chapter 6-3에서 배운 Rules, Workflows와 Skills의 차이점을 비교해봅시다.

1.3 Skills가 필요한 상황

1.4 Skills의 구성 요소

각 Skill에는 다음 내용이 포함됩니다.

2. Skills의 종류

Skills는 저장 위치에 따라 두 가지 종류로 나뉩니다.

2.1 Workspace Skills (프로젝트별)

현재 프로젝트에만 적용되는 Skill입니다.

저장 위치

<프로젝트-폴더>/.agents/skills/<skill-폴더>/

예시

my-project/
└── .agents/
    └── skills/
        └── my-skill/
            └── SKILL.md

사용 사례

• 이 프로젝트만의 배포 절차
• 팀 코딩 컨벤션
• 프로젝트 특화 테스트 방법

2.2 Global Skills (전역)

모든 프로젝트에 적용되는 Skill입니다.

저장 위치

# Mac/Linux
~/.gemini/antigravity/skills/<skill-폴더>/

# Windows
C:\Users\사용자이름\.gemini\antigravity\skills\<skill-폴더>\

사용 사례

• 개인적으로 자주 사용하는 도구
• 범용적인 코드 리뷰 가이드
• 공통 문서 작성 템플릿

2.3 두 종류의 차이 정리

3. Skill 만들기

3.1 기본 구조

Skill을 만들려면 폴더와 SKILL.md 파일이 필요합니다.

.agents/skills/
└── my-skill/          ← 폴더 이름 = Skill 이름
    └── SKILL.md       ← 필수 파일

3.2 SKILL.md 파일 형식

SKILL.md 파일은 YAML Frontmatter와 마크다운 본문으로 구성됩니다.

---
name: my-skill
description: 이 Skill이 하는 일을 설명합니다. Agent가 이 설명을 보고 Skill을 사용할지 결정합니다.
---

# My Skill

Agent가 따라야 할 상세 지침을 여기에 작성합니다.

## 언제 이 Skill을 사용하나요?

- 이런 상황에서 사용합니다
- 이런 작업에 유용합니다

## 사용 방법

단계별 안내, 규칙, 패턴 등을 작성합니다.

3.3 Frontmatter 필드 설명

description: Python 코드에 대한 유닛 테스트를 pytest 규칙에 맞게 생성합니다.

description: 테스트 관련 Skill

4. Skill 폴더 구조

SKILL.md 외에도 추가 리소스를 포함할 수 있습니다.

.agents/skills/my-skill/
├── SKILL.md          ← 메인 지침 (필수)
├── scripts/          ← 헬퍼 스크립트 (선택)
│   └── validate.sh
├── examples/         ← 참고용 예시 코드 (선택)
│   └── sample.js
└── resources/        ← 템플릿, 기타 자료 (선택)
    └── template.md

Agent는 SKILL.md의 지침을 따르면서 필요할 때 이 파일들을 참조할 수 있습니다.

그림 6-13: Skill 폴더 구조 예시

5. Agent가 Skills를 사용하는 방법

Skills는 점진적 공개(Progressive Disclosure) 패턴으로 작동합니다.

5.1 작동 흐름

1. Discovery (발견)
   Agent가 사용 가능한 Skills 목록을 확인
   (이름과 description만 확인)
        ↓
2. Activation (활성화)
   작업과 관련된 Skill이 있으면
   SKILL.md 전체 내용을 읽음
        ↓
3. Execution (실행)
   Skill의 지침을 따라 작업 수행

5.2 자동 vs 수동 사용

수동으로 Skill 사용 요청하기

my-skill Skill을 사용해서 이 PR을 검토해주세요.

6. 실습 1: 코드 리뷰 Skill 만들기

간단한 코드 리뷰 Skill을 만들어봅시다. 이 Skill을 만들면 Agent가 일관된 기준으로 코드를 리뷰해줍니다.

6.1 1단계: 프로젝트 폴더 준비

먼저 테스트용 프로젝트 폴더를 만들거나 기존 프로젝트를 사용합니다.

# 테스트 폴더 생성 (선택)
mkdir skill-test
cd skill-test

6.2 2단계: Skill 폴더 생성

프로젝트 폴더에서 다음 구조를 만듭니다.

Mac/Linux

mkdir -p .agents/skills/code-review

Windows (PowerShell)

New-Item -ItemType Directory -Path ".agent\skills\code-review" -Force

Windows (CMD)

mkdir .agent\skills\code-review

생성 후 폴더 구조를 확인합니다.

skill-test/
└── .agents/
    └── skills/
        └── code-review/
            (여기에 SKILL.md를 만들 예정)

6.3 3단계: SKILL.md 작성

.agents/skills/code-review/SKILL.md 파일을 생성하고 다음 내용을 작성합니다.

Anti-Gravity Editor에서 생성하는 방법

1. 파일 탐색기에서 .agents/skills/code-review 폴더 우클릭
2. "New File" 선택
3. 파일명: SKILL.md
4. 아래 내용 붙여넣기

---
name: code-review
description: 코드 변경사항을 검토하여 버그, 스타일 문제, 모범 사례를 확인합니다. PR 검토나 코드 품질 확인 시 사용합니다.
---

# 코드 리뷰 Skill

코드를 검토할 때 다음 단계를 따릅니다.

## 리뷰 체크리스트

### 1. 정확성 (Correctness)
- 코드가 의도한 대로 동작하는가?
- 엣지 케이스가 처리되었는가?
- 에러 처리가 적절한가?

### 2. 가독성 (Readability)
- 변수/함수 이름이 명확한가?
- 주석이 필요한 곳에 있는가?
- 코드 구조가 이해하기 쉬운가?

### 3. 스타일 (Style)
- 프로젝트 코딩 컨벤션을 따르는가?
- 일관된 포맷팅이 적용되었는가?

### 4. 성능 (Performance)
- 명백한 비효율이 있는가?
- 불필요한 반복이나 중복이 있는가?

## 피드백 방법

- 구체적으로 어떤 문제인지 설명
- 왜 문제인지 이유 제시
- 가능하면 대안 제시

## 피드백 형식 예시

```
### 문제: [문제 요약]
- <strong>위치</strong>: [파일명:라인번호]
- <strong>문제점</strong>: [무엇이 문제인지]
- <strong>이유</strong>: [왜 문제인지]
- <strong>제안</strong>: [어떻게 수정하면 좋을지]
```

6.4 4단계: Skill 테스트

Anti-Gravity에서 해당 프로젝트를 워크스페이스로 열고, Agent에게 코드 리뷰를 요청해봅니다.

테스트용 코드 (Agent에게 전달)

이 함수를 리뷰해주세요.

function calc(a,b,c) {
  if(a>0) {
    return a+b*c
  }
  return 0
}

6.5 5단계: 결과 확인

Agent가 code-review Skill을 인식하면, 체크리스트에 따라 체계적으로 리뷰를 수행합니다.

예상되는 피드백

그림 6-14: code-review Skill을 사용한 리뷰 결과

7. 실습 2: 새 페이지 생성 Skill 만들기

웹 프로젝트에서 새 페이지를 생성할 때 사용하는 Skill을 만들어봅시다.

7.1 1단계: Skill 폴더 생성

# Mac/Linux
mkdir -p .agents/skills/new-page

# Windows (PowerShell)
New-Item -ItemType Directory -Path ".agent\skills\new-page" -Force

7.2 2단계: SKILL.md 작성

.agents/skills/new-page/SKILL.md

---
name: new-page
description: 웹 프로젝트에서 새 HTML 페이지를 생성합니다. 표준 구조와 스타일을 자동으로 적용합니다.
---

# 새 페이지 생성 Skill

새 HTML 페이지를 만들 때 다음 규칙을 따릅니다.

## 파일 구조

새 페이지는 다음 위치에 생성합니다:
- HTML 파일: 루트 폴더 또는 pages/ 폴더
- 페이지 전용 CSS: css/ 폴더
- 페이지 전용 JS: js/ 폴더

## HTML 기본 구조

모든 페이지는 다음 구조를 따릅니다.

```html
<!DOCTYPE html>
<html lang="ko">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>페이지 제목</title>
    <link rel="stylesheet" href="css/style.css">
    <link rel="stylesheet" href="css/페이지명.css">
</head>
<body>
    <header>
        <!-- 공통 헤더 -->
    </header>

    <main>
        <!-- 페이지 콘텐츠 -->
    </main>

    <footer>
        <!-- 공통 푸터 -->
    </footer>

    <script src="js/main.js"></script>
    <script src="js/페이지명.js"></script>
</body>
</html>
```

## 네이밍 규칙

- 파일명: 케밥-케이스 (예: about-us.html)
- CSS 클래스: 케밥-케이스 (예: page-header)
- JavaScript 변수: camelCase (예: pageTitle)

## 체크리스트

새 페이지 생성 후 확인:

- [ ] HTML 유효성 검사
- [ ] 반응형 레이아웃 적용
- [ ] 접근성 기본 요소 (alt, aria-label 등)
- [ ] 네비게이션에 링크 추가

7.3 3단계: 테스트

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

연락처 페이지를 만들어주세요.
이름, 이메일, 메시지를 입력받는 폼이 있어야 합니다.

Agent가 new-page Skill을 사용하여 표준 구조에 맞게 페이지를 생성합니다.

예상 결과

• contact.html 또는 pages/contact.html 생성
• css/contact.css 생성
• js/contact.js 생성 (필요시)
• Skill에 정의된 HTML 기본 구조 적용
• 케밥-케이스 네이밍 규칙 적용

그림 6-15: new-page Skill을 사용한 페이지 생성 결과

8. Best Practices

1. 하나의 Skill은 하나의 목적

"모든 것을 하는" Skill 대신, 각 Skill이 하나의 작업에 집중하도록 합니다.

❌ do-everything Skill
✅ code-review Skill
✅ new-page Skill
✅ deploy Skill

2. 명확한 description 작성

Agent가 Skill 사용 여부를 판단하는 핵심입니다.

❌ description: 유용한 Skill입니다.
✅ description: Python 코드에 대한 유닛 테스트를 pytest 규칙에 맞게 생성합니다. 테스트 작성이나 TDD 시 사용합니다.

3. 스크립트는 블랙박스로 취급

Skill에 스크립트가 포함된 경우, Agent가 스크립트 전체를 읽기보다 --help 옵션으로 사용법만 확인하도록 안내합니다.

## 유효성 검사 스크립트

`scripts/validate.sh` 스크립트로 검증을 수행합니다.

사용 전 `./scripts/validate.sh --help`로 옵션을 확인하세요.

4. 의사결정 트리 포함

복잡한 Skill에는 상황별 대응 방법을 포함합니다.

## 상황별 대응

### 테스트가 실패하는 경우
1. 먼저 에러 메시지 확인
2. 관련 코드 위치 파악
3. 수정 후 재실행

### 의존성 오류인 경우
1. package.json 확인
2. npm install 실행
3. 버전 호환성 확인

9. Skill 관리

9.1 Skill 목록 확인

현재 프로젝트에서 사용 가능한 Skills를 확인하려면 파일 탐색기에서 .agents/skills/ 폴더를 확인합니다.

프로젝트/
└── .agents/
    └── skills/
        ├── code-review/     ← Skill 1
        │   └── SKILL.md
        └── new-page/        ← Skill 2
            └── SKILL.md

9.2 Skill 수정

SKILL.md 파일을 직접 편집하면 됩니다. 변경 사항은 즉시 적용됩니다.

9.3 Skill 삭제

Skill 폴더 전체를 삭제하면 됩니다.

9.4 Skill 공유 (팀 협업)

Workspace Skills는 .agents/skills/ 폴더에 저장되므로, Git에 커밋하면 팀원과 공유할 수 있습니다.

git add .agents/skills/
git commit -m "코드 리뷰 Skill 추가"
git push

10. 유용한 Skill 아이디어

다음은 만들어두면 유용한 Skill 예시입니다.

11. 정리

12. 다음 단계

Agent를 커스터마이징하는 방법(Rules, Workflows, Skills)을 모두 배웠습니다.

다음 챕터에서는 Agent가 생성하는 산출물(Artifacts)을 활용하는 방법을 배워봅시다.