[Claude Code] Claude Code의 Commands vs Skills, 뭐가 다른가❓

개요

Claude Code를 쓰다 보면 세 가지 설정 파일을 마주치게 됩니다.

• CLAUDE.md ➡️ 매 세션마다 자동으로 로드되는 프로젝트 규칙
• .claude/commands/ ➡️ 내가 직접 /명령어로 호출하는 커맨드
• .claude/skills/ ➡️ Claude가 대화 흐름을 보고 자동으로 감지해서 쓰는 스킬

처음에는 Commands와 Skills이 둘 다 슬래시 커맨드로 호출되니까 "그냥 같은 거 아닌가?" 싶었습니다. 실제로 원래는 별개 시스템이었는데 현재는 통합되어 둘 다 같은 /명령어 인터페이스로 작동합니다.

 

오늘은 이 차이점을 직접 포트폴리오 프로젝트를 만들면서 겪은 경험을 바탕으로 정리하고자 합니다.

 

Commands

Commands : 내가 직접 호출 하는 것

• 위치
  • claude/commands/명령어이름.md

내가 터미널에서 /명령어를 직접 입력했을 때만 실행됩니다. Claude가 "이 상황이면 이 커맨드를 써야겠다"고 판단해서 자동으로 실행하지 않습니다.

---

Ex ) /push 

## 절차
1. git status, git diff로 변경사항 분석
2. CLAUDE.md 커밋 컨벤션 참조해서 메시지 자동 생성
3. 생성된 메시지 확인 요청
4. git add -A && git commit && git push

 

Commands를 쓰는 경우

• 사이드이펙트가 있는 작업 (push, deploy, 파일 삭제)
• 내가 타이밍을 직접 제어해야 하는 작업
• 단순한 반복 작업 자동화

Skills

Skills: Claude가 자동으로 감지하는 것

• 위치
  • .claude/skills/스킬이름/SKILL.md

Skills는 YAML frontmatter의 description 필드를 보고 Claude가 "지금 이 스킬이 필요한 상황이다"라고 판단하면 자동으로 로드합니다.

 

내가 직접 호출할 수도 있지만, 핵심은 자동 감지입니다.

 

Ex ) explain-code 스킬

 

---
name: explain-code
description: 코드 설명 요청 시 사용. "어떻게 작동해?", 
             "이 코드 설명해줘" 같은 요청에 자동 감지.
---

코드를 설명할 때 항상:
1. 일상적인 비유로 시작
2. ASCII 다이어그램으로 흐름 표시
3. 단계별로 풀어서 설명

 

사용자가 "이 코드 어떻게 작동해?"라고 물으면 Claude가 explain-code 스킬을 자동으로 로드해서 그 방식대로 답변합니다.

 

Skills를 쓰는 경우

• Claude가 알아서 판단해서 써줬으면 하는 작업
• 지원 파일(스크립트, 템플릿)이 필요한 복잡한 작업
• 여러 프로젝트에서 공통으로 쓰는 방법론
  
  

---

Skills YAML frontmatter 구조

---
name: review-code          # 스킬 식별자 (필수)
description: |             # 자동 감지 트리거 (필수, 핵심)
  코드 리뷰 요청 시 사용.
  "리뷰해줘", "코드 봐줘", "문제 있어?" 같은
  요청에 자동 감지.
version: 1.0               # 버전 관리 (선택)
author: jinwoo             # 작성자 (선택)
tags: [review, quality]    # 분류용 태그 (선택)
---

 

여기서 description이 핵심입니다.

 

Claude는 이 필드를 보고 "지금 이 스킬을 써야 하는 상황인가"를 판단합니다.

 

한 가지 주의할 점이 있습니다. 공식 문서에서도 Claude가 스킬을 undertrigger하는 경향이 있다고 인정합니다. 필요한 상황인데 스킬을 안 쓰는 경우입니다.

 

그래서 description은 소극적으로 쓰면 안 됩니다.

# 소극적 (undertrigger 위험)
description: 코드 리뷰 스킬

# 적극적 (권장)
description: |
  코드 리뷰 요청 시 사용.
  "리뷰해줘", "코드 봐줘", "문제 있어?", "확인해줘" 같은
  요청뿐 아니라 코드를 보여주면서 의견을 묻는 상황에서도 반드시 사용할 것.

 

Commands vs Skills 핵심 차이점

위치	.claude/commands/	.claude/skills/<name>/
파일명	명령어.md	SKILL.md (고정)
호출	내가 직접 /명령어	자동 감지 + 직접 호출
지원 파일	없음	스크립트, 템플릿 등 가능

---

실제로 어떻게 구분해서 써야할까❓

처음엔 코드 리뷰도 Commands로 만들었습니다.

 

그런데 쓰다 보니 문제가 생겼습니다. /review를 타이핑해야 한다는 걸 매번 잊어버리니, "이 코드 좀 봐줘"라고 자연어로 물어보게 되고 일반 답변이 나올 뿐 내가 정해둔 리뷰 방식대로 동작하지 않았습니다.

 

반면 /push는 Commands가 딱 맞았습니다. Claude가 "변경사항이 많아 보이니 자동으로 푸시할게요"라고 하면 곤란하니까요.

 

그때 판단 기준이 명확해졌습니다. 내가 타이밍을 제어해야 하면 Commands, Claude가 알아서 판단해줬으면 하면 Skills.

• /push, /done 같은 사이드이펙트가 있는 작업은 내가 원할 때만 실행되어야 합니다. ➡️ Commands
• "리뷰해줘", "이 코드 설명해줘" 같은 요청은 슬래시 커맨드를 타이핑하지 않아도 Claude가 알아서 그 방식대로 답해줬으면 하는 작업입니다. ➡️ Skills

공식 문서에서도 /commit, /deploy 같은 사이드이펙트 있는 작업은 disable-model-invocation: true 설정으로 사용자만 호출 가능하게 하라고 권장합니다.

 

disable-model-invocation 예시

---
name: push
description: 변경사항을 git push한다
disable-model-invocation: true  # 사용자만 호출 가능
---

## 절차
1. git status, git diff로 변경사항 분석
...

 

disable-model-invocation: true를 설정하면 Claude가 "지금 push하면 좋을 것 같은데요"라며 자동으로 실행하는 걸 막습니다. 사이드이펙트 있는 커맨드엔 필수로 걸어두는 게 좋습니다.

---

결론

처음에는 둘 다 슬래시 커맨드로 보여서 같은 거라고 생각했지만, 핵심 차이는 누가 호출하느냐입니다.

• 내가 직접 호출 ➡️ Commands
• Claude가 자동 감지 + 직접 호출 모두 ➡️ Skills

규모가 작은 프로젝트 정도의 규모라면 Commands만으로도 충분합니다. Skills는 Claude가 자동으로 판단해서 실행해줬으면 하는 복잡한 워크플로우가 생겼을 때 도입하면 된다고 생각합니다.