한국 개발자를 위한 Claude Code 커스텀 스킬: 반복 작업 자동화
Claude Code의 커스텀 스킬(슬래시 커맨드)은 반복적인 작업을 한 줄 명령으로 실행할 수 있게 해주는 자동화 도구다. 매번 긴 프롬프트를 입력하는 대신 /새기능, /리뷰, /배포 같은 커맨드로 표준 워크플로우를 실행할 수 있다. 이 가이드는 한국 개발 팀에서 실제로 유용한 커스텀 스킬을 만드는 방법을 단계별로 설명한다.
커스텀 스킬이란?
커스텀 스킬은 ~/.claude/skills/ 또는 프로젝트의 .claude/skills/ 디렉토리에 저장된 마크다운 파일이다. 파일 이름이 슬래시 커맨드 이름이 된다.
~/.claude/skills/
├── 새기능/
│ └── SKILL.md → /새기능
├── 코드리뷰/
│ └── SKILL.md → /코드리뷰
└── 배포/
└── SKILL.md → /배포
.claude/skills/ (프로젝트 전용)
├── api-추가/
│ └── SKILL.md → /api-추가
첫 번째 스킬 만들기: 새 기능 구현
매번 타이핑하는 기능 구현 요청을 스킬로 만들기:
mkdir -p ~/.claude/skills/새기능
<!-- ~/.claude/skills/새기능/SKILL.md -->
# 새 기능 구현 스킬
## 입력
$ARGUMENTS — 기능 설명 (예: "사용자 프로필 수정 페이지")
## 실행 단계
1. **설계 검토**
- CLAUDE.md 읽기 (이미 있으면 참고)
- 기존 코드베이스의 유사 기능 패턴 확인
- 변경할 파일 목록 계획
2. **구현**
- 기능 브랜치 생성: `feature/[슬러그]`
- 백엔드 → 프론트엔드 순서로 구현
- 각 파일 변경 후 typecheck
3. **품질 검증**
- `bun run typecheck` 실행 → 에러 수정
- `bun run test` 실행 → 실패 수정
- 엣지 케이스 처리 확인
4. **완료 보고**
- 변경된 파일 목록
- 구현 내용 요약
- 남은 작업 (있는 경우)
## 규칙
- CLAUDE.md의 모든 컨벤션 준수
- 불명확한 요구사항은 가정하지 말고 물어볼 것
- main 브랜치에 직접 커밋 금지
사용법:
/새기능 사용자가 아바타를 업로드하고 프로필에 표시하는 기능
프로젝트 전용 스킬: API 엔드포인트 추가
프로젝트마다 다른 패턴이 있으면 프로젝트 내 스킬로:
mkdir -p .claude/skills/api-추가
<!-- .claude/skills/api-추가/SKILL.md -->
# REST API 엔드포인트 추가
## 입력
$ARGUMENTS — "[HTTP메서드] [경로] [설명]"
예: "POST /api/orders 주문 생성"
## 실행 단계
### 1. 라우트 파일 생성/수정
- Next.js App Router: `src/app/api/[경로]/route.ts`
- 필수 요소:
```typescript
import { auth } from "@clerk/nextjs/server";
import { NextResponse } from "next/server";
export async function [METHOD](req: Request) {
const { userId } = await auth();
if (!userId) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
try {
// 구현
} catch (error) {
console.error("[엔드포인트명] error:", error);
return NextResponse.json({ error: "Internal server error" }, { status: 500 });
}
}
2. DB 쿼리 함수
src/lib/db/[리소스].ts에 추가- organizationId 필터 포함 (멀티테넌트 필수)
3. TypeScript 타입
- 요청/응답 타입을
src/types/api.ts에 추가
4. 검증
- bun run typecheck
- bun run test (관련 테스트 파일 있으면 실행)
금지 사항
- DB 직접 접근을 라우트 파일에서 하지 말 것 (lib/db/ 사용)
- organizationId 없는 DB 쿼리 금지
- 에러 응답에 스택 트레이스 포함 금지
사용법:
```bash
/api-추가 POST /api/products 상품 생성
/api-추가 GET /api/analytics/summary 월별 매출 요약 조회
팀 공유 스킬: 코드 리뷰
mkdir -p .claude/skills/리뷰
<!-- .claude/skills/리뷰/SKILL.md -->
# 코드 리뷰 스킬
## 입력
$ARGUMENTS — PR 번호 또는 브랜치명 (선택, 없으면 현재 변경사항)
## 실행 단계
1. **변경사항 확인**
- 인자가 있으면: `gh pr diff [번호]` 또는 `git diff [브랜치]`
- 없으면: `git diff HEAD` (미커밋 변경사항)
2. **리뷰 체크리스트**
**보안**
- [ ] 인증/인가 체크 누락 없음
- [ ] 입력값 검증 있음
- [ ] SQL 인젝션 위험 없음
- [ ] API 키/비밀번호 하드코딩 없음
**논리**
- [ ] null/undefined 처리
- [ ] 배열 빈 경우 처리
- [ ] 경쟁 조건(race condition) 위험 없음
- [ ] 타임존 처리 일관성
**프로젝트 규칙**
- [ ] organizationId 필터 포함 (해당되는 경우)
- [ ] console.log 없음
- [ ] any 타입 없음
- [ ] AppError 사용 (plain Error 아님)
3. **리뷰 결과 출력**
- 심각도별 정리: 🔴 수정 필요 / 🟡 권고 / 🟢 확인됨
- 각 항목: 파일명, 라인 번호, 이유, 수정 방법
## 출력 형식
한국어로 작성. GitHub PR 코멘트로 바로 붙여넣기 가능한 형태.
사용법:
/리뷰 # 현재 변경사항 리뷰
/리뷰 42 # PR #42 리뷰
/리뷰 feature/auth # 브랜치 리뷰
반복 작업 스킬 모음
마이그레이션 생성
<!-- ~/.claude/skills/마이그레이션/SKILL.md -->
# Prisma 마이그레이션 생성
## 입력
$ARGUMENTS — 변경 내용 설명
## 실행 단계
1. schema.prisma 수정
2. `npx prisma migrate dev --name [이름]` 실행
3. 필요시 시드 데이터 업데이트
4. TypeScript 타입 재생성 확인: `npx prisma generate`
5. bun run typecheck
## 규칙
- 마이그레이션 이름은 영어 snake_case
- 기존 데이터 영향 있으면 명시적 경고
- 되돌리기 불가능한 변경(컬럼 삭제, 타입 변경)은 먼저 물어볼 것
컴포넌트 생성
<!-- .claude/skills/컴포넌트/SKILL.md -->
# React 컴포넌트 생성
## 입력
$ARGUMENTS — "컴포넌트명 [설명]"
## 실행 단계
1. src/components/[기능명]/[컴포넌트명].tsx 생성
2. Props 타입 정의
3. shadcn/ui 컴포넌트 활용
4. 모바일 반응형 (Tailwind)
5. 접근성: aria-label, 키보드 지원
6. 스토리북 파일 생성 (있는 경우)
## 컨벤션
- 서버 컴포넌트 기본
- 인터랙션 있으면 'use client' 추가
- Props: interface [이름]Props 형태
테스트 추가
<!-- .claude/skills/테스트/SKILL.md -->
# 테스트 코드 추가
## 입력
$ARGUMENTS — 테스트할 파일 경로 또는 기능 설명
## 실행 단계
1. 대상 코드 분석
2. 테스트 케이스 설계:
- 정상 동작 (happy path)
- 엣지 케이스 (null, empty, boundary)
- 에러 케이스
3. vitest/jest로 테스트 작성
4. 테스트 실행 및 통과 확인
## 규칙
- 설명은 한국어로 ("사용자가 없을 때 빈 배열 반환")
- 테스트당 하나의 assert
- Mock은 최소화 (실제 DB 연결 가능하면 사용)
스킬 디버깅 및 개선
스킬이 예상대로 동작하지 않을 때:
# 스킬 파일 직접 읽기
claude "@.claude/skills/api-추가/SKILL.md 이 스킬 파일에서
POST /api/payments 결제 처리 엔드포인트를 추가하는 상황에서
어떻게 실행될지 단계별로 설명해줘."
스킬 개선 패턴:
# 스킬을 실행하고 결과가 나쁘면
claude "방금 /api-추가 실행 결과가 마음에 안 들었어.
[구체적인 문제].
.claude/skills/api-추가/SKILL.md를 업데이트해서
이런 상황에서 더 잘 동작하도록 개선해줘."
팀 스킬 공유
프로젝트 내 스킬(.claude/skills/)은 git으로 공유:
# .gitignore에서 스킬 디렉토리 제외 (팀 공유)
# .gitignore에 .claude/settings.local.json만 제외
echo ".claude/settings.local.json" >> .gitignore
# .claude/skills/는 포함 (팀 공유)
git add .claude/skills/
git commit -m "docs: 팀 Claude Code 스킬 추가"
개인 스킬은 ~/.claude/skills/에 보관.
자주 묻는 질문
커스텀 스킬과 CLAUDE.md의 차이는 무엇인가요?
CLAUDE.md는 모든 세션에 항상 적용되는 규칙이다. 커스텀 스킬은 /커맨드로 명시적으로 호출할 때만 실행되는 워크플로우다. CLAUDE.md = 상시 규칙, 스킬 = 재사용 가능한 자동화 절차.
스킬 파일에 코드나 변수를 포함할 수 있나요?
스킬 파일은 마크다운 텍스트다. $ARGUMENTS로 입력값을 받을 수 있고, 셸 명령어를 포함할 수 있다. 하지만 프로그래밍 언어 코드가 실행되는 것은 아니다 — Claude가 파일을 읽고 지시사항으로 따른다.
스킬이 너무 많으면 Claude가 느려지나요? 스킬은 호출될 때만 읽히므로 보관 수에 관계없이 성능에 영향 없다.
회사 코드베이스에 맞게 스킬을 커스터마이징하려면?
프로젝트 루트 .claude/skills/에 스킬을 만들고, 프로젝트 특화 명령어를 포함하면 된다. 예: "이 프로젝트의 에러는 반드시 src/lib/errors/AppError를 사용", "DB 쿼리는 src/lib/repositories/ 패턴 따를 것".
관련 가이드
- Claude Code 완벽 가이드: 설치부터 고급 활용까지 — 기본 가이드
- Context Engineering for Claude — CLAUDE.md 심화
- Claude Code 커스텀 스킬 만들기 (영어) — 영어 심화 가이드
더 깊이 알고 싶다면
Power Prompts 300 — $29 — 바로 사용 가능한 커스텀 스킬 템플릿 10개 + CLAUDE.md 5종 + 팀 Claude Code 도입 체크리스트 포함.
30일 환불 보장. 즉시 다운로드.