Skills와 커스텀 명령어 가이드
팀/개인 워크플로우를 slash command와 skill로 설계하고 운영하는 방법
핵심 요약
- 공식 문서상 커스텀 명령어는 skill로 통합됐고,
.claude/commands/deploy.md와.claude/skills/deploy/SKILL.md는 둘 다/deploy를 만듭니다. - 명령 이름은
name프론트매터가 아니라 skill 디렉터리 이름에서 정해집니다(플러그인 루트SKILL.md만 예외). - 동일 이름의 skill과 command가 있으면 skill이 우선하며, 우선순위는 enterprise > personal > project 순입니다.
disable-model-invocation: true로 자동 호출을 막고,allowed-tools로 최소 권한을 지정하며,$ARGUMENTS·${CLAUDE_EFFORT}·!`command`로 인수와 동적 컨텍스트를 주입합니다.
목적
기본 명령어만으로 반복 업무가 남는다면 skill이나 커스텀 명령어로 표준화합니다.
공식 문서에 따르면 커스텀 명령어는 skill로 통합되었습니다. .claude/commands/deploy.md 파일과 .claude/skills/deploy/SKILL.md skill은 둘 다 /deploy 명령을 만들고 똑같이 동작합니다.
기존 .claude/commands/ 파일도 계속 동작하지만, 새 워크플로우라면 supporting files(보조 파일 디렉터리), invocation control(호출 주체 제어), dynamic context injection(동적 컨텍스트 주입)을 쓸 수 있는 skill 구조를 먼저 권합니다.
호출 형식
/<custom-command> [arguments]/<skill-name> [arguments]같은 이름을 직접 호출하면 동일하게 동작하며, /만 입력하면 사용 가능한 모든 명령과 skill 목록이 표시됩니다.
권장 구조
프로젝트 기준 skill 위치:
.claude/skills/
release-check/
SKILL.md
checklist.md
scripts/
collect-release-info.shSKILL.md 예시:
---
name: release-check
description: 릴리스 전 변경 범위, 테스트, 문서 누락을 점검합니다.
disable-model-invocation: true
allowed-tools: Read Grep Bash
---
## Inputs
Release target: $ARGUMENTS
Current effort: ${CLAUDE_EFFORT}
## Instructions
1. 변경 범위를 요약합니다.
2. 누락된 테스트와 문서를 찾습니다.
3. 위험 항목을 severity 순서로 정리합니다.명령 이름은 name 프론트매터가 아니라 skill 디렉터리 이름에서 정해집니다. 위 예시라면 release-check/ 폴더가 곧 /release-check입니다. name은 skill 목록에 표시되는 라벨로 쓰입니다(플러그인 루트 SKILL.md만 예외라서, 이때는 name이 명령 이름이 됩니다).
기존 커스텀 명령 구조
프로젝트 기준 위치:
.claude/commands/
review-pr.md
release-check.md간단한 예시:
---
description: PR 체크리스트 기반 리뷰를 실행
argument-hint: <PR URL or branch>
---
$ARGUMENTS를 기준으로 변경 범위, 리스크, 테스트 항목을 정리해줘.이 방식도 호환성 때문에 계속 쓸 수 있고, skill과 같은 프론트매터를 지원합니다. 다만 이름이 같은 skill과 command가 있으면 skill이 우선 적용되니, 마이그레이션할 때 이름 충돌을 확인하세요. (이름 우선순위는 enterprise > personal > project 순으로, 플러그인 skill은 plugin-name:skill-name 네임스페이스를 써서 충돌하지 않습니다.)
인수와 동적 컨텍스트
| 자리표시자 | 의미 |
|---|---|
$ARGUMENTS | 호출 시 전달된 전체 인수. 본문에 없으면 끝에 ARGUMENTS: <값>이 자동 추가됩니다. |
$ARGUMENTS[N] | 0-based 인덱스로 특정 인수 접근($ARGUMENTS[0]이 첫 번째). |
$N | $ARGUMENTS[N]의 약식($0, $1). |
${CLAUDE_EFFORT} | 현재 effort 레벨(low/medium/high/xhigh/max/ultra). |
${CLAUDE_SKILL_DIR} | 해당 skill의 SKILL.md가 있는 디렉터리 경로. 번들 스크립트 참조에 사용. |
본문에서 줄 시작(또는 공백 뒤)에 !`command` 형태를 쓰면, Claude가 내용을 읽기 전에 그 명령을 실행해 출력으로 치환합니다(dynamic context injection). 예: !`git diff HEAD`.
좋은 사용 예
/review-pr feature/login-refactor/release-check v1.2.0/deploy-check staging
비슷한 명령어 추천
- 내장
/review [PR]: 현재 세션에서 PR을 로컬 리뷰 - 내장
/code-review: 변경 diff의 버그·정리 항목 점검(--fix로 적용,--comment로 PR 코멘트). 더 깊은 클라우드 리뷰는/code-review ultra(/ultrareview는 별칭) - 커스텀
/review-pr: 팀 정책 포함 리뷰 /skills: 현재 세션에서 노출되는 skill 목록 확인(t로 토큰 정렬)/reload-skills: 세션 중 추가·변경된 skill을 재스캔(v2.1.152+)/plugin: 조직 공통 skill/command를 배포 단위로 관리
활용 사례
- 팀 릴리즈 전 체크 자동화
- 이슈 트리아지 템플릿 표준화
- PR 설명문 자동 생성
- 배포, incident response, 보안 점검처럼 부작용이 큰 절차를 사용자 직접 호출 전용으로 고정
운영 팁
- 명령어 이름은 짧고 명확하게 유지(명령 이름은 skill 디렉터리 이름에서 나옴)
- 새 워크플로우는
.claude/skills/<name>/SKILL.md로 만들고, legacy command는 점진적으로 이전 - 자동 호출되면 위험한 workflow에는
disable-model-invocation: true적용(직접/name으로만 호출 가능) - 도구 승인이 반복되는 workflow에는
allowed-tools를 최소 권한으로 지정(공백 또는 쉼표 구분 문자열, YAML 리스트 모두 가능). 절대 호출하면 안 되는 도구는disallowed-tools로 제거 $ARGUMENTS,$0,$1같은 인수 치환을 쓰되, 빈 인수일 때의 fallback 동작도 문서화${CLAUDE_EFFORT}로 현재 effort에 따라 점검 깊이를 조정- 긴 참고자료는
SKILL.md본문에 붙이지 말고 별도 파일로 분리(SKILL.md는 500줄 이하 권장) - 버전 변경 시
updates에 반영
검증 체크리스트
| 항목 | 확인 방법 |
|---|---|
| 노출 여부 | /skills에서 이름과 설명 검색 |
| 직접 호출 | /<name> sample-argument 실행 |
| 자동 호출 제한 | disable-model-invocation 의도와 실제 동작 확인 |
| 권한 범위 | allowed-tools가 필요한 도구만 포함하는지 검토 |
| 토큰 비용 | SKILL.md가 500줄을 넘지 않는지 확인 |