커스텀 커맨드 입문 — 슬래시 커맨드 만들기

커스텀 커맨드는 자주 쓰는 프롬프트를 Markdown 파일로 저장해 두고 /커맨드명 으로 불러 쓰는 Claude Code 기능입니다. 매번 같은 지시를 타이핑하는 수고가 사라지고, 팀에서 공유하면 지시 작성법이 사람마다 달라지는 문제도 함께 해결됩니다.

이 글은 커스텀 커맨드 코스의 첫 번째 글입니다. 기본 개념과 배치 장소, 첫 커맨드를 만들어 확인하는 절차까지 다루고, 프론트매터로 동작을 제어하는 방법은 커스텀 커맨드 프론트매터 설정에서, 인수를 받는 방법은 $ARGUMENTS 로 인수 받기에서 이어집니다.

핵심 요약

• 커스텀 커맨드는 자주 쓰는 프롬프트를 /커맨드명 으로 호출하는 기능입니다.
• 프로젝트용은 .claude/commands/, 개인용은 ~/.claude/commands/ 에 둡니다.
• 파일명이 그대로 커맨드명이 됩니다 (suggest-commit.md → /suggest-commit).
• Markdown 파일에 프롬프트를 쓰기만 하면 작성이 끝납니다.
• 커맨드를 추가·수정한 뒤에는 /reload-skills 로 반영합니다.

커스텀 커맨드란 무엇인가

커스텀 커맨드는 Claude Code에서 반복해 쓰는 프롬프트를 커맨드 하나로 묶는 기능입니다.

예를 들어 "main 브랜치와의 차분을 확인하고, 커밋 메시지를 제안해 주세요"라는 프롬프트를 매번 입력하는 대신 /suggest-commit 이라고만 치면 같은 지시가 실행됩니다. 입력 수고가 줄어드는 것은 물론, 프롬프트 내용이 통일되니 결과 품질이 들쭉날쭉해지는 것도 막을 수 있습니다. 팀에서 커맨드를 공유하면 그 효과가 팀 전체로 번집니다.

다만 커스텀 커맨드는 어디까지나 프롬프트의 숏컷이라는 점은 기억해 두는 편이 좋습니다. 복잡한 로직이나 조건 분기가 필요하다면 프론트매터 설정이나 서브에이전트 연동을 검토해야 합니다.

보충: 커스텀 슬래시 커맨드는 스킬과 같은 취급으로 통합됐습니다. 구 형식(.claude/commands/)도 계속 지원되므로 기존 커맨드는 그대로 쓸 수 있습니다. 둘의 역할 차이는 슬래시 명령어와 Skills에서 정리했습니다.

커맨드 파일은 어디에 두나

배치 장소는 두 곳입니다. 용도에 맞게 나눠 두면 관리가 수월합니다.

프로젝트 커맨드 — .claude/commands/

프로젝트 루트에 .claude/commands/ 디렉터리를 만들고 커맨드 파일을 둡니다.

project/
├── .claude/
│   └── commands/
│       └── suggest-commit.md
└── src/

프로젝트 커맨드의 특징은 세 가지입니다.

• 그 프로젝트에서만 사용할 수 있습니다.
• Git으로 관리되므로 팀과 공유할 수 있습니다.
• 프로젝트 고유의 워크플로를 담기에 알맞습니다.

"전원이 같은 절차로 리뷰했으면 좋겠다" 같은 팀 개발 장면에 잘 맞습니다.

개인 커맨드 — ~/.claude/commands/

홈 디렉터리의 ~/.claude/commands/ 에 두면 모든 프로젝트에서 쓸 수 있는 개인 커맨드가 됩니다.

~/.claude/
└── commands/
    ├── daily-report.md
    └── my-review.md

"어느 프로젝트에서든 쓰고 싶다"는 커맨드, 자기만의 작업 습관을 효율화하는 커맨드는 이쪽에 둡니다.

어느 쪽을 써야 하나

팀과 공유할 커맨드는 프로젝트 커맨드, 자기만 쓸 커맨드는 개인 커맨드로 나누는 것이 가장 단순합니다. 같은 이름의 커맨드가 양쪽에 있으면 개인 커맨드가 우선합니다. 이 규칙을 이용하면 팀 공유본을 유지하면서 자기 것만 살짝 바꿔 쓰는 것도 가능합니다.

첫 커맨드를 만드는 세 단계

작성 절차는 디렉터리 만들기, 파일 만들기, 확인하기 세 단계입니다. 실습용으로 ~/Desktop/command-test 디렉터리를 만들어 이동했다고 가정합니다.

mkdir -p ~/Desktop/command-test
cd ~/Desktop/command-test

1. 디렉터리 만들기

# 프로젝트 커맨드의 경우
mkdir -p .claude/commands

# 개인 커맨드의 경우
mkdir -p ~/.claude/commands

2. Markdown 파일 만들기

커맨드 내용을 담은 Markdown 파일을 만듭니다. 아래는 echo 로 만드는 예지만, 편집기로 직접 써도 됩니다.

echo "main 브랜치와의 차분을 확인하고, 적절한 커밋 메시지를 제안해 주세요." > .claude/commands/suggest-commit.md

이것으로 /suggest-commit 커맨드가 생겼습니다. 파일 안에 있는 것은 프롬프트 문장 한 줄뿐입니다.

3. 커맨드가 인식되는지 확인하기

Claude Code를 실행하고 / 를 입력하면 사용 가능한 커맨드가 후보로 뜹니다. 그 안에 /suggest-commit 이 보이면 성공입니다.

> /
  /suggest-commit     main 브랜치와의 차분을 확인하고, 적절한 커밋 메시지를 제안해
                      주세요. (project)

/help 를 실행하면 General 탭이 먼저 열리는데, 오른쪽 방향키를 두 번 눌러 Custom commands 탭으로 가면 커스텀 커맨드만 모아 볼 수 있습니다.

> /help
 General   Commands   Custom commands   (tab to cycle)
 Browse custom commands:
 ❯ /suggest-commit     main 브랜치와의 차분을 확인하고, 적절한 커밋 메시지를 제안해 주세요. (project)

후보 목록에 표시되는 설명문은 프롬프트 본문의 첫 줄입니다. 이 설명을 따로 지정하는 description 항목은 커스텀 커맨드 프론트매터 설정에서 다룹니다.

서브디렉터리로 커맨드를 묶는 방법

커맨드 파일은 .claude/commands/ 바로 아래가 아니라 서브디렉터리에 둘 수도 있습니다.

mkdir .claude/commands/test
echo "hello 라고만 출력해 주세요" > .claude/commands/test/hello.md

.claude/commands
├── suggest-commit.md
└── test
    └── hello.md

이렇게 두면 /test:hello 라는 이름으로 호출합니다. 디렉터리명이 test: 접두사로 붙기 때문에 후보 목록에서도 묶여서 보입니다.

> /test:hello
  /test:hello     hello 라고만 출력해 주세요 (project)

Git 관련 커맨드는 git/ 아래, 테스트 관련은 test/ 아래처럼 관련 커맨드를 묶어 두면 수가 늘어도 찾기 쉽습니다.

추가한 커맨드는 언제 반영되나

새 커맨드를 추가하거나 기존 커맨드를 고쳤다면 /reload-skills 를 실행합니다. 스킬·커맨드 디렉터리를 다시 스캔하므로 세션을 재시작하지 않아도 바로 반영됩니다.

/reload-skills

/reload-skills 를 비롯한 Claude Code 기본 커맨드는 기본 조작과 명령어에 정리돼 있습니다.

정리

• 커스텀 커맨드는 Markdown 파일 하나로 만드는 프롬프트 숏컷이며, 파일명이 곧 /커맨드명 입니다.
• 팀 공유용은 .claude/commands/, 개인용은 ~/.claude/commands/ 에 두고, 이름이 겹치면 개인 커맨드가 우선합니다.
• 서브디렉터리에 두면 /디렉터리:커맨드 형태로 묶여 관리하기 쉽습니다.
• 추가·수정 후에는 /reload-skills 로 반영합니다.
• 다음 단계로 프론트매터 설정으로 동작을 제어하고, $ARGUMENTS와 위치 인수 $0/$1/$2로 인수를 받아 보세요. 참조 파일과 스크립트까지 묶고 싶어지면 SKILL.md 작성법이 그다음입니다.