나만의 Claude Skills 만들기— 설계부터 배포까지 완전 정복

Claude는 단순한 챗봇이 아닙니다. Skills라는 플러그인 메커니즘을 통해 Claude에게 도메인 전용 지식, 워크플로우, 스크립트를 주입할 수 있습니다. 한 번 잘 만들어 둔 Skill은 팀 전체가 공유하고, 프로젝트마다 재활용할 수 있는 재사용 가능한 AI 모듈입니다.

이 글에서는 Anthropic 공식 문서를 기반으로 Skill의 구조를 분석하고, 실제 프로젝트에서 사용할 수 있는 커스텀 Skill을 직접 만드는 과정을 단계별로 안내합니다.

📌 이 글에서 다루는 것
Skills 아키텍처 원리 · SKILL.md 작성법 · 트리거 최적화 · 실전 예제 3종 · 자주 발생하는 오류 참조표

Claude.ai — 사용자 지정 › 스킬

---

1. 원인 분석 — Skills가 필요한 이유

Claude를 매일 사용하다 보면 같은 컨텍스트를 반복해서 입력해야 하는 순간이 옵니다. 예를 들어 "우리 팀은 Python 3.12 + FastAPI를 사용하고, 변수명은 snake_case, docstring은 Google 스타일로 써줘" 같은 지시를 매번 붙여넣는 상황입니다. 이 문제의 근본 원인을 살펴보면 세 가지 구조적 한계가 있습니다.

🔁

컨텍스트 재입력 비용

세션이 바뀔 때마다 도메인 지식, 코드 컨벤션, 제약 조건을 다시 설명해야 합니다.

🧩

워크플로우 단절

다단계 작업(분석→코드→테스트→문서)의 절차가 프롬프트에 흩어져 있어 재현이 어렵습니다.

👥

팀 공유 불가

개인이 정제한 프롬프트 노하우를 팀원에게 전달할 표준 방법이 없습니다.

Skills는 이 세 문제를 모두 해결합니다. SKILL.md 파일 하나를 작성하면 Claude가 해당 작업을 수행할 때 자동으로 그 파일을 읽고 지시에 따릅니다. 한 번 정의하면 팀 전체가 동일한 품질의 결과를 얻을 수 있습니다.

⚠️ 중요한 전제
Skills는 Claude Code, Claude.ai, Cowork 등 환경에 따라 동작 방식이 다릅니다. 특히 서브에이전트(병렬 실행)나 브라우저 렌더링은 Claude Code·Cowork 전용 기능입니다. 이 글은 Claude.ai + Claude Code 양쪽에 적용할 수 있는 내용을 중심으로 합니다.

Claude.ai — Skills 도입 전: 반복 컨텍스트 입력 문제

---

2. Skills 아키텍처 — 구조 이해하기

Skill은 디렉토리 단위로 구성됩니다. 필수 파일은 SKILL.md 하나뿐이며, 필요에 따라 스크립트, 참조 문서, 에셋을 번들로 포함할 수 있습니다.

my-skill/
├── SKILL.md ← 필수. 메타데이터 + 지시사항
├── scripts/ ← 반복/결정론적 작업용 스크립트
│ └── generate.py
├── references/ ← 필요할 때 로드하는 참조 문서
│ ├── aws.md
│ └── gcp.md
└── assets/ ← 템플릿, 이미지, 폰트 등

Progressive Disclosure — 3단계 로딩

Skill의 핵심 설계 원칙은 점진적 공개(Progressive Disclosure)입니다. Claude의 컨텍스트 윈도우를 효율적으로 사용하기 위해 정보를 세 단계로 나눠 로드합니다.

단계	내용	항상 컨텍스트에?	크기 가이드
1단계 · 메타데이터	SKILL.md의 name + description (YAML frontmatter)	항상 로드	~100 words
2단계 · 본문	SKILL.md 마크다운 본문 (지시사항, 워크플로우)	Skill 트리거 시	500줄 이하 권장
3단계 · 번들 리소스	scripts/, references/, assets/ 파일	필요 시에만	제한 없음

SKILL.md 최소 구조

---
name: my-skill
description: 이 Skill이 무엇을 하는지, 언제 트리거해야 하는지를 구체적으로 기술합니다.
---
# Skill 제목
여기서부터 마크다운 형식으로 지시사항을 작성합니다.
## 워크플로우
1. 첫 번째 단계
2. 두 번째 단계
...

💡 description 작성 팁
description은 Claude가 이 Skill을 언제 사용할지 결정하는 트리거 메커니즘입니다. 소극적으로 쓰면 Claude가 사용하지 않습니다. "이 Skill을 쓰세요" 대신 "X, Y, Z 상황이 발생하면 반드시 이 Skill을 참고하세요"처럼 능동적으로 작성하세요.

Claude.ai — 사용자 지정 › 스킬 › SKILL.md 코드 편집 뷰

---

3. 유사 사례 — 실전에서 쓰이는 Skills 3가지

개념을 이해했다면 실제로 어떤 Skills가 유용한지 살펴보겠습니다. 아래 세 가지는 모두 실무에서 즉시 활용 가능한 예시입니다.

📄사례 1 · 코드 리뷰 자동화 SkillHIGH VALUE

PR마다 리뷰 기준이 달라 품질이 들쭉날쭉한 팀에 적합합니다. 팀의 코딩 컨벤션, 보안 체크리스트, 성능 고려사항을 SKILL.md에 문서화하면 Claude가 일관된 기준으로 코드를 리뷰합니다.

---
name: code-review
description: 코드 리뷰를 요청하거나 PR diff를 보여줄 때 반드시 이 Skill을 사용합니다.
  Python/FastAPI 프로젝트의 코딩 컨벤션, 보안 패턴, 성능 체크리스트를 기반으로
  구조화된 리뷰 결과를 제공합니다.
---
## 리뷰 체크리스트
### 1. 코딩 컨벤션
- 변수명: snake_case, 상수: UPPER_SNAKE_CASE
- 함수 docstring: Google 스타일
### 2. 보안 체크
- SQL 인젝션 방지 (ORM 또는 parameterized query)
- 입력값 검증 (pydantic BaseModel)
### 3. 출력 형식
1. 요약 (1~3줄)
2. 심각도별 이슈 [CRITICAL / MAJOR / MINOR]
3. 개선 코드 예시

📊사례 2 · 데이터 파이프라인 디버깅 SkillSPECIALIZED

데이터 엔지니어링 팀에서 Airflow DAG, dbt 모델, Spark 잡의 오류 메시지를 분석할 때 사용합니다. 오류 패턴 DB를 references/에 저장해 두면 Claude가 맥락에 맞게 참조합니다.

---
name: data-pipeline-debug
description: Airflow, dbt, Spark, BigQuery 관련 오류 메시지, DAG 코드,
  스택 트레이스를 보여줄 때 이 Skill을 활성화하세요.
---
## 디버깅 프로세스
1. 오류 분류: references/error-patterns.md 참조
2. 환경 확인: Python 버전, 패키지 의존성 충돌 점검
3. 재현 가능한 최소 예시 도출
4. 수정 코드 + 검증 방법 제시

📝사례 3 · 기술 문서 자동 생성 SkillTEAM SHARE

API 엔드포인트, 함수 시그니처, 아키텍처 결정 기록(ADR)을 일관된 형식으로 문서화합니다. 마크다운 템플릿을 assets/에 포함해 두면 Claude가 그 형식을 그대로 따릅니다.

---
name: tech-doc-writer
description: API 문서, README, 아키텍처 결정 기록(ADR), 함수 레퍼런스를
  작성해 달라고 하거나 "문서화해줘"라는 요청이 오면 이 Skill을 사용하세요.
---
## 문서 유형별 처리
- API 문서: assets/api-template.md 로드 후 작성
- ADR: assets/adr-template.md 로드 후 작성
- README: 표준 섹션 순서 준수

---

4. 단계별 해결 방법 — Skill 만들기 실전

실제로 커스텀 Skill을 만드는 전 과정을 순서대로 따라가 봅니다. 예시로 "FastAPI 프로젝트용 코드 리뷰 Skill"을 만들겠습니다.

1. 1

   의도 정의 (Capture Intent)

   Skill을 만들기 전에 아래 4가지 질문에 답합니다. 막연하게 시작하면 트리거가 제대로 동작하지 않습니다.

   1. 이 Skill이 Claude에게 무엇을 가능하게 하는가?
   2. 언제 트리거되어야 하는가? (사용자가 어떤 말을 할 때?)
   3. 기대하는 출력 형식은?
   4. 검증 가능한 테스트 케이스가 필요한가?
2. 2

   디렉토리 생성 및 SKILL.md 초안 작성

   Skill 폴더를 생성하고 SKILL.md를 작성합니다.

   # 터미널에서 실행
   mkdir -p fastapi-code-review/references
   touch fastapi-code-review/SKILL.md

   Claude.ai — Skill이 트리거된 실제 코드 리뷰 응답

   
3. 3

   참조 문서 작성 (references/)

   SKILL.md 본문이 500줄을 초과하거나, 특정 상황에서만 필요한 정보는 references/로 분리합니다.

   # fastapi-code-review/references/checklist.md
   ## 코딩 컨벤션
   - [ ] 변수명 snake_case 준수
   - [ ] Google 스타일 docstring
   - [ ] 타입 힌트 누락 여부
   ## 보안
   - [ ] pydantic으로 입력값 검증
   - [ ] SQL raw query 사용 여부
   - [ ] 민감 정보 하드코딩 여부
   ## FastAPI 특이사항
   - [ ] response_model 명시 여부
   - [ ] HTTPException 사용 여부

4. 4

   테스트 케이스 작성 및 실행

   Skill이 의도대로 트리거되고 올바른 결과를 내는지 검증합니다.

   ⚠️ 트리거 테스트 주의사항
   단순한 1단계 요청("이 파일 읽어줘")은 Skill을 트리거하지 않을 수 있습니다. 테스트 케이스는 실제 업무 상황처럼 복합적이고 구체적인 요청이어야 Claude가 Skill을 활성화합니다.
5. 5

   Description 최적화 (Trigger Tuning)

   Claude는 name + description만으로 Skill을 사용할지 결정합니다. Description이 소극적이면 Claude가 Skill을 쓰지 않습니다.

   Before vs After — Description 최적화로 Skill 트리거 개선

   
6. 6

   패키징 및 배포

   Skill이 완성되면 .skill 파일로 패키징해 팀원과 공유합니다.

   # Claude Code 환경에서 패키징
   python -m scripts.package_skill fastapi-code-review/
   # 결과: fastapi-code-review.skill 파일 생성
   # 팀원은 이 파일을 가져다 설치하면 동일한 Skill 사용 가능

   터미널 — package_skill 실행 결과 & .skill 파일 생성

   

   ✅ Claude.ai 사용자라면
   패키징 스크립트는 Python 환경이 있으면 Claude.ai에서도 동작합니다. 생성된 .skill 파일을 다운로드해 설치하면 됩니다.
7. 7

   반복 개선 (Iterate)

   Skill은 한 번 만들면 끝이 아닙니다. 팀이 사용하면서 쌓이는 피드백, 새로운 오류 패턴, 변경된 컨벤션을 반영해 지속적으로 개선합니다.

   Draft Skill
       ↓
   Test with real prompts
       ↓
   Evaluate output quality
       ↓
   Identify gaps → Update SKILL.md / references/
       ↓
   Re-test → Repeat until satisfied
       ↓
   Optimize description → Package → Deploy

---

5. 오류별 빠른 참조 표

증상	상태	원인	해결책
Skill이 전혀 트리거되지 않음	ERROR	description이 소극적이거나 테스트 프롬프트가 너무 단순함	description에 "반드시 사용", "~할 때 이 Skill 활성화" 추가
Skill이 너무 자주 트리거됨	WARN	description의 트리거 조건이 너무 광범위함	description에 "~한 경우에만" 같은 제한 조건 명시
references/ 파일이 로드되지 않음	ERROR	SKILL.md에서 언제 읽어야 하는지 지시하지 않음	SKILL.md 본문에 "X 상황에서는 references/xxx.md를 로드하세요" 명시
출력 형식이 일관되지 않음	WARN	출력 형식 지시가 모호하거나 없음	SKILL.md에 출력 형식 템플릿(마크다운 예시 포함)을 명확히 포함
SKILL.md가 500줄을 초과해 성능 저하	WARN	세부 정보를 모두 SKILL.md에 포함함	자주 쓰지 않는 정보는 references/ 하위 파일로 분리
패키징 스크립트 실행 권한 오류	ERROR	read-only 마운트 경로에서 직접 편집 시도	Skill을 /tmp/ 등 쓰기 가능 경로로 복사 후 수정

---

6. 전체 요약 및 핵심 정리

🧠 핵심 원칙 7가지

• SKILL.md = 계약서: 이 파일 하나가 Skill의 모든 동작을 정의합니다. frontmatter의 name과 description이 특히 중요합니다.
• description은 능동적으로: "~할 수 있습니다" 대신 "~할 때 반드시 이 Skill을 사용하세요"로 써야 Claude가 제대로 트리거합니다.
• Progressive Disclosure 준수: SKILL.md 본문은 500줄 이하로 유지하고, 세부 정보는 references/로 분리합니다.
• 출력 형식을 템플릿으로: 일관된 결과를 얻으려면 SKILL.md에 출력 형식 예시를 마크다운 코드 블록으로 포함하세요.
• 테스트 케이스는 실무 수준으로: 단순 1단계 요청은 트리거 테스트로 부적합합니다. 실제 업무 상황과 같은 복합 요청을 사용하세요.
• 반복이 핵심: 첫 버전을 완벽하게 만들려 하지 마세요. Draft → Test → Evaluate → Improve 루프를 빠르게 돌리는 것이 더 효과적입니다.
• 팀 자산으로 관리: Skill 디렉토리를 Git 레포에 포함하고, 팀의 노하우가 쌓일수록 references/ 파일을 업데이트하세요.

프로젝트 유형별 추천 Skill 우선순위

프로젝트 유형	첫 번째로 만들 Skill	두 번째
웹 백엔드	코드 리뷰 (컨벤션 + 보안)	API 문서 자동 생성
데이터 엔지니어링	파이프라인 디버깅	SQL 쿼리 최적화
ML/AI	실험 결과 분석 + 보고서	모델 카드 자동 작성
DevOps/인프라	IaC 리뷰 (Terraform/K8s)	인시던트 포스트모템 작성
풀스택/스타트업	기술 문서 통합 생성기	온보딩 가이드 자동화

✅ 시작하는 방법
오늘 당장 팀에서 Claude에게 가장 자주 반복 설명하는 내용이 무엇인지 떠올려 보세요. 그것이 첫 번째 Skill의 주제입니다. SKILL.md 한 파일부터 시작해서 점진적으로 references/를 채워가면 됩니다. 완벽한 Skill보다 지금 당장 쓸 수 있는 Skill이 훨씬 가치 있습니다.

---

참고 문서
Anthropic Skills 공식 문서: github.com/anthropics/skills
Skill Creator 가이드: skill-creator/SKILL.md

이 글은 Anthropic 공식 문서를 기반으로 작성되었습니다. Skills 기능은 계속 업데이트되므로 최신 내용은 공식 문서를 참조하세요.