Claude Code Commands

Claude Code에서 사용자가 반복적으로 사용하는 프롬프트를 Markdown 파일로 저장하고, /명령어 형태로 호출할 수 있게 해주는 기능이다. 2025년 4월에 도입되었으며, 2026년 1월에 Skills 시스템으로 통합(merge)되었다.

해당 개념이 필요한 이유

• Claude Code를 반복적으로 사용하다 보면 동일한 패턴의 프롬프트를 매번 입력하게 됨
• 팀 단위로 표준화된 워크플로우를 공유할 필요가 있음
• 프로젝트별/개인별로 다른 작업 패턴을 재사용 가능한 단위로 관리하고 싶음

AS-IS (Commands 도입 전)

사용자가 매번 긴 프롬프트를 직접 입력

> "이 코드를 리뷰해줘. 보안 취약점, 성능 이슈,
>  코드 스타일을 확인하고 개선점을 알려줘..."
> (매번 동일한 내용 반복 입력)

TO-BE (Commands 도입 후)

.claude/commands/review.md 파일에 프롬프트 저장

> /review
> (한 줄로 동일한 작업 수행)

Commands의 구조와 동작 방식

파일 구조

Scope	Path	설명
프로젝트 명령어	.claude/commands/<name>.md	프로젝트에 특화된 명령어 (Git 공유 가능)
개인 명령어	~/.claude/commands/<name>.md	개인 전용 명령어 (모든 프로젝트에서 사용)

파일 포맷

# .claude/commands/review.md
 
다음 코드를 리뷰해주세요:
- 보안 취약점 확인
- 성능 이슈 점검
- 코드 스타일 개선점
 
대상: $ARGUMENTS

• 파일명 = 명령어 이름 (review.md → /review)
• $ARGUMENTS로 사용자 입력 인자를 치환
• YAML frontmatter 지원 (선택)

호출 방법

/review src/auth/login.ts
         ↑ $ARGUMENTS에 대입됨

전체 진화 타임라인

sequenceDiagram
    autonumber
    participant U as 사용자
    participant CMD as Commands<br/>(v0.2.31)
    participant AGT as Custom Agents<br/>(v1.0.60)
    participant SKL as Skills<br/>(v2.0.20)
    participant STD as Open Standard<br/>(agentskills.io)
    participant MRG as Unified System<br/>(v2.1.3)

    Note over CMD: 2025-04-02
    U->>CMD: .claude/commands/review.md 생성
    CMD->>U: /review 로 호출 가능

    Note over AGT: 2025-07-24
    U->>AGT: Custom Subagents 도입
    AGT->>U: 격리된 컨텍스트에서 실행 가능

    Note over SKL: 2025-10-16
    U->>SKL: .claude/skills/review/SKILL.md 생성
    SKL->>U: 디렉토리 구조 + 자동 감지 + frontmatter

    Note over STD: 2025-12-18
    SKL->>STD: Agent Skills 오픈 표준 발표
    STD->>U: VS Code, Cursor, Amp 등 채택

    Note over MRG: 2026-01-09
    CMD->>MRG: Commands가 Skills로 통합
    SKL->>MRG: Skills가 primary abstraction
    MRG->>U: 기존 commands 파일 그대로 동작

각 버전별 상세 변화

v0.2.31 — Commands 도입 (2025-04-02)

• .claude/commands/ 디렉토리에 .md 파일 저장
• 파일명이 곧 /명령어 이름
• $ARGUMENTS 치환 지원
• 단일 파일 구조 (보조 파일 불가)
• 사용자 수동 호출만 가능 (Claude가 자동 호출 불가)

v1.0.60 — Custom Agents 도입 (2025-07-24)

• 별도의 서브에이전트(subprocess)로 작업 위임 가능
• 격리된 컨텍스트에서 실행
• Commands와는 별개 기능이지만, 후에 Skills에 context: fork로 통합

v2.0.20 — Skills 도입 (2025-10-16)

• .claude/skills/<name>/SKILL.md 디렉토리 구조
• Claude가 자동으로 관련 skill을 감지하고 로딩 가능
• 보조 파일(template, script, example) 번들 지원
• YAML frontmatter로 동작 제어

v2.1.0 — Skills 강화 (2026-01-07)

• context: fork — 격리된 서브에이전트 컨텍스트에서 실행
• agent 필드 — 실행할 에이전트 타입 지정 (Explore, Plan 등)

v2.1.3 — Commands → Skills 통합 (2026-01-09)

• Slash commands가 skills로 머지됨
• .claude/commands/ 파일은 그대로 동작 (하위 호환)
• 동일 이름의 skill과 command가 있으면 skill이 우선

Commands vs Skills 비교

항목	Commands (구)	Skills (현)
파일 구조	단일 .md 파일	디렉토리 + SKILL.md + 보조 파일
위치	.claude/commands/	.claude/skills/
호출 방식	사용자가 /name으로만	사용자 /name 또는 Claude 자동 감지
보조 파일	미지원	template, script, example 번들 가능
서브에이전트	미지원	context: fork로 격리 실행
에이전트 선택	미지원	agent: Explore, Plan 등
도구 제한	미지원	allowed-tools 필드
모델 오버라이드	미지원	model 필드
호출 제어	없음	disable-model-invocation, user-invocable
인자 처리	$ARGUMENTS	$ARGUMENTS, $ARGUMENTS[N], $N, ${CLAUDE_SESSION_ID}
오픈 표준	아님	agentskills.io로 표준화
하위 호환	—	기존 commands 파일 그대로 동작

통합(Merge)의 핵심 포인트

1. Zero-effort Migration 기존 .claude/commands/ 파일을 변경할 필요가 전혀 없다. 그대로 동작한다.

2. 양방향 호출 모든 slash command는 skill로 호출 가능하고, 모든 skill은 /로 호출 가능하다.

3. 우선순위 규칙 동일 이름의 skill과 command가 공존할 경우 skill이 우선한다.

4. 신규 개발은 Skills 권장 기존 commands는 유지하되, 새로운 자동화는 .claude/skills/에 만드는 것을 권장한다.

오픈 표준화 — agentskills.io

2025년 12월 18일, Anthropic은 Agent Skills를 오픈 표준으로 발표했다.

채택한 플랫폼:

• Microsoft: VS Code, GitHub
• Cursor
• Goose, Amp, OpenCode

이는 .claude/skills/ 포맷이 Claude Code에 종속된 것이 아니라, 여러 AI 코딩 도구에서 공통으로 사용할 수 있는 표준이 되었음을 의미한다.

참고 문서

• Extend Claude with skills - Official Claude Code Docs
• Claude Code Evolution: MCP, Commands, Agents & Skills
• Claude Code Merges Slash Commands Into Skills - Medium
• Anthropic makes agent Skills an open standard - SiliconANGLE
• Equipping agents for the real world with Agent Skills - Anthropic Engineering
• Agent Skills Overview - agentskills.io