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

같은 요청을 매번 다시 타이핑하고 있다면 그 요청은 이미 커맨드가 될 자격이 있습니다. 우리 초급 8주 과정 3주차에서 만드는 "녹음을 회의록으로" 변환기가 그렇습니다. 회의 한 번 끝날 때마다 "참석자, 논의 내용, 결정 사항, 할 일 형식으로 정리해 줘"를 다시 적는 대신, /meeting:summary 한 줄로 부르게 만드는 것이 이 글의 목표입니다.

이 글은 커스텀 커맨드 코스의 첫 편입니다. 커맨드 파일을 어디에 두는지, 파일 이름이 어떻게 커맨드 이름이 되는지, 폴더로 묶으면 무엇이 달라지는지, 추가한 파일이 언제 목록에 나타나는지를 순서대로 다룹니다. 다음 편에서는 프론트매터로 설명과 도구 사전 승인을 붙이는 방법을 이어서 봅니다.

핵심 요약

• 커스텀 커맨드는 Markdown 파일 한 장입니다. 파일 이름이 곧 커맨드 이름이 됩니다.
• 두는 곳은 두 곳입니다. 프로젝트용 .claude/commands/와 개인용 ~/.claude/commands/.
• 하위 폴더에 넣으면 /폴더명:파일명 형태로 호출합니다. 폴더명이 접두어가 되어 이름 충돌을 막습니다.
• 공식 문서 기준으로 커스텀 커맨드는 Skills와 같은 메커니즘으로 통합됐습니다. 기존 .claude/commands/ 파일은 그대로 동작합니다.
• 세션 중에 추가한 파일은 /reload-skills로 다시 스캔할 수 있습니다.

커스텀 커맨드란 무엇인가

커스텀 커맨드는 "자주 쓰는 프롬프트를 파일로 저장해 두고 /이름으로 호출하는 기능"입니다. 파일 본문이 그대로 프롬프트가 됩니다. 따로 배울 문법은 거의 없고, 지금까지 채팅창에 쳐 넣던 문장을 파일에 옮겨 적으면 끝입니다.

우리 과정에서 이 기능을 중요하게 보는 이유는 "지침 파일 + 검증 게이트"라는 관점 때문입니다. CLAUDE.md가 프로젝트 전체에 항상 적용되는 규칙이라면, 커맨드는 특정 작업을 시작할 때만 불러오는 절차서입니다. 회의록 정리 절차를 CLAUDE.md에 넣으면 회의록과 무관한 작업에서도 매번 컨텍스트를 차지하지만, 커맨드로 빼 두면 부를 때만 읽힙니다. 공식 문서도 같은 이유로 "CLAUDE.md의 한 절이 사실이 아니라 절차로 자라났다면 스킬(커맨드)로 옮기라"고 안내합니다.

한 가지 알아 둘 배경이 있습니다. 2026년 8월 현재 공식 문서(code.claude.com/docs/ko/skills)에는 "사용자 정의 명령어가 skills로 병합되었습니다"라고 명시되어 있습니다. .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 둘 다 /deploy를 만들고 같은 방식으로 동작합니다. 예전의 slash-commands 문서 페이지는 skills 페이지로 흡수되었고, 지금 주소로 접속하면 404가 뜹니다. 그러니 이 코스에서 "커스텀 커맨드"라고 부르는 것은 정확히는 "단일 Markdown 파일 형태의 스킬"입니다. 기능은 그대로이고 이름만 넓어졌다고 이해하면 됩니다.

커맨드 파일은 어디에 두나

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

프로젝트 루트의 .claude/commands/ 폴더에 둔 파일은 그 프로젝트에서만 보입니다. 팀원과 함께 쓰는 절차, 예를 들어 우리 CRM 레포의 "PR 올리기 전 점검" 같은 커맨드가 여기에 어울립니다. 폴더째 git에 커밋하면 팀 전체가 같은 커맨드를 공유하게 됩니다.

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

홈 디렉터리 아래 ~/.claude/commands/에 둔 파일은 어느 프로젝트를 열어도 보입니다. 공식 문서의 .claude 디렉터리 안내는 이 위치를 "모든 프로젝트에서 사용 가능한 개인용 단일 파일 커맨드"로 설명합니다. 회의록 정리처럼 어느 레포에서든 쓰는 업무 커맨드는 여기에 두는 편이 편합니다.

macOS와 Windows의 경로만 다르게 읽으면 됩니다.

어느 쪽을 써야 하나

판단 기준은 하나입니다. "이 절차가 프로젝트에 묶여 있는가, 나에게 묶여 있는가." 레포의 테스트 명령이나 배포 순서처럼 코드와 함께 바뀌는 것은 프로젝트 커맨드로, 회의록 형식이나 일일 보고 양식처럼 내 업무 방식에 묶인 것은 개인 커맨드로 둡니다. 둘 다 있을 때 같은 이름이 겹치면 공식 문서 기준으로 personal(개인)이 project(프로젝트)보다 우선합니다. 그리고 같은 이름의 스킬(.claude/skills/이름/SKILL.md)과 커맨드 파일이 동시에 있으면 스킬이 우선합니다.

첫 커맨드를 만드는 세 단계

3주차 실습인 회의록 변환기를 커맨드로 옮겨 보겠습니다. 어느 프로젝트에서든 쓸 것이므로 개인 커맨드로 만듭니다.

1. 디렉터리 만들기

# macOS
mkdir -p ~/.claude/commands/meeting

# Windows (PowerShell)
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\commands\meeting"

meeting이라는 하위 폴더까지 만든 이유는 다음 절에서 설명합니다. 지금은 "회의 관련 커맨드를 한 폴더에 모은다" 정도로 이해하면 됩니다.

2. Markdown 파일 만들기

~/.claude/commands/meeting/summary.md를 만들고 본문을 적습니다. 프론트매터 없이 본문만 있어도 동작합니다.

녹음 전사 텍스트를 회의록으로 정리합니다.

형식은 다음 네 항목을 h2로 나눠 작성합니다.
1. 참석자
2. 논의 내용
3. 결정 사항
4. 할 일 (담당자와 기한을 함께)

규칙:
1. 전사에 없는 내용을 추측해서 채우지 않습니다.
2. 고객 실명은 첫 글자만 남기고 가립니다.
3. 결정 사항이 없으면 "결정 사항 없음"이라고 명시합니다.

두 번째 규칙은 우리 2주차 CLAUDE.md 규칙(실명 가리기)을 커맨드 안에서도 반복한 것입니다. 상담 녹음을 다루는 정책지도사 수강생에게 특히 중요합니다.

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

Claude Code를 열고 /를 입력하면 호출 가능한 목록이 뜹니다. 여기에 /meeting:summary가 보이면 성공입니다. /meeting까지만 쳐서 필터링해도 됩니다. 실제로 실행할 때는 전사 텍스트를 붙여 넣은 뒤 커맨드를 부르거나, 다음 편에서 다룰 인수로 파일 경로를 넘기면 됩니다.

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

.claude/commands/ 아래에 하위 폴더를 만들면 폴더명이 커맨드 이름의 접두어가 됩니다. 위 예시의 meeting/summary.md는 /meeting:summary로 호출됩니다. 이 동작은 2026년 8월 기준 공식 문서 본문에 별도 항목으로 설명되어 있지 않아, 우리가 Claude Code 2.1.246에서 직접 확인했습니다. 결과는 다음과 같았습니다.

1. .claude/commands/meeting/summary.md는 /meeting:summary로 호출됩니다.
2. 같은 파일을 /summary로 부르면 "Unknown command"가 뜹니다. 접두어를 생략할 수 없습니다.
3. 개인 커맨드 ~/.claude/commands/ 아래 하위 폴더도 같은 규칙으로 동작합니다.

이 규칙 덕분에 성격이 다른 커맨드를 이름 충돌 없이 나눌 수 있습니다. 우리 8주 과정에서 만드는 자동화를 예로 들면 이렇게 묶입니다.

~/.claude/commands/
├── meeting/
│   ├── summary.md      → /meeting:summary   (W3 회의록 정리)
│   └── actions.md      → /meeting:actions   (할 일만 뽑기)
└── report/
    ├── daily.md        → /report:daily      (W7 일일 보고)
    └── weekly.md       → /report:weekly

summary라는 이름을 다른 폴더에서도 쓰고 싶을 때 접두어가 있으면 헷갈리지 않습니다. 폴더가 많아질수록 이 장점이 커집니다.

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

공식 문서는 ~/.claude/skills/와 프로젝트 .claude/skills/ 아래의 변경을 세션 중에 자동 감지한다고 안내합니다. 커맨드 디렉터리에 대해서는 /reload-skills 명령이 준비되어 있습니다. 공식 명령어 참조에 따르면 이 명령은 "skill 및 명령어 디렉토리를 다시 스캔하여 세션 중에 디스크에서 추가되거나 변경된 skills를 재시작하지 않고 사용할 수 있도록" 하며, 사용 가능한 개수와 추가·제거된 개수를 보고합니다(v2.1.152부터).

그래서 우리 수업에서는 이렇게 가르칩니다.

1. 파일을 만들거나 고친 뒤 /reload-skills를 한 번 실행합니다.
2. 목록에 안 보이면 Claude Code를 종료하고 다시 시작합니다. 세션 시작 시점에 없던 최상위 폴더(예: 처음 만드는 ~/.claude/commands/ 자체)는 재시작해야 감시 대상에 들어갑니다.
3. 그래도 안 보이면 claude --debug로 실행해 파싱 오류를 확인합니다. 프론트매터 YAML이 깨지면 본문은 로드되지만 설명이 비어 버립니다.

정지 규칙은 여기서도 같습니다. "커맨드를 만들었다"가 아니라 "/ 목록에 떴다"가 완료 기준입니다.

정리

• 커스텀 커맨드는 Markdown 파일 한 장이며, 파일명이 커맨드명이 됩니다.
• 프로젝트에 묶인 절차는 .claude/commands/, 내 업무에 묶인 절차는 ~/.claude/commands/에 둡니다.
• 하위 폴더는 /폴더:파일 접두어로 동작하며 접두어 생략은 불가합니다(2.1.246 실측).
• 공식 문서상 커맨드는 스킬과 같은 메커니즘이고, 같은 이름이면 스킬이 우선합니다.
• 추가 후에는 /reload-skills, 안 되면 재시작, 완료 기준은 목록에 보이는 것입니다.

자주 묻는 질문