3.2슬래시 명령어와 스킬

커스텀 슬래시 명령어는 자주 쓰는 프롬프트를 마크다운 파일로 저장해 /이름으로 호출하는 기능입니다. 저장 위치에 따라 범위가 달라집니다.

• 프로젝트 명령어: .claude/commands/이름.md — 저장소에 커밋하면 팀 전체가 사용
• 개인 명령어: ~/.claude/commands/이름.md — 모든 프로젝트에서 나만 사용

<!-- .claude/commands/fix-issue.md -->
---
description: GitHub 이슈를 분석하고 수정한다
allowed-tools: Bash(gh issue view:*), Bash(git add:*)
---

이슈 #$1 을 gh 명령으로 조회한 뒤, 원인을 분석하고 수정하라.
수정 후 테스트를 실행하고 결과를 보고하라.

호출은 /fix-issue 123 형태로 합니다. 인자 전달 방법은 두 가지입니다.

• $ARGUMENTS — 명령 뒤에 입력한 전체 문자열이 통째로 치환됩니다.
• $1, $2, … — 위치 인자(positional argument)를 개별로 받습니다.

프런트매터에서 자주 쓰는 필드는 description(명령 목록에 표시), allowed-tools(이 명령 실행 중 허용할 도구), model(특정 모델 강제) 입니다. 본문에서 !명령 문법으로 배시 명령을 먼저 실행해 그 출력을 프롬프트에 포함할 수 있고, @경로로 파일 내용을 참조할 수 있습니다. 예를 들어 !git diff HEAD를 포함하면 명령 실행 시점의 실제 diff가 컨텍스트로 들어갑니다. 하위 디렉터리로 명령을 정리하면 /dir:name 형태의 네임스페이스가 됩니다.

스킬은 슬래시 명령어보다 큰 단위의 재사용 가능한 능력 패키지입니다. 디렉터리 하나가 스킬 하나이며, 진입점은 SKILL.md 파일입니다.

<!-- .claude/skills/pdf-report/SKILL.md -->
---
name: pdf-report
description: 분석 결과를 PDF 보고서로 만든다. 보고서, PDF 생성 요청 시 사용.
---

# PDF 보고서 생성 절차

1. scripts/generate.py 를 실행해 초안을 만든다
2. templates/report.html 템플릿을 적용한다
3. 상세 스타일 규칙은 STYLE.md 참고

스킬의 핵심 설계 원리는 점진적 공개(progressive disclosure) 입니다. 세션 시작 시에는 각 스킬의 name과 description만 컨텍스트에 올라가고, 본문은 Claude가 그 스킬이 필요하다고 판단했을 때만 읽습니다. SKILL.md에서 참조하는 보조 파일(STYLE.md, 스크립트, 템플릿)은 그보다도 늦게, 실제로 필요할 때 읽힙니다. 덕분에 스킬을 수십 개 설치해도 평소 컨텍스트 부담이 작습니다.

이 구조에서 description의 품질이 결정적입니다. 언제 이 스킬을 써야 하는지 트리거 조건을 구체적으로 적어야 Claude가 올바른 시점에 스킬을 선택합니다. "PDF 관련 작업"보다 "사용자가 보고서·PDF 생성을 요청하거나 분석 결과를 문서화할 때"가 좋은 description입니다.

스킬도 저장 위치로 범위가 갈립니다. 프로젝트 스킬은 .claude/skills/, 개인 스킬은 ~/.claude/skills/에 두며, 플러그인(plugin)을 통해 배포·설치할 수도 있습니다.

두 메커니즘 모두 "재사용 가능한 프롬프트"라는 점은 같지만 호출 방식과 규모가 다릅니다.

기준	슬래시 명령어	스킬
호출	사용자가 명시적으로 /이름 입력	Claude가 상황을 보고 자동 선택 (사용자가 /이름으로 강제 호출도 가능)
규모	프롬프트 한 개 분량	여러 파일·스크립트·템플릿 포함 가능
컨텍스트	호출 시 본문 전체 삽입	평소엔 description만, 필요 시 본문 로드
적합한 용도	자주 치는 정형 프롬프트 (커밋 정리, 이슈 수정, 리뷰 요청)	절차적 전문 지식 (사내 보고서 형식, 배포 절차, 특정 도구 사용법)

판단 기준을 한 문장으로 줄이면 이렇습니다. 사람이 시점을 결정하는 반복 프롬프트는 명령어, Claude가 시점을 결정해야 하는 전문 절차는 스킬입니다.

시험에서는 "팀 전체가 공유해야 하는 배포 절차 문서 + 검증 스크립트"처럼 여러 파일이 얽힌 사례를 주고 무엇으로 패키징할지 묻습니다. 파일이 여러 개고 Claude가 맥락에 따라 알아서 참조해야 한다면 스킬이 정답입니다. 반대로 "매번 같은 형식으로 PR 설명을 만들어 달라"처럼 단일 프롬프트를 사용자가 직접 트리거하는 경우는 명령어가 적합합니다.

또 하나의 관련 메커니즘으로 서브에이전트(subagent) 정의(.claude/agents/*.md)가 있습니다. 별도의 컨텍스트 윈도우에서 독립 실행되어야 하는 역할(예: 코드 리뷰어)은 명령어·스킬이 아니라 서브에이전트로 정의합니다.

명령어에 사전 컨텍스트 주입. ! 배시 실행을 프런트매터의 allowed-tools와 함께 쓰면, 명령 실행 시점의 실시간 상태(diff, 브랜치, 이슈 목록)를 프롬프트에 넣을 수 있습니다.

---
description: 현재 변경사항으로 커밋 메시지를 작성하고 커밋한다
allowed-tools: Bash(git status:*), Bash(git diff:*), Bash(git commit:*)
---

## 현재 상태
- 상태: !`git status`
- 변경: !`git diff HEAD`

위 변경사항을 Conventional Commits 형식의 커밋 1개로 커밋하라.

스킬에 스크립트 동봉. 결정적(deterministic)으로 처리 가능한 부분은 모델에게 시키지 말고 스크립트로 동봉한 뒤 "이 스크립트를 실행하라"고 지시합니다. 토큰을 아끼고 결과 편차를 없앱니다.

팀 배포는 저장소 커밋으로. .claude/commands/와 .claude/skills/를 저장소에 커밋하면 팀원이 저장소를 클론하는 것만으로 같은 도구 세트를 갖게 됩니다. 조직 차원 배포가 필요하면 플러그인 마켓플레이스로 묶는 방법도 있습니다.

이름 충돌 주의. 같은 이름의 프로젝트 명령어와 개인 명령어가 있으면 충돌을 피하기 위해 각각의 출처가 구분 표시됩니다. 팀 공용 이름과 개인 이름을 겹치지 않게 짓는 것이 좋습니다.