🚀 Claude Skills로 반복 작업 자동화하기 - 5단계 실전 가이드

소개

프론트엔드 개발을 하다 보면 커밋 메시지 작성, 코드 리뷰, 문서화 등 반복적인 작업이 많아요. Claude Skills는 이러한 반복 작업을 자동화하는 도구예요. Claude Code CLI에서 커스텀 워크플로우를 정의하여, 복잡한 다단계 작업을 하나의 명령어로 실행할 수 있어요.

이 글에서는 Claude Skills의 기본 개념부터 실전 예제까지 단계별로 알아볼게요. 이 글을 읽으면 나만의 스킬을 만들어 개발 생산성을 높일 수 있어요.

이 글은 Claude Code CLI를 설치하고 기본 사용법을 이해한 개발자를 대상으로 해요.

Claude Skills 시작하기

설치 확인

Claude Code가 설치되어 있는지 확인해보세요.

claude --version

디렉토리 구조

Claude Skills는 프로젝트의 .claude/skills/ 디렉토리에 저장돼요.

.claude/
└── skills/
    └── my-skill/
        ├── SKILL.md        # 스킬 정의 파일 (필수)
        └── references/     # 참조 파일 (선택)
            ├── template.md
            └── config.json

스킬 자동 인식

.claude/skills/ 디렉토리에 있는 모든 스킬은 자동으로 인식돼요. 별도의 등록 과정이 필요 없어요.

첫 번째 스킬 만들기

가장 간단한 스킬부터 시작해볼게요. SKILL.md 파일은 YAML frontmatter와 워크플로우 지시사항으로 구성돼요.

## <!-- .claude/skills/hello-skill/SKILL.md -->

name: hello-skill
description: 사용자에게 간단한 인사 메시지를 생성해요

---

# hello-skill

간단한 인사 메시지를 생성하는 스킬이에요.

## 워크플로우

### Step 1: 사용자 이름 확인

사용자가 인자로 이름을 제공했는지 확인해요.

- 제공된 경우: 해당 이름 사용 (첫 번째 인자를 이름으로 사용)
- 제공되지 않은 경우: 사용자에게 이름 입력 요청

### Step 2: 인사 메시지 생성 및 출력

다음 형식으로 인사 메시지를 생성하여 출력해요.

안녕하세요, [이름]님!
Claude Skills에 오신 것을 환영합니다.

SKILL.md는 지시사항이에요

SKILL.md는 프로그래밍 언어가 아니라 Claude를 위한 지시사항이에요. Claude가 이 내용을 읽고 해석하여 필요한 도구(Read, Write, Bash 등)를 자동으로 선택해서 사용해요.

스킬 실행 방법은 다음과 같아요.

# CLI에서
claude skills hello-skill "홍길동"

# 또는 대화형 모드에서
/hello-skill 홍길동

실전 예제: 커밋 메시지 자동 생성

이제 실전 예제로 Conventional Commits 형식의 커밋 메시지를 자동 생성하는 스킬을 만들어볼게요.

워크플로우 설계

커밋 메시지 생성 스킬은 다음 5단계로 구성돼요.

변경사항 분석: git diff로 수정된 파일과 내용 확인
변경 유형 분류: feat, fix, refactor 등 타입 결정
영향 범위 파악: 어떤 모듈/컴포넌트가 변경되었는지 분석
메시지 생성: Conventional Commits 형식으로 작성
사용자 확인: 메시지 승인 후 클립보드 복사 또는 직접 커밋

SKILL.md 작성

## <!-- .claude/skills/commit-msg/SKILL.md -->

name: commit-msg
description: git 변경사항을 분석하여 Conventional Commits 형식의 커밋 메시지를 자동 생성해요
allowed-tools: Bash, Read

---

# commit-msg 스킬

git 변경사항을 분석하여 Conventional Commits 형식의 커밋 메시지를 자동 생성해요.

## 워크플로우

### Step 1: 변경사항 분석

다음 명령어를 실행하여 변경사항을 분석해요.

```bash
git diff --cached --stat
git diff --cached
```

변경된 파일 목록과 diff 내용을 분석해요.

변경된 파일 개수
추가/삭제된 라인 수
주요 변경 내용

Step 2: 변경 유형 분류

references/commit-types.md를 읽어 다음 기준으로 타입을 결정해요.

feat: 새로운 기능 추가
fix: 버그 수정
refactor: 코드 리팩토링
style: 코드 포맷팅, 세미콜론 등
docs: 문서 수정
test: 테스트 코드
chore: 빌드 설정, 패키지 업데이트

파일 경로와 변경 내용을 기반으로 타입을 자동 선택해요. 불명확한 경우 AskUserQuestion으로 사용자에게 확인해요.

Step 3: 영향 범위 파악

변경된 파일 경로를 분석해요.

src/components/ → scope: "components"
src/utils/ → scope: "utils"
src/pages/ → scope: "pages"

여러 범위가 섞인 경우 가장 주요한 범위를 선택해요.

Step 4: 메시지 생성

Conventional Commits 형식으로 메시지를 생성해요.

<type>(<scope>): <subject>

<body>

<footer>

예시

feat(components): add dark mode toggle button

- Add DarkModeToggle component with theme switching
- Integrate with ThemeProvider context
- Add animation for smooth transition

Closes #123

Step 5: 사용자 확인 및 적용

생성된 메시지를 사용자에게 보여주고 선택을 요청해요.

AskUserQuestion 도구 사용

옵션 1: "이 메시지로 커밋" (Recommended)
옵션 2: "클립보드에 복사"
옵션 3: "수정 필요"

옵션 1 선택 시

git commit -m "생성된 메시지"

옵션 2 선택 시

echo "생성된 메시지" | pbcopy  # macOS
# 또는 xclip -selection clipboard  # Linux

옵션 3 선택 시 수정 사항을 입력받아 Step 4로 돌아가요.

SKILL.md는 Claude가 실행할 프로그램처럼 작성해야 해요. 단계별로 명확한 조건문, 도구 호출, 검증 로직을 포함하세요.

References 파일 구성

스킬이 참조할 파일을 references/ 디렉토리에 저장해요.

<!-- .claude/skills/commit-msg/references/commit-types.md -->

# Conventional Commits 타입 가이드

## feat (기능)

새로운 기능을 추가하는 경우예요.

**패턴**

- 새 컴포넌트 생성
- 새 API 엔드포인트 추가
- 새 기능 구현

**예시**

- `feat(auth): add OAuth login`
- `feat(ui): add loading spinner component`

## fix (버그 수정)

버그를 수정하는 경우예요.

**패턴**

- 에러 해결
- 의도하지 않은 동작 수정
- 버그 픽스

**예시**

- `fix(login): resolve token expiration issue`
- `fix(ui): correct button alignment`

## refactor (리팩토링)

기능 변경 없이 코드 구조만 개선해요.

**패턴**

- 코드 정리
- 함수 분리
- 변수명 변경

## docs (문서)

문서만 수정해요.

**패턴**

- README 수정
- 주석 추가/수정
- 문서 파일 업데이트

## style (스타일)

코드 포맷팅, 세미콜론 등을 수정해요.

## test (테스트)

테스트 코드를 추가하거나 수정해요.

## chore (기타)

빌드 설정, 패키지 업데이트 등을 처리해요.

SKILL.md 핵심 개념

YAML Frontmatter

모든 SKILL.md 파일은 상단에 YAML frontmatter가 필요해요.

---
name: 스킬이름
description: 스킬 설명 (Claude가 자동 실행 판단에 사용)
allowed-tools: Bash, Read, Write # 선택사항
disable-model-invocation: false # 선택사항
---

필수 필드:

name: 스킬 이름 (kebab-case, 최대 64자)
description: 스킬 설명 (언제 사용하는지 명확히 작성)

선택 필드:

allowed-tools: 사용 가능한 도구 제한
disable-model-invocation: true로 설정 시 수동 실행만 가능

인자 사용하기

스킬 실행 시 전달된 인자를 사용할 수 있어요.

---
name: greet
description: 사용자에게 인사하기
---

안녕하세요, $0님!
오늘 날씨는 $1이에요.

실행 예시:

/greet 홍길동 맑음
# 결과: 안녕하세요, 홍길동님! 오늘 날씨는 맑음이에요.

$0, $1, $2 등으로 각 인자에 접근
$ARGUMENTS로 모든 인자 문자열에 접근

고급 팁

사용자 입력 받기

SKILL.md에서 사용자에게 질문하고 선택을 받을 수 있어요.

### 배포 환경 선택

사용자에게 다음 중 배포 환경을 선택하도록 요청해요.

1. Staging (테스트 환경) - 권장
2. Production (실서비스)

**Staging 선택 시**
`npm run deploy:staging` 실행

**Production 선택 시**
추가 확인 후 백업 생성 및 배포

Claude가 이 지시사항을 읽고 사용자에게 선택지를 제시해요.

복잡한 워크플로우 구성

여러 작업을 조합하여 복잡한 워크플로우를 구현할 수 있어요.

### 코드베이스 분석

1. `**/*.tsx` 패턴으로 모든 TSX 파일 찾기
2. 각 파일 내용 읽기
3. `useState` 패턴 검색
4. `npm list` 명령어로 의존성 확인

결과를 종합하여 프로젝트 구조 보고서를 생성해요.

Claude가 이 지시사항을 읽고 Glob, Read, Grep, Bash 도구를 자동으로 선택해서 사용해요. 각 단계의 결과를 다음 단계의 입력으로 사용하는 파이프라인 방식으로 설계하세요.

트러블슈팅

Skills이 인식되지 않을 때

스킬이 인식되지 않는 경우 다음을 확인해보세요.

디렉토리 위치 확인

ls -la .claude/skills/

SKILL.md 파일 존재 확인

ls .claude/skills/my-skill/SKILL.md

Claude Code 재시작

exit
claude

주의

스킬 디렉토리 이름은 kebab-case(하이픈 구분)를 사용해야 해요. 공백이나 특수문자가 포함되면 인식되지 않을 수 있어요.

디버깅 방법

단계별 출력을 추가하여 디버깅할 수 있어요.

### Step 2: 파일 분석

Glob 도구로 `**/*.tsx` 검색

**디버깅**
검색된 파일 목록 출력:

검색된 파일: [N]개

각 파일을 Read 도구로 읽기

**디버깅**
읽은 파일 개수 출력:

총 [N]개 파일 읽기 완료

마무리

Claude Skills의 핵심 개념을 정리하면 다음과 같아요.

SKILL.md: 워크플로우를 정의하는 마크다운 파일. 명확한 단계별 지시사항을 작성해요
References: 템플릿, 체크리스트 등을 별도 파일로 관리해요
도구 통합: Read, Write, Glob, Grep, Bash, AskUserQuestion 등을 조합해요
단계별 확인: 주요 단계마다 사용자 승인을 받아 품질을 보장해요