Claude Code의 커스텀 스킬(SKILL.md)을 만드는 핸즈온 과정에서, description 필드의 역할을 올바르게 이해하지 못하면 기대한 대로 작동하지 않는다는 점을 발견했습니다. 슬래시 명령어 3가지 분류와 함께 정리합니다.
/clear → 빌트인 커맨드 (Claude Code 본체의 기능)
/code-review ★ → 번들 스킬 (Anthropic 공식 제공, 17개)
/pre-pr-check → 커스텀 스킬 (직접 작성)
/skills 명령어로는 현재 사용 가능한 스킬 목록을 확인할 수 있으며, Anthropic 공식 번들 스킬에는 ★ 표시가 붙습니다. 커스텀 스킬은 이 번들 스킬과 동일한 SKILL.md 형식으로 구현할 수 있으므로, 공식 스킬의 구현이 참고가 됩니다.
mkdir -p .claude/skills/pre-pr-check
touch .claude/skills/pre-pr-check/SKILL.md
폴더 이름 자체가 슬래시 명령어명이 됩니다. 특별한 빌드나 등록 작업은 필요하지 않으며, /reload-skills를 실행하거나 세션을 재시작하는 것만으로 유효해집니다.
# 나쁜 예: 무엇을 하는지만 작성함
description: PR의 체크를 실행한다
# 좋은 예: 언제 사용될지 명확하게
...
description은 사람을 위한 설명문이 아니라, Claude가 '이 스킬을 자동으로 호출해야 할 타이밍'을 판단하는 자료입니다. 영어로 Use when... 형식으로 구체적으로 작성할수록, 의도한 타이밍에서의 자동 제안 정확도가 높아집니다.
.claude/skills/ → 프로젝트에만 유효, git으로 관리하여 팀 공유 가능
~/.claude/skills/ → 모든 프로젝트에서 유효, 개인 설정 (공유 불가)
프로젝트 고유의 절차(배포처・테스트 명령어)는 프로젝트 레벨에, 어느 프로젝트에서든 사용할 범용적인 작업은 사용자 레벨에 배치합니다. 헷갈린다면 우선 프로젝트 레벨로 만들고 나중에 사용자 레벨로 이동하는 것이 팀 공유 관점에서 다루기 쉽다는 운영상의 팁도 있습니다.
.claude/skills/code-review/SKILL.md를 작성
→ Anthropic의 /code-review 번들 스킬보다 우선하여 호출됨
의도적으로 번들 스킬을 커스터마이징하고 싶을 때는 유효하지만, 실수로 덮어쓰는 경우도 있으므로 명명 시 주의가 필요합니다.
description 필드가 '언제 호출할지' 판단 자료라는 이해가, 커스텀 스킬을 의도대로 작동시키는 가장 중요한 포인트였습니다. CLAUDE.md는 상시 로드・SKILL.md는 호출 시에만 로드한다는 사용 구분 원칙 역시 컨텍스트 소비를 줄이는 데 있어 인지하고 있을 가치가 있습니다.
