오늘만 무료

CLAUDE.md 완전 정복 -Skills 완전 가이드

슬래시 커맨드로 반복 작업을 자동화하는 커스텀 커맨드 만들기

by AI개발자

Mar 21. 2026 brunch_membership's

Skills란 무엇인가

Claude Code Skills는 반복해서 사용하는 작업 절차를 슬래시 커맨드로 등록하는 기능입니다.

CLAUDE.md가 "항상 이렇게 해줘"라는 상시 적용 설정이라면, Skills는 "지금부터 이걸 해줘"라는 온디맨드 지시 템플릿입니다.

Skills는 .claude/skills/ 디렉토리에 배치하는 마크다운 파일입니다. 파일명이 그대로 슬래시 커맨드명이 됩니다.

.claude/
└── skills/
├── commit.md → /commit 으로 호출
├── review-pr.md → /review-pr 으로 호출
├── new-component.md → /new-component 으로 호출
└── migrate.md → /migrate 으로 호출

기본적인 Skill 작성법

Skill 파일은 마크다운으로 자유롭게 작성합니다. 단, 절차는 번호 붙인 리스트, 출력 형식은 명시하는 것이 핵심입니다.

예: 커밋 Skill

.claude/skills/commit.md:

변경 내용을 확인하고, 적절한 커밋 메시지를 생성하여 커밋해 주세요.

절차:
1. `git diff --staged`로 변경 내용을 확인한다
2. 변경이 스테이징되지 않은 경우, `git diff`로 확인하고 관련 파일을 스테이징한다
3. 변경 내용을 분석하여 Conventional Commits 형식의 메시지를 생성한다
4. `git commit`을 실행한다

커밋 메시지 규칙:
- 프리픽스: feat, fix, refactor, docs, test, chore
- 한국어로 기술한다
- 1행은 50자 이내
- 필요에 따라 본문에 상세 내용 기재 (왜 변경했는지 중심으로)

에러 처리:
- 커밋 실패 시 원인을 분석하고 수정 후 재시도한다
- 충돌이 있는 경우 사용자에게 알리고 중단한다

사용법: 채팅에서 /commit 이라고 입력하기만 하면 됩니다.

예: PR 리뷰 Skill

.claude/skills/review-pr.md:

지정된 PR을 리뷰해 주세요.

사용법: /review-pr {PR번호}

절차:
1. `gh pr diff {PR번호}`로 변경 차분을 취득한다
2. `gh pr view {PR번호}`로 PR 설명을 취득한다
3. 다음 관점에서 리뷰한다:
- 버그 또는 논리 오류가 없는지
- 보안상 문제가 없는지 (인증·인가 누락, SQL 인젝션 등)
- 퍼포먼스 문제가 없는지 (N+1 쿼리, 불필요한 재렌더링 등)
- 테스트가 충분한지 (엣지 케이스, 에러 케이스 포함)
- 팀 코딩 규약에 따르고 있는지
4. 문제가 있으면 코멘트 안을 작성한다
5. 문제가 없으면 LGTM임을 보고한다

리뷰 결과 출력 형식:
## PR #{ PR번호} 리뷰 결과

### � 수정 필요
- [ ] `파일명:행번호` — 설명 및 수정 제안

### � 개선 제안 (선택)
- `파일명:행번호` — 제안 내용

### � 좋은 점
- 구체적으로 좋은 점을 든다

### 종합 판정
LGTM / 수정 요청 / 논의 필요

사용법: /review-pr 123 으로 PR #123을 리뷰합니다.

실용적인 Skill 패턴

컴포넌트 생성 Skill

.claude/skills/new-component.md:

새로운 React 컴포넌트를 생성해 주세요.

사용법: /new-component {ComponentName}

절차:
1. `components/ui/{ComponentName}.tsx`에 컴포넌트를 생성한다
2. 같은 파일 안에 `type Props = { ... }` 형식으로 Props 타입을 정의한다
3. Tailwind CSS로 스타일링한다
4. `components/ui/index.ts`에 named export를 추가한다
5. `__tests__/components/{ComponentName}.test.tsx`에 테스트를 생성한다
6. `pnpm test`로 테스트가 통과하는지 확인한다

컴포넌트 규칙:
- named export만 사용 (default export 금지)
- forwardRef가 필요한 경우 Ref를 받는다
- className 병합에는 cn 유틸리티 (`lib/utils.ts`)를 사용한다
- 접근성(a11y) 속성을 적절히 설정한다

에러 처리:
- 테스트 실패 시 원인을 수정하고 재실행한다
- TypeScript 에러가 있는 경우 수정 후 진행한다

DB 마이그레이션 Skill

.claude/skills/migrate.md:

데이터베이스 마이그레이션을 생성해 주세요.

사용법: /migrate {마이그레이션 설명 (예: "users 테이블에 phone 컬럼 추가")}

절차:
1. `prisma/schema.prisma`에 필요한 변경을 가한다
2. `pnpm prisma migrate dev --name {설명을 영어 kebab-case로 변환}`으로 마이그레이션을 생성한다
3. 생성된 SQL 파일의 내용을 표시하여 의도하지 않은 변경이 없는지 확인한다
4. 영향을 받는 `lib/db/`의 쿼리 함수를 업데이트한다
5. 관련 타입 정의를 `types/`에서 업데이트한다
6. 테스트를 업데이트하거나 추가한다
7. `pnpm test`로 전체 테스트가 통과하는지 확인한다

주의 사항:
- 컬럼 삭제나 타입 변경은 파괴적 변경임을 사용자에게 알리고 확인을 받는다
- 개인정보 관련 컬럼에는 주석으로 암호화 여부를 명시한다

API 엔드포인트 생성 Skill

.claude/skills/new-api.md:

새로운 API 엔드포인트를 생성해 주세요.

사용법: /new-api {리소스명} {HTTP메서드} (예: /new-api orders GET,POST)

절차:
1. `schemas/{resource}.ts`에 요청·응답 Zod 스키마를 생성한다
2. `services/{resource}.ts`에 비즈니스 로직을 생성한다
3. `app/api/{resource}/route.ts`에 라우트 핸들러를 생성한다
4. 인증이 필요한 경우 `authMiddleware`를 적용한다
5. 테스트를 `__tests__/api/{resource}.test.ts`에 생성한다
6. `pnpm test`로 테스트가 통과하는지 확인한다
7. `pnpm typecheck`로 타입 에러가 없는지 확인한다

API 응답 형식:
- 성공 (단일): `{ data: T }`
- 성공 (목록): `{ data: T[], meta: { total, page, limit } }`
- 에러: `{ error: { code: string, message: string } }`

HTTP 상태 코드:
- 200: 조회·수정 성공
- 201: 생성 성공
- 400: 유효성 검사 에러
- 401: 미인증
- 404: 리소스 없음

릴리스 노트 생성 Skill

.claude/skills/release-notes.md:

최신 릴리스 노트를 생성해 주세요.

절차:
1. `git describe --tags --abbrev=0`으로 직전 태그를 취득한다
2. `git log {직전태그}..HEAD --oneline`으로 커밋 목록을 취득한다
3. 커밋을 카테고리별로 분류한다:
- feat: 신규 기능
- fix: 버그 수정
- refactor: 리팩터링
- docs: 문서 수정
- 기타
4. 다음 형식으로 출력한다:

## v{버전} 릴리스 노트 ({날짜})

### ✨ 신규 기능
- 설명 (관련 PR: #번호)

### � 버그 수정
- 설명 (관련 PR: #번호)

### � 기타 변경
- 설명

### ⚠️ Breaking Changes (있는 경우)
- 설명 및 마이그레이션 방법

국내 서비스 특화: 결제 연동 체크 Skill

.claude/skills/check-payment.md:

결제 관련 코드를 점검해 주세요.

절차:
1. `features/payment/` 이하의 파일을 확인한다
2. 다음 항목을 체크한다:
- 결제 금액 계산이 서버 사이드에서만 이루어지는가
- 토스페이먼츠 시크릿 키가 클라이언트에 노출되지 않는가
- 결제 완료 웹훅의 서명 검증 로직이 있는가
- 결제 실패·취소 케이스의 에러 처리가 있는가
- 결제 이력이 DB에 올바르게 기록되는가
3. 문제가 있으면 수정 제안을 출력한다

출력 형식:
## 결제 코드 점검 결과

### ✅ 정상 항목
- 항목명: 확인됨

### ❌ 문제 항목
- 항목명: 문제 설명 및 수정 제안

### � 권장 개선 사항
- 항목 및 이유

유저 스코프의 Skills

~/.claude/skills/에 배치하면 모든 프로젝트에서 사용할 수 있는 글로벌 Skill이 됩니다.

~/.claude/
└── skills/
├── explain.md → /explain (코드 해설 요청)
├── optimize.md → /optimize (퍼포먼스 개선 제안)
├── security-check.md → /security-check (보안 관점 점검)
└── translate-ko.md → /translate-ko (영문 주석·메시지 한국어 번역)