Claude Skills: 커스텀 Claude Code Skills 생성 방법 (2026)

Claude Skills: 커스텀 Claude Code Skills 만들기 가이드 (2026)

Claude Code는 Anthropic에서 제공하는 소프트웨어 개발용 AI 구동 CLI 도구입니다. 이 도구의 가장 강력하면서도 잘 알려지지 않은 기능 중 하나는 커스텀 기술(Skills)입니다. 이는 반복적인 작업을 자동화하고, 팀 내 컨벤션을 강제하며, 표준화된 워크플로우를 구축하기 위해 직접 만들 수 있는 재사용 가능한 슬래시(/) 명령어입니다.

이 가이드는 Claude Code 기술을 생성, 구성 및 공유하는 데 필요한 모든 내용을 다룹니다.

Claude Code Skills란 무엇인가요?

기술(Skills)은 Claude Code에 일반적인 작업에 대한 특정 지침을 제공하는 커스텀 슬래시 명령어입니다. Claude Code에서 /skill-name을 입력하면, Claude의 동작을 안내하는 컨텍스트, 제약 조건 및 예시가 포함된 사전 정의된 프롬프트를 로드합니다.

기술을 '성능이 대폭 강화된 저장된 프롬프트'라고 생각하세요. 다음과 같은 작업이 가능합니다.

• 특정 출력 형식 정의
• 프로젝트별 컨텍스트 포함
• 코딩 표준 및 컨벤션 강제
• 다단계 워크플로우 자동화
• 버전 관리를 통해 팀 전체에 공유

기술의 작동 원리

기술은 특정 디렉토리에 마크다운 파일로 저장됩니다. 명령어가 호출되면 Claude Code는 해당 파일을 읽고 그 내용을 지침으로 사용합니다.

분류	상세 내용
파일 형식	마크다운 (.md)
저장 위치	프로젝트 내 .claude/skills/ 또는 전역 ~/.claude/skills/
호출 방식	Claude Code에서 /skill-name 입력
범위	프로젝트 단위 또는 사용자 단위
공유 방법	팀 공유를 위해 버전 관리 시스템(Git 등)에 커밋

첫 번째 기술 설정하기

1단계: Skills 디렉토리 생성

mkdir -p .claude/skills

모든 프로젝트에서 사용할 전역 기술의 경우:

mkdir -p ~/.claude/skills

2단계: 기술 파일 생성

.claude/skills/commit.md 파일을 생성합니다.

# Commit

현재 스테이징된 변경 사항에 대한 git 커밋 메시지를 생성합니다.

## 규칙

1. `git diff --cached`를 사용하여 모든 스테이징된 변경 사항을 분석합니다.
2. Conventional Commits 형식을 따라 커밋 메시지를 작성합니다.
3. 첫 줄: type(scope): description (최대 72자)
4. Types: feat, fix, refactor, docs, test, chore, perf, ci
5. 변경 사항이 사소하지 않은 경우 본문(body)을 포함합니다.
6. 코드 변경 사항에 언급된 관련 이슈 번호를 참조합니다.
7. 커밋 메시지에 이모지를 포함하지 마십시오.
8. 커밋을 스테이징하되 실행 전 사용자에게 확인을 받습니다.

## 형식

type(scope): 짧은 설명

변경 내용과 이유에 대한 상세 설명. 간단한 변경의 경우 선택 사항입니다.

Refs: #이슈번호 (해당되는 경우)

## 예시

좋은 예:
- `feat(auth): add JWT refresh token rotation`
- `fix(api): handle null response in user endpoint`
- `refactor(db): migrate from raw SQL to Prisma ORM`

나쁜 예:
- `updated stuff` (너무 모호함)
- `fix bug` (범위와 설명 없음)
- `FEAT: Add new feature!!!` (잘못된 형식, 과도한 느낌)

3단계: 기술 사용하기

Claude Code에서 다음과 같이 입력합니다.

/commit

Claude Code는 기술 파일을 읽고 지침에 따라 적절한 형식의 커밋 메시지를 생성합니다.

실용적인 기술 예시

코드 리뷰 기술 (Code Review Skill)

.claude/skills/review.md 파일을 생성합니다.

# Code Review

지정된 파일 또는 최근 변경 사항에 대해 철저한 코드 리뷰를 수행합니다.

## 프로세스

1. 파일이 지정되지 않은 경우, `git diff`를 사용하여 커밋되지 않은 모든 변경 사항을 리뷰합니다.
2. 다음 카테고리에 대해 코드를 분석합니다.

### Security
- SQL 인젝션, XSS, CSRF 취약점
- 하드코딩된 비밀번호 또는 자격 증명
- 부적절한 입력 유효성 검사
- 인증/인가 문제

### Performance
- N+1 쿼리
- 누락된 인덱스 (데이터베이스 관련인 경우)
- 불필요한 리렌더링 (React인 경우)
- 메모리 누수
- 비효율적인 알고리즘

### Code Quality
- 명명 규칙(Naming conventions)
- 함수 길이 (50줄 이상의 함수 표시)
- 중복 로직
- 누락된 에러 핸들링
- 누락된 TypeScript 타입 (TS 프로젝트인 경우)

### Testing
- 새로운 기능이 테스트로 커버되는가?
- 엣지 케이스(Edge cases)가 고려되었는가?
- Mock 데이터가 적절한가?

## 출력 형식

발견된 각 이슈에 대해 다음을 제공합니다.
- **심각도(Severity)**: Critical / Warning / Suggestion
- **위치(Location)**: 파일 및 줄 번호
- **이슈(Issue)**: 문제 내용
- **해결책(Fix)**: 이를 해결하기 위한 구체적인 코드

마지막에 요약을 포함합니다: 심각도별 총 이슈 수 및 전반적인 평가.

API 엔드포인트 기술 (API Endpoint Skill)

.claude/skills/api-endpoint.md 파일을 생성합니다.

# API Endpoint

프로젝트 컨벤션에 따라 새로운 API 엔드포인트를 생성합니다.

## 기술 스택

이 프로젝트는 다음을 사용합니다.
- Next.js App Router (Route Handlers)
- TypeScript (strict 모드)
- Zod (유효성 검사)
- Prisma (데이터베이스 액세스)
- NextAuth (인증)

## 요구 사항

1. `src/app/api/[endpoint]/route.ts`에 라우트 핸들러를 생성합니다.
2. Zod 스키마를 사용한 입력 유효성 검사를 포함합니다.
3. `getServerSession`을 사용한 인증 확인을 추가합니다.
4. 적절한 HTTP 상태 코드로 에러를 처리합니다.
5. 타입이 지정된 JSON 응답을 반환합니다.
6. 엔드포인트에 대한 JSDoc 주석을 추가합니다.

## 템플릿

```typescript
import { NextRequest, NextResponse } from "next/server";
import { getServerSession } from "next-auth";
import { z } from "zod";
import { authOptions } from "@/lib/auth";
import { prisma } from "@/lib/prisma";

const requestSchema = z.object({
  // 여기에 스키마 정의
});

/**
 * 이 엔드포인트의 기능 설명
 * @method POST/GET/PUT/DELETE
 * @auth Required
 */
export async function POST(request: NextRequest) {
  try {
    const session = await getServerSession(authOptions);
    if (!session?.user) {
      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
    }

    const body = await request.json();
    const validated = requestSchema.parse(body);

    // 구현부

    return NextResponse.json({ data: result });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json({ error: error.errors }, { status: 400 });
    }
    console.error("[API_ENDPOINT]", error);
    return NextResponse.json({ error: "Internal server error" }, { status: 500 });
  }
}

엔드포인트 생성을 요청받으면 이 템플릿을 정확히 따르고 특정 사용 사례에 맞게 조정하십시오.

### 컴포넌트 기술 (Component Skill)

`.claude/skills/component.md` 파일을 생성합니다.

```markdown
# Component

프로젝트 컨벤션에 따라 새로운 React 컴포넌트를 생성합니다.

## 기술 스택

- React 19 (Server Components 기본)
- TypeScript strict 모드
- Tailwind CSS v4 (스타일링)
- Shadcn/ui (기본 컴포넌트)
- 필요한 경우에만 "use client" 지시어 사용 (이벤트 핸들러, 훅, 브라우저 API 등)

## 규칙

1. 적절한 디렉토리에 컴포넌트를 생성합니다:
   - 공통 UI: `src/components/ui/`
   - 기능별: `src/components/[feature]/`
   - 페이지 단위: 페이지와 동일한 위치
2. Props에는 interface를 사용합니다 (type 지양)
3. Named export를 사용합니다 (default export 지양)
4. 모든 Props에 적절한 TypeScript 타입을 포함합니다.
5. 조건부 클래스에는 `cn()` 유틸리티를 사용합니다.
6. 컴포넌트 접근성을 준수합니다 (ARIA 속성, 키보드 네비게이션).
7. 컴포넌트는 150줄 이하로 유지하며, 더 커지면 분리합니다.

## 명명 규칙

- 파일: `kebab-case.tsx`
- 컴포넌트: `PascalCase`
- Props 인터페이스: `ComponentNameProps`

## 템플릿

```tsx
import { cn } from "@/lib/utils";

interface ComponentNameProps {
  className?: string;
  children?: React.ReactNode;
}

export function ComponentName({ className, children }: ComponentNameProps) {
  return (
    <div className={cn("base-styles", className)}>
      {children}
    </div>
  );
}

### 데이터베이스 마이그레이션 기술 (Database Migration Skill)

`.claude/skills/migration.md` 파일을 생성합니다.

```markdown
# Migration

Prisma 데이터베이스 마이그레이션을 생성합니다.

## 프로세스

1. 마이그레이션 작업 내용(테이블 추가, 컬럼 수정, 인덱스 추가 등)을 확인합니다.
2. `prisma/schema.prisma`에서 Prisma 스키마를 업데이트합니다.
3. `npx prisma migrate dev --name descriptive-name`을 실행합니다.
4. 마이그레이션이 새 모델을 생성하는 경우 다음도 함께 생성합니다:
   - `src/lib/validations/`에 Zod 유효성 검사 스키마
   - `src/lib/db/`에 기본 CRUD 함수
5. 마이그레이션 성공 여부를 확인합니다.

## 명명 규칙

마이그레이션 이름은 설명적인 kebab-case여야 합니다:
- `add-users-table`
- `add-email-index-to-users`
- `rename-post-title-to-headline`
- `add-subscription-status-enum`

## 규칙

- 기존 마이그레이션 파일을 절대 수정하지 마십시오.
- 기존 테이블의 새로운 필수 컬럼에는 항상 기본값을 추가하십시오.
- WHERE 절에 사용되는 컬럼에는 인덱스를 추가하십시오.
- snake_case 데이터베이스 이름에는 `@map` 및 `@@map`을 사용하십시오.

프로젝트 레벨 vs. 전역 기술

범위	위치	사용 사례
프로젝트	.claude/skills/	팀 컨벤션, 프로젝트별 워크플로우
전역	~/.claude/skills/	개인 선호도, 여러 프로젝트 공통 도구

프로젝트 레벨 기술은 이름이 같은 전역 기술보다 우선순위를 갖습니다. 이를 통해 개발자는 개인적인 선호도를 유지하면서도 팀의 컨벤션을 따를 수 있습니다.

팀과 기술 공유하기

기술은 리포지토리 내의 마크다운 파일일 뿐이므로, 버전 관리 시스템에 커밋하는 것만으로 간단히 공유할 수 있습니다.

git add .claude/skills/
git commit -m "feat: add team coding skills for Claude Code"
git push

Claude Code를 사용하는 모든 팀원은 리포지토리를 pull할 때 자동으로 해당 기술들을 사용할 수 있게 됩니다.

효과적인 기술 작성을 위한 팁

1. 출력 형식을 구체적으로 지정하세요. 모호한 지침은 일관성 없는 결과를 낳습니다. 정확한 코드 템플릿을 제시하세요.
2. 예시를 포함하세요. 좋은 예와 나쁜 예는 Claude가 사용자의 기대치를 이해하는 데 도움이 됩니다.
3. 기술 스택을 명시하세요. 특정 프레임워크, 언어 및 도구를 언급하는 기술이 훨씬 더 나은 결과를 생성합니다.
4. 기술의 초점을 명확히 유지하세요. 작업당 하나의 기술을 만드세요. "review-and-commit" 대신 "review"와 "commit" 기술을 따로 만드는 것이 좋습니다.
5. 기술 파일을 지속적으로 개선하세요. 간단하게 시작한 다음, Claude의 출력 품질을 바탕으로 내용을 정교하게 다듬으세요.
6. 제약 조건을 사용하세요. "Named export를 선호하세요" 보다는 "default export를 사용하지 마세요"가 더 효과적입니다.

기술 디버깅

기술이 예상대로 작동하지 않는 경우:

1. 파일 위치를 확인하세요. 반드시 .claude/skills/ 또는 ~/.claude/skills/에 있어야 합니다.
2. 파일 확장자를 확인하세요. 반드시 .md여야 합니다.
3. Claude Code를 재시작하세요. 기술은 Claude Code가 시작될 때 로드됩니다.
4. 프롬프트를 직접 테스트하세요. 기술 내용을 복사하여 일반 메시지로 붙여넣어 문제가 파일 자체에 있는지 확인하세요.

마치며

커스텀 Claude Code 기술은 Claude를 일반적인 어시스턴트에서 팀의 컨벤션, 프레임워크 및 워크플로우를 꿰뚫고 있는 파트너로 진화시켜 줍니다. 설정에는 몇 분밖에 걸리지 않지만, 이를 통한 생산성 향상은 사용할수록 배가될 것입니다.

개발 워크플로우에 AI 생성 미디어가 포함되어 있다면, Hypereal AI를 무료로 체험해 보세요 (35 크레딧 제공, 카드 정보 불필요). 개발 과정에서 이미지 생성, 비디오 제작, 아바타 제작과 같은 작업을 위해 Claude Code에서 직접 API를 호출할 수 있습니다.