278 lines
8.9 KiB
Markdown
278 lines
8.9 KiB
Markdown
# 스킬 작성 가이드 (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가 알고 있는 일반적 지식.
|