Claude Code Skills는 자주 반복하는 작업을 슬래시(/) 명령 하나로 묶어두는 기능입니다. “git 커밋 메시지 잘 써줘”, “이 코드 리뷰해줘”처럼 매번 설명을 풀어쓰는 대신, /commit이나 /review 한 줄로 끝낼 수 있어요. 마크다운 파일 하나가 곧 하나의 명령이 됩니다.
Skills가 뭔가요? (슬래시 명령 = 나만의 AI 단축키)
비유하자면, Skills는 Claude Code에 등록해두는 “단축키 + 지시사항 묶음”입니다.
예를 들어볼게요. 코드 리뷰를 요청할 때마다 “변수명이 명확한지, 예외 처리가 빠진 곳은 없는지, 중복 코드가 있으면 리팩토링 방법도 같이 알려줘” 같은 긴 설명을 반복한다면 피곤하겠죠. /review라는 스킬을 만들어두면, 그 한 줄이 모든 지시를 대신합니다.
이전에는 비슷한 기능이 Commands(.claude/commands/)라는 이름으로 분리돼 있었지만, 현재는 Skills로 통합됐습니다. 이름이 바뀐 정도이고, 원리는 그대로예요.
Skills와 Hooks의 차이도 짚어두면:
- Skills: 사용자가 명시적으로
/명령을 입력할 때 실행. “이걸 해줘”라는 요청을 단축 - Hooks: 특정 이벤트(파일 저장, 도구 실행 등)가 발생하면 자동 실행. 사람이 말 안 해도 동작
둘 다 자동화지만 방향이 다릅니다. Skills는 내가 트리거하고, Hooks는 시스템이 트리거해요.
첫 번째 Skill 만들기 (5분 가이드)
Skills 파일은 마크다운(.md) 파일 하나입니다. 특별한 도구가 필요 없어요.
파일 위치
- 프로젝트 전용: 작업 폴더 안의
.claude/skills/— 해당 프로젝트에서만 사용 - 모든 프로젝트 공통: 홈 폴더의
~/.claude/skills/— 어디서든 쓸 수 있는 글로벌 스킬
공통으로 쓸 것 같으면 글로벌에, 이 프로젝트에서만 쓸 거라면 로컬에 넣으면 됩니다.
기본 형식
---
name: my-skill
description: 이 스킬이 하는 일을 한 줄로
---
# 지시사항
1. 첫 번째 단계
2. 두 번째 단계
3. 결과 형식
파일을 저장하면 Claude Code에서 /my-skill로 바로 호출할 수 있습니다. ---로 감싼 YAML 부분이 메타데이터(이름과 설명), 그 아래가 Claude에게 전달되는 실제 지시사항이에요.
스킬 이름이 곧 명령어
파일명이 commit.md이면 명령어는 /commit, 파일명이 weekly-report.md이면 /weekly-report가 됩니다. YAML의 name 필드와 일치시키는 게 좋습니다.
실전 Skill 예시 4가지
어떤 상황에 쓸 수 있는지 바로 갖다 쓸 수 있는 예시로 보여드릴게요.
1. /commit — 커밋 메시지 자동 생성
---
name: commit
description: 변경 사항을 분석해 커밋 메시지를 작성한다
---
# 커밋 메시지 작성 규칙
1. git diff --staged 로 변경 내용을 확인한다
2. 변경의 목적(why)을 중심으로 커밋 메시지를 작성한다
3. 형식: `타입: 요약 (50자 이내)`
- 타입: feat / fix / docs / refactor / chore
4. 본문이 필요하면 한 줄 띄고 추가 설명을 쓴다
5. 커밋 실행 전, 메시지를 먼저 보여주고 확인을 받는다
특히 마지막 줄 “확인을 받는다”가 중요합니다. 자동으로 커밋까지 실행하지 않고, 사람이 한 번 더 보게 하는 안전장치예요.
2. /review — 코드 리뷰 실행
---
name: review
description: 현재 변경된 코드를 리뷰한다
---
# 코드 리뷰 체크리스트
변경된 코드를 아래 기준으로 검토한다:
1. **가독성**: 변수명, 함수명이 역할을 명확히 드러내는가
2. **예외 처리**: 빠진 에러 핸들링이 없는가
3. **중복**: 비슷한 로직이 반복되면 리팩토링 방법 제안
4. **성능**: 명확히 비효율적인 부분이 있으면 지적
5. **보안**: 민감 정보 노출, 인젝션 위험 등
심각도를 🔴(필수 수정) / 🟡(권장) / 🟢(참고)로 표시한다.
3. /report — 일일 보고서 생성
---
name: report
description: 오늘 작업 내용을 정리해 보고서를 작성한다
---
# 일일 보고서 작성
1. 오늘 날짜(KST)를 확인한다
2. 현재 디렉토리의 최근 변경 파일 목록을 확인한다
3. git log --oneline --since=today 로 오늘 커밋 이력을 확인한다
4. 아래 형식으로 보고서를 작성한다:
## 오늘 한 일
- (작업 항목)
## 생성된 산출물
- (파일 목록)
## 내일 할 일
- (다음 작업)
보고서는 마크다운으로 출력하고, 파일로 저장할지 물어본다.
4. /deploy — 배포 파이프라인 (안전장치 포함)
---
name: deploy
description: 프로덕션 배포를 실행한다
disable-model-invocation: true
---
echo "배포를 시작합니다. 프로덕션 환경입니다."
npm run build
npm run test
git push origin main
echo "배포 완료"
disable-model-invocation: true가 붙어 있으면 Claude가 AI 판단 없이 명령을 그대로 실행합니다. 배포처럼 AI가 맥락을 “해석”해서 엉뚱한 걸 하면 곤란한 작업에 씁니다.
고급 기능 — arguments, context, 안전장치
기본 스킬에서 한 단계 더 나아가면 이런 기능들을 쓸 수 있어요.
$ARGUMENTS — 인자 전달
슬래시 명령 뒤에 추가 정보를 전달할 때 씁니다.
---
name: translate
description: 텍스트를 지정한 언어로 번역한다
---
아래 텍스트를 $ARGUMENTS 로 번역해줘.
현재 선택된 텍스트 또는 클립보드 내용을 번역 대상으로 한다.
/translate 영어라고 입력하면, $ARGUMENTS 자리에 “영어”가 들어갑니다. /translate 일본어면 일본어로 번역되고요. 같은 스킬을 다용도로 쓸 수 있게 해줍니다.
context — 동적 컨텍스트 주입
스킬이 실행될 때 셸 명령을 미리 실행하고, 그 결과를 Claude에게 자동으로 전달하는 기능입니다.
---
name: status
description: 현재 프로젝트 상태를 요약한다
context:
- type: shell
command: git status
- type: shell
command: git log --oneline -10
---
위의 git 정보를 바탕으로 현재 프로젝트 상태를 한 페이지로 요약해줘.
사용자가 /status를 입력하면 Claude는 git status와 최근 커밋 10개를 이미 보고 시작합니다. “어떤 파일이 바뀌었냐”고 별도로 물을 필요가 없어요.
allowed-tools — 도구 제한
해당 스킬에서 Claude가 사용할 수 있는 도구를 제한합니다. 파일을 읽기만 해야지 수정하면 안 되는 스킬이라면 Write나 Edit을 막아둘 수 있어요.
---
name: analyze
description: 코드를 분석하되 수정은 하지 않는다
allowed-tools:
- Read
- Grep
- Bash
---
현재 프로젝트의 코드 구조를 분석하고 개선 포인트를 제안해줘.
수정은 하지 않고 제안만 한다.
disable-model-invocation — 부작용 방지
true로 설정하면 Claude가 AI 판단 없이 스킬 내용을 그대로 실행합니다. 주로 셸 스크립트 형태의 스킬에서 “AI가 알아서 해석하지 말고 그냥 이 명령을 돌려라”고 지정할 때 씁니다. 배포, 데이터베이스 작업, 파일 일괄 삭제 같은 되돌리기 어려운 작업에 적합합니다.
Skills 관리 팁
스킬이 늘어날수록 관리가 중요해집니다. 실제로 쓰다 보니 효과 있던 원칙들을 정리했어요.
하나의 스킬은 하나의 일만 합니다. “커밋하고 배포하고 슬랙에 알림까지”를 한 스킬에 넣으면, 하나가 실패했을 때 어디서 멈췄는지 파악하기 어렵습니다. /commit, /deploy, /notify를 따로 만들어두는 편이 훨씬 낫습니다.
코드 실행 전에 질문 먼저. 스킬 지시사항 안에 “실행 전에 확인을 받아라”는 문장을 넣어두세요. 특히 파일을 지우거나 배포하는 작업은, Claude가 한 번 더 “이렇게 하면 되나요?”라고 묻게 하는 게 안전합니다.
description을 성의 있게 씁니다. /help나 자동완성에서 description이 표시되기 때문에, 석 달 뒤에 봐도 이 스킬이 뭘 하는지 바로 알 수 있게 써두면 편합니다.
글로벌 vs 로컬을 구분합니다. /commit이나 /review처럼 어디서나 쓸 법한 스킬은 글로벌(~/.claude/skills/)에, 이 프로젝트의 특정 배포 방식이나 보고서 형식처럼 프로젝트 종속적인 스킬은 로컬(.claude/skills/)에 둡니다.
버전 관리에 같이 넣습니다. .claude/skills/ 폴더를 git에 포함시키면, 팀원들이 같은 스킬을 그대로 쓸 수 있어요. “나는 /commit 쓰는데 너는 왜 손으로 쓰냐”는 상황이 없어집니다.
정리
Claude Code Skills는 반복적인 지시를 슬래시 명령 하나로 압축하는 기능입니다. 마크다운 파일 하나를 만들어두면, 그게 바로 내 AI 단축키가 됩니다.
시작은 단순하게 해도 됩니다. 자주 쓰는 지시 하나를 .claude/skills/my-command.md로 저장해보세요. /my-command로 호출해서 동작하는 걸 보면, 나머지는 자연스럽게 늘려가게 됩니다.
인자($ARGUMENTS)나 컨텍스트(context) 같은 고급 기능은 기본 스킬이 익숙해진 뒤에 하나씩 붙여도 충분해요. 처음부터 완벽하게 만들려다 보면 시작 자체를 못 하게 됩니다.
함께 읽으면 좋은 글