[Claude Code] commands가 skills로 통합됐다 - SKILL.md 작성법 완전 정리

 

Claude Code를 쓰다 보면 같은 지침을 채팅에 반복해서 붙여넣게 된다. 코드 리뷰 기준, 커밋 규칙, 배포 절차 같은 것들이다. CLAUDE.md가 점점 절차서로 변해간다면 이미 signals가 왔다는 뜻이다.

Anthropic은 이 문제를 해결하기 위해 기존 .claude/commands/ 방식을 skills로 통합했다. Claude Code v2.1.101(2026년 4월 11일)부터 커스텀 커맨드와 skills는 같은 체계로 동작한다.

 

출처 : https://code.claude.com/docs/ko/skills

 

기존 .claude/commands/deploy.md와 새로운 .claude/skills/deploy/SKILL.md는 둘 다 /deploy 커맨드를 만든다. 기존 파일은 그대로 작동한다. Skills가 디렉토리 구조, frontmatter 제어, Claude 자동 로드 기능을 추가로 지원한다.

 

바뀐 핵심 구조

 

Skills는 디렉토리 단위다. 각 skill은 SKILL.md를 진입점으로 하는 폴더다.

my-skill/
├── SKILL.md # 주요 지침 (필수)
├── template.md # Claude가 채울 템플릿
├── examples/
│ └── sample.md # 예상 출력 예시
└── scripts/
└── validate.sh # Claude가 실행할 스크립트

 

저장 위치에 따라 적용 범위가 결정된다.

 

위치	경로	적용 대상
Enterprise	관리 설정 참조	조직 전체 사용자
Personal	~/.claude/skills/<이름>/SKILL.md	모든 프로젝트
Project	.claude/skills/<이름>/SKILL.md	해당 프로젝트만
Plugin	<plugin>/skills/<이름>/SKILL.md	플러그인 활성화 위치

 

사용 방법

 

1단계: skill 디렉토리 생성

개인 skills 폴더에 디렉토리를 만든다. 디렉토리 이름이 곧 슬래시 커맨드 이름이 된다.

mkdir -p ~/.claude/skills/summarize-changes

 

프로젝트 전용으로 만들려면 리포지토리 내 .claude/skills/ 아래에 생성한다.

 

2단계: SKILL.md 작성

SKILL.md는 두 부분으로 구성된다. YAML frontmatter와 마크다운 지침이다.

---
name: summarize-changes
description: 커밋되지 않은 변경 사항을 요약하고 위험 항목을 표시한다. 사용자가 변경된 내용을 물어보거나 커밋 메시지를 요청할 때 사용.
---

## 현재 변경 사항

!`git diff HEAD`

## 지침

위 변경 사항을 2~3개 요점으로 요약한 뒤, 누락된 에러 처리·하드코딩 값·갱신이 필요한 테스트 등 위험 항목을 나열한다. diff가 비어 있으면 커밋되지 않은 변경 사항이 없다고 말한다.

 

!`git diff HEAD` 줄은 동적 컨텍스트 주입이다. Claude가 skill을 보기 전에 명령어가 실행되고, 출력이 그 자리를 대체한다. Claude는 추측이 아닌 실제 diff를 기반으로 응답한다.

 

3단계: 호출 방식 선택

skill을 누가 언제 호출하는지를 frontmatter로 제어한다.

 

Frontmatter	사용자 호출	Claude 자동 호출	설명
(기본값)	O	O	관련 있을 때 Claude가 자동으로 로드
disable-model-invocation: true	O	X	/deploy처럼 수동으로만 쓸 때
user-invocable: false	X	O	배경 지식형, / 메뉴에 안 보임

 

배포·커밋처럼 타이밍을 직접 제어하고 싶은 skill에는 disable-model-invocation: true를 쓴다. Claude가 코드가 준비됐다고 판단해 혼자 배포하는 일을 막는다.

 

적용 전후 비교

 

Before (기존 commands 방식):

# .claude/commands/deploy.md
Deploy the application to production:
1. Run tests
2. Build
3. Push

 

After (skills 방식 - frontmatter 추가):

# .claude/skills/deploy/SKILL.md
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
allowed-tools: Bash(git *) Bash(npm *)
---

Deploy $ARGUMENTS to production:
1. Run tests
2. Build
3. Push
4. Verify deployment

 

기존 파일은 그대로 두어도 동작하고, skill로 마이그레이션하면 지원 파일·자동 트리거·도구 사전 승인 기능이 추가된다.

 

주요 Frontmatter 필드

 

필드	설명
description	Claude가 자동 사용 여부를 판단하는 기준. 주요 트리거 키워드를 앞에 배치한다
disable-model-invocation	true면 사용자만 호출 가능. /deploy, /commit 같은 작업형 skill에 사용
allowed-tools	skill 활성화 시 승인 없이 사용할 도구 목록
context: fork	격리된 subagent에서 실행. 대화 기록에 접근하지 않음
agent	fork 실행 시 사용할 에이전트 유형 (Explore, Plan, general-purpose 등)
model	이 skill이 활성화될 때 사용할 모델 재정의
paths	특정 파일 패턴으로 작업할 때만 skill 활성화
shell	bash(기본값) 또는 powershell 선택

 

기대 효과

 

1. 반복 지침 제거

같은 내용을 매번 채팅에 붙여넣지 않아도 된다. skill은 Claude가 관련 컨텍스트를 감지하면 자동으로 로드하거나, /name으로 직접 호출한다. CLAUDE.md는 사실 기반 정보로만 유지할 수 있다.

 

2. 컨텍스트 비용 최소화

CLAUDE.md에 절차가 담기면 매 턴마다 토큰을 소모한다. Skills는 호출될 때만 로드되므로 긴 참조 자료도 필요할 때까지 비용이 거의 들지 않는다.

 

3. 도구 권한 세밀 제어

allowed-tools 필드로 이 skill이 활성화된 동안만 특정 도구를 승인 없이 허용한다. 전역 권한을 풀지 않고도 skill 단위로 도구 접근을 제어한다.

 

4. 세션 재시작 없이 즉시 반영

Claude Code는 skill 디렉토리를 실시간으로 감시한다. ~/.claude/skills/ 또는 .claude/skills/에서 파일을 추가·편집·제거하면 현재 세션에 바로 적용된다.

 

참고 자료:

https://code.claude.com/docs/ko/skills

https://code.claude.com/docs/ko/commands