# 스킬 작성 가이드 (Antigravity CLI)

하네스에서 생성하는 스킬의 품질을 높이기 위한 상세 작성 가이드. SKILL.md Phase 4의 보충 레퍼런스.

---

## 목차

1. [Description 작성 패턴](#1-description-작성-패턴)
2. [본문 작성 스타일](#2-본문-작성-스타일)
3. [출력 형식 정의 패턴](#3-출력-형식-정의-패턴)
4. [예시 작성 패턴](#4-예시-작성-패턴)
5. [Progressive Disclosure 패턴](#5-progressive-disclosure-패턴)
6. [스크립트 번들링 판단 기준](#6-스크립트-번들링-판단-기준)
7. [데이터 스키마 표준](#7-데이터-스키마-표준)
8. [스킬에 포함하지 않을 것](#8-스킬에-포함하지-않을-것)

---

## 1. Description 작성 패턴

Description은 스킬의 유일한 트리거 메커니즘이다. Antigravity CLI는 `available_skills` 목록에서 name + description만 보고 스킬 사용 여부를 결정한다.

### 트리거 메커니즘 이해

Antigravity CLI는 기본 도구로 쉽게 처리할 수 있는 단순 작업(단순 파일 읽기 등)에는 스킬을 쉽게 호출하지 않는 성향이 있다. 복잡하고 다단계이며 전문성이 강력하게 요구되는 작업일수록 스킬 트리거 확률이 높다.

### 작성 원칙

1. **스킬이 하는 일** + **구체적 트리거 상황**을 모두 기술.
2. 유사하지만 트리거하면 안 되는 경우를 구분하는 경계 조건 명시.
3. 약간 "pushy"하게 — 트리거 결정을 보수적으로 판단하려는 경향을 해소.

### 좋은 예시

```yaml
description: "PDF 파일 읽기, 텍스트/테이블 추출, 병합, 분할, 회전, 워터마크,
  암호화/복호화, OCR 등 모든 PDF 작업을 수행. .pdf 파일을 언급하거나
  PDF 산출물을 요청하면 반드시 이 스킬을 사용할 것. 단순히 PDF를
  '읽어달라'는 요청이 아닌 변환/편집/분석이 필요할 때 특히 유용."
```

```yaml
description: "엑셀/CSV/TSV 파일의 열 추가, 수식 계산, 서식, 차트,
  데이터 정제를 포함한 모든 스프레드시트 작업. 사용자가 스프레드시트
  파일을 언급하면 — 심지어 캐주얼하게('다운로드 폴더의 xlsx')라고만
  해도 — 이 스킬을 사용할 것."
```

### 나쁜 예시

- `"데이터를 처리하는 스킬"` — 너무 모호, 어떤 파일/작업인지 불분명.
- `"PDF 관련 작업"` — 구체적 동작 나열 없음, 트리거 상황 미기술.

---

## 2. 본문 작성 스타일

### Why-First 원칙

LLM은 이유를 이해하면 엣지 케이스에서도 올바르게 판단한다. 강압적 규칙보다 맥락 전달이 효과적이다.

**나쁜 예:**
```markdown
ALWAYS use pdfplumber for table extraction. NEVER use PyPDF2 for tables.
```

**좋은 예:**
```markdown
테이블 추출에는 pdfplumber를 사용한다. PyPDF2는 텍스트 추출에 특화되어
있어 테이블의 행/열 구조를 보존하지 못하기 때문이다. pdfplumber는
셀 경계를 인식하여 구조화된 데이터를 반환한다.
```

### 일반화 원칙

피드백이나 테스트 결과에서 문제가 발견되면, 특정 예시에만 맞는 좁은 수정 대신 **원리 수준에서 일반화**한다.

**오버피팅 수정:**
```markdown
"Q4 매출" 열이 있으면 해당 열을 숫자로 변환하라.
```

**일반화된 수정:**
```markdown
열 이름에 "매출", "금액", "수량" 등 수치를 암시하는 키워드가 있으면
해당 열을 숫자 타입으로 변환한다. 변환 실패 시 원본 값을 유지한다.
```

### 명령형 어조

"~합니다", "~할 수 있습니다" 대신 "~한다", "~하라" 형태를 사용한다. 스킬은 지시서이다.

### 다국어 및 영문 작성 원칙

사용자가 영어로 요청을 하거나, 프로젝트의 글로벌 협업 환경/코드베이스 표준이 영어인 경우, 스킬(`SKILL.md`)은 완벽하게 영어로 작성되어야 한다.

1. **YAML Frontmatter Description**: Antigravity CLI가 이해하기 쉽도록 구체적이고 명확한 영어 기술 용어를 사용하여 "pushy"하게 작성한다.
2. **자연스러운 영어 어조 (Technical English)**:
   - 지시조의 동사 원형(Imperative Mood)으로 작성한다. (예: "Create", "Extract", "Validate" 등. "~is used to" 나 "~should be" 와 같은 수동태 대신 능동태 명령형 권장)
   - 설명식 문장에서는 3인칭 단수/현재형 또는 간결한 문장 구조를 사용한다.
3. **용어 통일**: 한국어 스킬에서의 "서브에이전트", "산출물", "오케스트레이터" 등의 용어는 영문 스킬에서 "subagent", "artifact", "orchestrator"로 번역 및 정의를 일관되게 사용한다.

### 컨텍스트 절약

컨텍스트 윈도우는 공공재다. 모든 문장이 토큰 비용을 정당화하는지 자문한다:
- "Antigravity CLI가 이미 알고 있는 내용인가?" → 삭제.
- "이 설명이 없으면 에이전트가 실수하는가?" → 유지.
- "구체적 예시 하나가 긴 설명보다 효과적인가?" → 예시로 대체.

---

## 3. 출력 형식 정의 패턴

산출물의 형식이 중요한 스킬에서 사용:

```markdown
## 보고서 구조
다음 템플릿을 정확히 따른다:

# [제목]
## 요약
## 핵심 발견
## 권장 사항
```

형식 정의는 간결하게, 실제 예시를 포함하면 더 효과적이다.

---

## 4. 예시 작성 패턴

예시는 긴 설명보다 효과적이다:

```markdown
## 커밋 메시지 형식

**예시 1:**
입력: JWT 토큰 기반 사용자 인증 추가
출력: feat(auth): JWT 기반 인증 구현

**예시 2:**
입력: 로그인 페이지에서 비밀번호 표시 버튼이 동작하지 않는 버그 수정
출력: fix(login): 비밀번호 표시 토글 버튼 동작 수정
```

---

## 5. Progressive Disclosure 패턴

### 패턴 1: 도메인별 분리

```
bigquery-plugin/
└── skills/
    └── bigquery-skill/
        ├── SKILL.md (개요 + 도메인 선택 가이드)
        └── rules/
            ├── finance.md (매출, 빌링 메트릭)
            ├── sales.md (기회, 파이프라인)
            └── product.md (API 사용량, 기능)
```

사용자가 매출에 대해 물으면 `finance.md`만 로드하여 컨텍스트 효율을 최대화한다.

### 패턴 2: 조건부 상세

```markdown
# DOCX 처리

## 문서 생성
docx-js로 새 문서를 생성한다. → [DOCX-JS.md](rules/docx-js.md) 참조.

## 문서 편집
단순 편집은 XML을 직접 수정.
**추적 변경이 필요하면**: [REDLINING.md](rules/redlining.md) 참조.
```

### 패턴 3: 대형 레퍼런스 파일 구조

300줄 이상의 reference 파일은 상단에 목차를 포함한다:

```markdown
# API 레퍼런스

## 목차
1. [인증](#인증)
2. [엔드포인트 목록](#엔드포인트-목록)
3. [에러 코드](#에러-코드)
4. [레이트 리밋](#레이트-리밋)

---

## 인증
...
```

---

## 6. 스크립트 번들링 판단 기준

테스트 실행에서 에이전트들의 실행 이력을 관찰한다. 다음 패턴이 보이면 번들링 대상:

| 신호 | 조치 |
|:---|:---|
| 3개 테스트 중 3개에서 동일한 헬퍼 스크립트 생성 | `scripts/`에 번들링 |
| 매번 같은 pip install/npm install 실행 | 스킬에 의존성 설치 단계 명시 |
| 동일한 다단계 접근법 반복 | 스킬 본문에 표준 절차로 기술 |
| 매번 비슷한 에러 후 같은 회피책 적용 | 스킬에 알려진 문제와 해결법 기술 |

번들링된 스크립트는 반드시 실행 테스트를 거친다.

---

## 7. 데이터 스키마 표준

스킬 간 데이터 교환의 일관성을 위해 표준 스키마를 사용한다. 하네스에서 생성하는 스킬의 테스트/평가에 사용할 수 있다.

### eval_metadata.json

각 테스트 케이스의 메타데이터:

```json
{
  "eval_id": 0,
  "eval_name": "descriptive-name-here",
  "prompt": "사용자의 작업 프롬프트",
  "assertions": [
    "산출물에 X가 포함되어 있다",
    "Y 형식으로 파일이 생성되었다"
  ]
}
```

### grading.json

assertion 기반 채점 결과:

```json
{
  "expectations": [
    {
      "text": "산출물에 '서울'이 포함됨",
      "passed": true,
      "evidence": "3번째 단계에서 '서울 지역 데이터 추출' 확인"
    }
  ],
  "summary": {
    "passed": 2,
    "failed": 1,
    "total": 3,
    "pass_rate": 0.67
  }
}
```

**필드명 주의:** `text`, `passed`, `evidence`를 정확히 사용한다 (`name`/`met`/`details` 등 변형 금지).

### timing.json

실행 시간/토큰 측정:

```json
{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}
```

---

## 8. 스킬에 포함하지 않을 것

- README.md, CHANGELOG.md, INSTALLATION_GUIDE.md 등 부가 문서.
- 스킬 생성 과정의 메타 정보 (테스트 결과, 반복 이력).
- 사용자 대상 설명서 (스킬은 AI 에이전트를 위한 지시서).
- 이미 Antigravity CLI가 알고 있는 일반적 지식.