Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Claude Code에서 재사용 가능한 워크플로우를 만드는 'Skill' 메커니즘의 설계와 구현 방법을 설명합니다. Markdown 파일을 기반으로 명령어를 정의하고, 세션 종료 기록이나 리스크 체크와 같은 실무 패턴을 구축하는 가이드를 제공합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기Claude Code에는 「Skill」이라고 불리는 메커니즘이 있습니다. /session-close나 /risk-check와 같이 /로 시작하는 명령어를 직접 정의할 수 있습니다.
「매번 같은 절차를 밟는 조작」을 Skill로 만들어 두면, 한마디로 호출할 수 있는 재사용 가능한 워크플로우가 됩니다. 이 기사에서는 Skill의 정의 방법부터 실제로 사용할 수 있는 패턴까지 해설합니다.
Claude Code의 세션 내에서 /명령어이름을 입력하면 실행되는 워크플로우 정의입니다.
/session-close ← 세션 종료 시 기록을 수행
/risk-check ← 공개 전 콘텐츠를 체크
/add-task ← 태스크 큐에 카드를 추가
내부적으로는 .claude/skills/<스킬이름>/SKILL.md라는 Markdown 파일을 읽어서, Claude Code가 해당 절차를 실행합니다.
.claude/
└── skills/
├── session-close/
...
각 스킬은 디렉토리 단위로 관리합니다. 향후에 지원 파일(support file)을 추가할 수 있기 때문입니다.
---
name: my-skill
description: "이 Skill이 무엇을 하는지 (1~2행)"
...
스킬의 식별자. /my-skill로 호출할 때 사용합니다.
영문 소문자 + 하이픈으로 명명합니다.
Claude Code가 「이 Skill을 사용해야 하는가」를 판단할 때 참조합니다.
「무엇을 하는가」뿐만 아니라 「언제 사용하는가」를 1~2행으로 작성하면 정확도가 높아집니다.
# 나쁜 예
description: "파일을 체크한다"
# 좋은 예
...
true로 설정하면 /skill-name으로 호출할 수 있습니다.
false로 설정하면 다른 Skill이나 Agent로부터 호출하는 전용이 됩니다.
이 Skill이 사용할 수 있는 도구(tool) 리스트. 사용하지 않는 도구는 제외해 둡니다.
| 도구 | 용도 |
|---|---|
| Read | 파일 읽기 |
| ... |
/skill-name 뒤에 이어질 수 있는 인자(argument)의 형식. 명령어 보완(command completion) 힌트로 표시됩니다.
argument-hint: "<file_path> [--target zenn|booth]"
매 세션의 작업 내용·토큰 소비·실수를 기록하는 Skill입니다.
---
name: session-close
description: "세션 종료 전에 실행하여, 작업 로그·토큰 개략치·실수를
...
오늘: 2026-05-16
로그: logs/daily/2026-05-16.md
그 파일을 Read로 확인한다. 없다면 템플릿을 만든다.
### Step 2: 작업 요약을 구성한다
이 세션에서 수행한 일을 되돌아보고, 다음을 열거한다:
...
중요한 것은 Step 구조로 절차를 명확히 하는 것입니다. Claude는 긴 절차서라도 순서대로 실행하지만, 모호한 지시가 있으면 해석이 엇갈립니다.
---
name: risk-check
description: "공개 전 콘텐츠(기사·상품 설명)에 대해 리스크 검사를 실행한다.
...
```bash
# API 키
grep -nE 'sk-[a-zA-Z0-9]{20,}' "$TARGET"
# 수익 관련 수치 (교육적 언급은 대상 외)
grep -nE '売上[：:].*[0-9,]+円|収益[：:].*[0-9,]+円' "$TARGET"
...
【결과】 ⚠ 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는 절차서를 읽고 실행합니다. 모호함이 있으면 해석이 세션마다 달라질 수 있습니다.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
와 같이 전부 적으면 의도하지 않은 도구를 사용할 수 있습니다.
체크 계열의 Skill에는 Write/Edit이 필요하지 않습니다. 필요한 도구만 적습니다.
# 좋은 예에 추가
### 에러 케이스
- 대상 파일을 찾을 수 없는 경우: 에러를 보고하고 종료한다
...
Claude는 지시사항에 적혀 있지 않은 상황에 직면하면 해석이 흔들릴 수 있습니다.
name은 영문 소문자 + 하이픈(-)description은 "언제 사용하는지"까지 작성함allowed-tools는 필요 최소한으로 제한함### Step N: 구조로 명확하게 작성함한 번 만든 Skill은 반복해서 사용할 수 있습니다. 정형화된 작업이 늘어날 때마다 Skill화하는 습관을 들이면, "매번 똑같은 설명을 하는" 수고를 덜 수 있습니다.
이 기사는 Claude(claude-sonnet-4-6)가 초안을 작성하고, 인간(CEO)이 확인 및 편집을 수행합니다.
