Claude Code 스킬 파일 구조와 베스트 프랙티스 문서 작성법

Claude Code로 작업하다 보면 같은 지시를 반복하게 되는 순간이 있어요. "PR 올릴 때 항상 테스트 먼저 돌리고, 커밋 메시지는 이 형식으로" 같은 걸 매번 프롬프트에 붙여 넣는 거죠. 스킬은 이 반복을 없애는 방법이에요. 주의할 점 하나 — 스킬은 단일 .md 파일이 아니라 디렉토리 + 그 안의 SKILL.md 구조예요. 이 규칙을 한 번만 잡아두면 그 다음은 쉬워요.

준비물

• Claude Code 설치된 환경
• 터미널 접근 가능한 프로젝트 루트
• 에디터 (VS Code, Cursor 등)

스텝

1. 스킬 디렉토리 만들기

스킬 하나당 하나의 디렉토리예요. commit이라는 스킬을 만든다면 디렉토리 이름이 바로 스킬 이름이 돼요. 프로젝트에만 적용하려면 프로젝트 루트의 .claude/skills/ 아래, 개인 전역으로 쓰려면 홈 디렉토리의 ~/.claude/skills/ 아래에 만들어요.

# 프로젝트 스킬 (git에 커밋해서 팀과 공유)
mkdir -p .claude/skills/commit

# 개인 스킬 (모든 프로젝트에서 사용)
mkdir -p ~/.claude/skills/commit

2. SKILL.md 파일 작성

디렉토리 안에 반드시 파일명이 SKILL.md여야 해요. 이름을 commit.md로 바꾸면 인식 안 돼요. 파일은 두 부분으로 나뉘어요. 위쪽은 YAML frontmatter, 아래쪽은 Claude가 따라야 할 지시사항이에요.

---
name: commit
description: Stages and writes a conventional commit message. Use when the user says "커밋해줘" or after finishing a feature.
---

스테이징 안 된 변경사항이 있으면 git add . 실행.

커밋 메시지 형식:
- feat: 새 기능
- fix: 버그 수정
- refactor: 동작 변경 없는 리팩토링

제목은 50자 이내, 한국어. 본문은 왜 바꿨는지 2-3줄로.

description 필드가 핵심이에요. 여기 적힌 문장을 보고 Claude가 "지금 이 스킬을 쓸 타이밍인지"를 판단해요. "언제 써야 하는지"를 구체적으로 적을수록 자동 호출이 잘 맞아요. name은 생략하면 디렉토리 이름을 그대로 써요.

3. 세션에서 확인

설정 파일을 건드린 게 아니기 때문에 Claude Code를 재시작할 필요는 없어요. 이미 열어둔 세션에서도 .claude/skills/ 아래 파일 변경은 실시간으로 감지돼요. 커맨드 프롬프트에서 / 누르면 방금 만든 스킬이 목록에 떠요.

/commit

직접 입력하면 즉시 실행돼요. 아니면 description에 적어둔 트리거 문구("커밋해줘" 같은)를 자연어로 치면 Claude가 알아서 스킬을 불러요.

확인 방법

/ 치고 스킬 이름이 안 보인다면 구조를 다시 살펴봐요. 파일명이 정확히 SKILL.md인지, 디렉토리 이름에 공백이나 대문자가 없는지 (소문자·하이픈·숫자만 허용, 최대 64자).

응용

수동 실행 전용 스킬로 만들기

배포·커밋처럼 Claude가 혼자 판단해서 돌리면 안 되는 스킬은 자동 호출을 막아둬요. disable-model-invocation: true를 frontmatter에 추가하면 /커맨드로 호출할 때만 실행돼요.

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

특정 툴만 자동 허가

allowed-tools에 적어둔 툴은 스킬이 활성화된 동안 권한 프롬프트 없이 바로 실행돼요. 반복 작업에서 매번 Enter 눌러주는 귀찮음을 줄여줘요.

---
name: commit
description: ...
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

보조 파일 추가

SKILL.md만 필수고 같은 디렉토리에 다른 파일을 같이 둘 수 있어요. 긴 레퍼런스 문서·템플릿·실행 스크립트 같은 건 분리해두는 게 좋아요.

.claude/skills/commit/
├── SKILL.md            # 필수
├── reference.md        # SKILL.md에서 참조
└── scripts/
    └── pre-check.sh

SKILL.md에서 다른 파일을 명시적으로 참조하면 Claude가 필요할 때만 불러 읽어요. 전부 한번에 컨텍스트에 올라오지 않아서 큰 레퍼런스도 부담이 없어요.

트러블슈팅

스킬이 호출되지 않으면 description이 너무 뻔하거나 짧은 경우가 많아요. Claude에게 "언제 이 스킬을 써야 하는지"를 트리거 문구와 함께 적어주면 매칭이 개선돼요. 반대로 너무 자주 호출되면 disable-model-invocation: true를 추가해서 수동 전용으로 돌려요.

스킬 파일을 처음 만들 때 자주 틀리는 부분은 구조예요. 디렉토리를 건너뛰고 .claude/skills/commit.md처럼 바로 파일을 두면 인식 안 돼요. 항상 <스킬명>/SKILL.md 두 단계인지 확인해요.

한 번 만들어두면 같은 지시를 다시 타이핑할 일이 없어져요. 반복 패턴이 보이는 순간 스킬로 옮기는 습관이 하네스 품질을 올리는 가장 빠른 길이에요.