Agent Skills (에이전트 스킬)

Agent Skills란? 공식 문서 #

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

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

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

Skills vs Rules 차이 Rules & Workflows

스킬 저장 위치 공식 문서 #

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

스킬 만들기 공식 문서 #

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

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

스킬 생성 검증 체크리스트

스킬 활성화 매커니즘

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

SKILL.md 기본 구조 공식 문서

Frontmatter 필드 공식 문서 #

SKILL.md 맨 위에 위치하는 YAML frontmatter는 에이전트가 스킬을 언제, 어떻게 활성화할지 결정하는 핵심 메타데이터입니다. frontmatter가 없거나 description이 비어 있으면 에이전트가 스킬을 인식하지 못해 자동 활성화가 전혀 이루어지지 않습니다. 스킬 파일을 만든 뒤 가장 먼저 채워야 할 항목입니다. 공식 문서

좋은 description vs 나쁜 description

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

스킬 폴더 구조 공식 문서 #

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

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

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

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

Progressive Disclosure 단계별 세부 동작

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

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

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

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

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

EDA 스킬 SKILL.md 전체 예시

실행 시나리오

EDA 스킬에 오류 처리 추가하기

실제 데이터는 인코딩 오류, 잘못된 파일 경로, 예상치 못한 컬럼 구조 등 다양한 예외 상황이 발생할 수 있습니다. SKILL.md에 오류 처리 지침을 명시하면 에이전트가 이런 상황에서도 올바르게 대응합니다.

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

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

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

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

차트 선택 의사결정 트리

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

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

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

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

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

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

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

진단 플로차트

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

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

배경: Karpathy의 LLM 코딩 관찰

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

4가지 핵심 원칙

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

SKILL.md 파일 전체 코드

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

설치 및 사용 방법

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

방법 C: GitHub에서 클론

적용 전 vs 적용 후 비교

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

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

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

실전 예시: 전역 코드 리뷰 스킬 (code-review) #

공식 문서의 주요 예시입니다. 글로벌 스킬로 설치하면 모든 워크스페이스에서 사용할 수 있습니다. PR 검토나 코드 품질 확인 시 자동으로 활성화됩니다.

스킬 디렉토리 생성

SKILL.md 작성

사용 방법

에이전트가 code-review 스킬을 자동으로 감지하고 체크리스트에 따라 검토합니다.

실전 예시: 라이선스 헤더 추가 스킬 (license-header-adder) #

공식 문서에서 소개하는 license-header-adder 스킬입니다. 소스 파일에 자동으로 라이선스 헤더를 추가하는 실용적인 예시로, resources/ 폴더를 활용한 파일 참조 패턴을 보여줍니다.

스킬 구조

resources/HEADER.txt

공식 예시는 C스타일 /* */ 블록을 사용합니다. SKILL.md가 언어별 주석 변환을 지시하므로 C스타일로 작성합니다.

SKILL.md

외부 스킬 설치 — Anthropic 공식 스킬 라이브러리 활용 #

스킬을 처음부터 작성하기 전에, Anthropic이 공개한 공식 스킬 모음을 먼저 들여다보세요. 실무에서 검증된 PDF·DOCX·PPTX·XLSX 변환, 캔버스 디자인, 알고리즘 아트, MCP 빌더, skill-creator 등이 그대로 포함되어 있어, 좋은 스킬의 작성 패턴을 학습하고 즉시 사용할 수도 있습니다.

설치 방법 1: 저장소 전체 클론

여러 스킬을 한꺼번에 가져오고 업데이트도 추적하고 싶다면 통째로 클론합니다.

# 1) 임시 위치에 클론
git clone https://github.com/anthropics/skills.git ~/anthropic-skills

# 2) 사용할 스킬만 골라 복사 (예: skill-creator, pdf, pptx, xlsx)
mkdir -p ~/.agents/skills
cp -r ~/anthropic-skills/skills/skill-creator ~/.agents/skills/
cp -r ~/anthropic-skills/skills/pdf          ~/.agents/skills/
cp -r ~/anthropic-skills/skills/pptx         ~/.agents/skills/
cp -r ~/anthropic-skills/skills/xlsx         ~/.agents/skills/

# 3) Antigravity 재시작 후 활성화 확인
ls ~/.agents/skills/

설치 방법 2: 단일 스킬만 가져오기 (sparse-checkout)

저장소 전체를 받고 싶지 않다면 git의 sparse-checkout으로 필요한 폴더만 받을 수 있습니다.

git clone --filter=blob:none --no-checkout https://github.com/anthropics/skills.git tmp-skills
cd tmp-skills
git sparse-checkout init --cone
git sparse-checkout set skills/skill-creator
git checkout main

# 추출된 스킬을 워크스페이스에 복사
cp -r skills/skill-creator ~/.agents/skills/
cd .. && rm -rf tmp-skills

주요 공식 스킬 한눈에 보기

skill-creator로 데이터 분석 스킬 만들기 (실습) #

skill-creator는 "스킬을 만드는 스킬"입니다. 활성화하면 에이전트가 스킬 생성 워크플로(이름 정하기 → description 작성 → SKILL.md 골격 → 검증)를 단계별로 진행합니다. 직접 SKILL.md를 처음부터 쓰는 것보다 훨씬 빠르고 실수가 적습니다.

Step 1 — skill-creator 설치 확인

ls ~/.agents/skills/skill-creator/SKILL.md
# 파일이 있어야 합니다. 없다면 위 "외부 스킬 설치" 섹션 참고

Step 2 — 에이전트에게 데이터 분석 스킬 생성 요청

skill-creator로 새 스킬을 만들어줘. 이름은 "korean-eda"이고,
한국어 컬럼명을 가진 CSV·Excel을 받아 다음을 자동 수행하는 스킬이야:

1) 인코딩 자동 감지 (utf-8 → cp949 폴백)
2) 컬럼명 정규화 (공백·특수문자 제거, snake_case 변환)
3) 결측치 리포트 (열별 비율, 시각화)
4) 자료형 추론 결과 표
5) koreanize_matplotlib import한 한글 차트 5종 자동 생성

위치는 ~/.agents/skills/korean-eda/ 로 만들어 주고,
SKILL.md와 함께 scripts/ 폴더에 검증용 코드를 넣어줘.

skill-creator는 위 요청을 받으면 다음을 자동으로 진행합니다.

1. 이름 검증 — korean-eda가 다른 스킬과 충돌하지 않는지 확인
2. description 초안 작성 — "한국어 컬럼/한글 데이터 EDA, 인코딩 자동 감지, 결측치 리포트…" 같은 자연어 트리거 문구 생성
3. frontmatter + 본문 골격 생성 — Progressive Disclosure 원칙에 맞춰 description은 짧고, 본문은 단계별 절차로
4. scripts/ 폴더 생성 — encoding_detect.py, missing_report.py, korean_charts.py 등 보조 스크립트 자동 작성
5. 검증 — SKILL.md 길이·필드·예시 사용 여부를 자체 체크리스트로 점검

Step 3 — 결과물 구조 확인

~/.agents/skills/korean-eda/
├── SKILL.md                       # frontmatter + 단계별 지침
├── scripts/
│   ├── encoding_detect.py         # utf-8 → cp949 폴백 로직
│   ├── normalize_columns.py       # 컬럼명 정규화
│   ├── missing_report.py          # 결측치 표·차트
│   └── korean_charts.py           # 한글 폰트 차트 5종
└── examples/
    └── sample_korean.csv          # 검증용 샘플

Step 4 — 실전 사용

판매_2024.xlsx 데이터를 korean-eda 스킬로 분석해줘.

에이전트가 korean-eda description을 보고 자동으로 스킬을 활성화합니다. 인코딩 감지부터 한글 차트 5종 생성까지 일관된 절차를 매번 동일하게 수행합니다.

외부 스킬 적용 사례: pptx-design-styles로 슬라이드 디자인 자동화 #

커뮤니티에서 공개된 외부 스킬을 가져와 즉시 적용하는 흐름을 보여줍니다. 예시 스킬은 오늘코드가 직접 제작·공개한 corazzon/pptx-design-styles로, 한국어 PPTX 슬라이드 작성에 30여 종의 모던 디자인 스타일을 적용해주는 스킬입니다. 분석 결과를 발표 자료로 만들 때 디자인 일관성을 한 번에 확보할 수 있고, 본 튜토리얼과 같은 저자가 만든 만큼 한국어 환경(폰트·줄바꿈·문장 부호)에서의 동작도 검증되어 있습니다.

Step 1 — 저장소 클론 및 설치

# 사용자 전역 스킬 폴더에 직접 클론
mkdir -p ~/.agents/skills
git clone https://github.com/corazzon/pptx-design-styles.git \
  ~/.agents/skills/pptx-design-styles

# 또는 워크스페이스 단위로 설치 (팀 공유용)
cd ~/projects/my-analysis
mkdir -p .agents/skills
git clone https://github.com/corazzon/pptx-design-styles.git \
  .agents/skills/pptx-design-styles

# 설치 확인
cat ~/.agents/skills/pptx-design-styles/SKILL.md | head -20

Step 2 — Antigravity 재시작 & 활성화 확인

스킬은 Antigravity 시작 시점에 스캔됩니다. 설치 후 한 번 재시작한 뒤 새 대화에서 다음을 입력해 활성화 여부를 확인하세요.

지금 활성화 가능한 스킬 목록 보여줘. pptx-design-styles가 보이는지 알려줘.

Step 3 — 분석 결과 PPTX에 적용

EDA 결과나 시각화 산출물을 슬라이드로 변환할 때 스킬을 호출합니다. 스킬은 자동으로 "제품 출시·데이터 리포트·기술 발표·임원 보고" 등 시나리오에 어울리는 디자인 스타일을 적용합니다.

판매_2024.xlsx EDA 결과를 발표용 PPTX로 만들어줘.

조건:
- pptx-design-styles 스킬을 사용해 "임원 보고용 미니멀" 스타일 적용
- 표지 / 매출 추이 차트 / 지역별 비교 / 결론 4장 구성
- 차트 이미지는 reports/ 폴더에 이미 저장되어 있음
- 한글 폰트 깨짐 방지 처리 포함

파일은 reports/판매_2024_보고.pptx 로 저장해줘.

Step 4 — 결과 확인 & 스타일 변경

생성된 PPTX가 마음에 들지 않으면 다른 스타일로 즉시 재생성할 수 있습니다.

방금 만든 reports/판매_2024_보고.pptx를
"제품 출시 키노트(big-typo)" 스타일로 다시 만들어줘.
구조와 데이터는 동일하게 유지.

Antigravity 워크플로 안에서의 시너지

이 스킬은 단독으로 쓰기보다 다른 데이터 분석 스킬과 체인을 이룰 때 진가를 발휘합니다.

• EDA 스킬 → 시각화 스킬 → pptx-design-styles — 분석 결과를 발표 자료까지 한 번의 흐름으로
• 크롤링 스킬 → 시각화 스킬 → pptx-design-styles — 외부 데이터 수집부터 임원 보고까지
• Karpathy 코딩 가이드라인 + pptx-design-styles — 코드 품질과 산출물 디자인을 동시에 표준화

자주 묻는 질문 (FAQ) #