Claude 스킬 만들기 — 반복 작업을 SKILL.md 하나로 (5분)

Claude에게 매번 같은 지시를 복붙하고 있다면, 그 지시는 이미 스킬 후보입니다. 그대로 두면 설명은 매번 반복되고, 말이 조금씩 달라져 결과도 들쭉날쭉해집니다.

 

Claude Code를 매일 쓰면서 블로그 자동화는 커스텀 명령으로 돌리고, 개인 스킬도 넣어 쓰는 입장에서 정리했습니다. 이 순서대로 가면 Claude 스킬 만들기부터 호출 테스트까지 5분 안에 끝납니다.

스킬이 뭐고, 예전 명령(commands)과 뭐가 다른가

스킬은 지시문을 담은 폴더이고, 최소 구성은 SKILL.md 하나입니다. 에이전트와의 차이는 스킬 vs 에이전트에서 다뤘으니, 여기선 Claude 스킬 만들기에만 집중합니다.

 

예전엔 .claude/commands/에 마크다운 파일을 넣어 /명령을 만들었는데, 지금은 커스텀 명령이 스킬로 통합됐습니다. commands/deploy.md와 skills/deploy/SKILL.md는 똑같이 /deploy로 동작합니다.

 

기존 commands 파일도 계속 동작합니다. 이 블로그 자동화(/blog-new 등)도 아직 commands 방식입니다. 다만 새로 만든다면 스킬이 낫습니다. 보조 파일을 함께 둘 수 있고, 관련 있을 때 Claude가 알아서 불러옵니다.

Claude 스킬 만들기 3단계

1단계 — 폴더 만들기

• 개인: ~/.claude/skills/<스킬이름>/ — 모든 프로젝트에서 사용
• 프로젝트: .claude/skills/<스킬이름>/ — 커밋하면 팀이 같이 씀

Windows에서 ~는 %USERPROFILE%(예: C:\Users\이름)입니다.

mkdir "$env:USERPROFILE\.claude\skills\crystalize"

폴더 이름이 곧 명령 이름이라 이 폴더는 /crystalize가 됩니다.

2단계 — SKILL.md 작성

맨 위는 ---로 감싼 frontmatter(파일 맨 위 설정 영역), 아래는 Claude가 따를 지시문입니다. 개인 스킬 폴더에 넣어 쓰는 crystalize의 실제 frontmatter입니다(본문 약 60줄은 요지만).

---
name: crystalize
description: 긴 프롬프트나 지침을 토큰 효율적으로 압축. "프롬프트 압축해줘", "토큰 줄여줘" 요청 시 사용.
argument-hint: [압축할 텍스트 또는 파일 경로]
---

# 압축 원칙
1. 의도 보존
2. 고해상도 토큰화 — 장황한 설명은 핵심 키워드로
3. 암묵지 활용 — LLM이 아는 건 신호만

여는 ---는 반드시 파일 첫 줄이어야 합니다. 아니면 파일 전체를 그냥 본문으로 읽습니다.

3단계 — 호출 테스트

저장하면 재시작 없이 바로 반영됩니다.

• 자동 호출: description과 맞는 요청("이 프롬프트 압축해줘")이면 Claude가 알아서 불러옵니다.
• 직접 실행: /crystalize 파일경로 — 본문에 $ARGUMENTS를 써두면 뒤의 인자가 그 자리에 들어갑니다.

목록에 떴는지는 /skills로 확인합니다.

자주 쓰는 frontmatter 필드

필드	하는 일	언제 쓰나
name	명령 이름 지정(폴더명 덮어씀)	폴더명과 다르게 부를 때
description	무엇을 하는지	항상(자동 호출 판단 기준)
when_to_use	언제 쓰는지 보충	상황 설명이 모자랄 때
disable-model-invocation	true면 /이름으로만 실행	배포·커밋·메시지 전송
argument-hint	자동완성 인자 힌트	인자를 받는 스킬
allowed-tools	승인 없이 쓸 도구	승인 창이 번거로울 때

allowed-tools는 Bash(git diff *)처럼 명령 단위로 좁게 엽니다. 넓게 열면 승인 창이 막던 실행까지 통과합니다.

description이 스킬의 절반이다

Claude 스킬 만들기에서 가장 공들일 곳은 본문보다 description입니다. 자동 호출 여부를 description으로 판단하기 때문입니다.

• ❌ 나쁜 예: "코드 작업용 유틸리티"
• ✅ 좋은 예: "커밋 안 된 git 변경 사항을 요약하고 위험한 패턴을 표시한다"

좋은 예는 하는 일이 동사로 드러납니다. 사용자가 실제로 할 말까지 넣으면 더 잘 불립니다. crystalize의 "프롬프트 압축해줘" 요청 시 사용이 그 패턴입니다. description과 when_to_use는 합쳐 1,536자에서 잘리니 핵심 용도를 맨 앞에 둡니다.

증상: /이름이 목록에 안 뜨거나 Claude가 스킬을 안 불러옴

원인: 여는 ---가 첫 줄이 아님(빈 줄·BOM 등 보이지 않는 문자), 또는 세션 도중 skills 폴더 자체를 새로 만듦

해결: ---를 첫 줄로 올리고 /reload-skills 실행 후 /skills로 확인

Q&A — 자주 보는 질문 4개

Q. 예전 .claude/commands 파일은 옮겨야 하나요?
아니요, 계속 동작합니다. 옮긴다면 deploy.md를 deploy/SKILL.md 구조로 바꿉니다.

Q. Claude가 제 스킬을 자동으로 안 불러요.
description을 구체적으로 고치고 실제로 할 말("~해줘")을 넣으세요.

Q. 배포 같은 건 자동 실행되면 곤란한데요?
disable-model-invocation: true를 넣으면 /이름으로 직접 실행할 때만 돌아갑니다.

Q. 스킬을 수정하면 재시작해야 하나요?
아니요. 세션 시작 때 없던 skills 폴더 자체를 새로 만든 경우만 /reload-skills가 필요합니다.

 

Claude 스킬 만들기는 폴더 하나, SKILL.md 하나, 잘 쓴 description 한 줄이 전부입니다. 같은 환경이면 위 순서대로 따라가도 무리 없습니다.

 

설치 환경: Windows 11, Claude Code (Claude Max)

관련 글

• Claude Code 업데이트, 지금 켜둘 것 6가지 (매주 쏟아지는 것 중)
• Claude Code 플러그인 만들기 — 스킬·훅·MCP를 하나로 묶어 배포하기
• Claude Code 활용법 정리 — 망치는 습관 3개와 살리는 습관 7개