Claude Code 슬래시 커맨드: 커스텀 커맨드를 A부터 Z까지 만들기 (2026)

- 이 가이드는 code.claude.com/docs/skills의 공식 문서(2026/08/20 확인)를 따라요. 예전 slash-commands 페이지는 지금 이곳으로 리디렉션되고, 내장 커맨드 목록은 code.claude.com/docs/commands(「Slash」가 빠지고 「Commands」로)로 옮겨졌어요. Claude Code 문서는 갱신이 빨라서 일부 필드는 최신 빌드(Claude Code v2.1.x 이상)가 필요해요.

Claude Code에서 슬래시 커맨드란? (내장 vs 커스텀)

Claude Code에서 슬래시 커맨드는 /로 시작하고, 채팅 세션 안에서 바로 입력해 무언가를 빠르게 실행하는 커맨드예요. Anthropic의 공식 용어집은 이제 이것을 「Command」라고 부르지만(제품 표기에서 「Slash」를 뺐어요), 이 가이드는 사람들이 여전히 이 단어로 검색하기 때문에 제목과 본문에서 검색어인 「slash command(슬래시 커맨드)」를 계속 써요. 종류는 두 가지이고, 헷갈리기 쉬우니 주의해요.

내장 커맨드는 Anthropic이 Claude Code에 기본 제공하며, 따로 설치할 필요가 없어요. 거의 매일 손이 가는 것 몇 가지를 소개할게요.

• /help - 사용 가능한 모든 커맨드를 목록으로 보여줘요
• /clear - 대화 기록을 지우고 깨끗한 컨텍스트로 시작해요
• /compact - 대화를 압축해 컨텍스트를 아껴요
• /init - 프로젝트용 CLAUDE.md 파일을 생성해요
• /model - 사용 중인 모델을 전환해요
• /status - 세션, 계정, 컨텍스트 상태를 확인해요

커스텀 커맨드는 자주 쓰는 프롬프트를 키 한 번으로 묶기 위해 직접 만드는 것이에요. 쉽게 말해, 커스텀 슬래시 커맨드는 .claude/commands/ 안의 Markdown 파일이고, 파일 이름이 커맨드 이름, 파일 본문이 호출했을 때 Claude가 실행하는 프롬프트예요.「이 체크리스트에 맞춰 현재 diff를 리뷰해줘…」를 매번 붙여넣는 대신, 한 번 저장해 두고 /review만 입력하면 돼요.

좋은 점은, 커스텀 커맨드가 내장 커맨드와 같은 메뉴에 나온다는 거예요. /를 입력하면 메뉴가 뜨면서 내장 커맨드와 여러분의 커맨드가 모두 후보로 떠요. .claude/commands/ 폴더를 저장소에 커밋하면 팀 전체가 같은 커맨드 세트를 공유할 수 있어요. 바로 이 점이 커스텀 커맨드가 「복붙 프롬프트」를 크게 앞서는 이유예요.

그럼 왜 매번 프롬프트를 붙여넣지 않을까요? 현실적인 이유가 세 가지예요. 자주 쓰는 프롬프트는 보통 길어서 기억에 의존해 입력하면 한 줄을 빠뜨리게 돼요. 팀원마다 조금씩 다르게 써서 결과가 들쭉날쭉해요. 그리고 프롬프트를 개선해도 그 개선을 나머지 팀원에게 반영할 방법이 없어요. 커맨드 파일로 만들면 이 세 가지가 모두 해결돼요. 프롬프트는 한 곳에 모이고, 모두가 같은 커맨드를 호출하며, 파일을 수정하면 모두에게 반영돼요. 다시 말해, 커스텀 커맨드는 「개인의 요령」을 코드처럼 버전 관리할 수 있는 「공유 도구」로 바꿔줘요.

첫 커스텀 슬래시 커맨드 만들기 (.claude/commands)

Claude에게 코드 변경을 리뷰시키는 /review 커맨드를 만들어 볼게요. 세 단계이고, 모두 복붙해서 바로 쓸 수 있어요.

1단계 - 커맨드 폴더 만들기. 프로젝트 루트에서 실행해요.

mkdir -p .claude/commands

Windows PowerShell에는 mkdir -p가 없으니 다음을 써요.

New-Item -ItemType Directory -Force .claude/commands

2단계 - 그 폴더 안에 review.md 만들기. 파일 이름(.md를 뺀 부분)이 커맨드 이름이에요. 파일 본문이 프롬프트예요.

You are a strict reviewer. Review the current code changes.

Focus on:
- Logic bugs and unhandled edge cases
- Security holes (unvalidated input, leaked secrets)
- Naming, clarity, and duplicated code

For each issue: give the file + line, the severity,
and a concrete fix. No vague praise.

3단계 - 커맨드 실행하기. Claude Code 세션 안에서 실행해요.

/review

Claude는 파일 내용을 프롬프트로 읽어 바로 실행해요. 끝이에요. 코드 한 줄 쓰지 않고 첫 커스텀 커맨드를 만들었어요.

팁: 파일을 방금 만들었는데 / 메뉴에 커맨드가 아직 안 보이면, 끝부분의 「자주 겪는 문제」 섹션으로 가 보세요. 보통은 폴더를 잘못 골랐거나 세션 재시작이 필요한 것뿐이에요.

커맨드에 인자 넘기기 ($ARGUMENTS, $1, 이름 있는 인자)

딱딱한 커맨드는 잘 재사용되지 않아요. 진짜 힘은 인자에서 나와요. 커맨드 이름 뒤에 입력한 텍스트가 프롬프트에 끼워 넣어져요.

전부 가져오기 - $ARGUMENTS. 이 변수는 커맨드 이름 뒤의 텍스트를 전부 담아요. .claude/commands/fix-issue.md를 만들어요.

Fix GitHub issue #$ARGUMENTS. Read the issue description,
find the root cause in the code, then write a fix with tests.

/fix-issue 123을 입력하면 $ARGUMENTS는 123이 돼요. /fix-issue 123 security first를 입력하면 $ARGUMENTS는 문자열 전체인 123 security first가 돼요.

위치 인자 - $1, $2… 각 인자를 따로 다뤄야 할 때는 위치 변수를 써요. 예를 들어 .claude/commands/rename.md예요.

Rename the variable `$1` to `$2` across every open file,
keeping the logic intact and updating all references.

/rename oldName newName을 입력하면 $1은 oldName, $2는 newName이 돼요. 여러 단어로 된 인자는 따옴표로 감싸요: /rename "user id" "customer id".

이름 있는 인자 - arguments 프런트매터. $1/$2 대신 의미 있는 이름을 쓰고 싶다면, 프런트매터에서 선언하고(다음 섹션 참고) 이름으로 참조해요. arguments: [from, to]로 선언하면 인자 순서에 매핑된 $from과 $to를 쓸 수 있어요.

치환 변수 빠른 참고표예요.

참고: 현재 Skills 페이지에는 위의 1부터 시작하는 $1/$2 형식과 함께, 0부터 시작하는 $ARGUMENTS[N]/$N 형식($0이 첫 번째 인자)도 나와 있어요. 이 글을 쓰는 시점에는 문서에 둘 다 등장하므로, 특정 인덱스에 의존하기 전에 실제 문서를 확인해요.

어느 걸 써야 할까요? 규칙은 간단해요. 커맨드가 「자유 텍스트 한 덩어리」(이슈 설명, 질문, 설명할 스니펫)만 받는다면 $ARGUMENTS로 충분하고 가장 유연해요. 정해진 순서로 정확히 정해진 개수의 인자가 필요하면(rename: 무엇을 -> 무엇으로), 위치 인자 $1/$2가 더 명확해요. 이름 있는 인자는 헷갈리기 쉬운 인자가 여러 개인 커맨드일 때만 값어치를 해요. 그때는 $from/$to가 $1/$2보다 읽기 좋아요.

$ARGUMENTS와 위치 인자의 자세한 내용은 Claude Code 문서(2026/08/20 확인)에 있어요(지금은 Skills 페이지에 통합됐고, 별도의 slash-commands 페이지는 더 이상 없어요). 모든 커맨드 문법을 빠르게 훑고 싶을 때는 Claude Code 치트시트를 손닿는 곳에 둬요.

프런트매터: YAML로 커맨드 설정하기

커맨드 파일 맨 위에, 동작을 설정하는 YAML 프런트매터 블록(두 개의 --- 줄 사이)을 추가할 수 있어요. 커맨드의 안전성과 편의성을 실제로 좌우하는 부분인데도, 대부분의 가이드가 통째로 건너뛰는 요소예요.

전부 선택이지만, 실제로 매번 넣을 만한 건 description뿐이에요. 다음은 git 외에는 아무것도 건드리지 못하게 한 .claude/commands/commit.md 예예요.

---
description: Create a conventional commit from staged changes
argument-hint: [optional scope]
allowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git diff:*)
---

Look at the staged changes and write one tight, accurate
conventional commit (feat/fix/docs/refactor...).
If nothing is staged, tell me to `git add` first.

allowed-tools를 제대로 설정하면 커맨드는 미리 정해 둔 몇 개의 git 커맨드만 실행할 수 있어요. Claude가 아무거나 자유롭게 실행하게 두는 것보다 훨씬 안전해요. 셸을 건드리는 커맨드라면 들여 둘 만한 습관이에요.

!`bash`로 실시간 데이터 넣기 (그리고 파일 참조)

커맨드는 여러분이 붙여넣게 하는 대신 현재 컨텍스트를 스스로 가져올 수 있으면 훨씬 강력해져요. Claude Code는 !`<command>` 문법으로 bash 커맨드의 출력을 프롬프트에 바로 넣게 해줘요.

핵심은 이거예요. !`...` 안의 커맨드는 Claude가 프롬프트를 읽기 전에 실행되고, 그 출력이 내용에 곧바로 끼워 넣어져요. 이건 Claude가 커맨드 실행을 결정하는 게 아니라, 이미 실행된 거예요. 다음은 현재 diff를 스스로 가져오는 /review 커맨드예요.

Review the diff below and point out bugs + security risks:

!`git diff HEAD`

/review를 입력하면 Claude Code가 git diff HEAD를 실행하고, 그 결과를 가져와 그 자리에 붙인 뒤, 그제서야 프롬프트 전체를 Claude에게 넘겨요. 이제 diff를 손으로 복사할 일이 없어요.

여러 줄짜리 bash 블록에는 !로 시작하는 펜스 블록을 써요.

```!
git status --short
git log --oneline -5
```

참고: !`...`는 줄 맨 앞이나 공백 뒤에 두세요. 텍스트 안에서 리터럴 $(예를 들어 \$1.00 같은 가격)를 쓰고 싶다면, 인자로 읽히지 않도록 \로 이스케이프해요.

커맨드 공유하기: 프로젝트 vs 개인 + 하위 폴더

커스텀 커맨드는 범위가 다른 두 곳에 둘 수 있어요.

• 프로젝트 - 저장소 루트의 .claude/commands/. git에 커밋하면 팀 전체가 세트를 공유해요. 프로젝트 전용 커맨드에 좋아요: /deploy, /test, 팀의 커밋 규칙 등.
• 개인 - 홈 디렉터리의 ~/.claude/commands/. 여러분의 머신에서만 쓰지만 모든 프로젝트에서 사용할 수 있어요. 개인 습관에 좋아요: /explain, /tldr.

이름이 충돌하면 보통 프로젝트 레벨 커맨드가 이겨요. 프로젝트 컨텍스트에 더 가깝기 때문이에요.

하위 폴더로 커맨드 묶기(네임스페이스). 커맨드가 늘어나면 하위 폴더를 만들어 묶어요. 예를 들어 .claude/commands/git/commit.md는 커맨드를 git 그룹 아래에 드러내, / 메뉴를 깔끔하고 찾기 쉽게 유지해줘요.

이 「저장소마다 설정하고, 커밋해서 팀과 공유한다」는 방식은 바로 CLAUDE.md 파일의 정신이에요. 처음 접한다면 저장소용 CLAUDE.md 작성법을 읽어 두면 둘이 서로를 잘 보완해요. CLAUDE.md는 공유 규칙을 말하고, .claude/commands/는 반복 작업을 묶어줘요.

복붙해서 쓰는 커맨드 템플릿 5개 (바로 실행 가능)

제가 실제로 매일 쓰는 세트예요. .claude/commands/에 복사한 뒤 여러분의 스택에 맞게 손봐요.

1. /review - 현재 diff 리뷰 (review.md):

---
description: Review current changes for bugs and security risks
---

Review the diff below, prioritizing logic bugs and security holes:

!`git diff HEAD`

For each issue: give file:line, severity, and a concrete fix.

2. /commit - Conventional Commit (commit.md):

---
description: Write a conventional commit from staged changes
allowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git diff:*)
---

Look at `git diff --staged` and write one accurate
conventional commit. Do not add AI references to the message.

3. /test - 테스트 실행 후 실패 수정 (test.md):

---
description: Run the test suite and fix failing tests
argument-hint: [optional test file path]
---

Run the tests for $ARGUMENTS (run everything if empty).
If any test fails: read the error, find the root cause, fix
the code or the test, then rerun until green.

4. /docs - 독스트링 작성 (docs.md):

---
description: Write docstrings for the open file
---

Write docstrings for the functions/classes in the open file.
Follow the language's convention, list parameters, return
values, and errors that can be thrown. Keep it short, don't
repeat the function name.

5. /fix-issue - 번호로 이슈 수정 (fix-issue.md):

---
description: Fix a GitHub issue by number
argument-hint: <issue-number>
---

Fix issue #$ARGUMENTS: read the description, find the root
cause, write a fix with tests, briefly explain the fix.

[2026년 신규] 커스텀 커맨드가 Skills에 통합, 그리고 「Slash Command」는 이제 「Command」

이건 현재 대부분의 가이드가 아직 따라잡지 못한 큰 변화예요. 공식 Claude Code Skills 문서(2026/08/20 확인)에 따르면, 커스텀 커맨드는 Skills에 통합됐어요. 공식 용어집의 「폐기 및 이름 변경된 용어」 표가 분명히 밝혀요. 「Slash commands → Commands」(제품 표기에서 「Slash」 제거)와 「Custom commands → Skills」, 그리고 「Skills는 커스텀 커맨드의 권장 후속입니다」라고 못박아요. 다만 예전 .claude/commands/ 파일은 여전히 잘 동작해요.

구체적으로, .claude/commands/deploy.md 파일과 .claude/skills/deploy/SKILL.md 스킬은 같은 프런트매터 방식을 써서 둘 다 /deploy 커맨드를 만들어요. 여러분에게 중요한 건 예전 .claude/commands/*.md 파일이 여전히 잘 동작한다는 점이에요. 서둘러 마이그레이션할 게 없어요.

그럼 언제 Skill로 넘어가야 할까요? Skill은 커맨드와 두 가지 점에서 달라요. (1) 폴더라서 프롬프트 옆에 보조 파일(스크립트, 템플릿, 참고 문서)을 담을 수 있고, (2) 커맨드를 입력하지 않아도, 눈앞의 작업과 관련이 있으면 Claude가 자동으로 불러올 수 있어요. 요컨대, 커맨드는 손으로 호출하는 단일 동작에, 스킬은 스스로 트리거되길 원하는 복잡한 여러 파일짜리 기능에 어울려요.

더 깊이 알고 싶다면 Claude Code의 Skills란 무엇인가를 읽고, 이어서 커스텀 스킬 만드는 법을 보세요. 개념이 여전히 뒤섞인다면, skills vs subagents vs hooks vs MCP 글이 정리해줘요.

자주 겪는 문제와 팁

• 커맨드가 / 메뉴에 안 나와요. 올바른 폴더(.claude/commands/, 복수형에 앞에 점)에 있는지, 파일에 .md 확장자가 붙었는지 확인해요. 하위 폴더를 처음 만들었다면 다시 스캔하도록 Claude Code 세션을 재시작해요.
• 인자가 확장되지 않아요. 프롬프트에 $2가 있는데 인자를 하나만 넘기면 $2는 문자 그대로 남아요. 인자 개수가 고정이 아닐 때는 $ARGUMENTS를 써요.
• $가 변수로 잘못 읽혀요. 일반 텍스트에서 리터럴 달러 기호를 쓰고 싶으면 \$1.00(\ 포함)처럼 적어요.
• 커맨드로 만들지 말아야 할 때. 일회성이거나 매번 내용이 다르다면 프롬프트를 바로 입력하는 편이 빨라요. 커맨드는 그 동작이 반복되고 안정적일 때만 제값을 해요. 뭐든 커맨드로 만들지 마세요. 비대해지고 거의 안 쓰는 커맨드 세트는 / 메뉴만 어지럽혀요.

직접 쓰기 싫으세요? 이미 만들어진 커맨드 세트를 쓰세요

커맨드를 직접 써 보는 건 원리를 이해하고 주도권을 쥐는 가장 좋은 방법이라, 적어도 처음 몇 개는 손으로 만들어 보라고 누구에게나 권해요. 하지만 흔한 워크플로에 맞춰 이미 설계·테스트된 커맨드와 스킬 세트를 원한다면, AgentKit의 이미 만들어진 커맨드·스킬 세트를 살펴보세요. 홈페이지에 따르면 Claude Code용 스킬 108개 이상과 AI 에이전트 45개를 묶어 Engineer Kit와 Marketing Kit로 나눠 제공해요. 보통의 .claude/commands/ 파일처럼 전부 커스터마이즈할 수 있으니, 그저 맨바닥에서 시작하지 않는 것뿐이에요. 바로 보고 싶다면 여기에서 AgentKit을 사용해 볼 수 있어요(링크로 20% 할인). 사이트에는 환불 보장(구체 조건 명시 없음)과 키트 평생 업데이트가 적혀 있어요.

자주 묻는 질문 (FAQ)

커스텀 슬래시 커맨드는 어디에 저장되나요?

프로젝트 루트의 .claude/commands/(git에 커밋하면 팀과 공유)나 홈 디렉터리의 ~/.claude/commands/(여러분 머신 전용이지만 모든 프로젝트에서 사용 가능)에 저장돼요. .md 확장자를 뺀 파일 이름이 커맨드 이름이에요.

커맨드에 인자를 여러 개 넘기려면?

$ARGUMENTS를 쓰면 커맨드 이름 뒤의 텍스트를 한 번에 전부 가져오고, $1, $2… 로 각 위치 인자를 다뤄요. 여러 단어짜리 인자는 따옴표로 감싸요: /rename "old id" new.

커스텀 커맨드는 내장 커맨드와 어떻게 다른가요?

내장 커맨드(/help, /clear, /compact…)는 Anthropic이 Claude Code에 기본 제공해요. 커스텀 커맨드는 여러분이나 팀의 프롬프트를 묶어 Markdown 파일로 만든 거예요. 둘 다 / 메뉴에 함께 나와요.

커맨드 안에서 터미널 커맨드를 실행할 수 있나요?

네. !`<command>` 문법을 써요. bash 커맨드가 먼저 실행되고, 그 출력이 Claude가 읽기 전에 프롬프트에 끼워 넣어져요. 예를 들어 !`git diff HEAD`로 커맨드가 현재 diff를 스스로 가져와요.

커맨드를 커밋해서 팀 전체와 공유할 수 있나요?

네. 저장소 루트의 .claude/commands/에 커맨드를 두고 git에 커밋해요. 저장소를 클론한 모두가 같은 커맨드 세트를 받아, 팀의 워크플로를 동기화된 상태로 유지해요.

커스텀 커맨드는 Skills와 어떻게 다른가요?

2026년 기준으로 둘은 통합됐고, 예전 커맨드 파일도 여전히 동작해요. 차이는, 커맨드는 손으로 호출하는 단일 프롬프트 파일인 반면, 스킬은 보조 파일을 담을 수 있고 Claude가 관련 있다고 판단하면 자동으로 불러올 수 있는 폴더라는 점이에요. 커맨드는 단일 동작에, 스킬은 복잡한 기능에 어울려요.

마무리 + 다음 단계

커스텀 슬래시 커맨드는 반복되는 프롬프트를 공유 도구로 바꾸는 가장 저렴한 방법이에요. Markdown 파일 하나, 키 한 번이면 팀 전체가 덕을 봐요. /review와 /commit으로 시작하고, 안전성이 필요하면 프런트매터를 더하고, 워크플로가 복잡해지면 Skill로 넘어가요. Claude Code의 Skills란 무엇인가와 커스텀 스킬 만드는 법으로 이어 읽거나, Claude Code 치트시트를 열어 언제든 문법을 찾아보세요.