[Claude Code] 명령어 및 스킬(Skills) 시스템 정리

1. 도입부 (Introduction)

Claude Code를 처음 설치하고 나면 터미널에서 말을 거는 것만으로도 신기함을 느낀다. 하지만 복잡한 프로젝트를 진행하다 보면 매번 똑같은 코딩 규칙을 설명하거나, 특정 분석 스크립트를 실행해 달라고 부탁하는 것이 번거로워지는 순간이 온다.

Claude Code의 진정한 가치는 사용자가 직접 모델의 행동 양식을 정의하고 기능을 확장할 수 있는 '명령어(Commands)'와 '스킬(Skills)' 시스템에 있다. 이 시스템을 이해하면 Claude는 단순한 챗봇이 아니라, 내 프로젝트의 맥락을 완벽히 이해하고 복잡한 작업을 병렬로 수행하는 '팀장급 에이전트'로 진화한다.
오늘은 공식 문서를 기준으로 이 강력한 도구들을 어떻게 내 입맛에 맞게 요리할 수 있는지 심층적으로 분석해 본다.

 

2. 주요 특징 및 핵심 로직 (Main Features & Logic)

Claude Code의 제어 시스템은 '고정형 제어'와 '유연한 확장'이라는 두 축으로 설계되었다.

1. 명령어 (Commands): 세션 상태 관리, 설정 변경, 모델 전환 등 CLI 자체의 로직을 제어한다. /로 시작하며 즉각적이고 결정론적인 동작을 보장한다.
2. 스킬 (Skills): SKILL.md 파일을 통해 정의되는 '프롬프트 기반 확장 도구'다. 상황에 따라 모델이 스스로 판단하여 사용하거나 사용자가 직접 호출할 수 있다.

 

💡 왜 '스킬'인가? (On-demand Context)

모든 규칙을 CLAUDE.md에 때려 넣으면 모델이 읽어야 할 토큰이 기하급수적으로 늘어나 비용이 상승하고 집중력이 떨어진다. 반면 스킬은 해당 기능이 호출되는 순간에만 관련 지침을 로드하므로, 토큰 비용 절감과 성능 최적화라는 두 마리 토끼를 동시에 잡는 핵심 전략이다.

 

3. 상세 가이드 1: 핵심 명령어(Commands) 정리

명령어는 대화 시작 부분에 /를 입력하여 실행한다. 작업 흐름에 따라 필수 명령어들을 나눴다.

📌 3.1 세션 및 상태 관리

명령어	목적	전문가의 팁
/clear	대화 초기화	컨텍스트가 너무 차서 답변이 느려질 때 사용하라. (메모리는 보존됨)
/compact	대화 압축	긴 대화의 핵심만 요약하여 남기고 토큰 공간을 확보한다.
/resume	이전 세션 재개	어제 작업하던 흐름을 그대로 터미널로 불러올 때 필수다.
/rewind	체크포인트 되감기	코딩이 꼬였을 때 특정 시점의 대화와 코드로 안전하게 롤백한다.

 

📌 3.2 지능 및 출력 제어

명령어	목적	전문가의 팁
/effort	지능 수준 조절	슬라이더를 통해 low(단순 작업)부터 xhigh(복잡한 버그 수정)까지 즉시 변경 가능하다.
/model	모델 전환	sonnet, opus, haiku 사이를 오가며 지능과 비용의 균형을 맞춘다.
/config	설정 패널	테마, 편집기 모드(Vim/Normal), 출력 스타일 등을 GUI 없이 탭 형식으로 조정한다.

 

📌 3.3 분석 및 리뷰 (Skills 기반 명령어)

명령어	목적	전문가의 팁
/simplify	코드 최적화	최근 변경된 파일의 품질을 검토하고 불필요한 로직을 제거한다.
/review	로컬 PR 리뷰	현재 브랜치의 변경 사항을 시니어 개발자의 시각에서 검토한다.
/security-review	보안 취약점 분석	인젝션 위험이나 데이터 노출 등 보안 이슈를 집중적으로 탐지한다.

 

 

4. 상세 가이드 2: 사용자 정의 스킬 (Skills) 심층 분석

스킬은 특정 워크플로우를 자동화하는 '지능형 모듈'이다.

📌 4.1 스킬의 해부학: SKILL.md 구조

각 스킬은 고유한 디렉토리 내의 SKILL.md 파일로 정의된다.

• YAML Frontmatter (설정부): 스킬의 메타데이터와 권한을 정의한다.
• Markdown Content (지침부): 모델이 실제로 수행할 구체적인 단계와 규칙이다.

 

📌 4.2 핵심 변수 및 치환 (Substitutions)

스킬 지침 내에서 아래 변수들을 활용하면 동적인 프롬프트 생성이 가능하다.

• $ARGUMENTS: 사용자가 /스킬이름 [인수] 형식으로 전달한 전체 텍스트.
• $N: 특정 순서의 인수 (예: $0은 첫 번째 단어).
• ${CLAUDE_SKILL_DIR}: 해당 스킬 파일이 위치한 물리적 경로 (스크립트 실행 시 유용).

 

📌 4.3 동적 컨텍스트 주입 기법 (!)

스킬 실행 직전 터미널 명령어를 실행하고 그 결과물을 프롬프트에 인라인으로 삽입한다. 이는 Claude가 '현재 시스템의 실시간 상태'를 알게 만드는 마법 같은 도구다.

 

5. 실전 예제 코드

💻 예제 1: 실시간 변경 사항 요약 에이전트

사용자가 무엇을 고쳤는지 물어볼 때 실시간 git diff를 가져와 분석하는 스킬이다.

경로: ~/.claude/skills/summarize-changes/SKILL.md

---
name: summarize-changes
description: 커밋되지 않은 변경 사항을 요약하고 잠재적 위험을 경고합니다. 사용자가 "뭐가 변했지?"라고 물을 때 자동 활성화됩니다.
allowed-tools: Bash(git diff *)
---
# 현재 프로젝트 변경 사항
다음은 현재 작업 트리의 실시간 Diff 데이터입니다:

!`git diff HEAD`

# 지침
1. 위 변경 사항을 개발자 관점에서 3개의 글머리 기호로 요약하세요.
2. 하드코딩된 값, 누락된 에러 핸들링, 테스트 업데이트 필요 여부를 반드시 체크하세요.
3. Diff가 비어있다면 "수정된 내용이 없습니다."라고 답변하세요.

 

💻 예제 2: 독립형 보안 감사 에이전트 (context: fork)

메인 대화의 간섭 없이 특정 파일만 떼어내어 정밀 보안 진단을 수행하는 스킬이다.

경로: ~/.claude/skills/audit-security/SKILL.md

---
name: audit-security
description: 특정 파일의 보안 취약점을 독립적으로 분석합니다.
context: fork  # 현재 대화와 격리된 새로운 에이전트 환경에서 실행
agent: Explore # 탐색에 최적화된 서브에이전트 유형 사용
arguments: [target_file]
---
당신은 보안 화이트 해커입니다.
`$target_file`을 정밀 조사하여 다음 항목을 체크하세요:
- SQL Injection 위험
- 취약한 인증 로직
- 환경 변수로 처리되지 않은 민감 정보

분석 결과를 위협 수준(High/Medium/Low)별로 분류하여 보고서를 제출하세요.

 

 

6. 실무 활용 팁 및 주의사항

1. 설명(Description)의 구체성: Claude가 스킬을 자동으로 로드하게 하려면 description에 사용자가 평소에 물어볼 법한 키워드(예: "리팩토링", "배포", "로그 확인")를 반드시 포함해야 한다.
2. 권한(Allowed Tools) 설정: allowed-tools 필드에 실행할 Bash 명령어를 미리 승인해 두면, 에이전트가 작업 도중 "실행할까요?"라고 묻는 횟수가 줄어들어 흐름이 끊기지 않는다.
3. 지침의 간결함: 스킬 본문이 너무 길면 매 턴마다 토큰을 소모한다. "어떻게" 하는지 구구절절 설명하기보다 "무엇을" 해야 하는지 명확한 단계(Step) 위주로 기술하라.
4. 시각적 출력 활용: 스킬 내에서 Python 스크립트를 실행해 HTML 보고서를 생성하고 webbrowser.open()을 호출하게 하면, 터미널을 넘어 브라우저에 대화형 차트를 띄우는 고도화된 경험이 가능하다.

 

 

7. 마무리하며

Claude Code의 명령어와 스킬 시스템은 '수동적인 도구'를 '능동적인 파트너'로 바꾸는 핵심 열쇠다.

필요할 때만 호출되는 온디맨드 스킬 설계를 통해 토큰을 절약하고, 동적 컨텍스트 주입으로 모델에게 실시간 데이터라는 장점을 이용할 수 있다. 

참고 자료:

• Claude Code 명령어 완전 참조
• Skills 개방형 표준 가이드 (agentskills.io)
• Anthropic 공식 도구 사용(Tool Use) 가이드