⚖

Commands vs Skills 완전 비교

Claude Code

.claude/commands/ 와 .claude/skills/ — 언제 뭘 써야 하나

Claude Code에서 커스텀 자동화를 만들 때 Commands와 Skills 중 어떤 걸 써야 하는지 헷갈리는 경우가 많다. 핵심 차이를 정리한다.

가장 큰 차이: 자동 실행 여부

Commands는 사용자가 /이름으로 직접 호출해야만 실행된다. Skills는 그것도 가능하지만, Claude가 작업 맥락을 보고 알아서 판단해서 실행할 수도 있다. 예를 들어 Rails 코드를 작성하면 rspec-test-generator 스킬이 자동으로 트리거되는 식이다.

두 번째 차이: 파일 구조

Commands는 commands/이름.md 파일 하나가 전부다. Skills는 skills/이름/ 디렉토리 안에 SKILL.md(메인 지시서) + references/(참조 문서) + 기타 보조 파일을 포함할 수 있다.

세 번째 차이: 복잡도

Commands는 "이거 해라"라는 단순한 프롬프트에 적합하다. Skills는 여러 단계의 워크플로우, 참조 문서, 템플릿 패턴 등이 필요한 복잡한 작업에 적합하다.

선택 기준

단순한 반복 작업(커밋 메시지 생성, 블로그 스타일 선택 등) → Command

복잡한 워크플로우(앱 스캐폴딩, PR 리뷰, SEO 감사 등) → Skill

Commands vs Skills 비교표

구분	.claude/commands/	.claude/skills/
호출 방법	/command-name으로 직접 실행만 가능	/skill-name으로 실행하거나, Claude가 자동 판단해서 실행
파일 구조	단일 `.md` 파일	디렉토리 (`SKILL.md` + `references/` 등 보조 파일)
복잡도	단순한 프롬프트/지시서	복잡한 워크플로우 + 참조 문서 포함 가능
자동 트리거	불가 — 수동 호출만	가능 — description에 트리거 조건 명시하면 Claude가 자동 실행
인자 전달	`$ARGUMENTS`로 받음	`$ARGUMENTS`로 받음 (동일)
참조 파일	불가 — .md 파일 하나에 전부 작성	가능 — references/ 폴더에 스펙, 가이드, 템플릿 등 배치
공유 범위	프로젝트 루트 .claude/commands/에 위치 → 프로젝트 전체	프로젝트 루트 .claude/skills/에 위치 → 프로젝트 전체

파일 구조 비교

Command 예시

.claude/commands/
  blog-help.md      ← 파일 1개가 전부
  blog-comparison.md
  pr.md

각 .md 파일 = 하나의 커맨드

Skill 예시

.claude/skills/
  geo-audit/
    SKILL.md          ← 메인 지시서
    references/
      scoring.md      ← 점수 기준
      platforms.md    ← 플랫폼 목록
  add-auth/
    SKILL.md
    references/
      template.rb     ← 코드 템플릿

디렉토리 = 하나의 스킬

언제 뭘 쓸까?

Command가 적합한 경우

✓ 블로그 엔트리 생성 (/blog-comparison)
✓ 커밋 메시지 생성 (/commit)
✓ PR 생성 (/pr)
✓ DB 스캔 (/db-scan)
✓ 도움말 표시 (/blog-help)

공통점: 한 문장~한 페이지 지시로 끝남

Skill이 적합한 경우

✓ SEO/GEO 종합 감사 (스코어링 기준 참조 필요)
✓ 앱 인증 추가 (템플릿 코드 참조 필요)
✓ RSpec 테스트 자동 생성 (코드 변경 감지 시 자동 트리거)
✓ PDF 리포트 생성 (여러 단계 + 참조 문서)
✓ 스키마 마크업 감사 (검증 규칙 참조 필요)

공통점: 참조 문서가 필요하거나, 자동 트리거가 필요함

사용 방법

1

단순 반복 작업이면 → .claude/commands/이름.md 생성

2

복잡한 워크플로우면 → .claude/skills/이름/SKILL.md + references/ 생성

3

자동 트리거가 필요하면 → Skill의 description에 트리거 조건 명시

4

인자가 필요하면 → $ARGUMENTS 변수로 받기 (Commands/Skills 둘 다 지원)

Source

Anthropic Docs