Claude Code Skills 작성법: 반복 작업을 명령 하나로 만드는 실전 가이드

핵심 요약: Skill은 "특정 작업의 매뉴얼"을 파일로 만들어두고 필요할 때 로드시키는 기능입니다. 구조는 단순합니다 — 스킬 폴더 안에 SKILL.md 하나(frontmatter에 name·description, 본문에 작업 절차), 필요하면 참고 파일·스크립트를 동봉. CLAUDE.md와의 차이가 핵심인데, CLAUDE.md는 항상 읽히는 상식, Skill은 해당 작업 때만 로드되는 전문 지식입니다. 릴리스 절차, 보고서 형식, 마이그레이션 순서처럼 "가끔 하지만 순서가 정해진 일"이 스킬화 1순위입니다.

이 글에서 다루는 내용: Skill의 구조, CLAUDE.md·슬래시 명령과의 구분, 잘 쓰이는 스킬의 조건, 실전 예시 2개.

구조: SKILL.md 하나면 시작

스킬 디렉터리(개인 전역 또는 프로젝트의 .claude/skills/) 아래 폴더를 만들고 SKILL.md를 둡니다:

---
name: release-check
description: 배포 전 점검 절차. 릴리스, 배포 준비, 버전 태깅 작업 시 사용
---

# 배포 전 점검

1. 테스트 전체 실행 — 실패가 있으면 여기서 중단하고 보고
2. CHANGELOG.md 갱신 (커밋 로그에서 사용자 영향 변경만 추림)
3. 버전 범프: pyproject.toml과 package.json 동기화 확인
4. 마이그레이션 파일 유무 확인, 있으면 배포 노트에 명시
5. 태그 생성은 사람에게 확인받은 뒤에만

동작 원리가 중요합니다: Claude는 평소에 스킬의 description만 보고 있다가, 관련 작업이 오면 그때 본문을 로드합니다. 그래서 description이 스킬의 절반입니다 — "언제 이 스킬을 써야 하는지"가 트리거 단어까지 포함해 명확해야 합니다.

CLAUDE.md·슬래시 명령과 뭐가 다른가

수단	로드 시점	담을 것
CLAUDE.md	항상	프로젝트 상식 (구조, 관례, 금기)
Skill	관련 작업 때만	특정 작업의 절차·전문 지식
슬래시 명령	사용자가 호출	자주 쓰는 프롬프트의 단축키

구분 기준은 빈도와 분량입니다. 매번 필요하면 CLAUDE.md(작성법), 가끔 필요하고 내용이 길면 Skill, 짧은 지시를 반복 호출하면 슬래시 명령(총정리). 긴 절차를 CLAUDE.md에 넣으면 모든 대화가 그 토큰을 지고 다니므로, "가끔+길다"는 반드시 스킬로 빼는 게 이득입니다.

잘 쓰이는 스킬의 조건 3가지

① 트리거가 분명한 description. "배포 관련 작업"보다 "릴리스, 배포 준비, 버전 태깅 시 사용"이 잘 잡힙니다. ② 절차는 번호로, 중단 조건은 명시. "테스트 실패 시 중단하고 보고"처럼 실패 분기를 적어두면 에이전트가 실패 상태로 폭주하지 않습니다. ③ 검증 가능한 완료 기준. "잘 정리"가 아니라 "CHANGELOG에 항목 추가, 버전 두 파일 일치"처럼 확인 가능한 상태로 끝을 정의하세요. 좋은 명세의 원칙(명세 글) 그대로입니다.

실전 예시: 제가 쓰는 스킬 둘

django-migration: "모델 변경 시 마이그레이션 생성→로컬 적용→롤백 테스트→충돌 확인" 절차와 우리 팀의 마이그레이션 명명 규칙을 담았습니다. 이전에는 매번 지시문에 절차를 다시 썼는데, 지금은 "User 모델에 필드 추가하고 마이그레이션까지"라고만 하면 절차대로 갑니다. weekly-report: 주간 작업 요약의 형식(섹션 구성, 커밋 로그에서 뽑는 기준)을 담아, 금요일마다 같은 품질의 초안이 나옵니다. 공통점은 둘 다 "내가 매번 다시 설명하던 것"이라는 점 — 스킬 후보를 찾는 가장 좋은 방법은 자기 지시문에서 반복되는 문단을 찾는 것입니다.

자주 묻는 질문 (FAQ)

Q. 스킬이 로드가 안 되는 것 같아요.

A. description을 점검하세요. 사용자의 지시에 나올 법한 단어(한국어 작업이라면 한국어 트리거 포함)가 description에 있어야 매칭이 잘 됩니다. 폴더 위치와 SKILL.md 파일명도 확인 대상입니다.

Q. 스킬 안에서 스크립트도 실행할 수 있나요?

A. 네, 스킬 폴더에 스크립트를 동봉하고 본문에서 실행을 지시하는 패턴이 일반적입니다. 절차 중 기계적인 부분은 스크립트로, 판단이 필요한 부분만 지시문으로 두면 안정적입니다.

Q. 팀과 공유하려면?

A. 프로젝트 저장소의 .claude/skills/에 커밋하면 팀원 모두가 같은 스킬을 씁니다. 팀 절차의 표준화 도구로서 Rules(.mdc)의 Claude Code판이라고 봐도 됩니다.

한눈에 보는 요약

가끔 하지만 순서가 정해진 일 → SKILL.md로. description에 트리거를, 본문에 번호 절차와 중단 조건을, 끝에 완료 기준을. 후보는 "내가 반복해서 설명하는 문단"에서 찾으세요.

함께 보면 좋은 글

Claude Code 서브에이전트·훅·스킬 활용법
CLAUDE.md 작성법
AI에게 좋은 작업 명세 쓰는 법

참고 자료

Claude Code 공식 문서 (Skills)