Claude Code Skills 완전 가이드: 무엇이고 언제 써야 하나

Q: Skill은 디스크 어디에 있나요?

사용자 전역: ~/.claude/skills/ /SKILL.md. 프로젝트: .claude/skills/ /SKILL.md. 둘 다 자동 로드, 이름 충돌 시 프로젝트가 우선.

Q: 팀과 skill을 공유할 수 있나요?

네. .claude/skills/를 레포에 커밋하면 프로젝트별 skill. 팀 전역은 공유 dotfiles 레포로 배포하거나 ~/.claude/skills/를 동기화 폴더에 심볼릭 링크.

Q: Skill과 MCP 서버의 차이는?

MCP 서버는 도구(호출 가능한 함수 — query_database, send_email)를 노출. Skill은 워크플로우 — 기존 도구를 사용하는 단계별 절차. MCP 서버 도구를 호출하는 skill을 만들 수 있음.

Q: Skill이 사용자에게 입력을 요청할 수 있나요?

네. skill 본문 내에서 AskUserQuestion 사용. 또는 $ARGUMENTS로 CLI 스타일 호출. Skill은 둘을 섞을 수 있음 — 선택적 인자 받고 누락된 것은 묻기.

Claude Code Skills는 ~/.claude/skills/ 디렉토리의 SKILL.md 파일로 정의하는 재사용 가능한 AI 호출 워크플로우입니다. 각 skill은 Claude Code가 자동 발견하고 Skill 도구로 호출하며, 매번 복붙하는 30줄짜리 지시문을 /skill-name 한 번의 호출로 압축합니다 (2026 기준). 반복되는 워크플로우(코드 리뷰, 배포, 콘텐츠 생성, 감사)를 재사용 가능한 블록으로 압축하는 방법입니다. 일주일에 같은 지시를 여러 번 Claude Code에 붙여넣고 있다면, skill로 만들면 됩니다.

이 가이드는 모델을 다룹니다: skill이란 무엇인지, Claude가 어떻게 발견하는지, skill vs 슬래시 명령어 vs CLAUDE.md 차이, 그리고 이미 공개된 skill 라이브러리.

Skill이란 정확히 무엇인가

Skill은 프론트매터가 있는 마크다운 파일(SKILL.md)로, Claude Code가 도구처럼 호출할 수 있습니다. 다음을 포함합니다:

YAML 프론트매터 — 이름, 설명, 호출 시점
마크다운 본문 — Claude가 따를 단계별 지시
선택적 헬퍼 파일 — 스크립트, 템플릿, 참조

예시 skill (~/.claude/skills/deploy/SKILL.md):

---
name: deploy
description: 현재 브랜치를 운영에 배포. "ship it", "deploy", "go live" 또는 PR merge 후 호출.
---

# 현재 브랜치 배포

1. `bun run build` 실행 — exit code != 0이면 중단
2. `vercel deploy --prod --yes` 실행
3. "Aliased: ..." 라인 대기, HTTP 200 확인
4. 새 콘텐츠 슬러그가 있으면 IndexNow 제출
5. 배포 URL + git SHA + 변경 파일 라인 수 보고

이제 Claude Code 세션에서 "ship it"이라고 하면 Claude가 이 skill을 호출하고 단계를 명확히 할 필요 없이 실행합니다.

Skill vs 슬래시 명령어 vs CLAUDE.md

세 가지가 겹치는 목적을 가집니다. 올바르게 선택하는 것이 절반의 승리:

사용 사례	선택
반복 가능한 다단계 워크플로우 ("deploy", "audit", "review")	Skill
일회성 UI 명령 (`/clear`, `/exit` 같은 Claude 내장)	슬래시 명령어
프로젝트별 컨텍스트 (스택, 컨벤션, 명령어)	CLAUDE.md

룰: CLAUDE.md에 "매번 이 단계를 따르라"고 쓸 것 같다면, 대신 skill로 만드세요. Skill은 필요할 때 호출되고, CLAUDE.md는 매 세션 로드됩니다.

Skill 사용에 적합한 경우

적합

배포 워크플로우 — deploy, rollback, canary (Claude Code Hooks 8가지 패턴 패턴 참고)
감사/리뷰 — aeo-audit, quality-gate, security-scan
콘텐츠 생성 — write-blog-post, generate-changelog, summarize-pr
조사 — investigate-bug, find-related-tests, trace-deployment
셋업 — init-project, setup-deploy, configure-monitoring (Claude Code 메모리 시스템과 짝이 잘 맞음)

부적합

사소한 일회성 작업 — "이 파일 포맷해줘"는 skill 필요 없음, 그냥 말하기
매번 다른 변수 필요 — 너무 가변적이면 skill이 깨지기 쉬움
프로젝트별 명령 — CLAUDE.md에 넣는 게 맞지 전역 skill 아님

공개 Skill 라이브러리

Anthropic과 커뮤니티가 ~/.claude/skills/에서 유지하는 주요 예시:

gstack — 전체 개발 스택 (review, ship, qa, investigate)
superpowers — TDD, 디버깅, 코드 리뷰 패턴
engineering — debug, system-design, deploy-checklist
design — design-review, accessibility-check
finance — reconciliation, journal-entry-prep

설치된 skill은 ls ~/.claude/skills/로 확인할 수 있습니다. 각 디렉토리에 SKILL.md가 있어 언제 호출할지 정의합니다.

Claude가 Skill을 발견하는 방법

세션 시작 시 Claude Code는 모든 사용 가능한 skill을 설명과 함께 나열합니다. "ship it" 또는 "deploy this"라고 말하면 Claude는 의도를 skill 설명과 매칭해 최적의 매치를 호출합니다.

ls ~/.claude/skills/
# deploy/  audit/  review/  investigate/  setup-deploy/

첫 Skill 만들기

최소 5줄짜리 skill로 시작 가능:

---
name: bun-test
description: 현재 패키지에서 bun test 실행. "test it", "run tests", 또는 테스트 파일 수정 후 호출.
---

`bun test`를 실행하고 결과를 보고. 실패하면 출력을 보여주고 중단.

~/.claude/skills/bun-test/SKILL.md로 저장하고 Claude Code를 재시작하면 끝.

인자, 헬퍼 스크립트, 조건부 로직이 있는 더 깊은 가이드는 커스텀 Claude Code Skill 만드는 법을 참고하세요.

인자가 있는 Skill

Skill은 $ARGUMENTS로 인자를 받을 수 있습니다:

---
name: trace
description: SHA로 배포 추적. 사용법 /trace <sha>
---

git SHA $ARGUMENTS에 대한 배포 조회.
1. 이 SHA에 매치되는 Vercel 배포 찾기
2. 배포 URL, 빌드 시간, 상태 표시
3. 해당 git 커밋의 변경 파일 나열

호출: /trace abc123

Skill 조합

Skill이 다른 skill을 호출할 수 있습니다. 흔한 패턴: ship skill이 qa, review, deploy를 순차 호출.

---
name: ship
description: 전체 ship 파이프라인. "ship this", PR 승인 후 호출.
---

1. `qa` skill 호출 — FAIL이면 중단
2. `review` skill 호출 — 사람 승인 대기
3. `deploy` skill 호출
4. 최종 배포 URL 보고

gstack과 비슷한 툴킷이 이렇게 워크플로우를 구조화합니다.

Skill을 쓰지 말아야 할 때

한 번만 할 작업 — 그냥 프롬프트 직접 입력
주마다 워크플로우 바뀜 — skill이 빨리 낡음, CLAUDE.md에 두기
작업에 대한 추론 필요 — skill은 절차용, 탐색용 아님

Skill 성능 고려사항

Skill은 세션 시작 시 로드됩니다. 50개 이상 설치되면 세션 부트스트랩에 1-3초 추가. 해법: skill 설명은 짧게(1-2문장) 유지, 전체 SKILL.md는 호출 시에만 읽음.

Skill 본문은 호출 전엔 로드 안 됨. 500줄짜리 skill도 사용할 때만 컨텍스트에 들어가 OK.

Frequently Asked Questions

Skill은 디스크 어디에 있나요?

사용자 전역: ~/.claude/skills/<name>/SKILL.md. 프로젝트: .claude/skills/<name>/SKILL.md. 둘 다 자동 로드, 이름 충돌 시 프로젝트가 우선.

팀과 skill을 공유할 수 있나요?

네. .claude/skills/를 레포에 커밋하면 프로젝트별 skill. 팀 전역은 공유 dotfiles 레포로 배포하거나 ~/.claude/skills/를 동기화 폴더에 심볼릭 링크.

Claude.ai 웹에서도 Skill이 작동하나요?

아니오. Skill은 Claude Code 전용 기능. claude.ai 웹은 별도 시스템(Projects, custom instructions) 사용. Skill은 로컬 Claude Code 설치에 종속.

Skill과 MCP 서버의 차이는?

MCP 서버는 도구(호출 가능한 함수 — query_database, send_email)를 노출. Skill은 워크플로우 — 기존 도구를 사용하는 단계별 절차. MCP 서버 도구를 호출하는 skill을 만들 수 있음.

Skill이 사용자에게 입력을 요청할 수 있나요?

네. skill 본문 내에서 AskUserQuestion 사용. 또는 $ARGUMENTS로 CLI 스타일 호출. Skill은 둘을 섞을 수 있음 — 선택적 인자 받고 누락된 것은 묻기.

Claude Code 생산성 마스터하기

P1 Power Prompts 300 ($29) — skill로 만들 수 있는 300개의 프로덕션 검증 프롬프트. 리뷰, 배포, 감사, 콘텐츠 생성, 조사 외 14개 카테고리.