Claude Code 실전 (3): Custom Skills로 팀 표준 만들기

/setup-dev 하나로 신입 온보딩 완료. /deploy staging 한 줄로 배포 자동화. Custom Skills로 팀만의 명령어를 만드는 법.

TL;DR

Skills: 재사용 가능한 Claude 명령어 세트
팀 표준화: 복잡한 워크플로우를 단일 명령어로
온보딩 자동화: /setup-dev로 환경 설정 일원화
지식 공유: 암묵지를 명시적 명령어로 전환

1. Custom Skills란?

기존의 문제

신입 개발자 첫 날:

"개발 환경 어떻게 설정하나요?" → "위키 보세요" (위키는 3개월 전 버전)
"node 버전은요?" → "nvm use"
".env 파일은요?" → ".env.example 복사해서..."
"DB는요?" → "docker-compose up 하시고..."
결과: 반나절 소요

Skills를 사용하면

신입 개발자 첫 날:

"개발 환경 어떻게 설정하나요?" → "Claude에서 /setup-dev 실행하세요"
자동으로 Node.js 버전 확인, 의존성 설치, .env 생성, DB 실행, 마이그레이션 완료
결과: 5분 소요

Skills는 팀의 암묵지를 실행 가능한 명령어로 바꿉니다.

2. Skill 구조

파일 위치

프로젝트/
├── .claude/
│   └── skills/
│       ├── setup-dev.md      # 개발 환경 설정
│       ├── deploy.md         # 배포 자동화
│       ├── create-feature.md # 기능 생성 템플릿
│       └── review-pr.md      # PR 리뷰 가이드
└── CLAUDE.md

기본 구조

# /skill-name

## Description
이 스킬이 무엇을 하는지 한 줄 설명

## Arguments
- `arg1`: 첫 번째 인자 설명 (필수/선택)
- `arg2`: 두 번째 인자 설명 (기본값: xyz)

## Steps
1. 첫 번째 단계
2. 두 번째 단계
3. 세 번째 단계

## Example
/skill-name arg1 arg2

3. 실전 예제: /setup-dev

`.claude/skills/setup-dev.md`

# /setup-dev

## Description
새로운 개발자를 위한 로컬 개발 환경 완전 자동 설정

## Prerequisites
- macOS 또는 Linux
- Docker Desktop 설치됨
- Git 설치됨

## Steps

### 1. 시스템 요구사항 확인
- Node.js 18+ 설치 확인, 없으면 nvm으로 설치 안내
- pnpm 설치 확인, 없으면 `npm install -g pnpm` 실행
- Docker 실행 중인지 확인

### 2. 의존성 설치

pnpm install

### 3. 환경 변수 설정
- `.env.example`을 `.env.local`로 복사
- 필요한 기본값 설정:
  - `DATABASE_URL`: `postgresql://localhost:5432/myapp_dev`
  - `REDIS_URL`: `redis://localhost:6379`
- 사용자에게 외부 API 키가 필요한지 확인

### 4. 데이터베이스 설정

docker-compose up -d postgres redis

pnpm db:migrate

pnpm db:seed

### 5. 확인

pnpm dev

- http://localhost:3000 접속 가능한지 확인
- 기본 로그인 계정 안내: test@example.com / password123

## Troubleshooting
- 포트 3000 사용 중: `lsof -i :3000`으로 확인 후 종료
- DB 연결 실패: Docker가 실행 중인지 확인
- 권한 에러: `sudo chown -R $(whoami) .`

## Success Message
🎉 개발 환경 설정 완료!
- 개발 서버: http://localhost:3000
- DB Admin: http://localhost:5555 (pnpm db:studio)
- 문서: http://localhost:3000/docs

4. 실전 예제: /deploy

`.claude/skills/deploy.md`

# /deploy

## Description
지정된 환경에 애플리케이션 배포

## Arguments
- `environment`: 배포 환경 (staging | production) - 필수
- `--skip-tests`: 테스트 스킵 (production에서는 무시됨)

## Pre-checks
1. 현재 브랜치 확인
   - staging: 모든 브랜치 가능
   - production: main 브랜치만 가능
2. 커밋되지 않은 변경사항 확인
3. 원격과 동기화 상태 확인

## Steps

### Staging 배포

1. 테스트 실행

pnpm test

pnpm lint

2. 빌드

pnpm build

3. 배포

git push origin HEAD:staging

- Vercel/Netlify 자동 배포 트리거됨
- 배포 URL: https://staging.myapp.com

### Production 배포

1. 반드시 모든 체크 통과

pnpm test

pnpm lint

pnpm typecheck

pnpm build

2. 태그 생성

VERSION=$(node -p "require('./package.json').version")

git tag -a "v$VERSION" -m "Release v$VERSION"

git push origin "v$VERSION"

3. main 브랜치 푸시

git push origin main

## Post-deploy
- Slack 채널 #deployments에 알림 발송
- 배포 후 5분 내 health check 확인
- 문제 발생 시 롤백 명령어: `/rollback production`

## Examples

/deploy staging

/deploy staging --skip-tests

/deploy production

5. 실전 예제: /create-feature

`.claude/skills/create-feature.md`

# /create-feature

## Description
새로운 기능을 위한 파일 구조와 보일러플레이트 생성

## Arguments
- `name`: 기능 이름 (kebab-case) - 필수
- `--with-api`: API 엔드포인트 포함
- `--with-tests`: 테스트 파일 포함

## Generated Structure

src/features/{name}/

├── components/

│ └── {Name}View.tsx

├── hooks/

│ └── use{Name}.ts

├── api/

│ └── {name}.api.ts # --with-api

├── types/

│ └── {name}.types.ts

├── __tests__/ # --with-tests

│ └── {Name}.test.tsx

└── index.ts

## Component Template

// src/features/{name}/components/{Name}View.tsx

import { use{Name} } from '../hooks/use{Name}';

import type { {Name}Props } from '../types/{name}.types';

export function {Name}View({ ... }: {Name}Props) {

const { data, isLoading, error } = use{Name}();

if (isLoading) return <LoadingSpinner />;

if (error) return <ErrorMessage error={error} />;

return (

{/* TODO: Implement UI */}

</div>

);

}

## Hook Template

// src/features/{name}/hooks/use{Name}.ts

import { useQuery } from '@tanstack/react-query';

import { {name}Api } from '../api/{name}.api';

export function use{Name}() {

return useQuery({

queryKey: ['{name}'],

queryFn: {name}Api.getAll,

});

}

## After Creation
1. 생성된 파일 목록 출력
2. index.ts에 export 추가 안내
3. 라우트 설정이 필요하면 안내

## Examples

/create-feature user-profile

/create-feature shopping-cart --with-api --with-tests

6. 팀 온보딩 최적화

온보딩 체크리스트를 Skill로

`.claude/skills/onboarding-checklist.md`

# /onboarding-checklist

## Description
신입 개발자 온보딩 진행 상황 체크 및 다음 단계 안내

## Checklist

### Day 1: 환경 설정
- [ ] `/setup-dev` 실행 완료
- [ ] Slack 채널 참여 (#dev, #deployments, #alerts)
- [ ] GitHub 팀 추가됨
- [ ] Jira/Linear 접근 권한

### Day 2: 코드베이스 이해
- [ ] CLAUDE.md 읽기
- [ ] 아키텍처 문서 읽기 (docs/architecture.md)
- [ ] 첫 번째 Good First Issue 할당받기

### Day 3-5: 첫 PR
- [ ] 로컬에서 기능 개발
- [ ] `/create-feature` 사용해보기
- [ ] PR 생성 및 리뷰 받기
- [ ] `/deploy staging` 체험

### Week 2: 심화
- [ ] 온콜 로테이션 이해
- [ ] 모니터링 대시보드 익히기
- [ ] 장애 대응 프로세스 숙지

## Current Progress
진행 상황을 체크하고 다음 할 일을 안내해주세요.

7. PR 리뷰 표준화

`.claude/skills/review-pr.md`

# /review-pr

## Description
PR 리뷰 수행 및 팀 표준에 따른 피드백 제공

## Arguments
- `pr_number`: PR 번호 또는 URL (선택, 없으면 현재 브랜치)

## Review Checklist

### 1. 코드 품질
- [ ] 네이밍 컨벤션 준수 (CLAUDE.md 참조)
- [ ] 불필요한 코드 중복 없음
- [ ] 함수/컴포넌트 크기 적절 (50줄 이하 권장)
- [ ] 에러 처리 적절함

### 2. 타입 안전성
- [ ] `any` 사용 없음
- [ ] 적절한 타입 정의
- [ ] null/undefined 처리

### 3. 테스트
- [ ] 새 기능에 테스트 포함
- [ ] 엣지 케이스 커버
- [ ] 테스트가 의미 있음 (구현 세부사항 X)

### 4. 보안
- [ ] 사용자 입력 검증
- [ ] SQL Injection 방지
- [ ] XSS 방지
- [ ] 민감 정보 노출 없음

### 5. 성능
- [ ] N+1 쿼리 없음
- [ ] 불필요한 리렌더링 없음
- [ ] 큰 번들 추가 시 정당화

## Output Format
각 항목에 대해:
- ✅ 통과
- ⚠️ 제안 (선택적 개선)
- ❌ 필수 수정

## Example

/review-pr 123

/review-pr https://github.com/org/repo/pull/123

8. Skill 작성 팁

1) 명확한 단계 정의

❌ 모호함:

## Steps
1. 환경 설정
2. 코드 작성
3. 테스트

✅ 구체적:

## Steps
1. Node.js 18+ 설치 확인
   - `node --version` 실행
   - 18 미만이면 `nvm install 18 && nvm use 18`
2. 의존성 설치
   - `pnpm install` 실행
   - 에러 시 `rm -rf node_modules && pnpm install`

2) 예외 상황 처리

## Troubleshooting
- **포트 충돌**: `lsof -i :3000`으로 확인 후 해당 프로세스 종료
- **권한 에러**: Docker Desktop 실행 확인
- **M1 Mac**: `--platform linux/amd64` 옵션 필요할 수 있음

3) 환경별 분기

## Environment-specific

### macOS

brew install postgresql

### Ubuntu

sudo apt-get install postgresql

### Windows (WSL)

wsl --install

WSL 내에서 Ubuntu 명령어 사용

9. 팀별 추천 Skills

프론트엔드 팀

백엔드 팀

DevOps 팀

마무리

Custom Skills는 단순한 자동화가 아닙니다.

팀의 암묵지를 실행 가능한 형태로 문서화하는 것입니다.

다음 편에서는 MCP 서버를 구축해 Claude가 외부 시스템과 통신하는 방법을 다룹니다.

시리즈 목차

Context가 전부다
Hooks로 워크플로우 자동화
Custom Skills로 팀 표준 만들기 (현재 글)
MCP 서버 구축하기
모델 믹스 전략

Claude Code 실전 (3): Custom Skills로 팀 표준 만들기

/setup-dev 하나로 신입 온보딩 완료. /deploy staging 한 줄로 배포 자동화. Custom Skills로 팀만의 명령어를 만드는 법.

TL;DR

Skills: 재사용 가능한 Claude 명령어 세트
팀 표준화: 복잡한 워크플로우를 단일 명령어로
온보딩 자동화: /setup-dev로 환경 설정 일원화
지식 공유: 암묵지를 명시적 명령어로 전환

1. Custom Skills란?

기존의 문제

신입 개발자 첫 날:

"개발 환경 어떻게 설정하나요?" → "위키 보세요" (위키는 3개월 전 버전)
"node 버전은요?" → "nvm use"
".env 파일은요?" → ".env.example 복사해서..."
"DB는요?" → "docker-compose up 하시고..."
결과: 반나절 소요

Skills를 사용하면

신입 개발자 첫 날:

"개발 환경 어떻게 설정하나요?" → "Claude에서 /setup-dev 실행하세요"
자동으로 Node.js 버전 확인, 의존성 설치, .env 생성, DB 실행, 마이그레이션 완료
결과: 5분 소요

Skills는 팀의 암묵지를 실행 가능한 명령어로 바꿉니다.

2. Skill 구조

파일 위치

프로젝트/
├── .claude/
│   └── skills/
│       ├── setup-dev.md      # 개발 환경 설정
│       ├── deploy.md         # 배포 자동화
│       ├── create-feature.md # 기능 생성 템플릿
│       └── review-pr.md      # PR 리뷰 가이드
└── CLAUDE.md

기본 구조

# /skill-name

## Description
이 스킬이 무엇을 하는지 한 줄 설명

## Arguments
- `arg1`: 첫 번째 인자 설명 (필수/선택)
- `arg2`: 두 번째 인자 설명 (기본값: xyz)

## Steps
1. 첫 번째 단계
2. 두 번째 단계
3. 세 번째 단계

## Example
/skill-name arg1 arg2

3. 실전 예제: /setup-dev

`.claude/skills/setup-dev.md`

# /setup-dev

## Description
새로운 개발자를 위한 로컬 개발 환경 완전 자동 설정

## Prerequisites
- macOS 또는 Linux
- Docker Desktop 설치됨
- Git 설치됨

## Steps

### 1. 시스템 요구사항 확인
- Node.js 18+ 설치 확인, 없으면 nvm으로 설치 안내
- pnpm 설치 확인, 없으면 `npm install -g pnpm` 실행
- Docker 실행 중인지 확인

### 2. 의존성 설치

pnpm install

### 3. 환경 변수 설정
- `.env.example`을 `.env.local`로 복사
- 필요한 기본값 설정:
  - `DATABASE_URL`: `postgresql://localhost:5432/myapp_dev`
  - `REDIS_URL`: `redis://localhost:6379`
- 사용자에게 외부 API 키가 필요한지 확인

### 4. 데이터베이스 설정

docker-compose up -d postgres redis

pnpm db:migrate

pnpm db:seed

### 5. 확인

pnpm dev

- http://localhost:3000 접속 가능한지 확인
- 기본 로그인 계정 안내: test@example.com / password123

## Troubleshooting
- 포트 3000 사용 중: `lsof -i :3000`으로 확인 후 종료
- DB 연결 실패: Docker가 실행 중인지 확인
- 권한 에러: `sudo chown -R $(whoami) .`

## Success Message
🎉 개발 환경 설정 완료!
- 개발 서버: http://localhost:3000
- DB Admin: http://localhost:5555 (pnpm db:studio)
- 문서: http://localhost:3000/docs

4. 실전 예제: /deploy

`.claude/skills/deploy.md`

# /deploy

## Description
지정된 환경에 애플리케이션 배포

## Arguments
- `environment`: 배포 환경 (staging | production) - 필수
- `--skip-tests`: 테스트 스킵 (production에서는 무시됨)

## Pre-checks
1. 현재 브랜치 확인
   - staging: 모든 브랜치 가능
   - production: main 브랜치만 가능
2. 커밋되지 않은 변경사항 확인
3. 원격과 동기화 상태 확인

## Steps

### Staging 배포

1. 테스트 실행

pnpm test

pnpm lint

2. 빌드

pnpm build

3. 배포

git push origin HEAD:staging

- Vercel/Netlify 자동 배포 트리거됨
- 배포 URL: https://staging.myapp.com

### Production 배포

1. 반드시 모든 체크 통과

pnpm test

pnpm lint

pnpm typecheck

pnpm build

2. 태그 생성

VERSION=$(node -p "require('./package.json').version")

git tag -a "v$VERSION" -m "Release v$VERSION"

git push origin "v$VERSION"

3. main 브랜치 푸시

git push origin main

## Post-deploy
- Slack 채널 #deployments에 알림 발송
- 배포 후 5분 내 health check 확인
- 문제 발생 시 롤백 명령어: `/rollback production`

## Examples

/deploy staging

/deploy staging --skip-tests

/deploy production

5. 실전 예제: /create-feature

`.claude/skills/create-feature.md`

# /create-feature

## Description
새로운 기능을 위한 파일 구조와 보일러플레이트 생성

## Arguments
- `name`: 기능 이름 (kebab-case) - 필수
- `--with-api`: API 엔드포인트 포함
- `--with-tests`: 테스트 파일 포함

## Generated Structure

src/features/{name}/

├── components/

│ └── {Name}View.tsx

├── hooks/

│ └── use{Name}.ts

├── api/

│ └── {name}.api.ts # --with-api

├── types/

│ └── {name}.types.ts

├── __tests__/ # --with-tests

│ └── {Name}.test.tsx

└── index.ts

## Component Template

// src/features/{name}/components/{Name}View.tsx

import { use{Name} } from '../hooks/use{Name}';

import type { {Name}Props } from '../types/{name}.types';

export function {Name}View({ ... }: {Name}Props) {

const { data, isLoading, error } = use{Name}();

if (isLoading) return <LoadingSpinner />;

if (error) return <ErrorMessage error={error} />;

return (

{/* TODO: Implement UI */}

</div>

);

}

## Hook Template

// src/features/{name}/hooks/use{Name}.ts

import { useQuery } from '@tanstack/react-query';

import { {name}Api } from '../api/{name}.api';

export function use{Name}() {

return useQuery({

queryKey: ['{name}'],

queryFn: {name}Api.getAll,

});

}

## After Creation
1. 생성된 파일 목록 출력
2. index.ts에 export 추가 안내
3. 라우트 설정이 필요하면 안내

## Examples

/create-feature user-profile

/create-feature shopping-cart --with-api --with-tests

6. 팀 온보딩 최적화

온보딩 체크리스트를 Skill로

`.claude/skills/onboarding-checklist.md`

# /onboarding-checklist

## Description
신입 개발자 온보딩 진행 상황 체크 및 다음 단계 안내

## Checklist

### Day 1: 환경 설정
- [ ] `/setup-dev` 실행 완료
- [ ] Slack 채널 참여 (#dev, #deployments, #alerts)
- [ ] GitHub 팀 추가됨
- [ ] Jira/Linear 접근 권한

### Day 2: 코드베이스 이해
- [ ] CLAUDE.md 읽기
- [ ] 아키텍처 문서 읽기 (docs/architecture.md)
- [ ] 첫 번째 Good First Issue 할당받기

### Day 3-5: 첫 PR
- [ ] 로컬에서 기능 개발
- [ ] `/create-feature` 사용해보기
- [ ] PR 생성 및 리뷰 받기
- [ ] `/deploy staging` 체험

### Week 2: 심화
- [ ] 온콜 로테이션 이해
- [ ] 모니터링 대시보드 익히기
- [ ] 장애 대응 프로세스 숙지

## Current Progress
진행 상황을 체크하고 다음 할 일을 안내해주세요.

7. PR 리뷰 표준화

`.claude/skills/review-pr.md`

# /review-pr

## Description
PR 리뷰 수행 및 팀 표준에 따른 피드백 제공

## Arguments
- `pr_number`: PR 번호 또는 URL (선택, 없으면 현재 브랜치)

## Review Checklist

### 1. 코드 품질
- [ ] 네이밍 컨벤션 준수 (CLAUDE.md 참조)
- [ ] 불필요한 코드 중복 없음
- [ ] 함수/컴포넌트 크기 적절 (50줄 이하 권장)
- [ ] 에러 처리 적절함

### 2. 타입 안전성
- [ ] `any` 사용 없음
- [ ] 적절한 타입 정의
- [ ] null/undefined 처리

### 3. 테스트
- [ ] 새 기능에 테스트 포함
- [ ] 엣지 케이스 커버
- [ ] 테스트가 의미 있음 (구현 세부사항 X)

### 4. 보안
- [ ] 사용자 입력 검증
- [ ] SQL Injection 방지
- [ ] XSS 방지
- [ ] 민감 정보 노출 없음

### 5. 성능
- [ ] N+1 쿼리 없음
- [ ] 불필요한 리렌더링 없음
- [ ] 큰 번들 추가 시 정당화

## Output Format
각 항목에 대해:
- ✅ 통과
- ⚠️ 제안 (선택적 개선)
- ❌ 필수 수정

## Example

/review-pr 123

/review-pr https://github.com/org/repo/pull/123

8. Skill 작성 팁

1) 명확한 단계 정의

❌ 모호함:

## Steps
1. 환경 설정
2. 코드 작성
3. 테스트

✅ 구체적:

## Steps
1. Node.js 18+ 설치 확인
   - `node --version` 실행
   - 18 미만이면 `nvm install 18 && nvm use 18`
2. 의존성 설치
   - `pnpm install` 실행
   - 에러 시 `rm -rf node_modules && pnpm install`

2) 예외 상황 처리

## Troubleshooting
- **포트 충돌**: `lsof -i :3000`으로 확인 후 해당 프로세스 종료
- **권한 에러**: Docker Desktop 실행 확인
- **M1 Mac**: `--platform linux/amd64` 옵션 필요할 수 있음

3) 환경별 분기

## Environment-specific

### macOS

brew install postgresql

### Ubuntu

sudo apt-get install postgresql

### Windows (WSL)

wsl --install

WSL 내에서 Ubuntu 명령어 사용

9. 팀별 추천 Skills

프론트엔드 팀

백엔드 팀

DevOps 팀

마무리

Custom Skills는 단순한 자동화가 아닙니다.

팀의 암묵지를 실행 가능한 형태로 문서화하는 것입니다.

다음 편에서는 MCP 서버를 구축해 Claude가 외부 시스템과 통신하는 방법을 다룹니다.

시리즈 목차

Context가 전부다
Hooks로 워크플로우 자동화
Custom Skills로 팀 표준 만들기 (현재 글)
MCP 서버 구축하기
모델 믹스 전략