claude skills 사용법 — SKILL.md 만들기와 폴더 위치 정리

클로드 코드 스킬(Claude Skills)은 SKILL.md 파일 하나로 만듭니다. ~/.claude/skills/<스킬이름>/SKILL.md에 저장하면 그 폴더 이름이 그대로 명령어가 되어 /스킬이름으로 부를 수 있고, 프론트매터의 description을 보고 클로드가 필요할 때 알아서 불러오기도 합니다. 매번 채팅에 똑같은 지시사항이나 체크리스트를 붙여넣고 있다면 그게 스킬로 만들 신호입니다. 이 글은 Claude Code v2.1.204 기준으로 폴더 위치, 프론트매터 필드, 인자 전달까지 정리합니다.

1. 5분이면 만드는 첫 스킬

커밋 안 한 변경사항을 요약해 주는 스킬을 만들어 보겠습니다. 폴더를 만들고 파일 하나만 쓰면 끝입니다.

mkdir -p ~/.claude/skills/summarize-changes

그 안에 SKILL.md를 만듭니다. --- 사이가 프론트매터(설정), 그 아래가 클로드가 따를 지시사항입니다.

---
description: 커밋하지 않은 변경사항을 요약하고 위험한 부분을 짚는다. 사용자가 "뭐 바뀌었지", "커밋 메시지 써줘", "내 diff 좀 봐줘" 라고 할 때 쓴다.
---

## 현재 변경사항

!`git diff HEAD`

## 지시

위 변경사항을 두세 줄로 요약하고, 빠진 예외 처리·하드코딩된 값·같이 고쳐야 할 테스트처럼
눈에 띄는 위험을 목록으로 적어라. diff가 비어 있으면 변경사항이 없다고 답해라.

이제 /summarize-changes로 직접 부르거나, 그냥 "뭐 바뀌었어?"라고 물어도 클로드가 description을 보고 알아서 이 스킬을 불러옵니다.

💡 !`git diff HEAD` 줄이 핵심입니다. 클로드가 파일을 읽기 전에 클로드 코드가 이 명령을 실행해 그 자리에 출력을 끼워 넣습니다. 그래서 클로드는 추측이 아니라 실제 작업 트리를 보고 답합니다.

2. 스킬을 어디에 두느냐가 적용 범위를 정한다

같은 SKILL.md라도 놓는 위치에 따라 누가 쓸 수 있는지가 달라집니다.

구분	경로	적용 범위
개인	~/.claude/skills/<이름>/SKILL.md	내 모든 프로젝트
프로젝트	.claude/skills/<이름>/SKILL.md	그 저장소에서만 (커밋하면 팀 공유)
플러그인	<plugin>/skills/<이름>/SKILL.md	플러그인이 켜진 곳

이름이 겹치면 개인 스킬이 프로젝트 스킬을 덮어씁니다. 그리고 어느 위치든 같은 이름이면 클로드 코드에 기본 내장된 스킬(예: /code-review)까지 대체합니다. 플러그인 스킬만 플러그인이름:스킬이름으로 이름 공간이 갈려서 충돌하지 않습니다.

폴더 구조는 이렇게 잡으면 됩니다. SKILL.md만 필수고 나머지는 필요할 때만 둡니다.

my-skill/
├── SKILL.md           # 본 지시사항 (필수)
├── template.md        # 클로드가 채울 템플릿
├── examples/
│   └── sample.md      # 기대하는 출력 예시
└── scripts/
    └── validate.sh    # 클로드가 실행할 스크립트

딸린 파일은 SKILL.md 본문에서 "이 파일에 뭐가 있고 언제 열어라"라고 링크해 두면 클로드가 필요할 때만 읽습니다. CLAUDE.md와 달리 스킬 본문은 쓰일 때만 불러오므로, 긴 참고 자료를 넣어도 평소 컨텍스트를 잡아먹지 않습니다.

3. 프론트매터 — 자주 쓰는 필드만

필드는 전부 선택 사항이고, description 하나만 제대로 써도 됩니다. 자주 쓰는 것만 추리면 이렇습니다.

필드	하는 일
description	뭘 하는 스킬이고 언제 쓰는지. 클로드가 자동 호출 여부를 이걸로 판단한다. 생략하면 본문 첫 문단을 쓴다.
when_to_use	호출 트리거가 될 만한 말투·요청 예시를 덧붙인다.
allowed-tools	이 스킬이 도는 턴 동안 허가를 안 묻고 쓸 도구. 다음 메시지를 보내면 해제된다.
disable-model-invocation	true면 클로드가 알아서 부르지 못하고 /이름으로만 실행된다. 위험한 작업에 쓴다.
argument-hint	자동완성에 보여 줄 인자 힌트. 예: [issue-number]
paths	글로브 패턴. 그 패턴에 맞는 파일을 다룰 때만 자동으로 불러온다.
context: fork	별도 서브에이전트 컨텍스트에서 돌린다. 긴 탐색 작업에 유용하다.
model / effort	이 스킬이 도는 동안 쓸 모델과 사고 강도. 설정에 저장되지 않고 그 턴에만 적용된다.

⚠️ description과 when_to_use를 합친 길이는 스킬 목록에서 1,536자에서 잘립니다. 컨텍스트를 아끼려는 제한이므로 핵심 사용 사례를 맨 앞에 쓰세요. 뒤에 몰아 쓰면 잘려서 클로드가 못 봅니다.

개인·프로젝트 스킬에서 name 필드는 목록에 표시할 이름일 뿐이고, 실제 명령어는 폴더 이름에서 나옵니다. .claude/skills/deploy-staging/SKILL.md는 /deploy-staging이 됩니다.

4. 인자 넘기기 — $ARGUMENTS

/스킬이름 인자로 부를 때 넘긴 값은 본문에서 치환됩니다. 자주 쓰는 것만 보면 이렇습니다.

표현	치환되는 값
$ARGUMENTS	넘긴 인자 전체
$0, $1	첫 번째·두 번째 인자 (0부터 셈)
${CLAUDE_SKILL_DIR}	그 SKILL.md가 있는 폴더 경로
${CLAUDE_PROJECT_DIR}	프로젝트 루트 경로

${CLAUDE_SKILL_DIR}는 본문과 allowed-tools 양쪽에서 치환됩니다. 그래서 같이 넣어 두면 스킬에 딸린 스크립트를 허가 창 없이 실행시킬 수 있습니다.

---
name: render-chart
description: CSV 파일로 차트를 그린다
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---

`${CLAUDE_SKILL_DIR}/scripts/render.sh <csv파일>` 을 실행해 차트를 그려라.

5. .claude/commands는 어떻게 되나

커스텀 커맨드는 스킬로 합쳐졌습니다. .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 둘 다 /deploy를 만들고 똑같이 동작합니다. 기존 commands/ 파일은 그대로 쓸 수 있으니 급히 옮길 필요는 없습니다. 다만 이름이 겹치면 스킬 쪽이 이깁니다. 딸린 파일을 두거나 호출 주체를 제어하고 싶어지면 그때 스킬로 옮기면 됩니다.

6. 어떤 일을 스킬로 만들면 좋나

후보를 고르는 기준은 간단합니다. 매번 똑같은 순서로 하는 여러 단계짜리 절차이고, 순서를 하나라도 빠뜨리면 결과가 틀어지는 일. 이런 게 스킬로 만들기 좋습니다. 반대로 한 번 물어보고 끝나는 일은 그냥 물어보는 게 낫습니다.

• 배포 전 점검 — 테스트·린트·빌드를 정해진 순서로 돌리고 실패 지점을 정리
• 릴리스 노트 작성 — 지난 태그 이후 커밋 로그를 훑어 팀이 쓰는 형식으로 정리
• API 한 벌 추가 — 컨트롤러·서비스·DTO·테스트를 프로젝트 규칙대로 같은 모양으로 생성
• 장애 대응 체크리스트 — 로그 확인 → 지표 확인 → 롤백 판단 순서를 고정

지금 채팅창에 반복해서 붙여넣고 있는 지시사항이 있다면, 그게 첫 스킬 후보입니다.

클로드를 개발에 붙여 쓰는 이야기가 궁금하시면 Claude MCP 서버 추천과 Claude 모델 비교(Opus·Sonnet·Haiku)도 같이 보시면 좋습니다. 스킬이 "무엇을 어떤 순서로 할지"를 정한다면, MCP는 "어떤 외부 도구에 손을 뻗을지"를 정하는 쪽입니다.

자주 묻는 질문 (FAQ)

Q. 스킬을 만들었는데 클로드가 안 불러옵니다.
대개 description 문제입니다. "무엇을 하는지"만 쓰고 "언제 쓰는지"를 안 쓴 경우가 많습니다. 사용자가 실제로 칠 법한 말("배포해줘", "뭐 바뀌었지")을 description이나 when_to_use에 넣어 주세요. 그래도 안 되면 /스킬이름으로 직접 부르면 됩니다.

Q. 팀원과 공유하려면요?
프로젝트 스킬(.claude/skills/)로 만들어 저장소에 커밋하면 됩니다. 클론한 사람은 별도 설정 없이 바로 씁니다. 개인 스킬(~/.claude/skills/)은 내 컴퓨터에만 있습니다.

Q. 스킬과 CLAUDE.md는 뭐가 다른가요?
CLAUDE.md는 항상 컨텍스트에 올라가는 사실·규칙이고, 스킬 본문은 쓰일 때만 올라가는 절차입니다. CLAUDE.md의 한 항목이 사실이 아니라 절차로 길어지고 있다면 그게 스킬로 뺄 때입니다.

Q. 다른 AI 도구에서도 쓸 수 있나요?
클로드 코드 스킬은 Agent Skills 오픈 표준을 따르며 여러 AI 도구에서 동작합니다. 다만 호출 주체 제어나 서브에이전트 실행 같은 건 클로드 코드가 표준에 더한 기능이라 도구마다 다를 수 있습니다.

마무리

정리하면 스킬은 SKILL.md 한 파일이고, 폴더 이름이 명령어가 되며, description이 자동 호출의 열쇠입니다. 거창하게 시작할 필요 없이 지금 채팅에 반복해서 붙여넣고 있는 지시사항 하나를 골라 열 줄짜리 SKILL.md로 옮겨 보세요. 쓰면서 부족한 부분을 채워 나가는 편이 처음부터 완벽하게 쓰려는 것보다 훨씬 빠릅니다. 필드가 자주 늘어나는 영역이니 세부 옵션은 공식 문서를 함께 확인하시길 권합니다.

---

📚 참고 출처 (2026년 7월 22일 확인 · Claude Code v2.1.204 기준)
· Claude Code 공식 문서 — Extend Claude with skills
· Agent Skills 오픈 표준