Claude Code의 스킬(Skill)이란 무엇인가

Claude Code를 어느 정도 사용하다 보면 이런 순간이 온다.

"분명 같은 일을 시키고 있는데, 어떤 날은 잘 맞고 어떤 날은 다시 설명해야 한다."

이 문제는 프롬프트를 잘 쓰느냐의 문제가 아니라, Claude Code에서 '규칙을 어디에 정의하느냐'를 이해했느냐의 문제다.

1. 먼저 짚고 가야 할 용어 정리

Claude Code에는 "규칙"을 정의하는 방법이 여러 가지 있고, 이들이 종종 혼동된다. 이 구분을 먼저 이해해야 글 전체가 명확해진다.

Claude Code에서 규칙을 정의하는 3가지 방법

2. Claude Code의 '스킬(Skill)'이란?

Claude Code에서 말하는 **스킬(Skill)**은 다음과 같다.

스킬은 슬래시 커맨드(/)로 호출되는, 특정 작업을 수행하기 위해 미리 정의된 워크플로우다.

예를 들면 다음과 같다.

• /commit → 변경 사항을 분석해 커밋 메시지 생성
• /review-pr → PR 변경 내역을 기준으로 코드 리뷰 수행

즉, 스킬은 **항상 자동으로 적용되는 규칙"이 아니라, "필요할 때 명시적으로 실행하는 도구**다.

3. '항상 같은 방식으로 처리'는 어디서 정의할까?

많은 사람들이 말하는 "항상 같은 기준으로 처리하게 한다"는 개념은 스킬이 아니라 CLAUDE.md의 역할에 가깝다.

CLAUDE.md의 역할과 위치

CLAUDE.md는 프로젝트 루트에 두는 파일로,

• 이 프로젝트에서의 기본 전제
• 반복해서 설명하던 규칙
• 하지 말아야 할 것들

을 지속적으로 적용되는 규칙으로 정의한다.

추가로, 전역적으로 적용하고 싶은 규칙이 있다면 ~/.claude/CLAUDE.md에 둘 수도 있다.

CLAUDE.md 예시 (TDD 규칙)

## 개발 규칙
 
- 모든 기능 개발은 테스트부터 작성한다
- RED → GREEN → REFACTOR 순서를 따른다
- 테스트 없이 구현 코드를 추가하지 않는다
- 불확실한 경우 추측하지 말고 질문한다

이렇게 정의해두면, 기능 개발 요청 자체가 TDD 전제 위에서 처리된다.

4. 스킬을 사용하지 않을 때의 사용자 경험

스킬과 CLAUDE.md를 구분하지 않고 사용할 때의 경험은 보통 이렇다.

1) 매번 기준을 다시 설명한다

• "이번에는 최소 변경으로"
• "테스트부터 작성해줘"
• "추측하지 말고"

같은 설명을 계속 반복하게 된다.

2) 결과의 일관성이 떨어진다

• 어떤 날은 과한 리팩토링
• 어떤 날은 테스트 생략
• 어떤 날은 설명 부족

결과를 사람이 계속 보정해야 한다.

이 단계의 Claude는 능력은 있지만 성향이 일정하지 않은 동료에 가깝다.

5. 스킬과 CLAUDE.md를 함께 사용할 때의 경험

역할을 명확히 나누면 사용자 경험이 완전히 달라진다.

• CLAUDE.md → "이 프로젝트의 기본 규칙"
• 스킬(Skill) → "특정 작업을 수행하는 도구"

실제 사용 흐름 예시

1. 프로젝트에 CLAUDE.md로 기본 규칙 정의
2. 기능 개발 요청
3. Claude는 규칙(TDD 등)을 자동으로 전제
4. 필요할 때 /commit, /review-pr 같은 스킬 호출

이 구조가 되면:

• 설명 비용이 급격히 줄고
• 결과의 톤과 품질이 안정되며
• 반복 작업일수록 더 편해진다

Claude는 내 일하는 방식에 맞춰진 팀원처럼 느껴진다.

6. "추천 스킬 셋"이 아니라 "추천 역할 분담 구조"

흔히 "추천 스킬 셋"이라고 부르지만, 정확히 말하면 스킬·규칙·프롬프트의 역할 분담에 가깝다.

1) CLAUDE.md에 두면 좋은 규칙 (프로젝트 기본값)

• 최소 변경(diff 최소화)
• 추측 금지, 불확실하면 질문
• 테스트 우선(TDD)
• 민감 파일(.env, 키 등) 접근 금지
• 요청 없는 대규모 리팩토링 금지

2) 필요할 때 호출하는 스킬

• /commit : 커밋 메시지 작성
• /review-pr : PR 리뷰
• 또는 프로젝트에 맞게 직접 정의한 커스텀 스킬

(반복 작업이 명확하다면 커스텀 스킬로 분리하는 것이 효과적이다.)

3) 프롬프트는 예외 처리용으로만 사용

• "이번 작업은 PoC라서 테스트 없이"
• "이 파일만 빠르게 수정"

7. 지금 바로 해볼 수 있는 액션

글을 읽고 끝나지 않도록, 바로 실천할 수 있는 단계다.

지금 바로 해볼 것

1. 프로젝트 루트에 CLAUDE.md 파일 생성
2. 반복해서 설명하던 규칙 3가지를 적기
3. 다음 작업에서 설명 없이 요청해보고 차이 체감하기
4. 반복 작업은 /commit, /review-pr 같은 스킬로 분리하기

8. 정리

• **스킬(Skill)**은 작업을 실행하는 도구다
• CLAUDE.md는 프로젝트의 기본 규칙이다
• 프롬프트는 일회성 예외 처리다

이 셋을 구분해서 쓰기 시작하면, Claude Code는 단순한 AI가 아니라

**"내 일하는 방식을 이해하고 따르는 협업자"**가 된다.

핵심 메시지는 변하지 않는다.

AI에게 일을 시키는 게 아니라, 일하는 방식을 가르치는 것이다.