Claude Code Skills 만들기: 반복 작업을 슬래시 커맨드 하나로
claude code skills 만들기 한 줄 요약
짧은 답:
~/.claude/skills/<이름>/SKILL.md나 프로젝트의.claude/skills/<이름>/SKILL.md폴더를 만들고,description을 한 줄로 또렷하게 적으면 시작은 끝나요.
실무 팁: 근데 여기서 멈추면 자동 발동이 들쭉날쭉할 수 있거든요. 핵심 키워드를description앞에 두고, 반복 작업이면 훅으로 한 번 더 밀어주는 쪽이 안정적이에요.
주의할 점: 배포나 커밋처럼 부작용 있는 작업은disable-model-invocation: true를 붙여 손으로만 실행되게 두세요.
처음 SKILL.md를 써봤을 때, 정작 Claude가 안 불러줘서 더 열받았어요. Claude Code Skills 만들기 자체는 10분이면 끝나는데, 자동 발동이 들쭉날쭉하면 매번 슬래시 커맨드를 손으로 치게 되거든요. 그러면 반복 프롬프트를 줄이려고 skill을 만든 의미가 확 줄어요.
2026년 4월 18일 기준 공식 문서를 다시 훑어보니, 이 기능은 터미널 실행판만 보는 걸로 끝나지 않더라고요. VS Code 확장, JetBrains 플러그인, 데스크톱 앱, 웹 세션, Slack 연동, Chrome 확장 프로그램, 모바일 앱 모니터링까지 연결돼 있어요. 그래서 어디서 만들고 어디서 테스트할지부터 정리해야 덜 꼬여요.
아래 흐름은 PR 설명 초안 skill 하나를 직접 만드는 기준으로 잡았어요. 폴더 구조, SKILL.md 앞부분 YAML 메타데이터, 자동 발동을 올리는 훅 아이디어, commands에서 skills로 옮길 때 기준, 자주 터지는 버그까지 한 번에 묶었어요. 공식 기준이 궁금하면 Claude를 skills로 확장하기와 Skill authoring best practices 두 페이지를 같이 열어두면 훨씬 빨라요.
Skills가 돌아가는 환경부터 정리
Claude Code Skills를 어디서 쓰는지부터 정리해야 설치와 테스트가 덜 꼬여요. 작성은 파일 편집이 쉬운 쪽, 실행은 세션이 붙어 있는 쪽으로 나눠 보면 생각보다 단순해요.
이거 아직도 터미널 전용 기능이라고 생각하고 있었던 건 아니죠?
아니에요. 이제 여러 환경이 함께 붙어서 돌아가요.
| 사용 환경 | 공식 문서 기준 상태 | skill 관점에서 보면 |
|---|---|---|
| 터미널 CLI | 메인 환경 | SKILL.md 만들고 /name 테스트하기 제일 편해요 |
| VS Code 확장 | 전용 UI + CLI 포함 | 편집, 호출, diff 보기까지 한 자리에서 끝나요 |
| JetBrains IDE | 플러그인 제공 | IntelliJ, PyCharm 같은 환경에서 비슷하게 써요 |
| 데스크톱 앱 | skill 호출, 플러그인 브라우저 지원 | 시각적 diff 확인과 plugin 관리에 좋아요 |
| 웹 | research preview | 리포에 있는 .claude/skills/를 원격 세션에서 불러와요 |
| Slack | 코딩 요청을 웹 세션으로 라우팅 | 채널에서 작업 시작하고 웹으로 이어가요 |
| Chrome 확장 프로그램 | beta | CLI나 VS Code와 묶어 브라우저 작업까지 붙여요 |
| 모바일 앱 | 웹 세션 모니터링 | 오래 도는 작업 상태 확인용으로 보면 돼요 |
정리하면 이래요. SKILL.md 직접 만들고 고치는 건 터미널이나 IDE 쪽이 편하고, 데스크톱 앱과 웹은 불러서 이어서 쓰거나 검토하는 쪽에 가까워요. 설치가 아직이면 Claude Code 사용법: 설치부터 첫 실행까지 5분 가이드부터 보고 오는 게 훨씬 빨라요.
첫 skill 만들기
처음 만들 skill은 최대한 작아야 해요. 개인 전역에 둘지, 프로젝트 안에 넣어 팀과 같이 쓸지만 먼저 정하면 바로 움직일 수 있어요.
매번 같은 PR 설명 프롬프트를 붙여넣을 건 아니죠?
먼저 위치부터 고르세요.
- 내 모든 프로젝트에서 쓸 거면
~/.claude/skills/<name>/SKILL.md - 팀 리포에 같이 넣을 거면
.claude/skills/<name>/SKILL.md - 예제, 참고 문서, 스크립트가 붙을 예정이면 폴더형으로 시작
- 만든 뒤 바로
what skills are available?로 로딩 체크
.claude/
└── skills/
└── pr-summary/
├── SKILL.md
├── examples.md
└── reference.md
# 프로젝트 전용 skill 폴더 만들기
mkdir -p .claude/skills/pr-summary
# Claude 세션에서 로딩 여부 확인
claude "what skills are available?"
# 출력 예시
# - pr-summary: PR 설명 초안을 한국어로 정리하고 리뷰 포인트를 묶음
/pr-summary main
출력 예시
- 변경 요약 3줄
- 테스트 체크리스트
- 리뷰어가 먼저 볼 파일
여기서 examples.md와 reference.md를 미리 나눠두면 나중에 SKILL.md가 덜 비대해져요. 참고로 코드베이스를 길게 뒤지게 하는 작업은 skill 하나로 억지로 우겨 넣기보다 Claude Code 서브에이전트 만들기 실전 가이드: 자동 위임·비용 절감 세팅까지처럼 하위 에이전트로 분리하는 편이 더 낫더라고요.
SKILL.md 작성: 자주 쓰는 6개 필드
SKILL.md는 길게 쓰는 것보다 앞부분을 정확하게 쓰는 게 더 중요해요. 처음엔 자주 쓰는 6개 필드만 잡고, 나머지 고급 옵션은 나중에 붙여도 충분해요.
설명란에 하고 싶은 말 다 넣고 싶은 마음, 진짜 눌러야 할까요?
| 필드 | 언제 쓰나 | 실무 메모 |
|---|---|---|
name |
슬래시 커맨드 이름 정할 때 | 소문자와 하이픈 위주가 덜 꼬여요 |
description |
자동 발동 힌트 줄 때 | 한 줄로, 핵심 유스케이스를 앞에 둬요 |
argument-hint |
자동 완성 힌트 보여줄 때 | [target-branch]처럼 짧게 적으면 끝 |
disable-model-invocation |
부작용 있는 작업 막을 때 | 배포, 커밋, 메시지 발송 계열은 거의 필수예요 |
user-invocable |
/ 메뉴에서 숨길 때 |
배경 지식용 skill이면 false도 괜찮아요 |
allowed-tools |
허용 도구를 미리 열어둘 때 | 자주 쓰는 git diff, git log 정도만 좁게 줘요 |
---
name: pr-summary
description: PR 설명 초안을 한국어로 정리하고 변경점, 테스트, 리뷰 포인트를 묶어요
argument-hint: "[target-branch]"
disable-model-invocation: true
user-invocable: true
allowed-tools:
- Bash(git status)
- Bash(git diff *)
- Bash(git log *)
---
# PR 설명 초안 만들기
1. 현재 브랜치와 대상 브랜치 차이를 읽어요.
2. 변경 파일을 기능 단위로 묶어요.
3. 아래 순서로 한국어 초안을 써요.
4. 확실하지 않은 항목은 추측하지 말고 `TODO: ...` 주석으로 남겨요.
## 출력 형식
- 변경 요약
- 테스트 결과
- 리뷰 포인트
- 배포 영향
description은 특히 중요해요. 공식 문서 기준으로 자동 발동 판단에 직접 쓰이고, 250자보다 길면 잘릴 수 있거든요. 무거운 분석을 새 컨텍스트에서 돌리고 싶다면 고급 옵션으로 context: fork를 붙이면 되는데, 모델과 노력 수준까지 만질 생각이면 Claude Opus 4.7 코딩 활용법: xhigh와 비전 업그레이드로 바뀐 실전 워크플로우 쪽을 같이 보는 게 덜 헷갈려요.
Claude Code Skills 자동 발동 안정화
자동 발동은 description만 잘 써도 조금 나아져요. 근데 반복 작업을 진짜 줄이고 싶다면 훅, 그러니까 세션 특정 타이밍에 자동으로 끼어드는 스크립트까지 붙이는 쪽이 훨씬 안정적이에요.
왜 분명 있는 skill을 Claude가 못 본 척할까요?
먼저 체감 차이를 이렇게 보면 쉬워요.
| 방법 | 체감 | 언제 쓰면 좋은가 |
|---|---|---|
| 훅 없음 | 랜덤한 편 | skill 수가 적고 직접 /name을 자주 칠 때 |
description만 다듬기 |
조금 나아짐 | 가벼운 knowledge skill일 때 |
| 강제 평가 훅 | 가장 안정적 | 자동 발동이 핵심인 반복 작업일 때 |
| 수동 슬래시 호출 | 제일 확실함 | 실수 비용이 큰 작업일 때 |
공개된 한국어 실사용 기록에서도 강제 평가 훅을 붙이자 자동 발동률이 체감상 확연히 올라갔다는 후기가 반복돼요. 근데 리포 구조와 skill 설명 길이에 따라 차이가 꽤 크거든요. 남의 숫자에만 기대지 말고 내 환경에서 최소 몇 번은 다시 재보는 게 맞아요.
#!/usr/bin/env bash
# 현재 작업 전에 등록된 skill을 먼저 점검하게 하는 예시
cat <<'EOF'
작업을 시작하기 전에 현재 등록된 skills를 먼저 평가하세요.
관련된 skill이 있으면 이유를 한 줄로 적고 바로 호출하세요.
해당 skill이 없을 때만 일반 작업으로 넘어가세요.
EOF
이 정도 문장만 있어도 무시 빈도가 줄어드는 경우가 많아요. 정말 매번 지켜져야 하는 흐름이면 Claude Code Hooks 완벽 가이드 – 자동화 훅 설정법 쪽처럼 훅으로 강제하는 편이 덜 답답해요.
Claude Commands vs Skills 선택 기준
지금도 commands 파일은 돌아가요. 새로 만들 걸 어디에 둘지만 판단하면 돼요.
기존 /command 잘 돌아가는데 굳이 옮겨야 할까요?
| 구분 | Commands | Skills |
|---|---|---|
| 호출 방식 | 주로 명시적 /name |
자동 발동 + 명시적 /name 둘 다 |
| 파일 구조 | 단일 파일 위주 | 폴더형, 지원 파일 추가 쉬움 |
| 현재 공식 방향 | 계속 동작 | 새 작업은 이쪽이 더 자연스러워요 |
| 잘 맞는 작업 | 짧은 수동 실행 | 반복 프롬프트, 지식, 다단계 작업 |
| 팀 공유성 | 가능은 함 | 예제와 참조 문서까지 묶기 좋아요 |
공식 문서 기준으로 커스텀 commands는 skills에 합쳐졌고, 기존 .claude/commands/*.md 파일도 계속 동작해요. 솔직히 /review-pr처럼 짧은 수동 실행 하나면 당장 안 옮겨도 돼요. 근데 예제 파일, 참고 문서, 도구 허용 범위, 자동 발동까지 붙을 순간 skill 쪽이 훨씬 덜 답답하더라고요.
# 둘 다 /review-pr 를 만들 수 있어요
.claude/commands/review-pr.md
.claude/skills/review-pr/SKILL.md
팀에 배포까지 고민한다면 이야기가 조금 달라져요. 데스크톱 앱 문서에는 플러그인 브라우저와 Anthropic 공식 marketplace가 보이거든요. 설치형 배포가 필요하면 Claude Code 플러그인 마켓플레이스: 설치부터 커스텀 제작까지처럼 plugin으로 감싸는 쪽까지 같이 보세요.
버그와 체크리스트
여기만 피해도 삽질 시간이 확 줄어요. 공식 문서, GitHub 이슈, 실사용 재현에서 반복된 문제를 실무 체크리스트로 묶었어요.
skill이 안 뜨면 매번 세션 탓부터 하고 있지 않나요?
| 문제 | 증상 | 지금 할 일 |
|---|---|---|
플랫 .md 파일 배치 |
skill 목록에 안 떠요 | 폴더 안 SKILL.md 구조로 바꿔요. #36888 기준 2026-04-18에도 열려 있어요 |
description 멀티라인 |
skill이 조용히 사라질 수 있어요 | 설명은 한 줄만 써요 |
disable-model-invocation 과거 버그 |
수동 호출이 꼬인 적 있어요 | 문서대로 쓰되 새 세션에서 /name을 꼭 한 번 테스트해요. #43875, #26251 둘 다 중복으로 닫혔어요 |
| skill 과다 설치 | 자동 발동이 서로 간섭해요 | 5~8개 선에서 정리하고 설명 길이를 줄여요 |
| 설명 예산 초과 | 키워드가 잘려 자동 발동이 약해져요 | 설명을 앞부분부터 압축하고, 필요하면 SLASH_COMMAND_TOOL_CHAR_BUDGET를 봐요 |
| 세션 시작 컨텍스트 부풀림 | 시작부터 무거워요 | 2.1.111 관련 제보가 남아 있어요. #49593 상태를 확인해요 |
SKILL.md 비대화 |
세션 후반부 품질이 떨어져요 | 공식 문서 권장대로 500줄 아래로 잡고 참고 자료는 분리해요 |
빠르게 체크하면 이 순서예요.
- skill 위치가 폴더형인지 먼저 보기
description이 한 줄인지 보기- 새 세션에서
what skills are available?로 노출 여부 보기 /skill-name수동 호출이 되는지 보기- 같은 계열 skill이 너무 많은지 보기
SKILL.md안에 넣지 말아도 될 참고 자료를 빼기
반복 실행 자체가 목적이면 skill보다 루틴이 더 맞을 때도 있어요. 밤마다 PR 검토나 배포 점검을 돌릴 생각이면 Claude Code 루틴 실전 가이드: PR 리뷰·배포 검증을 노트북 꺼도 돌리는 법 쪽으로 넘기는 게 덜 꼬여요.
자주 묻는 질문
Q1: Skills와 Commands 차이가 뭔가요? 지금도 .claude/commands/에 파일 넣으면 되나요?
A: 네, 기존 commands 파일은 계속 돌아가요. 근데 새로 만드는 작업이 반복 프롬프트, 지원 파일, 자동 발동까지 필요하면 skills로 가는 쪽이 더 자연스럽죠.
Q2: 내 skill이 자동 발동이 안 돼요. 뭘 먼저 봐야 하나요?
A: description 앞부분에 사용자가 실제로 칠 표현이 있는지부터 보세요. 그다음 새 세션에서 what skills are available?로 노출 여부를 보고, 그래도 들쭉날쭉하면 훅으로 한 번 더 밀어주는 식이 낫더라고요.
Q3: deploy나 commit 같은 위험한 skill이 혼자 실행될까 걱정돼요. 막을 수 있나요?
A: 네, disable-model-invocation: true를 붙이면 돼요. 그래도 과거엔 수동 호출이 꼬인 버그가 있었으니 새 세션에서 /skill-name 테스트까지 해두는 게 안전해요.
Q4: skill은 몇 개까지 두는 게 적당한가요?
A: 공식 문서에 딱 잘라 숫자가 박혀 있진 않아요. 근데 설명 예산과 간섭 문제 때문에 5개를 넘기기 시작하면 정리 필요성이 확 커져요. 8개 안팎부터는 비슷한 skill끼리 합치는 편이 덜 헷갈려요.
Q5: .claude/skills/에 그냥 .md 파일 하나 넣으면 안 되나요?
A: 지금은 권하지 않아요. 2026-04-18 기준 공개 이슈에서도 폴더형 SKILL.md만 안정적으로 잡힌다고 나와 있어요. 그냥 폴더 하나 만들고 SKILL.md를 넣는 쪽으로 가세요.
