Claude Code 스킬(슬래시 커맨드) 만들기 — 재사용 자동화 단위 완전 가이드
Claude Code 스킬을 만들면 코드 리뷰, 커밋 메시지 생성, 문서화 같은 반복 작업이 /review 한 번으로 끝난다. 반복해서 프롬프트를 치는 개발자, 팀 내 AI 활용 기준을 통일하고 싶은 리드에게 이 글이 직접 답한다. 스킬 파일 구조부터 frontmatter 옵션, 실전 예시 3가지, 팀 공유·버전 관리까지 순서대로 다룬다.
Claude Code 스킬을 재사용 자동화 단위로 구성하는 흐름을 요약한 AI 생성 대표 이미지.
슬래시 커맨드와 스킬, 무엇이 다른가?
슬래시 커맨드는 '저장된 프롬프트'이고, 스킬은 그 상위 개념이다. /clear, /compact 같은 내장 커맨드는 Claude Code CLI에 하드코딩된 고정 동작이다. 반면 커스텀 슬래시 커맨드·스킬은 개발자가 직접 마크다운 파일로 작성하는 재정의 가능한 단위다.
과거에는 .claude/commands/의 단순 마크다운 파일(커맨드)과 .claude/skills/의 SKILL.md(스킬)가 별도 개념으로 존재했다. 현재는 두 디렉터리 모두 동일한 슬래시 커맨드 인터페이스를 생성한다. 다만 스킬 형식이 frontmatter 제어, 하위 파일(템플릿·스크립트) 동봉, 동적 컨텍스트 주입 등 더 풍부한 기능을 지원하므로 신규 작성 시 스킬 형식이 권장된다.
스킬 파일은 어디에 두는가?
저장 위치에 따라 적용 범위가 달라진다. 프로젝트 전용은 .claude/skills/, 개인 전역은 ~/.claude/skills/에 둔다. 각 스킬은 폴더 하나로 구성하며, 폴더 이름이 그대로 슬래시 커맨드 이름이 된다.
.claude/
├── CLAUDE.md ← 프로젝트 전역 지시
├── settings.json ← 팀 공유 설정
├── settings.local.json ← 개인 로컬 설정 (.gitignore 권장)
└── skills/
├── commit/
│ └── SKILL.md → /commit
├── review/
│ └── SKILL.md → /review
└── doc/
├── SKILL.md → /doc
└── template.md ← 보조 파일(선택)단순 커맨드 파일(.claude/commands/review.md)도 여전히 동작한다. 하지만 보조 파일을 함께 두거나 frontmatter로 세부 제어가 필요하다면 스킬 폴더 구조를 쓰는 것이 낫다.
SKILL.md frontmatter에는 어떤 옵션이 있는가?
YAML frontmatter는 --- 블록 안에 작성한다. 모든 필드는 선택 사항이지만, description과 allowed-tools는 실용 가치가 높다.
| 필드 | 역할 | 예시 |
|---|---|---|
description |
/메뉴 표시 문구, 자동 호출 판단 근거 | 'PR diff 검토 후 인라인 코멘트 작성' |
allowed-tools |
사용 가능한 도구 제한(권한 프롬프트 감소) | Bash, Read, Write |
argument-hint |
호출 시 인자 힌트 표시 | [branch-name] [issue-number] |
model |
특정 모델 강제 지정 (시점마다 유효 ID 확인 필요) | claude-opus-4-8 (2026-05 기준 최신) |
user-invocable |
수동 호출 허용 여부(기본 true) | true / false |
context |
컨텍스트 격리 방식 | fork / inherit |
disable-model-invocation |
Claude 자동 호출 비활성화 (수동 호출만 허용) | true |
공식 문서(Extend Claude with skills)에서 최신 필드 목록을 확인하는 것이 좋다. 스펙은 버전에 따라 추가·변경될 수 있다.
기본 스킬 구조는 어떻게 작성하는가?
아래가 최소 동작 SKILL.md 구조다. frontmatter 다음에 Claude에게 전달할 지시를 마크다운으로 자유롭게 작성하면 된다.
---
description: 스테이지된 변경을 분석해 Conventional Commits 형식 메시지를 제안한다
allowed-tools: Bash, Read
argument-hint: "[scope] (선택)"
---
# commit 스킬
## 목표
`git diff --staged` 출력을 읽고 커밋 메시지 초안을 작성한다.
## 규칙
- 형식: `<type>(<scope>): <summary>` (영문, 현재형)
- type: feat / fix / refactor / docs / test / chore
- summary 50자 이내
- 본문은 변경 이유 중심, 불필요한 줄 생략
## 절차
1. `git diff --staged`를 실행해 변경 내용을 파악한다.
2. 변경 유형과 영향 범위를 분류한다.
3. 커밋 메시지 초안 1~3개를 제안하고 선택을 요청한다.
4. 확정 후 `git commit -m` 으로 커밋한다.인자($ARGUMENTS)를 활용하면 호출 시점에 동적 값을 주입할 수 있다. 예를 들어 /commit feat으로 호출하면 $ARGUMENTS 위치에 'feat'가 전달된다.
실전 스킬 3가지 — 커밋, 코드 리뷰, 문서화
팀에서 가장 자주 쓰이는 3가지 스킬을 살펴본다. 아래 예시는 출발점이며, 팀 컨벤션에 맞게 수정해야 한다.
1. /commit — 커밋 메시지 자동 초안
---
description: 스테이지된 diff를 읽어 Conventional Commits 메시지를 제안한다
allowed-tools: Bash, Read
---
git diff --staged 전체를 읽는다.
변경 유형(feat/fix/refactor/docs/test/chore)과 scope를 추론한다.
메시지 후보 2개를 제안하고, 선택 후 git commit -m 으로 실행한다.
이미 스테이지된 파일 외에는 절대 수정하지 않는다.2. /review — PR diff 코드 리뷰
---
description: 현재 브랜치 diff를 리뷰하고 인라인 코멘트 형식으로 출력한다
allowed-tools: Bash, Read
argument-hint: "[base-branch] (기본: main)"
---
$ARGUMENTS 가 있으면 해당 브랜치를 base로, 없으면 main을 base로 사용한다.
git diff <base>...HEAD 를 읽는다.
다음 항목을 순서대로 검토한다:
1. 로직 버그 및 엣지케이스 누락
2. 보안 취약점 (SQL injection, XSS, 인증 누락)
3. 성능 문제 (N+1, 불필요한 루프)
4. 네이밍 및 가독성
각 이슈는 `파일명:라인` 형식으로 위치를 명시한다.
이슈가 없는 파일은 언급하지 않는다.3. /doc — 함수·모듈 문서 자동 생성
---
description: 지정 파일의 public 함수에 JSDoc/KDoc 주석을 추가한다
allowed-tools: Read, Write
argument-hint: "<file-path>"
---
$ARGUMENTS 에서 파일 경로를 읽는다.
해당 파일을 열고 public 함수·메서드를 식별한다.
기존 주석이 있으면 보완, 없으면 새로 작성한다.
파라미터 타입은 기존 코드에서 추론하고, 불확실하면 @param {*} 로 표시한다.
주석 외 코드 로직은 변경하지 않는다.3가지 모두 allowed-tools를 명시해 Claude가 불필요한 도구 사용 권한을 요청하지 않도록 했다. 이 1줄이 팀 사용성을 크게 높인다.
스킬을 팀과 공유하고 버전 관리하는 방법은?
프로젝트 루트의 .claude/skills/를 git에 커밋하면 팀 전체가 동일한 스킬을 쓴다. git pull만 해도 업데이트된 스킬이 배포되는 구조다.
-
.claude/skills/ → git 커밋 대상 (팀 공유)-
.claude/settings.local.json → .gitignore 추가 (개인 설정)-
~/.claude/skills/ → 전역 개인 스킬 (git 관리 별도)
팀 규모가 커지거나 여러 프로젝트에 동일 스킬을 쓰고 싶다면 플러그인으로 승격하는 방법이 있다. 플러그인은 .claude-plugin/plugin.json을 포함한 독립 디렉터리 구조로, 마켓플레이스 배포나 버전 릴리스 관리에 적합하다. 단일 프로젝트라면 스킬 폴더로 충분하다.
스킬 파일을 수정할 때는 변경 이유를 커밋 메시지에 남기는 것이 좋다. 프롬프트도 코드와 동일하게 변경 추적이 가능하고, 이전 버전으로 롤백도 된다.
스킬이 효과적인 작업과 그렇지 않은 작업의 차이는?
스킬이 빛나는 상황은 3가지다. 첫째, 매번 같은 패턴의 지시가 반복될 때. 둘째, 팀 내 기준을 통일해야 할 때(리뷰 체크리스트, 커밋 컨벤션). 셋째, 인자 1~2개만 바뀌고 나머지는 동일한 작업.
반대로 작업이 매번 크게 달라지거나, 컨텍스트를 실시간으로 재구성해야 하는 경우는 스킬보다 CLAUDE.md에 원칙을 기술하는 편이 낫다. 스킬은 '동일한 작업의 반복'을 위한 도구이지, '모든 상황의 지시'를 담는 그릇이 아니다.
스킬 하나의 분량도 중요하다. 지시가 200줄을 넘기 시작하면 단일 책임 원칙대로 분리하는 것이 좋다. 그래야 Claude가 의도를 명확하게 파악하고 실행한다.
🤖 AI·자동화 가이드 더 보기
FAQ
Q1. .claude/commands/와 .claude/skills/의 차이는 실제로 있는가?
현재 버전에서 두 디렉터리 모두 슬래시 커맨드를 생성한다. 기능 차이는 거의 없지만, 스킬 형식은 하위 파일 동봉과 frontmatter 제어가 가능해 신규 작성 시 권장된다. 공식 문서를 시점마다 확인하는 것이 안전하다.
Q2. argument-hint를 쓰면 인자가 강제되는가?
아니다. argument-hint는 /메뉴에서 사용자에게 보여주는 힌트 문구일 뿐이다. 실제로 인자 없이 호출해도 스킬은 실행된다. 스킬 본문에서 $ARGUMENTS가 비어있을 때 기본값을 처리하는 로직을 직접 작성해야 한다.
Q3. 개인 스킬과 프로젝트 스킬이 같은 이름이면 어떻게 되는가?
공식 문서 기준으로 우선순위는 enterprise > personal(~/.claude/skills/) > project(.claude/skills/) > plugin 순이다. 즉, 같은 이름이면 개인 전역 스킬(~/.claude/skills/)이 프로젝트 스킬(.claude/skills/)보다 우선 적용된다. 팀 공유 기준을 프로젝트 스킬로 두고 싶다면 개인 전역에 동명 스킬을 두지 않도록 주의해야 한다.
Q4. 스킬 안에서 외부 API를 호출하거나 셸 스크립트를 실행할 수 있는가?
가능하다. allowed-tools: Bash를 지정하면 Claude가 셸 명령을 실행할 수 있다. 단, 외부 시스템에 부하를 주는 반복 호출은 별도 확인 절차를 스킬 본문에 명시하는 것이 좋다.
Q5. 스킬을 플러그인으로 언제 전환해야 하는가?
여러 프로젝트에서 동일 스킬을 쓰거나, 버전 릴리스 단위로 배포해야 하거나, 팀 외부(마켓플레이스)와 공유할 때다. 단일 프로젝트 내 팀 공유는 .claude/skills/ git 커밋으로 충분하다.
3줄 요약
- 스킬은 SKILL.md 파일 하나로 만들고, 폴더 이름이 슬래시 커맨드 이름이 된다.
- frontmatter의
description과allowed-tools만 챙겨도 팀 사용성이 크게 오른다. .claude/skills/를 git에 커밋하면 팀 전원이 동일한 자동화 기준을 공유한다.
다음 글 예고: Claude Code 플러그인 구조와 plugin.json 작성법, 마켓플레이스 등록 절차를 다룬다. 스킬을 팀 외부까지 배포하고 싶다면 플러그인이 답이다.
도구 기능·가격은 업데이트가 잦아 공식 문서 재확인을 권한다.
댓글
댓글 쓰기