Agent Skills는 Claude의 기능을 확장하는 모듈입니다. 각 Skill은 지시사항, 메타데이터를 포함하고, 선택적으로 스크립트나 템플릿 같은 리소스를 패키징하여 Claude가 관련 작업을 수행할 때 자동으로 활용하게 할 수 있습니다.
쉽게 말해, Skill은 새로운 claude 세션에게 줄 온보딩 가이드와 같습니다. 특정 도메인의 워크플로우, 컨텍스트, 베스트 프랙티스를 담아두면 Claude가 필요할 때 참조하여 도메인 전문가처럼 행동하게 됩니다.
Skills를 사용하는 이유
기존 프롬프트의 한계
매번 대화할 때마다 같은 지침을 반복해서 입력하는 것은 비효율적입니다:
Java 코드를 작성할 때는 Spring Boot 3.x 규칙을 따르고,
Entity는 protected 기본 생성자를 사용하고,
DTO는 record 타입을 활용하고...
Skills의 해결책
Skills를 사용하면:
반복 제거: 한 번 정의하면 자동으로 적용
Claude 특화: 도메인별 전문 지식으로 Claude를 맞춤 설정
조합 가능: 여러 Skill을 조합해 복잡한 워크플로우 구성
컨텍스트 효율: 필요할 때만 로딩되어 토큰 절약
Skills의 3단계 로딩 구조
Skills의 핵심 개념은 Progressive Disclosure(점진적 공개)입니다.
모든 정보를 한 번에 로딩하지 않고 단계별로 필요한 내용만 로딩합니다.
Level 1: 메타데이터 (항상 로딩)
Claude에게 명령을 내릴 때 항상 로딩되는 가벼운 정보입니다. 이름과 설명 정도의 간단한 내용을 포함합니다.
사용자의 명령 맥락을 분석하여, Skills에 등록된 것들 중에 쓸만한 게 없는지 찾아보는 거라고 생각하시면 쉽습니다.
---
name: pdf-processing
description: PDF 파일에서 텍스트와 표를 추출하고, 폼을 채우거나 문서를 병합합니다. PDF, 폼, 문서 추출 관련 작업 시 사용하세요.
---
아주 작은 분량의 텍스트이므로 토큰 소모량이 크지 않고, 약 100 토큰 정도만 사용하므로 많은 Skill을 설치해도 컨텍스트 부담이 거의 없습니다.
Level 2: 지시사항 (트리거 시 로딩)
사용자 요청이 Skill의 description과 매칭되면 SKILL.md 본문이 로딩됩니다.
여기에는 워크플로우(절차적 지식, procedural knowledge), 모범 사례(best-practice), 지침 등을 포함합니다.
Level1에서 name, description이 사용자의 명령을 처리하는데 필요하다고 판단되면, 그때 컨텍스트에 로드하고 읽습니다. 즉, 여기에 내용을 많이 작성해도 항상 많이 읽기 토큰을 소모하는게 아니라 꼭 필요할때만 읽어가는 것 입니다.
# PDF Processing
## Quick start
pdfplumber를 사용해 PDF에서 텍스트를 추출합니다:
```python
import pdfplumber
with pdfplumber.open("document.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
폼 작성 기능은 FORMS.md를 참고하세요.
이 단계는 약 5,000 토큰 이하를 사용합니다.
Level 3: 리소스 & 코드 (필요 시 로딩)
정말 상세한 가이드가 필요할때 SKILL.md 이외에 사실상 무제한의 파일을 넣을 수 있습니다.
여기에는 상세 지침, 레퍼런스 자료, 코드(script) 등이 포함될 수 있습니다.
추가 파일들은 참조될 때만 로딩됩니다.
SKILL.md에 "A 상황에서는 REFERENCE-A.md 를 참고하고, B 상황에서는 REFERENCE-B.md를 참고하세요." 라는 내용을 넣을 수 있습니다. skill끼리도 참조할 수 있고, 레퍼런스 끼리, 레퍼런스에서 script 언급 등 대부분 생각할 수 있는 모든것이 가능합니다. (자세한건 claude와 대화해보세요. skill-creator라는 스킬을 만드는 것을 도와주는 skill 도 있습니다. )
pdf-skill/
├── SKILL.md # 메인 지시사항
├── FORMS.md # 폼 작성 가이드 (필요 시 로딩)
├── REFERENCE.md # 상세 API 문서 (필요 시 로딩)
└── scripts/
└── fill_form.py # 실행 스크립트 (출력만 컨텍스트에 포함)
이 단계는 사실상 무제한의 토큰이 사용될 수 있습니다. 분량에 제한이 없고, 권장도 없습니다.
얼마전 vercel이 공개한 react-best-practice을 보면 SKILL에는 별 내용이 없고, rules 디렉터리 아래에 작은 단위로 나눠놓은 마크다운 파일들이 있습니다. SKILL.md에는 오직 어떤 rule을 어떨때 사용하고, 참조하면 되는지에 대한 정리만 되어있습니다.
---
name: your-skill-name
description: 이 Skill이 무엇을 하고 언제 사용해야 하는지 설명
---
# Your Skill Name
## Instructions
[Claude가 따라야 할 명확한 단계별 지침]
## Examples
[이 Skill 사용의 구체적인 예시]
필수 필드 규칙
name 필드:
최대 64자
소문자, 숫자, 하이픈만 허용
"anthropic", "claude" 예약어 사용 금지
description 필드:
최대 1,024자
무엇을 하는지 + 언제 사용해야 하는지 모두 포함
Claude가 Skill 활성화 여부를 판단하는 핵심 정보
좋은 description 예시
# ❌ 나쁜 예시 - 너무 간략함
description: Java 코딩 스킬
# ✅ 좋은 예시 - 무엇을 + 언제 사용하는지 명확
description: Java 17+ 및 Spring Boot 3.x 프로젝트 개발 가이드. Entity, DTO, Repository 패턴과 코드 컨벤션을 제공합니다. Java나 Spring 관련 코드 작성 시 사용하세요.
SKILL.md 본문 작성
본문에는 워크플로우, 모범사례, 지침 등을 포함해야한다고 되어있지만, 사실상 정해진 규칙은 없어보입니다.
다만 이해하기 쉽게 간결해야 한 부분은 간결하게, 상세해야 한 부분은 상세하게내용을 작성해야합니다.
자주 쓰이는 패턴은 단순 지침 나열, 워크플로우(작업 절차) 등이 있는 것 같습니다.
지침 나열 예제
## XXX 스킬
- 스킬에 대한 설명 나열
## 전반적인 가이드라인
- 전반적으로 이렇게 저렇게 해라
## 특정한 가이드라인 1
- 1 상황에서는 이렇게 해라
## 특정한 가이드라인 2
- 이럴땐 이렇게 하고, 이 경우엔 xxx.py를 이용해라.
워크 플로우 예제
# XXX skill
- 이 skill은 이러이러하다
## 핵심 규칙
- 이건 꼭 지켜라
- 이것도 꼭 지켜라
- 이건 하지마라
## First Step
- 첫번째 단계에선 이걸 해라
## Second Step
- 두번째 단계에선 이걸 해라
- 첫번째 결과가 이러면 이렇게 하고, 저러면 저렇게 해라
skill-creator
아래 깃허브는 anthropic의 공식 skills 깃허브입니다.
이 깃허브에는 skill을 더 잘 작성할 수 있도록 도와주는 스킬인 "skill-creator"를 제공합니다.
