Claude Code에서 말하는 ‘스킬(Skill)’이란

 

이 글에서 아래와 같은 내용을 다룰 예정이다.

1. Claude Code 스킬의 개념
2. 동작원리
3. 전역 Skill vs 프로젝트 Skill
4. Skill.md 구조 이해하기
5. Skill.md 핵심 구성요소
6. Description 작성법
7. Skill이 중요한 이유

 

Claude Code를 사용하다 보면 자주 등장하는 단어가 하나 있다.

바로 Skill(스킬)이다.

처음 보면 이런 생각이 든다.

"스킬? 프롬프트 같은 건가?
아니면 코드 라이브러리인가?"

결론부터 말하면 둘 다 맞고, 둘 다 아니다.

Claude Code에서 말하는 Skill은 AI에게 특정 작업을 수행하는 방법을 가르쳐주는 “작업 단위 모듈”에 가깝다.

조금 더 쉽게 말하면 [AI에게 특정 업무를 맡기기 위한 작은 툴킷]이라고 보면 된다.

이번 글에서는 Claude Code에서 자주 등장하는 Skill의 개념과 구조를 정리해보려고 한다.

 

 

 

---

1. Claude Code에서 말하는 Skill의 개념

Skill은 AI가 특정 작업을 수행할 수 있도록 정의된 작업 단위다.

예를 들면 이런 것들이 Skill이 될 수 있다.

• 코드 리뷰 수행
• PRD 생성
• 테스트 코드 생성
• 문서 자동 정리
• API 문서 분석
• 로그 분석

즉 AI에게 특정 역할을 맡기는 작은 프로그램 같은 것이라고 보면 된다.

AI에게 그냥 "API 문서 읽고 요약해 줘" 하는 것과

Skill을 사용하는 것은 차이가 있다.

Skill은

• 작업 목적
• 작업 방법
• 참고 자료
• 출력 형식

까지 함께 정의되어 있기 때문에
AI가 일관된 방식으로 작업을 수행할 수 있다.

그래서 Claude Code에서는 프롬프트보다 더 구조화된 작업 단위로 Skill을 사용한다.

 

 

 

---

2. Skill의 동작 원리

Claude Code에서 Skill이 동작하는 방식은 생각보다 단순하다.

핵심은 Claude가 요청을 해석한 뒤, 적절한 Skill을 찾아 실행한다는 것이다.

동작 흐름은 대략 이렇게 된다.

사용자 요청
-> Claude가 요청 분석
-> 사용 가능한 Skill 탐색
-> 적절한 Skill 선택
-> Skill 설명을 기반으로 작업 수행

 

 

Skill은 자동으로 호출되는 “작업 매뉴얼” 역할을 한다.

예를 들어 사용자가 "이 코드 리팩토링 해줘" 말하면

Claude는 내부적으로 [refactor-code skill] 같은 Skill을 찾아 실행할 수 있다.

그래서 Skill은 단순한 텍스트가 아니라

AI가 작업을 수행하는 방식 자체를 정의하는 구조라고 보면 된다.

 

 

 

---

3. 전역 Skill vs 프로젝트 Skill

Claude Code에서 Skill은 두 가지 범위로 존재한다.

1) Global Skill (전역 스킬)

모든 프로젝트에서 사용할 수 있는 Skill이다.

• 코드 리뷰
• 커밋 메시지 생성
• 문서 정리
• 로그 분석

개발자가 자주 사용하는 개인 생산성 도구 같은 것들이다.

예를 들어

generate-commit-message
code-review
test-generator

 

같은 Skill은 전역으로 만들어 두면
어떤 프로젝트에서도 사용할 수 있다.

즉 내가 사용하는 AI 업무 도구 세트라고 보면 된다.

 

2) Project Skill (프로젝트 스킬)

특정 프로젝트에서만 사용하는 Skill이다.

예를 들어 어떤 프로젝트에 이런 규칙이 있다고 해보자.

• PRD 작성 규칙
• 코드 스타일 규칙
• API 설계 방식
• 문서 구조

이런 것들은 프로젝트마다 다르다.

그래서 프로젝트 내부에

.skills/

 

같은 폴더를 만들어 Skill을 정의할 수 있다.

예시)
generate-prd
api-doc-parser
project-architecture-guide

즉 프로젝트에 특화된 AI 작업 가이드라고 보면 된다.

 

 

 

 

---

4. SKILL.md 구조 이해하기

Claude Code에서 Skill은 보통 SKILL.md 파일로 정의된다.

예시로 기본 구조는 이렇게 생겼다.

SKILL.md

# Skill: Code Review

## Description
Analyze code and provide review feedback focusing on readability, performance, and maintainability.

## When to use
Use when the user asks for code review or improvement suggestions.

## Steps
1. Read the provided code
2. Identify potential issues
3. Suggest improvements
4. Provide example fixes

## Output format
- Summary
- Issues found
- Suggested improvements

 

이 파일 하나가 AI에게 전달되는 작업 매뉴얼이 된다.

Claude는 이 내용을 읽고
어떻게 작업해야 하는지 판단한다.

 

 

 

---

5. SKILL.md의 핵심 구성 요소

보통 SKILL.md는 이런 구조로 작성된다.

1) Skill 이름

# Skill: Code Review

AI가 이 Skill을 인식하는 이름이다.

2) Description

Skill의 핵심 목적을 설명하는 부분이다.

(Analyze code and provide structured feedback)

여기서 중요한 것은 AI가 언제 이 Skill을 사용해야 하는지 알 수 있도록 설명하는 것이다.

3) When to use

Skill을 언제 사용해야 하는지 정의한다.

Use when the user asks for:
- code review
- code improvement
- bug detection

 

이 부분이 있어야 Claude가 "지금 이 Skill을 써야 하는 상황인가?"를 판단할 수 있다.

4) Steps

AI가 수행해야 할 작업 절차를 정의한다.

예시
1. Analyze the code structure
2. Identify potential bugs
3. Suggest improvements
4. Provide refactored example

이 부분이 Skill의 핵심 로직이다.

5) Output format

AI가 어떤 형식으로 답변해야 하는지 정의한다.

예시
- Summary
- Problems
- Suggestions
- Example code

이걸 정의해 두면 AI 출력이 훨씬 안정적으로 나온다.

 

 

 

---

6. SKILL.md Description 작성법

Skill에서 가장 중요한 부분이 Description이다.

왜냐하면 Claude는 Description을 보고 Skill을 선택하기 때문이다.

좋은 Description의 특징은 이것이다.

1) 작업 목적이 명확하다

- 좋지 않은 예 :
Helps with code

- 좋은 예 :
Analyze code and provide detailed review feedback including potential bugs, performance issues, and maintainability improvements.

2) 어떤 상황에서 사용하는지 드러난다

- 좋은 Description 예 :
Use this skill to review code and suggest improvements when a user asks for code review, refactoring, or bug detection.

 

Claude가 언제 이 Skill을 호출해야 하는지 이해할 수 있다.

3) 너무 길지 않다

Description은 보통 1~3 문장 정도가 가장 좋다.

너무 길면 오히려 판단이 어려워진다.

 

 

 

---

7. Skill이 중요한 이유

Claude Code에서 Skill은 단순한 기능이 아니라

AI 협업 방식 자체를 바꾸는 개념이다.

예전에는 AI에게 "PRD 작성해 줘" 이렇게 시켰다.

하지만 Skill을 사용하면

[generate-prd skill]같이 작업을 표준화할 수 있다.

이렇게 되면

• AI 출력 품질이 안정되고
• 반복 작업 자동화가 가능하고
• 팀 단위 AI 사용도 가능해진다.

그래서 최근 AI 개발 환경에서는

프롬프트보다 Skill 기반 작업 구조가 점점 중요해지고 있다.

 

 

 

---

 

Claude Code에서 Skill은 단순한 기능이 아니라

AI에게 일을 맡기는 방식에 가깝다.

정리하면 Skill은

• AI 작업 단위 모듈
• 작업 매뉴얼
• 자동 실행 가능한 프롬프트 구조

라고 볼 수 있다.

Claude Code를 제대로 활용하려면
결국 중요한 것은 Skill을 얼마나 잘 설계하느냐가 될 수 있다.

좋은 Skill 몇 개만 만들어도 AI는 단순한 챗봇이 아니라

진짜 협업 파트너처럼 동작하기 시작한다.