Claude Code Skills 실전 가이드: 나만의 스킬을 만들고 공유하는 법

Claude Code Skills 2.0에서는 CLAUDE.md에 프롬프트를 붙여넣는 대신 스킬 패키지로 지침을 관리합니다. 구조화된 패키지, 자동 발견, 플러그인 마켓플레이스로 AI 코딩 에이전트가 할 수 있는 일을 넓힙니다. 이 글에서는 Skills 2.0의 핵심 개념부터 나만의 스킬을 만들고 테스트하는 방법까지 단계별로 살펴보겠습니다.

Skills란 무엇인가?

Skills는 Claude Code의 능력을 확장하는 구조화된 지침 패키지입니다. 마크다운 지침·레퍼런스·템플릿·스크립트를 하나의 디렉토리로 묶습니다. Claude는 이 디렉토리를 자동으로 인식하고 필요한 시점에 호출합니다.

예를 들어 “changelog 생성” 스킬을 만들었다고 합시다. Claude는 “changelog 만들어줘”라는 요청을 받으면 이 스킬을 찾아, 정해진 형식·템플릿에 따라 CHANGELOG.md를 생성합니다. /changelog처럼 슬래시 커맨드로 직접 호출할 수도 있습니다.

Skills 1.0에서 2.0으로의 진화

1.0: CLAUDE.md 시대

초기에는 두 가지 방법뿐이었습니다.

• CLAUDE.md에 직접 프롬프트와 지침을 작성
• .claude/commands/ 디렉토리에 단순 마크다운 파일 배치

이 방식은 간단하지만 한계가 있었습니다. 지침이 길어지면 CLAUDE.md가 비대해지고, 스킬 간 재사용이 어렵고, 테스트나 검증 체계가 전혀 없었습니다.

2.0: 구조화된 스킬 패키지

Skills 2.0은 이 한계를 다음처럼 바꿉니다.

SKILL.md 구조 심화

모든 스킬에는 SKILL.md 파일이 있습니다. YAML frontmatter로 메타데이터를 정의하고, 마크다운 본문에 지침을 작성합니다.

Frontmatter 필드

---
name: my-skill # 슬래시 커맨드명 (/my-skill)
description: 스킬 설명 # Claude가 자동 호출 판단에 사용 (가장 중요!)
argument-hint: "[arg1] [--flag]" # 자동완성 힌트
disable-model-invocation: false # true면 자동 호출 차단 (수동 /호출만 가능)
user-invocable: true # false면 /메뉴에 숨김 (배경 지식용)
allowed-tools: Read, Grep, Glob # 허용 도구 제한
model: sonnet # 모델 오버라이드
context: fork # 서브에이전트에서 격리 실행
agent: Explore # 서브에이전트 타입 지정
---

본문에서 사용하는 변수

$ARGUMENTS            — 사용자가 전달한 전체 인자
$0, $1, $2            — 위치별 인자
${CLAUDE_SKILL_DIR} — 스킬 디렉토리 경로
${CLAUDE_SESSION_ID} — 현재 세션 ID

디렉토리 구조

하나의 스킬은 다음과 같은 디렉토리 구조를 가집니다.

my-skill/
├── SKILL.md           # 메인 지침 (필수)
├── reference/         # 상세 레퍼런스 문서
├── templates/         # 템플릿 파일
├── examples/          # 예제 출력
└── scripts/           # 실행 가능한 스크립트

SKILL.md만 필수이고, 나머지는 선택입니다. 스킬이 복잡해질수록 reference/와 templates/로 지침을 분리하면 유지보수가 쉬워집니다.

스킬 저장 위치와 적용 범위

플러그인 시스템과 마켓플레이스

Skills 2.0에는 플러그인 마켓플레이스가 생겼습니다. /plugin 명령어 하나로 스킬을 검색하고 설치할 수 있습니다.

설치 방법

# 공식 마켓플레이스에서 설치
/plugin install plugin-name@claude-plugins-official

# 커뮤니티 마켓플레이스 추가
/plugin marketplace add anthropics/skills        # GitHub repo
/plugin marketplace add https://gitlab.com/...   # Git URL
/plugin marketplace add ./local-path             # 로컬 경로

주요 공식 플러그인

공식 마켓플레이스(claude-plugins-official)에는 다양한 카테고리의 플러그인이 있습니다.

코드 인텔리전스 (LSP)

• TypeScript, Python, Go, Rust 등 11개 언어 지원
• 편집 후 자동 진단으로 타입 에러, 누락 import 즉시 감지

외부 서비스 통합

• GitHub, GitLab, Jira, Slack, Notion, Figma, Vercel, Sentry 등

개발 워크플로우

• commit-commands: 커밋·푸시·PR 자동화
• pr-review-toolkit: PR 리뷰 보조
• skill-creator: 스킬 제작·테스트·최적화

커뮤니티 생태계

공식 마켓플레이스 외에 커뮤니티 저장소도 있습니다.

• anthropics/skills ↗ — Anthropic 공식 예제 (2026년 3월 기준 90k+ stars)
• awesome-claude-skills ↗ — 커뮤니티 큐레이션
• 이 외에도 다양한 커뮤니티 통합 마켓플레이스가 등장하고 있습니다

Skill Creator: 스킬을 만드는 스킬

Skill Creator는 스킬을 만들고, 테스트하고, 최적화하는 메타 스킬입니다. SKILL.md 파일 생성에 더해 eval 기반 품질 검증도 제공합니다.

4가지 모드

flowchart TD
    A[Create<br/>스킬 생성] --> B[Eval<br/>테스트 실행]
    B --> C[Improve<br/>결과 분석·개선]
    C --> D[Benchmark<br/>성능 측정]
    D -->|회귀 감지| B

1. Create — 대화를 통해 새 스킬의 목적, 트리거 조건, 지침을 설계하고 SKILL.md를 생성합니다
2. Eval — 테스트 케이스를 작성하고 실행합니다. “이런 입력에 이런 출력이 나와야 한다”를 정의하면 스킬이 올바르게 동작하는지 자동 검증합니다
3. Improve — eval 결과를 분석하여 description 최적화, 지침 보강 등 구체적인 개선안을 제시합니다
4. Benchmark — 패스율, 실행 시간, 토큰 소비량을 측정합니다

A/B 비교와 회귀 감지

Skill Creator는 A/B 비교를 지원합니다. 두 스킬 버전을 격리된 컨텍스트에서 블라인드 테스트합니다. Comparator 에이전트가 결과를 분석하여 어떤 버전이 더 나은지 판별합니다.

모델이 업데이트되면 회귀 감지로 기존 스킬이 제대로 동작하는지 확인합니다. 프로덕션에서 쓰는 스킬의 품질을 이 방식으로 관리합니다.

스킬의 두 가지 분류

Skills 2.0은 스킬을 두 가지 카테고리로 나눕니다. 어떤 스킬을 만들지 결정할 때 이 구분이 도움됩니다.

Capability Uplift Skills (능력 확장)

모델이 아직 잘 못하는 영역을 보완하는 스킬입니다. PDF 처리, PPTX 생성, 특정 API 레퍼런스 제공 등이 해당합니다. 모델이 발전하면 역할이 줄어들 수 있습니다.

Workflow/Preference Skills (워크플로우·선호)

반복 업무를 자동화하거나 팀 컨벤션을 강제하는 스킬입니다. 커밋 메시지 포맷, 코드 리뷰 체크리스트, 블로그 작성 가이드 등이 해당합니다. 모델이 발전해도 역할이 줄지 않습니다.

실전: 나만의 스킬 만들기

git log를 분석해 CHANGELOG.md를 자동 생성하는 /changelog 스킬을 예제로 만들어보겠습니다.

1단계: SKILL.md 작성

---
name: changelog
description: Use when the user asks to generate or update a changelog.
  Analyzes git history and produces a structured CHANGELOG.md
  following Keep a Changelog format.
argument-hint: "[--from v1.0.0] [--to v2.0.0] [--unreleased]"
user-invocable: true
allowed-tools: Read, Write, Edit, Glob, Grep, Bash(git log *), Bash(git tag *)
context: fork
---

# Changelog 생성 스킬

## 워크플로우
1. git tag 목록에서 버전 범위 결정
2. 커밋 메시지를 카테고리별로 분류
3. 템플릿 기반으로 CHANGELOG.md 생성/업데이트

## 커밋 분류 규칙
- ${CLAUDE_SKILL_DIR}/reference/commit-types.md

## 출력 템플릿
- ${CLAUDE_SKILL_DIR}/templates/changelog-template.md

2단계: 레퍼런스와 템플릿 구성

.claude/skills/changelog/
├── SKILL.md
├── reference/
│   └── commit-types.md        # feat/fix/docs 등 분류 규칙
└── templates/
    └── changelog-template.md  # Keep a Changelog 형식 템플릿

reference/commit-types.md에는 Conventional Commits 접두사와 changelog 카테고리 매핑을 정의합니다. templates/changelog-template.md에는 Keep a Changelog 형식의 뼈대를 작성합니다. 분류 규칙과 출력 형식을 분리하면 SKILL.md에는 작업 흐름만 남습니다.

3단계: context: fork로 격리 실행

frontmatter에 context: fork가 있으면 스킬이 서브에이전트에서 격리 실행됩니다. changelog 생성처럼 git 히스토리를 대량으로 읽는 작업은 메인 컨텍스트를 오염시킬 수 있습니다. fork 모드에서는 독립된 컨텍스트에서 실행하고 결과만 돌려받습니다.

Skill Creator의 eval과 연동하면 품질도 검증할 수 있습니다. 예를 들어 “v1.0.0..v2.0.0 범위에서 changelog를 생성했을 때 feat, fix 카테고리가 올바르게 분류되는가”를 테스트 케이스로 씁니다. 그러면 스킬을 수정한 뒤 회귀를 자동으로 감지합니다.

서드파티 스킬과 오픈 표준

Vercel React Best Practices

Vercel이 공개한 React/Next.js 성능 최적화 스킬 ↗은 40개 이상의 규칙을 CRITICAL부터 incremental까지 8개 카테고리로 분류합니다. 각 규칙에 잘못된 패턴과 올바른 패턴을 코드로 제시해서, Claude가 코드를 작성할 때 자동으로 최적화 패턴을 적용합니다.

# Vercel 스킬 설치
npx skills add vercel-labs/agent-skills

2026년 3월 기준 20k 이상의 stars를 기록하며 가장 인기 있는 서드파티 스킬 중 하나입니다.

Agent Skills 오픈 표준

이 스킬들은 크로스 플랫폼으로 동작합니다. Anthropic이 공개한 Agent Skills 오픈 표준 ↗을 OpenAI Codex, VS Code, Cursor, GitHub 등이 채택했습니다. 그래서 한 번 만든 스킬을 여러 AI 도구에서 재사용합니다.

마무리

Skills 2.0으로 Claude Code에 기능을 패키지 단위로 더할 수 있습니다. 정리하면 다음과 같습니다.

• SKILL.md + 디렉토리 구조로 지침을 체계적으로 관리
• description 기반 자동 발견으로 필요한 시점에 자동 호출
• 플러그인 마켓플레이스로 커뮤니티 스킬을 한 줄로 설치
• Skill Creator의 eval/benchmark로 스킬 품질을 정량적으로 관리
• Agent Skills 오픈 표준으로 크로스 플랫폼 호환

처음에는 반복하는 작업을 하나 골라 SKILL.md 하나로 스킬을 만들어 봅니다.

관련 글

• npx skills: Vercel 실험에서 AI 에이전트 오픈 표준이 되기까지
• Superpowers 살펴보기

참고 링크

• 공식 문서: Extend Claude with skills ↗
• 플러그인 가이드: Discover and install plugins ↗
• Agent Skills 오픈 표준 ↗
• anthropics/skills GitHub ↗
• Skill Creator 소개 ↗