Skills와 커스텀 명령어 가이드

목적

기본 명령어만으로 반복 업무가 남는다면 skill 또는 커스텀 명령어로 표준화를 진행합니다. 최신 Claude Code 공식 문서에서는 .claude/commands/*.md 방식의 커스텀 명령과 .claude/skills/<name>/SKILL.md 방식의 skill을 같은 slash command 경험으로 묶어 설명합니다. 기존 .claude/commands/ 파일은 계속 동작하지만, 새 워크플로우는 supporting files, invocation control, dynamic context injection을 쓸 수 있는 skill 구조를 우선 권장합니다.

원본 선언(형식)

/<custom-command> [arguments]

/<skill-name> [arguments]

권장 구조

프로젝트 기준 skill 위치:

.claude/skills/
  release-check/
    SKILL.md
    checklist.md
    scripts/
      collect-release-info.sh

SKILL.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 순서로 정리합니다.

기존 커스텀 명령 구조

프로젝트 기준 위치:

.claude/commands/
  review-pr.md
  release-check.md

간단한 예시:

---
description: PR 체크리스트 기반 리뷰를 실행
argument-hint: <PR URL or branch>
---

$ARGUMENTS를 기준으로 변경 범위, 리스크, 테스트 항목을 정리해줘.

이 방식은 호환성을 위해 계속 사용할 수 있습니다. 다만 동일 이름의 skill과 command가 있으면 skill이 우선 적용되므로, 마이그레이션할 때 이름 충돌을 확인하세요.

좋은 사용 예

• /review-pr feature/login-refactor
• /release-check v1.2.0
• /deploy-check staging

비슷한 명령어 추천

• 내장 /review: 범용 코드 리뷰
• 커스텀 /review-pr: 팀 정책 포함 리뷰
• /skills: 현재 세션에서 노출되는 skill 목록 확인
• /plugin: 조직 공통 skill/command를 배포 단위로 관리

활용 사례

• 팀 릴리즈 전 체크 자동화
• 이슈 트리아지 템플릿 표준화
• PR 설명문 자동 생성
• 배포, incident response, 보안 점검처럼 부작용이 큰 절차를 사용자 직접 호출 전용으로 고정

운영 팁

1. 명령어 이름은 짧고 명확하게 유지
2. 새 워크플로우는 .claude/skills/<name>/SKILL.md로 만들고, legacy command는 점진적으로 이전
3. 자동 호출되면 위험한 workflow에는 disable-model-invocation: true 적용
4. 도구 승인이 반복되는 workflow에는 allowed-tools를 최소 권한으로 지정
5. $ARGUMENTS, $0, $1 같은 인수 치환을 쓰되, 빈 인수일 때의 fallback 동작도 문서화
6. ${CLAUDE_EFFORT}로 현재 effort에 따라 점검 깊이를 조정
7. 긴 참고자료는 SKILL.md 본문에 붙이지 말고 별도 파일로 분리
8. 버전 변경 시 updates에 반영

검증 체크리스트

출처

• Skills: https://code.claude.com/docs/en/skills
• Commands: https://code.claude.com/docs/en/commands