 커스텀 스킬(Custom Skill) 만들기 — 왜 만들고 어떻게 쓰나?){kind=link}
📌 핵심 요약
클로드 코드 커스텀 스킬은 SKILL.md 파일 하나로 Claude에게 나만의 전문가 핸드북을 쥐여주는 기능이다.
같은 프롬프트를 반복 입력할 필요 없이 Claude가 알아서 불러와 실행하는데, 2025년 10월 정식 출시 이후 커뮤니티 스킬만 85,000개를 돌파했고, 개발자들이 가장 많이 만드는 커스텀 스킬은 코드 리뷰, 프론트엔드 디자인, 커밋 메시지 포맷터 순이다.
"나 또 똑같은 프롬프트 쓰고 있네…"
솔직히 말해, 처음에는 Claude Code 쓸 때마다 같은 내용을 반복 입력하고 있었다.
"이 코드 리뷰해줘, 한국어로, 보안 이슈 먼저 봐줘, 설명은 초보자 눈높이로."
한 세션 끝나면? 또 처음부터. 다음 날도 또. 그러다 어느 날 이런 생각이 들었다.
"이거 그냥 Claude한테 외워두라고 하면 안 되나?" 😅
그게 바로 클로드 코드 커스텀 스킬의 시작점이다. Anthropic이 2025년 10월에 정식 출시한 이 기능, 한마디로 Claude에게 나만의 전문가 플레이북을 심어두는 것이다.
오늘은 왜 커스텀 스킬을 만들어야 하는지, 어떻게 만드는지, 그리고 커뮤니티에서 가장 핫한 스킬 3가지를 실제 코드와 함께 풀어보도록 하자.
🤔 클로드 코드 커스텀 스킬, 왜 만들어야 해?
Claude는 기본적으로 매 대화를 새로 시작한다. 이전 세션에서 내가 어떤 방식을 원했는지, 어떤 포맷을 선호하는지 기억 못 하는데, 커스텀 스킬은 이 문제를 정면으로 해결해 준다.
① 반복 프롬프트에서 해방돼
"같은 프롬프트를 반복해서 입력하고 있다면, 그건 스킬로 만들 때가 된 거야." — Anthropic 공식 문서에 나오는 말이다.
커뮤니티 데이터 보면 개발자들이 하루 평균 3~7회 같은 형태의 프롬프트를 재입력한다고 한다. 커스텀 스킬 하나가 이 반복을 0으로 만들어줄 것이다.
② 컨텍스트 낭비가 없어
클로드 코드 커스텀 스킬은 점진적 공개(Progressive Disclosure) 방식으로 동작한다. 스킬 메타데이터(이름+설명)는 ~100 토큰 수준으로 항상 대기하고, Claude가 필요하다고 판단할 때만 전체 지침(최대 5K 토큰)을 불러온다. 수십 개 스킬을 깔아도 컨텍스트 창이 터지지 않는 이유다.
③ 팀 전체 워크플로우가 통일돼
Team·Enterprise 플랜에서는 조직 전체에 커스텀 스킬을 배포할 수 있다. 코드 리뷰 기준, 커밋 메시지 규칙, 브랜드 가이드라인을 문서로 공유 안 해도, 스킬로 심어두면 새 팀원도 첫날부터 팀 기준에 맞는 결과물을 낼 수 있다.
🛠️ 클로드 코드 커스텀 스킬, 어떻게 만들어?
구조 자체는 놀랍도록 단순하다. 폴더 하나에 SKILL.md 파일 하나가 전부.
~/.claude/skills/
└── my-skill/
├── SKILL.md ← 필수 (지침 + 메타데이터)
├── references/ ← 선택 (참조 문서)
├── scripts/ ← 선택 (실행 스크립트)
└── assets/ ← 선택 (템플릿, 이미지 등)
SKILL.md 기본 구조 — 딱 두 파트야
상단에 YAML 프론트매터(메타데이터), 그 아래에 마크다운 본문(실제 지침). 이게 전부다.
---
name: my-skill
description: >
이 스킬이 무엇을 하는지 + 언제 사용해야 하는지.
"review/check/코드 봐줘" 키워드가 포함되면
반드시 이 스킬을 사용하라.
---
# My Skill
## 지침
1. 첫 번째 할 일
2. 두 번째 할 일
## 예시
입력: "이 코드 봐줘"
출력: 버그 → 가독성 → 개선점 순으로 정리
여기서 description 필드가 진짜 핵심이다. Claude는 이 설명을 읽고 지금 작업에 스킬을 쓸지 말지 결정하기 때문이다. "언제 사용하라"는 트리거 조건을 명확히 써야 자동 발동한다.
모호하게 쓰면 Claude가 스킬을 그냥 무시해버리니 주의하자.
설치 위치: 전역 vs 프로젝트별
| 설치 위치 | 경로 | 적용 범위 |
|---|---|---|
| 전역 (나 혼자) | ~/.claude/skills/ |
모든 프로젝트에서 사용 가능 |
| 프로젝트별 | .claude/skills/ |
해당 프로젝트에서만 동작 |
| Claude.ai 업로드 | 설정 → 커스터마이즈 → 스킬 | 웹/앱에서 사용 (Pro 이상) |
스킬 파일을 수정하면 Claude Code가 실시간으로 감지해서 재시작 없이 바로 적용해준다. 작성 → 테스트 → 수정 → 재테스트 루프가 굉장히 빠른 이유다. 대부분 2~3번 반복하면 완성도 있는 스킬이 나온다.
🏆 커뮤니티에서 가장 많이 만드는 클로드 코드 커스텀 스킬 3가지
GitHub 스타와 설치 수 기준으로, 개발자들이 가장 반복해서 만들고 또 공유하는 커스텀 스킬 유형 세 개를 골랐다. 단순 소개 말고, 실제로 써본 느낌과 코드를 같이 담았다.
코드 리뷰 자동화 스킬
Claude Code 쓰는 개발자라면 결국 다 만들게 되는 스킬이다. 매번 "이 코드 리뷰해줘, 버그 먼저, 가독성도 봐줘, 예시도 들어줘"라고 입력하는 대신, 한 번 정의해두면 끝이다.
가장 중요한 건 리뷰 순서를 고정하는 거다. Claude는 순서를 명시하지 않으면 매번 다른 구조로 답변하곤 한다. 스킬에 순서를 박아두면 매번 동일한 포맷으로 나와서 팀 리뷰 때도 비교가 편하다.
---
name: code-review
description: >
Python/JS 코드의 버그, 보안 이슈, 가독성을 체계적으로 리뷰한다.
"코드 리뷰해줘", "check", "audit", "이 코드 봐줘" 키워드가
포함되면 반드시 이 스킬을 사용하라.
---
# 코드 리뷰 스킬
아래 순서대로 반드시 진행하라:
1. **한 줄 요약**: 이 코드가 무엇을 하는지 한 문장으로
2. **버그 및 논리 오류**: 발견된 버그 목록 (없으면 "없음"으로 표시)
3. **보안 이슈**: SQL 인젝션, 하드코딩된 키, 인증 누락 등
4. **가독성 개선**: 네이밍, 함수 분리, 주석 제안
5. **종합 점수**: 10점 만점 + 핵심 감점 사유 한 줄
## 예시 출력
- 요약: 사용자 인증 후 프로필 반환하는 Django 뷰
- 버그: line 12 — user가 None일 때 체크 누락
- 보안: API 키 하드코딩 (line 8) → 환경변수 사용 권장
- 가독성: 변수명 `d` → `user_data` 변경 권장
- 점수: 6/10 (보안 이슈 심각)
활용법: 파일 열고 "이 코드 리뷰해줘"라고 하면 자동 발동된다. /code-review로 직접 호출도 가능하다. 팀 레포의 .claude/skills/에 넣으면 팀원 모두가 같은 기준으로 리뷰하게 돼서, "리뷰 기준이 사람마다 달라요"라는 문제가 바로 해결된다.
references/ 폴더에 팀 코딩 컨벤션 마크다운 파일을 넣고 SKILL.md에서 참조하면, Claude가 우리 팀 기준으로만 리뷰해준다. 레퍼런스 파일은 필요할 때만 로드되니까 토큰 낭비도 없다.
AI 슬롭 탈출 — 프론트엔드 디자인 스킬
Claude한테 UI 만들어달라고 하면 항상 비슷한 결과가 나왔다. Inter 폰트, 보라색 그라디언트, 카드 레이아웃. 커뮤니티에서 이걸 "AI 슬롭(AI Slop)"이라고 부른다. Anthropic이 이 문제를 해결하려고 직접 만든 공식 커스텀 스킬이 frontend-design이다.
이 스킬은 코드 한 줄 쓰기 전에 Claude가 반드시 네 가지를 정의하도록 강제한다. 목적(누가 왜 쓰는가), 톤(어떤 미학 방향인가), 제약(프레임워크, 접근성), 차별화(다른 AI 결과물과 어떻게 다를 건가). 그리고 Inter, Roboto, Arial 같은 흔한 폰트를 아예 금지 목록에 올려뒀다. 😂
| 항목 | 스킬 없을 때 | 스킬 있을 때 |
|---|---|---|
| 폰트 | Inter, Roboto 반복 | 독창적 페어링 선택 |
| 색상 | 보라+흰색 패턴 | CSS 변수 시스템으로 구성 |
| 레이아웃 | 카드 나열 | 비대칭, 레이어드 구성 |
| 애니메이션 | 거의 없음 | 스크롤 트리거, 호버 등 의도적 모션 |
활용법: /frontend-design 입력하거나, "랜딩 페이지 만들어줘"처럼 UI 관련 요청하면 자동 발동된다. Anthropic GitHub에서 공식 스킬을 그대로 가져다 써도 되고, 우리 회사 브랜드 가이드라인을 담아 커스터마이징해도 된다.
커밋 메시지 포맷터 스킬
가장 단순한 커스텀 스킬이 가장 자주 쓰인다. 많은 사람들이 첫 스킬로 이걸 만든다. git 커밋 메시지를 Conventional Commits 형식으로 통일하는 스킬인데, "added user auth"를 "feat(auth): implement JWT-based authentication"으로 바꿔준다.
---
name: commit-message-formatter
description: >
git 커밋 메시지를 Conventional Commits 규칙으로 포맷한다.
"커밋", "commit", "git message", "커밋 메시지" 키워드가
나오면 반드시 이 스킬을 사용하라.
---
# 커밋 메시지 포맷터
모든 커밋 메시지는 아래 형식을 따른다:
<type>(<scope>): <description>
## 규칙
- 명령형, 소문자, 마침표 없음, 72자 이내
- Breaking change: type 뒤에 `!` 추가
## type 목록
feat / fix / docs / style / refactor / test / chore
## 예시
입력: "added user auth with JWT"
출력: feat(auth): implement JWT-based authentication
입력: "버그 수정했음"
출력: fix(core): resolve null pointer in user service
이 스킬의 진짜 가치는 팀에 있다. 사람마다 커밋 스타일이 달라지면 히스토리 추적이 지옥이 된다. 이 파일 하나를 .claude/skills/에 넣고 팀 레포에 커밋하면, 팀원 전체가 같은 기준으로 커밋 메시지를 쓰게 된다.
❓ 자주 묻는 것들
Q. 클로드 코드 커스텀 스킬 쓰려면 어떤 플랜이 필요해?
Pro, Max, Team, Enterprise 플랜에서 사용할 수 있다. Free 플랜은 지원 안 된다. Claude Code는 커스텀 스킬만 지원하고, Claude.ai 웹에서는 공식 스킬도 같이 쓸 수 있다.
Q. 스킬이랑 CLAUDE.md는 뭐가 달라?
CLAUDE.md는 프로젝트 전반의 컨텍스트를 담는 파일이고, 스킬은 특정 작업을 위한 전문화된 핸드북이다. CLAUDE.md는 항상 로드되지만, 스킬은 필요할 때만 로드돼. 둘 다 쓰면 시너지 효과가 있다.
Q. 스킬이 자동으로 발동 안 되면 어떻게 해?
description 필드를 더 구체적으로 고쳐야 한다. "언제 사용하라"는 트리거 조건을 명시적으로 쓰는 게 핵심이다. 그래도 안 되면 /skill-name으로 직접 호출하면 된다.
Q. 스킬에 파이썬 스크립트도 넣을 수 있어?
scripts/ 폴더에 파이썬 파일을 넣으면 Claude가 필요할 때 실행해준다. 복잡한 외부 API 연동은 MCP(Model Context Protocol)와 결합하는 게 더 좋다.
🚀 마무리: 지금 당장 하나만 만들어 보자
Claude Code 커스텀 스킬의 철학은 단순하다. 전문가도 매번 처음부터 시작하지 않는다는 거다. 좋은 체크리스트, 자신만의 루틴, 팀과 공유한 기준. 커스텀 스킬은 그걸 AI한테도 적용하는 방법이기 때문이다.
오늘 소개한 세 스킬(코드 리뷰, 프론트엔드 디자인, 커밋 포맷터)은 시작점이다. 나만의 n8n 워크플로우 디버깅 스킬, 블로그 초안 스킬, Obsidian 노트 정리 스킬… 반복하는 작업이 있다면 뭐든 커스텀 스킬이 될 수 있다.
👉 지금 바로 해볼 것
커밋 메시지 포맷터 스킬부터 만들어보자. 10분이면 충분하고, 효과는 오늘 바로 느껴질 것이다. 만들고 나서 Anthropic 공식 skills GitHub 레포에서 더 많은 아이디어도 얻자. 커스텀 스킬 하나가 하루 루틴을 어떻게 바꾸는지 느껴보면 진짜 재미있다. 😄
🏷️ 태그: 클로드 코드 커스텀 스킬, Claude Code, SKILL.md, AI 코딩 자동화, 코드 리뷰 자동화, 프론트엔드 디자인, Anthropic 스킬, n8n 자동화, vibe coding
댓글 쓰기