Claude Code Skills — 나만의 슬래시 명령어 만들기

Claude Code Skills란?

Claude Code에서 /commit, /review 같은 슬래시 명령어를 본 적이 있을 것이다. Skills는 이런 나만의 슬래시 명령어를 직접 만들 수 있는 기능이다.

/blog React 렌더링 최적화     ← 블로그 자동 작성
/deploy                       ← 배포 자동화
/review-pr 123                ← PR 리뷰 자동화

SKILL.md 파일 하나만 작성하면 Claude에게 특정 작업의 절차, 규칙, 도구 권한을 미리 정의할 수 있다. 매번 같은 지시를 반복할 필요 없이, 한 번 만들어두면 계속 재사용할 수 있다.

---

파일 구조

Skill은 .claude/skills/ 디렉토리 안에 폴더 단위로 관리한다.

.claude/skills/
├── blog/
│   └── SKILL.md            ← /blog 명령어
├── deploy/
│   └── SKILL.md            ← /deploy 명령어
└── review/
    ├── SKILL.md            ← /review 명령어
    └── templates/
        └── review-form.md  ← 리뷰 템플릿 (선택)

어디에 만드느냐에 따라 범위가 다르다

위치	범위
./.claude/skills/	현재 프로젝트에서만 사용
~/.claude/skills/	내 모든 프로젝트에서 사용

프로젝트 전용 명령어는 프로젝트 안에, 범용 명령어는 홈 디렉토리에 만들면 된다.

---

SKILL.md 작성법

SKILL.md는 frontmatter(설정) + 본문(지시사항) 으로 구성된다.

기본 예시

---
name: blog
description: 블로그 포스트를 작성합니다
argument-hint: <주제>
---

# 블로그 작성

사용자가 입력한 주제로 블로그 포스트를 작성합니다.

1. content/posts/ 디렉토리에 md 파일 생성
2. 기존 포스트 스타일에 맞춰 작성
3. frontmatter 포함 (title, date, tags)

frontmatter 주요 필드

필드	설명	예시
name	명령어 이름 (/name으로 호출)	blog
description	Skill이 하는 일 설명	블로그 포스트를 작성합니다
argument-hint	인자 힌트 (자동완성에 표시)	<주제>
allowed-tools	허용할 도구 (승인 없이 실행)	Read Write Bash(git *)
disable-model-invocation	true면 수동 호출만 가능	true
user-invocable	false면 사용자 호출 불가 (Claude만 사용)	false
paths	특정 파일 편집 시 자동 로드	src/**/*.ts
context	fork면 별도 subagent에서 실행	fork

---

변수 ($ARGUMENTS)

사용자가 명령어 뒤에 입력한 값을 Skill 본문에서 변수로 받을 수 있다.

---
name: fix-issue
description: GitHub issue를 수정합니다
argument-hint: <issue-number>
---

GitHub issue $ARGUMENTS 를 수정합니다.

/fix-issue 42
→ "GitHub issue 42 를 수정합니다."

여러 인자를 받을 때

---
name: migrate
description: 컴포넌트를 마이그레이션합니다
---

$0 컴포넌트를 $1에서 $2로 마이그레이션합니다.

/migrate Button React Vue
→ $0 = Button, $1 = React, $2 = Vue

변수	설명
$ARGUMENTS	전체 인자 문자열
$0, $1, $2...	개별 인자 (0부터 시작)
${CLAUDE_SKILL_DIR}	Skill 디렉토리 경로
${CLAUDE_SESSION_ID}	현재 세션 ID

---

도구 권한 설정 (allowed-tools)

기본적으로 Claude는 위험한 도구를 실행할 때 사용자에게 승인을 요청한다. allowed-tools를 설정하면 특정 도구를 승인 없이 실행할 수 있다.

---
name: commit
description: 변경사항을 커밋합니다
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

변경사항을 커밋합니다:
1. git status로 변경사항 확인
2. git add로 스테이징
3. 커밋 메시지 작성 후 git commit

이렇게 하면 /commit 실행 시 git 명령어에 대해 매번 "허용하시겠습니까?"를 묻지 않는다.

---

자동 로드 vs 수동 호출

자동 로드

Claude는 사용자의 요청이 Skill의 description과 일치하면 자동으로 해당 Skill을 로드한다.

---
name: rust-conventions
description: Rust 코딩 컨벤션
paths: "src/**/*.rs"
---

Rust 코드 작성 시:
1. Result로 에러 처리
2. unwrap() 사용 금지
3. clippy 경고 0개 유지

이 Skill은 .rs 파일을 편집할 때 자동으로 적용된다.

수동 호출만 허용

배포처럼 위험한 작업은 Claude가 마음대로 실행하면 안 된다.

---
name: deploy
description: 프로덕션 배포
disable-model-invocation: true
---

배포 절차:
1. 테스트 실행
2. 빌드
3. 배포

disable-model-invocation: true로 설정하면 반드시 /deploy로만 실행할 수 있다.

---

동적 컨텍스트 주입

!`command` 문법으로 셸 명령어 결과를 Skill에 동적으로 주입할 수 있다. 이 명령어는 Skill이 로드되기 전에 먼저 실행된다.

---
name: pr-summary
description: 현재 PR을 요약합니다
---

## 변경된 파일
!`git diff --name-only`

## 변경 내용
!`git diff --stat`

위 변경사항을 분석하고 PR 요약을 작성하세요.

/pr-summary를 실행하면 git 명령어가 먼저 실행되고, 그 결과가 포함된 상태로 Claude에게 전달된다.

---

실전 예시: 블로그 작성 Skill

실제로 이 블로그에서 사용 중인 Skill이다.

---
name: blog
description: 블로그 포스트를 작성합니다
argument-hint: <주제>
allowed-tools: Read Write Edit Glob Grep Bash(ls *)
---

# 블로그 작성 Skill

## 작성 절차

### 1단계: 기존 포스트 스타일 파악
- content/posts/ 디렉토리의 기존 포스트를 읽어서 문체를 파악한다

### 2단계: 포스트 작성
- content/posts/ 디렉토리에 md 파일을 생성한다
- frontmatter 포함 (title, date, description, tags, thumbnail)

### 3단계: 로드맵 체크
- 블로그-작성-로드맵.md에서 해당 주제를 [x]로 체크한다

## 글쓰기 규칙
1. 쉬운 설명: 주니어 개발자도 이해할 수 있도록
2. 코드 예시 필수
3. 비유 활용
4. 마지막에 정리 섹션

/blog JWT 인증
→ JWT 인증에 대한 블로그 포스트가 자동으로 생성된다

---

Skill을 잘 만드는 팁

1. description을 구체적으로 써라

Claude가 자동 로드 여부를 description으로 판단한다. "유용한 도구"보다 "블로그 포스트를 content/posts/에 생성합니다"가 낫다.

2. 위험한 작업은 반드시 disable-model-invocation: true

배포, 삭제, 푸시 같은 작업은 Claude가 자동으로 실행하면 안 된다.

3. allowed-tools는 최소한으로

필요한 도구만 허용한다. Bash(*)처럼 모든 명령어를 허용하면 의미가 없다.

4. 동적 컨텍스트를 활용하라

!`git branch --show-current` 같은 명령어로 현재 상태를 주입하면 Skill이 더 똑똑하게 동작한다.

---

정리

개념	설명
Skill	SKILL.md로 정의하는 재사용 가능한 슬래시 명령어
위치	.claude/skills/name/SKILL.md (프로젝트) 또는 ~/.claude/skills/ (전역)
호출	/skill-name 인자 로 수동 호출, 또는 Claude가 자동 로드
변수	$ARGUMENTS, $0, $1 등으로 인자 전달
도구 권한	allowed-tools로 승인 없이 실행할 도구 지정
안전장치	disable-model-invocation으로 수동 호출만 허용
동적 주입	!`command`로 셸 결과를 Skill에 포함

Skill은 결국 "Claude에게 주는 업무 매뉴얼" 이다. 자주 반복하는 작업이 있다면, Skill로 만들어두면 매번 같은 설명을 할 필요가 없다.