Claude Code에는 「Skill」이라고 불리는 메커니즘이 있습니다. /session-close나 /risk-check와 같이 /로 시작하는 명령어를 직접 정의할 수 있습니다.

「매번 같은 절차를 밟는 조작」을 Skill로 만들어 두면, 한마디로 호출할 수 있는 재사용 가능한 워크플로우가 됩니다. 이 기사에서는 Skill의 정의 방법부터 실제로 사용할 수 있는 패턴까지 해설합니다.

Skill이란

Claude Code의 세션 내에서 /명령어이름을 입력하면 실행되는 워크플로우 정의입니다.

/session-close ← 세션 종료 시 기록을 수행
/risk-check ← 공개 전 콘텐츠를 체크
/add-task ← 태스크 큐에 카드를 추가

내부적으로는 .claude/skills/<스킬이름>/SKILL.md라는 Markdown 파일을 읽어서, Claude Code가 해당 절차를 실행합니다.

파일 구조

.claude/
└── skills/
    ├── session-close/
    ...

각 스킬은 디렉토리 단위로 관리합니다. 향후에 지원 파일(support file)을 추가할 수 있기 때문입니다.

SKILL.md의 기본 포맷

---
name: my-skill
description: "이 Skill이 무엇을 하는지 (1~2행)"
...

frontmatter 필드 상세 해설

name

스킬의 식별자. /my-skill로 호출할 때 사용합니다.

영문 소문자 + 하이픈으로 명명합니다.

description

Claude Code가 「이 Skill을 사용해야 하는가」를 판단할 때 참조합니다.

「무엇을 하는가」뿐만 아니라 「언제 사용하는가」를 1~2행으로 작성하면 정확도가 높아집니다.

# 나쁜 예
description: "파일을 체크한다"
# 좋은 예
...

user-invocable

true로 설정하면 /skill-name으로 호출할 수 있습니다.

false로 설정하면 다른 Skill이나 Agent로부터 호출하는 전용이 됩니다.

allowed-tools

이 Skill이 사용할 수 있는 도구(tool) 리스트. 사용하지 않는 도구는 제외해 둡니다.

도구	용도
Read	파일 읽기
...

argument-hint

/skill-name 뒤에 이어질 수 있는 인자(argument)의 형식. 명령어 보완(command completion) 힌트로 표시됩니다.

argument-hint: "<file_path> [--target zenn|booth]"

실제 Skill의 예

세션 종료 기록 Skill

매 세션의 작업 내용·토큰 소비·실수를 기록하는 Skill입니다.

---
name: session-close
description: "세션 종료 전에 실행하여, 작업 로그·토큰 개략치·실수를
...

오늘: 2026-05-16

로그: logs/daily/2026-05-16.md

그 파일을 Read로 확인한다. 없다면 템플릿을 만든다.
### Step 2: 작업 요약을 구성한다
이 세션에서 수행한 일을 되돌아보고, 다음을 열거한다:
...

중요한 것은 Step 구조로 절차를 명확히 하는 것입니다. Claude는 긴 절차서라도 순서대로 실행하지만, 모호한 지시가 있으면 해석이 엇갈립니다.

공개 전 체크 Skill

---
name: risk-check
description: "공개 전 콘텐츠(기사·상품 설명)에 대해 리스크 검사를 실행한다.
...
```bash
# API 키
grep -nE 'sk-[a-zA-Z0-9]{20,}' "$TARGET"
# 수익 관련 수치 (교육적 언급은 대상 외)
grep -nE '売上[：:].*[0-9,]+円|収益[：:].*[0-9,]+円' "$TARGET"

Step 3: 내용 검사 (WARN 조건)

...

【결과】 ⚠ WARN — 확인이 필요한 사항이 있습니다

---
## Skill 설계 패턴
### 패턴 1: 체크 & 리포트형
무언가를 검사하여 결과를 보고하는 Skill. 부작용(side effect) 없음.

/risk-check → PASS/WARN/BLOCK을 보고할 뿐. 파일은 변경하지 않음.

설계 포인트:
- `allowed-tools`에 Write/Edit을 포함하지 않음
- 보고 포맷을 고정함 (다음 액션이 명확해지도록 함)
- "이 Skill은 파일을 변경하지 않음"이라고 명시함

### 패턴 2: 기록 추가형
로그 파일에 정보를 추가하는 Skill.

/session-close → logs/daily/YYYY-MM-DD.md의 끝에 추가함

설계 포인트:
- 멱등성 (Idempotency)을 의식함 (몇 번을 실행해도 같은 결과가 나오도록 함)
- 기존 파일을 덮어쓰지 않음. 추가(Append)하는 설계로 함
- 파일이 존재하지 않을 경우의 동작을 명시함

### 패턴 3: 태스크 생성형
큐(Queue)나 티켓에 엔트리를 추가하는 Skill.

/add-task 기사 작성 --dept writer-team --pri 2

...

설계 포인트:
- 인자(Argument) 파싱 절차를 명확하게 작성함
- 생성할 파일의 명명 규칙을 고정함
- "생성만 수행함. 다른 조작은 하지 않음"이라고 명시함

### 패턴 4: 배분형
입력을 판단하여 다른 처리로 분배하는 Skill.

/dispatch 태스크 내용

...

설계 포인트:
- 판단 기준 테이블을 작성함
- 판단할 수 없는 경우의 폴백 (Fallback)을 명시함
- 실행은 "배분"만 수행. 처리 자체는 각 담당자에게 맡김

---

## Agent와 Skill의 차이를 의식하기
동일한 처리를 Skill로 할지 Agent로 할지 고민될 때가 있습니다.

| | Skill | Agent |
|---|---|---|
| 컨텍스트 | 메인과 공유 | 독립된 새로운 컨텍스트 |
| ... | 기준: **"30초 안에 끝나는가?"** | |
| | 끝남 → Skill | 끝나지 않음 → Agent |

---

## 자주 발생하는 실수

### 실수 1: 절차가 모호함
```markdown
# 나쁜 예
## 실행 절차
콘텐츠를 체크하여 문제가 있으면 보고한다.
...

Claude는 절차서를 읽고 실행합니다. 모호함이 있으면 해석이 세션마다 달라질 수 있습니다.

실수 2: allowed-tools를 제한하지 않음

allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch

와 같이 전부 적으면 의도하지 않은 도구를 사용할 수 있습니다.

체크 계열의 Skill에는 Write/Edit이 필요하지 않습니다. 필요한 도구만 적습니다.

실수 3: 에러 케이스를 작성하지 않음

# 좋은 예에 추가
### 에러 케이스
- 대상 파일을 찾을 수 없는 경우: 에러를 보고하고 종료한다
...

Claude는 지시사항에 적혀 있지 않은 상황에 직면하면 해석이 흔들릴 수 있습니다.

요약: Skill 설계 체크리스트

• name은 영문 소문자 + 하이픈(-)
• description은 "언제 사용하는지"까지 작성함
• allowed-tools는 필요 최소한으로 제한함
• 절차는 ### Step N: 구조로 명확하게 작성함
• 보고 포맷을 고정함
• 에러 케이스를 작성함
• "이 Skill이 변경하는 것 / 변경하지 않는 것"을 명시함

한 번 만든 Skill은 반복해서 사용할 수 있습니다. 정형화된 작업이 늘어날 때마다 Skill화하는 습관을 들이면, "매번 똑같은 설명을 하는" 수고를 덜 수 있습니다.

이 기사는 Claude(claude-sonnet-4-6)가 초안을 작성하고, 인간(CEO)이 확인 및 편집을 수행합니다.

Discussion