Skills (스킬) - 오늘코드 Antigravity 튜토리얼

Agent Skills란? 공식 문서 #

공식 정의

스킬(Skills)은 에이전트 기능을 확장하기 위한 오픈 표준입니다. 스킬은 에이전트가 특정 작업을 수행할 때 따를 수 있는 지시사항이 담긴 SKILL.md 파일을 포함하는 폴더입니다.

스킬은 에이전트가 할 수 있는 것을 확장하는 재사용 가능한 지식 패키지입니다. 각 스킬은 다음을 포함합니다: 공식 문서

지시사항 — 특정 유형의 작업에 어떻게 접근할지에 대한 안내
모범 사례와 규칙 — 따라야 할 베스트 프랙티스와 컨벤션
스크립트와 리소스 (선택) — 에이전트가 사용할 수 있는 스크립트와 리소스

대화를 시작하면, 에이전트는 사용 가능한 스킬 목록(이름과 설명)을 확인합니다. 스킬이 현재 작업과 관련 있어 보이면, 에이전트는 전체 지시사항을 읽고 그에 따라 작업을 수행합니다. 공식 문서

쉬운 비유

Skills은 "데이터 분석 전문가의 노하우 패키지"입니다. 팀에 신입 분석가가 들어왔을 때, "웹 크롤링은 이 매뉴얼대로 해"라고 정리된 문서를 주면 그 분야의 전문가처럼 행동하듯, 에이전트에게 SKILL.md를 주면 해당 데이터 작업을 전문적으로 수행합니다.

Rules vs Skills 차이

Rules는 "항상 한국어로 주석 달기"처럼 행동 방식을 정의합니다.
Skills는 "EDA를 할 때 이런 순서로 분석하고 이런 차트를 그려라"처럼 전문 지식을 제공합니다.
즉, Rules는 "어떻게(How)" Skills는 "무엇을(What)" 알려주는 것입니다.

Skills vs Rules 차이 Rules & Workflows

구분	Rules (규칙)	Skills (스킬)
적용 시점	설정에 따라 항상 또는 조건부 적용 (4가지 모드)	관련 작업이 감지될 때만 활성화
성격	지속적인 제약, 전역 규칙	재사용 가능한 지식 패키지
데이터 분석 예시	"항상 UTF-8 인코딩을 사용해" "CSV 저장 시 BOM 없이 저장해"	"크롤링할 때 이 단계를 따라" "EDA 수행 시 이 체크리스트를 적용해"
비유	회사의 사규 (항상 지켜야 할 것)	업무 매뉴얼 (특정 작업 시 참고)

스킬 저장 위치 공식 문서 #

공식 문서에 따르면, 스킬은 두 가지 위치에 저장할 수 있습니다: 공식 문서

위치	범위
`<workspace-root>/.agents/skills/<skill-folder>/`	워크스페이스 전용
`~/.gemini/antigravity/skills/<skill-folder>/`	글로벌 (모든 워크스페이스)

워크스페이스 스킬

프로젝트별 워크플로에 적합합니다. 예를 들어 팀의 배포 프로세스, 테스트 컨벤션, 또는 "이커머스 고객 데이터 전처리"나 "센서 데이터 정제" 같은 프로젝트별 데이터 처리 절차를 정의하기 좋습니다. Git으로 팀원과 공유됩니다.

<workspace-root>/.agents/skills/<스킬폴더>/

글로벌 스킬

모든 프로젝트에서 사용 가능합니다. 개인 유틸리티나 어디서든 사용하고 싶은 범용 도구에 적합합니다. "EDA 분석", "기본 시각화", "통계 검정" 같은 공통 분석 스킬이 여기에 해당됩니다.

~/.gemini/antigravity/skills/<스킬폴더>/

참고: Antigravity는 현재 .agents/skills를 기본으로 사용하지만, .agent/skills (단수형)에 대한 하위 호환성도 유지하고 있습니다. 새 프로젝트에서는 .agents/skills/ (복수형)을 사용하세요. 공식 문서

스킬 만들기 공식 문서 #

공식 문서에 따른 스킬 생성 절차입니다. 모든 스킬에는 상단에 YAML frontmatter가 있는 SKILL.md 파일이 필요합니다. 공식 문서

스킬 디렉토리 중 하나에 폴더를 생성합니다. (예: .agents/skills/eda-analysis/)
해당 폴더 안에 SKILL.md 파일을 추가합니다.
YAML frontmatter를 파일 최상단에 작성합니다 — 모든 스킬에는 frontmatter가 필요합니다.

최소 스킬 템플릿: 아래 내용을 .agents/skills/hello/SKILL.md에 저장하면 바로 사용할 수 있는 스킬이 됩니다. Frontmatter의 trigger 필드가 에이전트가 이 스킬을 자동으로 선택하는 조건입니다.

      ---
trigger: "데이터 요약|기술통계|describe"
---

# 데이터 요약 스킬

데이터프레임 요약 요청 시 아래 순서로 분석합니다:

1. `df.shape`로 행/열 수 확인
2. `df.dtypes`로 데이터 타입 확인
3. `df.describe()`로 기술통계 출력
4. 결측치 비율을 백분율로 표시
5. 결과를 한국어 표로 정리
    

스킬 생성 검증 체크리스트

확인 항목	체크 방법	흔한 실수
파일 위치	`.agents/skills/이름/SKILL.md` 경로 확인	폴더 없이 루트에 SKILL.md 생성
Frontmatter	`---` 구분선이 파일 맨 위에 2개 있는지 확인	구분선 누락 또는 공백 포함
description 필드	필수 필드! 3인칭 + 핵심 키워드 포함	description 필드 자체를 누락
폴더명	소문자, 하이픈 구분 (예: `eda-analysis`)	공백이나 대문자 사용
새 대화 시작	스킬 생성/수정 후 새 대화에서 테스트	기존 대화에서 테스트하여 반영 안 됨

스킬 활성화 매커니즘

사용자의 요청이 어떻게 스킬 활성화로 이어지는지 시각적으로 살펴봅니다. 공식 문서

SKILL.md 기본 구조 공식 문서

      SKILL.md
      ---
name: my-data-skill
description: CSV/Excel 데이터에 대해 탐색적 데이터 분석(EDA)을 수행합니다.
  결측치 확인, 기술통계, 분포 시각화를 포함합니다.
---

에이전트를 위한 상세 지시사항을 여기에 작성합니다.

## 이 스킬을 사용할 때

- CSV/Excel 데이터를 탐색적으로 분석할 때
- 결측치 처리 방법을 결정해야 할 때

## 사용 방법

단계별 분석 가이드, 코드 예시, 패턴 등을 작성합니다.

## 주의사항

- 원본 데이터를 직접 수정하지 마세요 (복사본 사용)
- 인코딩 문제가 있을 수 있는 한국어 데이터 주의
    

Frontmatter 필드 공식 문서 #

공식 문서에서 정의하는 YAML frontmatter 필드입니다. 공식 문서

필드	필수 여부	설명
`name`	아니오	스킬의 고유 식별자 (소문자, 공백 대신 하이픈 사용). 제공하지 않으면 폴더 이름이 기본값으로 사용됩니다.
`description`	예	스킬이 무엇을 하고 언제 사용해야 하는지에 대한 명확한 설명. 에이전트가 스킬 적용 여부를 결정할 때 보는 텍스트입니다.

공식 팁: description은 3인칭으로 작성하고, 에이전트가 스킬의 관련성을 인식하는 데 도움이 되는 키워드를 포함하세요. 예: "Python 코드에 대해 pytest 규칙을 사용하여 유닛 테스트를 생성합니다." 공식 문서

좋은 description vs 나쁜 description

description은 에이전트가 "이 스킬을 활성화할지 말지"를 판단하는 핵심 기준입니다. 공식 문서

좋은 description

CSV 파일에서 데이터를 로드하고 기본 탐색적 데이터 분석(EDA)을 수행합니다. 결측치 확인, 기술통계, 분포 시각화를 포함합니다.

3인칭으로 작성되었고, 핵심 키워드(CSV, EDA, 결측치, 기술통계, 시각화)가 포함되어 에이전트가 관련 요청을 정확히 매칭합니다.

나쁜 description

데이터 관련 작업

너무 모호합니다. "데이터"라는 단어가 포함된 모든 대화에서 활성화될 수 있고, 정작 필요한 순간에 다른 스킬과 충돌할 수 있습니다.

스킬 폴더 구조 공식 문서 #

공식 문서에 따르면, SKILL.md가 유일한 필수 파일이지만, 추가 리소스를 포함할 수 있습니다. 에이전트는 스킬의 지시사항을 따를 때 이 파일들을 읽을 수 있습니다. 공식 문서

      디렉토리 구조
      .agents/skills/eda-analysis/
├── SKILL.md              # 필수: 분석 절차와 지시사항
├── scripts/
│   ├── validate_data.py    # 데이터 검증 스크립트
│   └── generate_profile.py # 데이터 프로파일링 자동화
├── examples/
│   ├── sample_eda.ipynb    # 참고용 EDA 노트북
│   └── sample_output.html  # 기대 결과물 예시
└── templates/
    └── report_template.md  # 분석 리포트 양식
    

에이전트가 스킬을 사용하는 방법 (Progressive Disclosure) 공식 문서 #

공식 문서에 따르면, 에이전트는 3단계의 Progressive Disclosure(점진적 공개) 패턴으로 스킬을 사용합니다: 공식 문서

발견 (Discovery) — 대화가 시작되면, 에이전트는 사용 가능한 스킬의 이름과 설명(description) 목록을 확인합니다.
활성화 (Activation) — 스킬이 현재 작업과 관련 있어 보이면, 에이전트는 SKILL.md의 전체 내용을 읽습니다.
실행 (Execution) — 에이전트는 스킬의 지시사항을 따라 작업을 수행합니다.

공식 문서 안내: 에이전트에게 스킬 사용을 명시적으로 말할 필요가 없습니다 — 컨텍스트를 기반으로 자동 판단합니다. 하지만 특정 스킬을 확실히 사용하고 싶다면 이름을 언급하면 됩니다. 공식 문서

모범 사례 (공식) 공식 문서 #

공식 문서에서 권장하는 스킬 작성 모범 사례입니다. 이 원칙들을 따르면 에이전트가 스킬을 더 정확하게 감지하고, 일관성 있게 작업을 수행합니다. 공식 문서

1. 스킬을 집중적으로 유지하세요

공식 권장: "각 스킬은 하나의 일을 잘 수행해야 합니다." "EDA + 크롤링 + 시각화 + 통계"를 하나에 넣지 마세요. EDA 스킬, 크롤링 스킬, 시각화 스킬, 통계 분석 스킬로 분리하면 각각 더 정확하게 활성화됩니다. 공식 문서

2. 명확한 설명을 작성하세요

공식 권장: "description은 에이전트가 스킬 사용 여부를 결정하는 기준입니다." 3인칭으로 작성하고, 에이전트가 관련성을 인식하는 데 도움이 되는 키워드를 포함하세요. 예: "Python 코드에 대해 pytest 규칙을 사용하여 유닛 테스트를 생성합니다." 공식 문서

3. 스크립트를 블랙박스로 사용하세요

공식 권장: "에이전트가 소스를 읽기보다 --help를 먼저 실행하도록 권장하세요." 에이전트가 스크립트의 소스 코드를 읽으면 컨텍스트 윈도우를 불필요하게 소모합니다. --help 출력을 기반으로 사용하도록 안내하세요. 공식 문서

4. 의사결정 트리를 포함하세요

공식 권장: "복잡한 스킬에는 에이전트가 올바른 접근 방식을 선택하도록 돕는 섹션을 추가하세요." 데이터 유형별 분석 방법 선택, 차트 유형 선택 등의 분기 로직을 제공하면 에이전트가 상황에 맞게 판단합니다. 공식 문서

데이터 분석에 적용한 공식 모범 사례

공식 원칙	데이터 분석 적용 예시
스킬을 집중적으로	EDA 스킬, 크롤링 스킬, 시각화 스킬, 통계 분석 스킬을 별도로 분리
명확한 설명	"CSV/Excel 데이터에 대해 탐색적 데이터 분석(EDA)을 수행합니다. 결측치 확인, 기술통계, 분포 시각화를 포함합니다."
스크립트를 블랙박스로	validate_data.py, generate_profile.py 등은 --help로 사용법 확인 후 실행
의사결정 트리	"숫자형 → 히스토그램, 범주형 → 막대 그래프" 분기 로직 제공

실전 예시: EDA(탐색적 데이터 분석) 스킬 공식 문서 #

공식 모범 사례를 적용한 EDA 스킬 예시입니다. CSV나 Excel 파일을 받았을 때 에이전트가 자동으로 체계적인 탐색적 데이터 분석을 수행합니다.

EDA 스킬 SKILL.md 전체 예시

      SKILL.md
      ---
name: eda-analysis
description: CSV/Excel 데이터에 대해 탐색적 데이터 분석(EDA)을 수행합니다.
  데이터 로딩, 결측치 확인, 기술통계, 분포 시각화, 상관관계 분석을 포함합니다.
---

# EDA (탐색적 데이터 분석) 스킬

CSV 또는 Excel 파일을 받으면 아래 단계를 순서대로 수행하세요.
각 단계의 결과를 사용자에게 설명하고, 발견한 특이사항을 강조하세요.

## 1단계: 데이터 로드
```python
import pandas as pd
df = pd.read_csv('data.csv', encoding='utf-8')
```

## 2단계: 기본 정보 확인
```python
print(f"데이터 크기: {df.shape[0]}행 x {df.shape[1]}열")
print(df.dtypes)
df.head()
```

## 3단계: 결측치 분석
```python
missing = df.isnull().sum()
missing_pct = (missing / len(df) * 100).round(2)
```

## 4단계: 기술통계
```python
print(df.describe())
```

## 5단계: 분포 시각화
```python
import matplotlib.pyplot as plt
import seaborn as sns
sns.histplot(df[col].dropna(), kde=True)
```

## 6단계: 상관관계 분석
```python
corr = df.select_dtypes(include='number').corr()
sns.heatmap(corr, annot=True, cmap='coolwarm')
```

## 체크리스트
- [ ] 모든 컬럼의 데이터 타입이 적절한가
- [ ] 결측치 현황을 파악했는가
- [ ] 이상치(outlier)가 있다면 확인했는가
- [ ] 주요 변수의 분포를 시각화했는가
- [ ] 변수 간 상관관계를 확인했는가
    

실행 시나리오

실행 시나리오: 이커머스 매출 분석

사용자: "sales_2024.csv 파일을 분석해줘. 어떤 제품이 잘 팔리는지 알고 싶어."

에이전트 (eda-analysis 스킬 자동 활성화):
1단계: 데이터를 로드했습니다. 총 15,240행 x 12열입니다.
2단계: 컬럼 정보 - product_name(object), category(object), price(float64), quantity(int64)...
3단계: 결측치 - category 컬럼에 2.3% (351건)의 결측치가 있습니다.
4단계: 평균 주문 금액 45,200원, 최대 주문 890,000원 (이상치 가능성)...
5단계: [히스토그램] price 분포가 오른쪽으로 치우쳐 있습니다.
6단계: price와 quantity 간 약한 음의 상관관계(r=-0.32) 발견.

실전 예시: 크롤링 스킬 공식 문서 #

공식 모범 사례 "스킬을 집중적으로 유지하세요"와 "의사결정 트리를 포함하세요"를 적용한 웹 크롤링 스킬입니다.

      SKILL.md
      ---
name: web-crawling
description: 웹사이트에서 데이터를 수집(크롤링/스크래핑)합니다.
  requests와 BeautifulSoup을 사용하며, robots.txt 확인과
  rate limiting을 포함한 안전한 크롤링 절차를 따릅니다.
---

# 웹 크롤링/스크래핑 스킬

## 크롤링 전 필수 확인사항

1. **robots.txt 확인** (반드시 먼저 수행)
2. **이용약관 확인**: 크롤링이 금지되어 있는지 사용자에게 알립니다
3. **Rate limiting**: 요청 사이에 최소 1초 대기

## 안티패턴

- robots.txt를 확인하지 않고 크롤링하지 마세요
- 1초 미만 간격으로 요청하지 마세요
- 에러 처리 없이 크롤링하지 마세요 (try/except 필수)
    

실행 시나리오: 뉴스 기사 수집

사용자: "tech-news.com에서 최근 AI 관련 기사 제목과 날짜를 수집해줘."

에이전트 (web-crawling 스킬 자동 활성화):
1. robots.txt 확인 완료: /articles/ 경로 크롤링 허용, Crawl-delay: 2초
2. 크롤링 시작: tech-news.com/articles?category=ai 페이지 순회
3. 총 5페이지, 47개 기사 수집 완료 (2초 간격 준수)
4. 결과 저장: ai_articles.csv (컬럼: title, date, url, summary)

실전 예시: 시각화 스킬 공식 문서 #

공식 모범 사례 "의사결정 트리를 포함하세요"를 적용한 데이터 시각화 스킬입니다. 데이터 유형에 따라 적절한 차트를 선택하는 분기 로직이 핵심입니다.

      SKILL.md
      ---
name: data-visualization
description: 데이터를 matplotlib과 seaborn으로 시각화합니다.
  차트 유형 선택 가이드, 스타일 컨벤션, 한글 폰트 설정을 포함합니다.
---

# 데이터 시각화 스킬

## 차트 유형 선택 가이드 (의사결정 트리)

### 변수 1개를 보여주고 싶다면:
- **숫자형** → 히스토그램 또는 박스플롯
- **범주형** → 막대 그래프 (가로 막대 권장 if 범주 > 5)

### 변수 2개의 관계를 보여주고 싶다면:
- **숫자 vs 숫자** → 산점도 (scatter plot)
- **범주 vs 숫자** → 박스플롯 또는 바이올린플롯

### 시간에 따른 변화를 보여주고 싶다면:
- **단일 계열** → 라인 차트
- **여러 계열 비교** → 멀티라인 차트 (최대 5개)
    

차트 선택 의사결정 트리

실행 시나리오: 시각화 요청

사용자: "sales_data에서 지역별 매출을 비교하는 그래프를 그려줘. 지역이 12개야."

에이전트 (data-visualization 스킬 자동 활성화):
의사결정 트리 적용: 범주형(지역) vs 숫자형(매출) → 범주 12개(>5개) → 가로 막대 그래프 선택
한글 폰트 설정 완료 (AppleGothic)
[가로 막대 그래프 생성] 서울 지역이 가장 높은 매출(2.3억), 제주가 최저(4,200만)입니다.

실전 예시: 통계 분석 스킬 공식 문서 #

가설 검정이 필요한 상황에서 적절한 통계 방법을 선택하고, 결과를 올바르게 해석하도록 안내하는 스킬입니다. 공식 모범 사례의 "의사결정 트리"가 핵심입니다.

      SKILL.md
      ---
name: stat-analysis
description: 통계적 가설 검정을 수행합니다. t-test, chi-square test,
  ANOVA 등의 선택 기준과 p-value 해석, 결과 보고 형식을 포함합니다.
---

# 통계 분석 스킬

## 검정 방법 선택 가이드 (의사결정 트리)

### 두 그룹의 평균 비교
- 정규분포 + 등분산 → **독립 t-test**
- 비정규분포 → **Mann-Whitney U**
- 같은 대상 전후 비교 → **대응 t-test**

### 세 그룹 이상의 비교
- 정규분포 → **일원배치 ANOVA**
- 비정규분포 → **Kruskal-Wallis**

### 범주형 변수 간 관계
- **카이제곱 검정**

## p-value 해석 가이드
p < 0.001 : 매우 강한 증거 (***)
p < 0.01  : 강한 증거 (**)
p < 0.05  : 유의한 증거 (*)
p >= 0.05  : 증거 불충분

주의: p-value만으로 결론을 내리지 마세요.
효과 크기(effect size)와 실질적 의미도 함께 보고하세요.
    

실행 시나리오: A/B 테스트 분석

사용자: "새로운 랜딩 페이지(B)가 기존(A)보다 전환율이 높은지 검정해줘."

에이전트 (stat-analysis 스킬 자동 활성화):
데이터 확인: 그룹A(n=1,024) 전환율 12.3%, 그룹B(n=1,031) 전환율 15.1%
검정 방법: 전환 여부(범주형) vs 그룹(범주형) → 카이제곱 검정 선택
결과: chi2=3.42, p=0.0321 (*), Cramer's V=0.041
해석: 그룹B의 전환율이 통계적으로 유의하게 높습니다(p<0.05). 다만 효과 크기(V=0.041)가 작으므로, 실제 비즈니스 임팩트는 제한적일 수 있습니다.

스킬 디버깅 가이드 공식 문서 #

스킬이 기대대로 동작하지 않을 때 참고하세요. 공식 문서

문제 1: 스킬이 활성화되지 않음

해결 방법:

description 키워드 확인 — 공식 팁: "description은 에이전트가 스킬 사용 여부를 결정하는 기준입니다." 사용자가 요청에 쓸 법한 키워드가 포함되어 있는지 확인하세요.
SKILL.md 파일 위치 확인 — .agents/skills/<skill-folder>/SKILL.md 경로가 정확한지 확인하세요.
frontmatter 문법 확인 — YAML frontmatter의 --- 구분선이 올바른지, description 필드가 존재하는지 확인하세요 (필수 필드).

해결 전 (나쁜 description)

description: 데이터 작업 도구

너무 모호하여 "CSV 분석해줘"와 매칭되지 않음

해결 후 (좋은 description)

description: CSV/Excel 데이터에 대해 탐색적 데이터 분석(EDA)을 수행합니다. 결측치 확인, 기술통계, 분포 시각화를 포함합니다.

3인칭 + 핵심 키워드로 정확히 매칭됨

문제 2: 스킬이 너무 자주 활성화됨

해결 방법:

description 범위 좁히기 — 공식 모범 사례 "각 스킬은 하나의 일을 잘 수행해야 합니다"를 따라, 넓은 표현 대신 구체적으로 작성하세요.
스킬 분리 — 하나의 스킬이 너무 많은 키워드를 커버하고 있다면 여러 스킬로 분리하세요.

문제 3: 스크립트 실행 오류

해결 방법:

--help 패턴 적용 — 공식 모범 사례 "스크립트를 블랙박스로 사용하세요"에 따라, SKILL.md에 "스크립트 실행 전 --help를 먼저 실행하세요"를 추가하세요.
의존성 명시 — 필요한 패키지를 SKILL.md에 명시하세요.

진단 플로차트

스킬이 기대대로 동작하지 않음
  → SKILL.md 파일이 존재하는가?
    → 아니오: 올바른 경로에 SKILL.md를 생성하세요
    → 예: frontmatter에 description이 있는가? (필수 필드)
      → 아니오: description 필드를 추가하세요
      → 예: description에 관련 키워드가 있는가?
        → 아니오: 사용자 요청에 맞는 키워드를 추가하세요
        → 예: 다른 스킬과 description이 겹치는가?
          → 예: description을 더 구체적으로 차별화하세요
          → 아니오: SKILL.md 본문의 지시사항을 점검하세요

실전 예시: Karpathy 코딩 가이드라인 스킬 #

AI 분야의 저명한 연구자 Andrej Karpathy가 공유한 LLM 코딩 가이드라인을 스킬로 만든 실제 사례입니다. LLM이 코드를 작성할 때 흔히 범하는 실수를 방지하기 위한 행동 규칙(Behavioral Guidelines)을 정의합니다.

출처: Karpathy의 X(Twitter) 포스트에서 공유된 LLM 코딩 경험을 기반으로, forrestchang/andrej-karpathy-skills 저장소에서 스킬로 구현되었습니다.

배경: Karpathy의 LLM 코딩 관찰

Karpathy는 에이전트 코딩 비중이 80%로 전환된 후, LLM이 반복적으로 범하는 실수 패턴을 발견했습니다.

4가지 핵심 원칙

이 스킬은 LLM의 코딩 품질을 높이기 위한 4가지 행동 원칙을 정의합니다.

1. Think Before Coding

가정하지 말고, 혼동을 숨기지 말고, 트레이드오프를 드러내라

가정을 명시적으로 진술할 것
여러 해석이 가능하면 제시하고, 조용히 하나를 선택하지 말 것
불확실하면 멈추고 질문할 것

2. Simplicity First

문제를 해결하는 최소한의 코드. 추측성 기능 금지.

요청받지 않은 기능 추가 금지
단일 사용 코드에 추상화 금지
200줄이 50줄로 가능하면 다시 작성

3. Surgical Changes

필요한 부분만 수정하고, 자기가 만든 불필요한 코드만 정리하라

인접 코드를 "개선"하지 말 것
깨지지 않은 것을 리팩토링하지 말 것
기존 스타일에 맞출 것

4. Goal-Driven Execution

성공 기준을 정의하고, 검증될 때까지 반복하라

"버그 수정" → "재현 테스트 작성 후 통과시키기"
멀티스텝 작업에 검증 포인트 명시
약한 기준("동작하게")은 지속적 확인 필요

SKILL.md 파일 전체 코드

아래가 실제 스킬 파일입니다. 이 내용을 .agents/skills/karpathy-guidelines/SKILL.md에 저장하면 바로 사용할 수 있습니다.

      SKILL.md
      ---
name: karpathy-guidelines
description: Behavioral guidelines to reduce common LLM
  coding mistakes. Use when writing, reviewing,
  or refactoring code to avoid overcomplication,
  make surgical changes, surface assumptions,
  and define verifiable success criteria.
license: MIT
---

# Karpathy Guidelines

Behavioral guidelines to reduce common LLM coding
mistakes, derived from Andrej Karpathy's observations
on LLM coding pitfalls.

**Tradeoff:** These guidelines bias toward caution
over speed. For trivial tasks, use judgment.

## 1. Think Before Coding

**Don't assume. Don't hide confusion. Surface tradeoffs.**

Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them
  - don't pick silently.
- If a simpler approach exists, say so.
  Push back when warranted.
- If something is unclear, stop. Name what's confusing.
  Ask.

## 2. Simplicity First

**Minimum code that solves the problem.
Nothing speculative.**

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't
  requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is
overcomplicated?" If yes, simplify.

## 3. Surgical Changes

**Touch only what you must.
Clean up only your own mess.**

When editing existing code:
- Don't "improve" adjacent code, comments,
  or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it
  differently.
- If you notice unrelated dead code,
  mention it - don't delete it.

When your changes create orphans:
- Remove imports/variables/functions that YOUR
  changes made unused.
- Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly
to the user's request.

## 4. Goal-Driven Execution

**Define success criteria. Loop until verified.**

Transform tasks into verifiable goals:
- "Add validation"
  → "Write tests for invalid inputs, then make
    them pass"
- "Fix the bug"
  → "Write a test that reproduces it, then make
    it pass"
- "Refactor X"
  → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let you loop independently.
Weak criteria ("make it work") require constant
clarification.
    

설치 및 사용 방법

방법	절차	적용 범위
방법 A: 직접 생성 권장	`.agents/skills/karpathy-guidelines/` 폴더를 만들고 위 SKILL.md 파일을 저장	해당 프로젝트에서만 적용
방법 B: 글로벌 설치	홈 디렉토리의 `~/.agents/skills/karpathy-guidelines/`에 저장	모든 프로젝트에 적용
방법 C: GitHub에서 클론	`git clone`으로 저장소를 받아 스킬 폴더에 복사	최신 업데이트 추적 가능

방법 A: 직접 생성 (단계별)

      터미널
      # 1. 스킬 디렉토리 생성
mkdir -p .agents/skills/karpathy-guidelines

# 2. SKILL.md 파일 생성 (위 내용을 붙여넣기)
nano .agents/skills/karpathy-guidelines/SKILL.md

# 3. 새 대화를 시작하면 스킬 자동 인식!
    

방법 C: GitHub에서 클론

      터미널
      # 저장소 클론
git clone https://github.com/forrestchang/andrej-karpathy-skills.git

# 스킬 폴더로 복사
cp -r andrej-karpathy-skills/skills/karpathy-guidelines \
  .agents/skills/karpathy-guidelines

# 복사 확인
cat .agents/skills/karpathy-guidelines/SKILL.md
    

적용 전 vs 적용 후 비교

같은 요청에 대해 스킬 적용 여부에 따라 에이전트의 행동이 어떻게 달라지는지 비교합니다.

상황	❌ 스킬 없이 (기본 행동)	✅ Karpathy 스킬 적용 후
요청이 모호할 때	자의적으로 해석하고 바로 코딩 시작	가정을 명시하고, 불확실한 부분을 질문
"로그인 기능 추가"	OAuth, 세션 관리, 비밀번호 복구까지 200줄+ 구현	요청된 핵심 기능만 50줄 이내로 구현
"이 버그 수정해줘"	버그 수정 + 주변 코드 리팩토링 + 스타일 변경	버그 재현 테스트 → 수정 → 테스트 통과 확인
멀티스텝 작업	한 번에 모든 것을 구현하려 시도	각 단계별 검증 포인트를 명시하고 순차 실행

이 스킬에서 배우는 작성 기법

Karpathy 가이드라인 스킬은 잘 만들어진 스킬의 모범 사례를 보여줍니다. 자신만의 스킬을 만들 때 참고하세요.

기법	이 스킬에서의 적용	왜 효과적인가
명확한 description	"Behavioral guidelines to reduce common LLM coding mistakes"	에이전트가 코딩/리뷰/리팩토링 상황에서 정확히 매칭
트레이드오프 명시	"These guidelines bias toward caution over speed"	사소한 작업에서는 유연하게 판단하도록 여지를 줌
금지 목록 (Don't)	"No features beyond what was asked", "Don't refactor things that aren't broken"	모호한 "잘 해라"보다 명확한 "하지 마라"가 LLM에 효과적
자기 점검 질문	"Would a senior engineer say this is overcomplicated?"	LLM에게 자체 검증 메커니즘을 제공
구체적 변환 예시	"Fix the bug" → "Write a test that reproduces it, then make it pass"	추상적 지시를 검증 가능한 목표로 바꾸는 패턴 학습

나만의 가이드라인 스킬 만들기

Karpathy 가이드라인은 범용 코딩 원칙입니다. 이를 기반으로 팀/프로젝트에 맞는 가이드라인 스킬을 만들어 보세요. 예를 들어 "우리 팀은 TypeScript strict 모드 사용", "모든 API 응답에 에러 핸들링 포함" 같은 팀 컨벤션을 스킬로 정의하면, 에이전트가 매번 일관된 코드를 생성합니다.

자주 묻는 질문 (FAQ) #

Q1. name 필드는 필수인가요?

name 필드는 필수가 아닙니다. 제공하지 않으면 폴더 이름이 기본값으로 사용됩니다. 반면 description 필드는 필수입니다.

필드	필수 여부	기본값	작성 규칙
`name`	선택	폴더 이름	소문자, 하이픈 구분 (예: `eda-analysis`)
`description`	필수	없음	3인칭, 키워드 포함
`trigger`	선택	자동 감지	자연어로 활성화 조건 기술

팁: name을 생략하면 폴더 이름이 그대로 사용되므로, 폴더명을 eda-analysis처럼 의미 있게 지으면 name 필드를 별도로 작성하지 않아도 됩니다.

공식 문서

Q2. 에이전트에게 "이 스킬을 써줘"라고 명시적으로 말해야 하나요?

명시적으로 말할 필요가 없습니다. 에이전트는 컨텍스트를 기반으로 자동 판단합니다. 하지만 특정 스킬을 확실히 사용하고 싶다면 이름을 언급할 수도 있습니다.

활성화 방식	사용자 입력 예시	결과
자동 감지 (권장)	"이 CSV를 분석해줘"	eda-analysis 스킬 자동 활성화
이름 직접 언급	"stat-analysis 스킬로 가설 검정해줘"	지정한 스킬 확실히 활성화
@ 멘션	"@eda-analysis 이 데이터 봐줘"	해당 스킬 강제 활성화

자동 감지가 안 될 때: description에 사용자가 요청할 만한 키워드가 빠져 있으면 자동 감지가 실패합니다. "분석", "EDA", "CSV" 등 핵심 키워드를 description에 포함하세요.

공식 문서

Q3. .agents/skills와 .agent/skills의 차이는 무엇인가요?

Antigravity는 현재 .agents/skills를 기본으로 사용하지만, .agent/skills에 대한 하위 호환성도 유지합니다.

경로	상태	사용 권장
`.agents/skills/` 복수형	현재 기본 경로	새 프로젝트에 권장
`.agent/skills/` 단수형	하위 호환성 유지	기존 프로젝트 계속 사용 가능

# 마이그레이션 방법 (필요한 경우)
mv .agent/skills .agents/skills
# .agent 폴더에 다른 파일이 없다면 삭제
rmdir .agent 2>/dev/null

주의: 두 경로가 동시에 존재하면 .agents/skills가 우선합니다. 혼동을 피하려면 하나의 경로만 사용하세요.

공식 문서

Q4. Skills과 Rules의 차이점은 무엇인가요?

Rules은 항상 적용되는 전역 규칙이고, Skills은 특정 작업에만 활성화되는 지식 패키지입니다.

구분	Rules (규칙)	Skills (스킬)
적용 시점	설정에 따라 항상 또는 조건부 적용	관련 작업이 감지될 때만 로드
역할	"어떻게" 행동할지 지시	"무엇을" 할지 절차 제공
비유	회사 사규 (항상 준수)	업무 매뉴얼 (필요할 때 참조)
예시	"UTF-8 인코딩으로 저장"	"EDA 수행 시 체크리스트"
파일 위치	`.agents/rules/`	`.agents/skills/스킬명/`
컨텍스트 비용	항상 소비 (간결하게 작성)	필요 시에만 소비 (상세 가능)

선택 기준: 모든 대화에서 지켜야 할 규칙이면 Rules, 특정 작업의 상세 절차면 Skills을 사용하세요. 예를 들어 "한국어로 응답"은 Rules, "EDA 분석 절차"는 Skills에 적합합니다.

Rules & Workflows

Q5. 하나의 대화에서 여러 스킬이 동시에 활성화될 수 있나요?

네, 가능합니다. 에이전트는 대화 컨텍스트를 분석하여 관련된 모든 스킬을 활성화합니다.

자동 복합 활성화: "이 웹사이트에서 데이터를 크롤링해서 분석해줘" → web-crawling + eda-analysis 동시 활성화
순차 활성화: 대화가 진행되면서 새로운 작업이 감지되면 추가 스킬이 활성화될 수 있음
우선순위: description이 더 구체적으로 매칭되는 스킬이 우선 적용

모범 사례: 각 스킬을 하나의 작업에 집중시키면 더 정확한 활성화가 가능합니다. "데이터 분석 + 시각화 + 보고서" 를 하나의 스킬에 넣기보다, EDA / Visualization / Reporting 으로 분리하세요.

공식 문서

Q6. 기존 스킬을 수정하면 바로 반영되나요?

SKILL.md 파일을 수정하고 저장하면 다음 대화부터 즉시 반영됩니다.

스킬 파일 수정: SKILL.md 내용을 편집하고 저장
새 대화 시작: 에이전트는 대화 시작 시 스킬 목록을 새로 스캔
변경 내용 적용: 수정된 description, 절차, 체크리스트가 반영됨

주의: 진행 중인 대화에서는 이미 로드된 스킬 내용이 유지됩니다. 변경 사항을 즉시 적용하려면 새 대화를 시작해야 합니다. 스킬을 삭제하는 경우에도 마찬가지입니다.

공식 문서

Q7. description 작성 시 가장 중요한 팁은?

공식 문서: "description을 3인칭으로 작성하고, 에이전트가 스킬의 관련성을 인식하는 데 도움이 되는 키워드를 포함하세요."

3인칭으로 작성: "분석합니다", "생성합니다", "수행합니다" 형태로 작성
핵심 키워드 포함: 사용자가 요청할 때 쓸 법한 단어를 반드시 포함
구체적 범위 명시: 어떤 파일 형식, 어떤 작업인지 명확히
간결하게 유지: 1~2문장으로 핵심만 전달

스킬 유형	좋은 description 예시
EDA	"CSV/Excel 데이터에 대해 탐색적 데이터 분석(EDA)을 수행합니다. 결측치 확인, 기술통계, 분포 시각화를 포함합니다."
테스트	"Python 코드에 대해 pytest 규칙을 사용하여 유닛 테스트를 생성합니다."
크롤링	"웹 페이지에서 구조화된 데이터를 추출합니다. BeautifulSoup과 Selenium을 활용하여 테이블, 리스트 등을 수집합니다."
시각화	"데이터를 matplotlib/seaborn 차트로 시각화합니다. 한글 폰트 설정과 스타일 가이드를 포함합니다."

공식 문서

Agent Skills (에이전트 스킬)

Agent Skills란? 공식 문서 #

Skills vs Rules 차이 Rules & Workflows

스킬 저장 위치 공식 문서 #

워크스페이스 스킬

글로벌 스킬

스킬 만들기 공식 문서 #

스킬 생성 검증 체크리스트

스킬 활성화 매커니즘

SKILL.md 기본 구조 공식 문서

Frontmatter 필드 공식 문서 #

좋은 description vs 나쁜 description

좋은 description

나쁜 description

스킬 폴더 구조 공식 문서 #

에이전트가 스킬을 사용하는 방법 (Progressive Disclosure) 공식 문서 #

모범 사례 (공식) 공식 문서 #

1. 스킬을 집중적으로 유지하세요

2. 명확한 설명을 작성하세요

3. 스크립트를 블랙박스로 사용하세요

4. 의사결정 트리를 포함하세요

데이터 분석에 적용한 공식 모범 사례

실전 예시: EDA(탐색적 데이터 분석) 스킬 공식 문서 #

EDA 스킬 SKILL.md 전체 예시

실행 시나리오

실전 예시: 크롤링 스킬 공식 문서 #

실전 예시: 시각화 스킬 공식 문서 #

차트 선택 의사결정 트리

실전 예시: 통계 분석 스킬 공식 문서 #

스킬 디버깅 가이드 공식 문서 #

문제 1: 스킬이 활성화되지 않음

문제 2: 스킬이 너무 자주 활성화됨

문제 3: 스크립트 실행 오류

진단 플로차트

실전 예시: Karpathy 코딩 가이드라인 스킬 #

배경: Karpathy의 LLM 코딩 관찰

4가지 핵심 원칙

1. Think Before Coding

2. Simplicity First

3. Surgical Changes

4. Goal-Driven Execution

SKILL.md 파일 전체 코드

설치 및 사용 방법

방법 A: 직접 생성 (단계별)

방법 C: GitHub에서 클론

적용 전 vs 적용 후 비교

이 스킬에서 배우는 작성 기법

자주 묻는 질문 (FAQ) #

공식 문서 및 관련 링크