[Claude 시리즈 12편] Claude Skills 만들기 - 반복 작업을 Claude에게 가르치기 (SKILL.md 완벽 가이드)

[Claude 시리즈 12편] Claude Skills 만들기 - 반복 작업을 Claude에게 가르치기 (SKILL.md 완벽 가이드)

테스트 환경: Claude Code, Claude.ai, Agent Skills (2026년 7월 기준)

똑같은 절차를 Claude에게 다섯 번째 설명하고 있다면, 뭔가 잘못된 것입니다.

"보고서 만들 땐 이 형식으로, 이 순서로, 이 규칙을 지켜서..." 를 매번 반복하는 대신, 한 번만 가르치고 계속 재사용할 수 있다면 어떨까요? 그게 Skills(Agent Skills) 입니다.

Skills는 절차·규칙·전문 지식을 폴더 하나에 담아 Claude에게 주는 기능입니다. Claude는 필요할 때만 자동으로 그 Skill을 불러 쓰고, 안 쓸 때는 무시합니다. 2025년 12월 오픈 표준이 되면서 Claude뿐 아니라 여러 AI에서 쓸 수 있게 되었습니다.

이 글에서 다룰 내용입니다.

• Skills가 무엇이고 왜 필요한가
• ★ MCP vs Skills vs CLAUDE.md vs Projects — 언제 뭘 쓸까
• SKILL.md 구조 완벽 해부
• 나만의 Skill 만들기 (3가지 방법)
• 실전 Skill 예시

이 글은 Phase 3의 세 번째 글로, MCP 편과 짝을 이룹니다.

 

Skills란 무엇인가 - "온디맨드 전문성"

Skills를 한마디로 표현하면 "필요할 때만 꺼내 쓰는 전문 지식 패키지" 입니다.

문제 상황

매번 반복하는 것들:
- "릴리스할 땐 테스트 → 버전업 → 태그 → 푸시 순서로"
- "보고서는 이 템플릿, 이 톤, 이 구조로"
- "PDF 만들 땐 이 규칙 지켜서"

이걸 매번 설명하는 건 시간 낭비입니다.

Skills의 해결

절차를 SKILL.md 파일에 한 번 적어두면:

1. Claude가 시작 시 Skill의 이름·설명만 스캔 (가벼움)
2. 관련 작업이 오면 그 Skill의 전체 내용을 로드
3. 그 절차대로 작업 수행
4. 안 쓸 때는 무시 (토큰 거의 안 씀)

핵심: Claude가 자율적으로 판단해서 필요할 때만 씁니다. 이걸 model-invoked라고 합니다.

2026년 현재 위상

• 2025년 12월 18일 Agent Skills 오픈 표준 발표
• 26개 이상 플랫폼 채택 (Claude, OpenAI Codex, Gemini CLI, Cursor, VS Code 등)
• Anthropic이 사전 제작 Skills 제공 (PowerPoint, Excel, Word, PDF)
• 오픈소스 Skill 저장소 공개 (github.com/anthropics/skills)

MCP처럼 Skills도 특정 회사 것이 아닌 범용 표준이 되었습니다.

 

★ MCP vs Skills vs CLAUDE.md vs Projects

가장 헷갈리는 부분입니다. 네 가지를 명확히 구분합니다.

도구 역할 비유

CLAUDE.md	프로젝트 환경·규칙 (항상 로드)	회사 취업 규칙
Skills	특정 절차·전문성 (필요시 로드)	업무 매뉴얼
MCP	외부 도구·데이터 연결	도구함
Projects	작업 공간 + 공유 파일	프로젝트 룸

언제 무엇을 쓰나

CLAUDE.md — "이 프로젝트는 이런 환경이다"

- 항상 적용되는 규칙
- 예: "이 프로젝트는 pnpm 사용, TypeScript, 이 코드 스타일"

Skills — "이 작업은 이렇게 하는 것이다"

- 특정 작업의 절차
- 예: "릴리스 절차", "PDF 생성 규칙", "보고서 작성법"

MCP — "이 외부 시스템에 접근한다"

- 도구/데이터 연결
- 예: GitHub 조회, DB 쿼리, 파일 접근

Projects — "이 작업 공간에서 일한다"

- claude.ai의 대화 묶음 + 파일
- 예: "A사 운영 프로젝트"

결정적 차이: CLAUDE.md vs Skills

이 둘이 가장 헷갈립니다.

CLAUDE.md에 이런 게 자라나고 있다면:
"릴리스하려면 테스트 돌리고, 버전 올리고, 
 태그 달고, 이 순서로 푸시하고..."
→ 이건 "사실"이 아니라 "절차"입니다
→ Skill로 빼내야 합니다

규칙(fact)은 CLAUDE.md, 절차(procedure)는 Skill. CLAUDE.md가 절차로 비대해지면 Skill로 분리하세요.

 

★ SKILL.md 구조 완벽 해부

Skill의 핵심은 SKILL.md 파일 하나입니다. 구조를 뜯어봅니다.

최소 구조

---
name: pdf-generator
description: PDF 문서를 생성할 때 사용. 표지, 목차, 
             페이지 번호가 필요한 공식 문서에 적합.
---

# PDF 생성 절차

1. 먼저 문서 구조를 확인합니다
2. 표지를 생성합니다
3. ...

필수 항목은 딱 2개: name과 description. 나머지는 모두 선택입니다.

frontmatter 해부

---
name: skill-이름              # 필수: 소문자, 하이픈
description: 무엇을, 언제      # 필수: 트리거 조건 명확히
---

description이 가장 중요합니다. Claude는 이 설명을 보고 "이 작업에 이 Skill을 쓸까" 판단합니다.

❌ description: "PDF 관련 스킬"  (모호)
✅ description: "PDF 문서를 생성하거나 편집할 때 사용. 
   표지, 목차, 페이지 번호, 워터마크가 필요한 
   공식 문서 작업에 적합."  (구체적)

3계층 Progressive Disclosure

Skills의 영리한 설계입니다. 토큰을 아끼기 위해 3단계로 로드됩니다.

1계층: name + description (~100 토큰)
        → 시작 시 모든 Skill의 이걸 스캔

2계층: SKILL.md 본문 (~5,000 토큰 권장)
        → 해당 Skill이 선택되면 로드

3계층: 참조 파일 (필요할 때만)
        → 본문에서 가리키는 추가 파일

이 구조 덕분에 Skill이 100개 있어도 시작 시엔 메타데이터만(가벼움), 실제 쓸 때만 전체를 로드합니다.

폴더 구조

Skill은 파일 하나가 아니라 폴더입니다.

my-skill/
├── SKILL.md           # 필수: 메인 지침
├── scripts/           # 선택: 실행 스크립트
│   └── generate.py
├── references/        # 선택: 참조 문서
│   └── template.md
└── assets/            # 선택: 리소스
    └── logo.png

간단한 Skill은 SKILL.md 하나로 충분하고, 복잡하면 스크립트·템플릿을 추가합니다.

 

★ 나만의 Skill 만들기 - 3가지 방법

방법 1: 대화로 만들기 (가장 쉬움)

Claude.ai나 Cowork에서 skill-creator를 쓰면 대화만으로 Skill을 만들 수 있습니다.

> skill-creator를 써서 스킬을 만들어줘.
  
  내가 자주 하는 작업: 주간 업무 보고서 작성
  형식: [설명]
  규칙: [설명]

Claude가 몇 가지 질문을 하고 SKILL.md를 작성해서 바로 쓸 수 있는 Skill로 패키징해줍니다. 비개발자에게 가장 좋은 방법입니다.

방법 2: 직접 작성 (Claude Code)

Claude Code에서 파일로 직접 만듭니다.

# 개인 스킬 위치
mkdir -p ~/.claude/skills/weekly-report
vi ~/.claude/skills/weekly-report/SKILL.md

---
name: weekly-report
description: 주간 업무 보고서를 작성할 때 사용. 
             완료/진행중/이슈로 분류하고 상급자가 
             5초 안에 파악 가능한 형식으로 정리.
---

# 주간 업무 보고서 작성

## 형식
1. 이번 주 완료 (불릿, 각 1줄)
2. 진행 중 (진행률 %)
3. 이슈/블로커 (심각도 표시)
4. 다음 주 계획

## 규칙
- 상급자 관점에서 핵심만
- 전문 용어는 괄호로 설명
- 각 항목 2줄 이내

저장하면 Claude가 자동으로 발견하고, 주간 보고 요청 시 이 Skill을 씁니다.

방법 3: 기존 Skill 가져오기

Anthropic 공식 저장소나 커뮤니티 Skill을 활용합니다.

github.com/anthropics/skills
→ 예술, 음악, 디자인, 테스트, MCP 생성 등 다양
→ 대부분 오픈소스 (Apache 2.0)

기존 Skill을 참고해서 본인 것으로 수정하는 게 빠릅니다.

Skill 위치 (Claude Code)

개인 스킬: ~/.claude/skills/<name>/SKILL.md
프로젝트 스킬: .claude/skills/<name>/SKILL.md

확인:
ls ~/.claude/skills/*/SKILL.md    # 개인
ls .claude/skills/*/SKILL.md      # 프로젝트

 

실전 Skill 예시

예시 1: 커밋 메시지 규칙 (개발자)

---
name: commit-message
description: git 커밋 메시지를 작성할 때 사용. 
             conventional commits 형식과 팀 규칙 적용.
---

# 커밋 메시지 작성 규칙

## 형식
<type>(<scope>): <제목>

<본문>

## type
- feat: 새 기능
- fix: 버그 수정
- refactor: 리팩터링
- docs: 문서
- test: 테스트

## 규칙
- 제목은 50자 이내, 명령형
- 본문은 "무엇을, 왜" (어떻게는 코드가 설명)
- 이슈 번호 있으면 하단에 참조

예시 2: SQL 리뷰 (DBA)

---
name: sql-review
description: SQL 쿼리를 리뷰할 때 사용. Oracle 환경 기준 
             성능, 보안, 가독성을 점검하고 개선안 제시.
---

# SQL 리뷰 절차

## 점검 항목
1. 성능: 인덱스 활용, 풀스캔 여부, 조인 순서
2. 보안: SQL 인젝션 위험, 권한 과다
3. 가독성: 명명 규칙, 들여쓰기, 주석
4. Oracle 특화: 힌트 적절성, 바인드 변수 사용

## 출력 형식
- 심각도별(높음/중간/낮음) 분류
- 각 지적에 개선 SQL 포함
- 운영 적용 시 주의사항

예시 3: 블로그 글 작성 (블로거)

---
name: blog-post
description: 기술 블로그 글을 작성할 때 사용. 
             트러블슈팅 형식과 SEO 규칙 적용.
---

# 블로그 글 작성 절차

## 구조
1. 도입부 (실제 장애 시나리오, 150자)
2. 빠른 진단 체크리스트
3. 원인별 해결 (3~5개)
4. 재발 방지
5. 관련 글 링크

## 규칙
- 존댓말, "여러분" 지양
- 코드 블록 언어 명시
- 상단에 테스트 환경 표기
- SEO: 제목 40~60자, 핵심 키워드 포함

 

Skill 잘 만드는 팁

1. description에 집중

Claude가 Skill을 쓸지 말지는 description으로 결정됩니다. 무엇을, 언제 쓰는지 구체적으로.

2. 본문은 5,000 토큰 이내

너무 길면 로드 비용이 큽니다. 핵심 절차만 담고, 상세는 참조 파일로 분리.

3. 하나의 Skill = 하나의 목적

여러 작업을 한 Skill에 담지 마세요. 목적별로 분리해야 정확히 트리거됩니다.

4. 절차 위주로

Skill은 "절차"를 담는 곳입니다. 단순 사실은 CLAUDE.md로.

5. 테스트하고 개선

만든 후 실제로 써보고, Claude가 제대로 트리거하는지 확인하며 description을 다듬으세요.

 

자주 하는 실수

실수 1: description이 모호함

Claude가 언제 쓸지 몰라서 트리거 안 됨. 구체적으로 작성.

실수 2: CLAUDE.md와 혼동

환경 규칙을 Skill로, 절차를 CLAUDE.md로 넣는 반대 실수. 절차=Skill, 사실=CLAUDE.md.

실수 3: 하나에 다 담기

여러 목적을 한 Skill에. 목적별 분리하세요.

실수 4: 너무 김

본문이 수만 토큰이면 비효율. 5,000 토큰 이내 + 참조 파일 활용.

실수 5: 만들고 검증 안 함

트리거 안 되는 Skill은 무용지물. 실제로 써보고 확인.

 

다음 글 예고

다음 글은 [Claude 시리즈 13편] Claude Code로 개인 자산 만들기 입니다. Phase 3의 마지막 글로, 지금까지 배운 것들(API, MCP, Skills, CLAUDE.md)을 종합해서 나만의 자동화 자산을 구축하는 방법을 다룹니다.

 

마무리

Claude Skills의 핵심을 다시 정리하면:

1. Skills = 온디맨드 전문성 — 필요할 때만 로드되는 절차
2. 절차는 Skill, 사실은 CLAUDE.md — 역할 구분
3. SKILL.md의 핵심은 description — 트리거를 좌우
4. 3계층 로드로 토큰 절약 — 많아도 가벼움
5. 하나의 Skill = 하나의 목적

매번 같은 설명을 반복하고 있다면, 그게 바로 Skill로 만들 신호입니다. 대화로 만드는 skill-creator부터 시작해서, 점점 본인만의 Skill 라이브러리를 쌓아가시길 권합니다. 한 번 가르치면 계속 재사용하는 것 — 이게 Skills의 본질입니다.

본인이 만든 유용한 Skill이나 활용 사례가 있다면 댓글로 공유해주세요.