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

CLAUDE.md에 프롬프트를 붙여넣던 시대는 끝났습니다. Claude Code Skills 2.0은 구조화된 패키지, 자동 발견, 플러그인 마켓플레이스를 통해 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 LR
    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 형식의 뼈대를 작성합니다. 이처럼 분류 규칙과 출력 형식을 분리하면 스킬 지침이 깔끔해집니다.

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를 단순한 코딩 어시스턴트에서 확장 가능한 AI 플랫폼으로 전환시킵니다. 핵심을 정리하면 다음과 같습니다.

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

가장 좋은 시작은 반복하는 작업을 하나 골라 스킬로 만들어보는 것입니다. SKILL.md 하나로 시작해서 점진적으로 확장하면 됩니다.

참고 링크

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