같은 프롬프트를 매일 반복해서 붙여 넣고 있다면 그 프롬프트는 이미 자동화 대상이다. Claude Code는 반복 프롬프트를 슬래시 명령어 한 줄로 줄여 주는 커스텀 명령어 기능을 제공한다. 마크다운 파일 하나만 만들면 끝난다. 이 글에서는 커스텀 명령어의 기본 구조, 프로젝트와 사용자 단위의 분리, 네임스페이스, 동적 인자, 프론트매터, 그리고 최근 통합된 Agent Skills와의 관계까지 정리한다
커스텀 명령어의 기본 구조
Claude Code에는 /init, /help 같은 기본 슬래시 명령어가 포함되어 있다. 사용자가 직접 정의하는 슬래시 명령어가 커스텀 명령어다. 자주 쓰는 프롬프트를 마크다운 파일로 저장해 두면 파일명과 동일한 슬래시 명령어로 즉시 호출할 수 있다
프로젝트 루트에 다음 경로로 파일을 만든다
.claude/commands/commit.md
파일 내용은 그대로 프롬프트가 된다
파일 내용은 그대로 프롬프트가 된다
Claude Code를 재실행한 뒤 /commit을 입력하면 위 프롬프트가 그대로 전달되어 커밋이 자동으로 생성된다
프로젝트 명령어와 사용자 명령어의 차이
커스텀 명령어는 저장 위치에 따라 적용 범위가 달라진다
| 종류 | 위치 | 적용 범위 | Git 공유 |
|---|---|---|---|
| 프로젝트 명령어 | <프로젝트 루트>/.claude/commands/ | 해당 프로젝트만 | 가능 (팀 공유) |
| 사용자 명령어 | ~/.claude/commands/ | 모든 프로젝트 | 불가 (개인 한정) |
팀이 공유해야 할 워크플로우는 프로젝트 명령어로 두고, 개인이 모든 프로젝트에서 쓰는 단축은 사용자 명령어로 분리한다. 이 분리만 지켜도 팀원 환경 오염을 막을 수 있다
네임스페이스로 명령어를 그룹화한다
명령어가 늘어나면 충돌과 혼란이 생긴다. commands 디렉터리 하위에 폴더를 만들면 폴더 이름이 네임스페이스가 된다
.claude/commands/
└── git/
└── commit.md
이렇게 두면 /git:commit 형태로 호출된다. Git, 테스트, 배포 같은 카테고리별로 명령어를 묶을 때 쓴다. 카테고리가 명령어 이름 앞에 붙으므로 자동완성에서도 그룹별로 정렬되어 보인다
$ARGUMENTS로 동적 값을 전달한다
같은 명령어에 매번 다른 입력을 넘기고 싶다면 $ARGUMENTS 키워드를 쓴다. 명령어 뒤에 입력한 모든 텍스트가 이 자리로 치환된다
커밋 메시지: $ARGUMENTS 현재 변경사항을 분석하고 커밋을 생성해주세요.
호출 예시
/git:commit 로그인 기능 완료
치환 결과
커밋 메시지: 로그인 기능 완료 현재 변경사항을 분석하고 커밋을 생성해주세요.
인자를 위치별로 따로 받고 싶다면 $1, $2, $3 같은 위치 변수를 쓴다. 공백으로 구분된 값이 순서대로 매핑된다
PR 번호: $1 우선순위: $2 리뷰어: $3
호출 예시
/review-pr 456 high alice
$1은 456, $2는 high, $3은 alice로 치환된다. 모든 값을 한꺼번에 받을 때는 $ARGUMENTS, 위치별로 분해할 때는 $숫자를 쓰는 식으로 용도를 구분한다
프론트매터로 명령어 메타데이터를 정의한다
마크다운 상단의 YAML 프론트매터로 명령어의 동작 범위와 설명을 지정한다
--- description: git commit 생성 allowed-tools: [Bash] argument-hint: message model: claude-sonnet-4 --- 커밋 메시지: $ARGUMENTS 현재 변경사항을 분석하고 커밋을 생성해주세요.
각 항목의 역할은 다음과 같다
description: 슬래시 메뉴에 표시되는 한 줄 설명allowed-tools: 명령어 실행 중 허용할 도구 목록 (예:Bash,Edit)argument-hint: 인자에 대한 힌트 표시model: 이 명령어 실행 시 사용할 모델 지정
allowed-tools는 보안과 직결된다. Bash가 필요 없는 명령어에 Bash를 열어 두면 의도하지 않은 실행이 발생할 수 있다. 명령어가 실제로 쓰는 도구만 명시하는 것이 원칙이다
컨벤셔널 커밋을 자동화하는 스마트 명령어
커스텀 명령어의 진가는 단순 치환이 아니라 워크플로우 자동화에서 드러난다. 컨벤셔널 커밋(Conventional Commits)은 Google, Microsoft 등에서 채택한 커밋 메시지 표준이며, 다음과 같은 타입을 사용한다
| 타입 | 의미 |
|---|---|
| feat | 새로운 기능 추가 |
| fix | 버그 수정 |
| docs | 문서 변경 |
| refactor | 리팩터링 |
| remove | 코드 또는 파일 삭제 |
| chore | 빌드·설정 등 잡무 |
이 규칙을 반영한 커밋 명령어를 만들면 다음 흐름이 자동화된다
변경사항 감지 ↓ 스테이지된 파일이 있으면 그것만 우선 처리 ↓ 변경 파일 분석 → 필요 시 분할 커밋 제안 ↓ 타입(feat/fix/docs 등) + 이모지 + 메시지 생성 ↓ 커밋 실행
결과 커밋 목록은 타입별로 자연스럽게 분류되어 이력 관리가 쉬워진다. 커스텀 명령어 하나로 팀 전원이 같은 커밋 컨벤션을 따르게 만들 수 있다는 뜻이다
스킬(Agent Skills) 통합으로 무엇이 바뀌었는가
최근 Claude Code의 커스텀 명령어는 스킬(Agent Skills)과 통합되었다. 호출 방식과 동작은 같지만 파일 구조에 변화가 생겼다.
| 구분 | 기존 (커스텀 명령어) | 신규 (스킬) |
|---|---|---|
| 단위 | 마크다운 파일 1개 | 폴더 1개 |
| 경로 | .claude/commands/git-commit.md | .claude/skills/git-commit/SKILL.md |
| 호출 | /git-commit | /git-commit |
| 추가 자원 | 단일 파일에 포함 | 폴더에 자유롭게 동봉 가능 |
핵심은 두 가지다
- 첫째, 기존 커스텀 명령어 방식은 그대로 동작한다. 마이그레이션 부담 없이 기존 파일을 계속 사용할 수 있다
- 둘째, 스킬 방식은 명령어 하나에 여러 보조 파일을 폴더로 묶을 수 있다. 예시 코드, 참고 템플릿, 외부 스크립트가 함께 필요한 복잡한 명령어라면 스킬 형태가 더 깔끔하다
선택 기준은 단순하다. 단일 프롬프트 한 장이면 충분한 경우 커스텀 명령어, 보조 파일을 동봉해야 하는 경우 스킬을 쓴다
메모리와 명령어를 함께 관리한다
커스텀 명령어는 한 번 만들고 끝나는 산출물이 아니다. 프로젝트를 진행하면서 같은 프롬프트를 두세 번 반복하고 있다면 그 즉시 명령어로 승격시킨다
역할 분담은 다음과 같이 잡는다
- Claude가 항상 기억해야 할 규칙:
CLAUDE.md(메모리 파일) - 자주 반복 호출하는 프롬프트:
.claude/commands/또는.claude/skills/ - Claude가 틀린 답을 반복할 때: 위 두 파일을 갱신해 가며 정확도를 끌어올림
이 세 축을 함께 운영해야 컨텍스트 비용을 줄이면서 결과 품질을 끌어올릴 수 있다
정리
정리하면 커스텀 명령어는 자주 쓰는 프롬프트를 슬래시 한 줄로 압축하는 도구이고, 스킬은 그 명령어가 폴더 단위로 진화한 형태다. 프롬프트 반복이 보이는 순간 마크다운 한 장으로 옮기는 것이 가장 빠른 생산성 개선이다