[이제와서 시작하는 Claude AI 마스터하기 #11] Skills: 나만의 명령어 만들기

반복되는 작업이 있나요? “PR 만들어줘”, “코드 리뷰해줘”… 매번 같은 지시를 내리기 번거롭죠. Skills를 사용하면 나만의 /slash-command를 만들어서 복잡한 지시를 한 단어로 실행할 수 있습니다!

완독 시간: 25분 ⭐⭐⭐

🎯 이번에 배울 것

• Skill이란 무엇인가
• 첫 번째 Skill 만들기
• SKILL.md 구조 이해하기
• 인자 전달하기
• 실전 Skill 예제

📚 사전 지식

• #10편: CLAUDE.md 완전 정복 - 메모리 시스템 이해

---

📖 Skill이란 무엇인가?

한 줄 설명

Skill = 재사용 가능한 Claude 지시서

SKILL.md 파일을 만들면 /skill-name으로 바로 실행할 수 있습니다.

CLAUDE.md vs Skill

구분	CLAUDE.md	Skill
역할	항상 적용되는 규칙	필요할 때 호출하는 명령
로딩	세션 시작 시 자동	호출 시에만 로드
형태	배경 지식, 컨텍스트	구체적인 작업 지시
예시	“2-space 들여쓰기”	“/review - 코드 리뷰 수행”

실제 사용 흐름

flowchart LR
    A[/review] --> B[SKILL.md 로드]
    B --> C[지시사항 실행]
    C --> D[결과 출력]

사용자: /review

Claude: (SKILL.md 내용 읽고)
        코드 리뷰를 시작합니다.
        1. 변경된 파일 확인 중...
        2. 코드 품질 검사 중...
        3. 리뷰 완료!

---

🛠️ 첫 번째 Skill 만들기

Step 1: Skill 디렉토리 생성

개인 Skill (모든 프로젝트에서 사용):

mkdir -p ~/.claude/skills/explain-code

프로젝트 Skill (이 프로젝트에서만):

mkdir -p .claude/skills/explain-code

Step 2: SKILL.md 작성

~/.claude/skills/explain-code/SKILL.md:

---
name: explain-code
description: 코드를 비유와 다이어그램으로 친절하게 설명합니다. "이거 어떻게 동작해?"라고 물을 때 사용하세요.
---

코드를 설명할 때 항상 다음을 포함하세요:

1. **비유로 시작**: 일상생활에 비유해서 설명
2. **다이어그램 그리기**: ASCII 아트로 흐름/구조 시각화
3. **단계별 설명**: 코드가 실행되는 순서대로 설명
4. **주의점 강조**: 흔한 실수나 오해하기 쉬운 부분

설명은 대화하듯 친근하게 해주세요.

Step 3: 사용하기

/explain-code src/auth/login.ts

또는 Claude가 관련 질문을 받으면 자동으로 이 Skill을 사용합니다:

이 코드 어떻게 동작해?

---

📋 SKILL.md 구조 이해하기

기본 구조

---
(YAML Frontmatter - 메타데이터)
---

(Markdown Body - 실제 지시사항)

Frontmatter 필드

필드	필수	설명
name	❌	Skill 이름 (없으면 폴더명 사용)
description	⭐ 권장	Claude가 자동 호출할 때 참고
disable-model-invocation	❌	true면 수동 호출만 가능
user-invocable	❌	false면 / 메뉴에서 숨김
allowed-tools	❌	허용할 도구 목록
model	❌	사용할 모델 지정
context	❌	fork면 Subagent로 실행

호출 제어하기

1. 자동 + 수동 호출 (기본)

---
name: explain-code
description: 코드 설명 요청시 사용
---

• /explain-code로 직접 호출 가능
• “이거 어떻게 동작해?” 물으면 Claude가 자동 호출

2. 수동 호출만

---
name: deploy
description: 프로덕션 배포
disable-model-invocation: true
---

• /deploy로만 실행 가능
• Claude가 마음대로 호출하면 안 되는 작업에 사용

3. Claude 자동 호출만

---
name: legacy-context
description: 레거시 시스템 관련 배경 지식
user-invocable: false
---

• / 메뉴에 표시 안 됨
• Claude가 필요할 때 자동으로 참조

---

📥 인자 전달하기

$ARGUMENTS 사용

---
name: fix-issue
description: GitHub 이슈 수정
disable-model-invocation: true
---

GitHub 이슈 $ARGUMENTS 를 수정합니다.

1. 이슈 내용 읽기
2. 요구사항 파악
3. 코드 수정
4. 테스트 작성
5. 커밋 생성

사용:

/fix-issue 123

$ARGUMENTS가 123으로 치환됩니다.

위치별 인자 접근

---
name: migrate
description: 컴포넌트 마이그레이션
---

$ARGUMENTS[0] 컴포넌트를 $ARGUMENTS[1]에서 $ARGUMENTS[2]로 마이그레이션합니다.

사용:

/migrate SearchBar React Vue

• $ARGUMENTS[0] = SearchBar (또는 $0)
• $ARGUMENTS[1] = React (또는 $1)
• $ARGUMENTS[2] = Vue (또는 $2)

인자가 없을 때

Skill 내용에 $ARGUMENTS가 없으면 Claude가 자동으로 끝에 추가합니다:

ARGUMENTS: 사용자가 입력한 내용

---

⚡ 동적 컨텍스트 주입

!command 문법

쉘 명령을 실행하고 결과를 Skill에 주입할 수 있습니다:

---
name: pr-summary
description: PR 요약
context: fork
---

## PR 정보
- Diff: !`gh pr diff`
- 코멘트: !`gh pr view --comments`
- 변경 파일: !`gh pr diff --name-only`

## 요청
이 PR을 요약해주세요...

동작 방식:

1. !command``가 먼저 실행됨
2. 출력이 해당 위치에 삽입됨
3. 완성된 프롬프트가 Claude에게 전달됨

---

🔀 Subagent에서 실행하기

복잡한 Skill은 독립된 컨텍스트에서 실행하면 좋습니다.

context: fork 사용

---
name: deep-research
description: 심층 리서치
context: fork
agent: Explore
---

$ARGUMENTS 에 대해 철저히 조사합니다:

1. Glob과 Grep으로 관련 파일 찾기
2. 코드 읽고 분석
3. 파일 참조와 함께 결과 요약

장점:

• 메인 대화 컨텍스트를 오염시키지 않음
• 읽기 전용 Explore 에이전트 사용
• 결과만 요약해서 반환

agent 옵션

값	설명
Explore	읽기 전용, 탐색 최적화
Plan	계획 수립용
general-purpose	모든 도구 사용 가능
(커스텀)	.claude/agents/의 커스텀 에이전트

---

📦 Skill 저장 위치

위치	적용 범위	우선순위
.claude/skills/	이 프로젝트만	높음
~/.claude/skills/	모든 프로젝트	중간
Plugin 내 skills/	Plugin 활성화 시	낮음 (네임스페이스 적용)

같은 이름의 Skill이 여러 곳에 있으면 높은 우선순위가 적용됩니다.

💡 서브디렉토리의 .claude/skills/도 자동으로 발견됩니다. 중첩된 프로젝트 구조에서도 Skill이 정상 동작합니다.

Skill 캐릭터 예산

Skill의 description은 컨텍스트에 로드되어 Claude가 자동 호출 여부를 판단합니다. 예산은 컨텍스트 윈도우의 2% 로 동적 조절됩니다. Skill이 너무 많아서 잘릴 때는 SLASH_COMMAND_TOOL_CHAR_BUDGET 환경변수로 제한을 조정하세요.

---

🧩 Plugins: Skill 배포하기

Skill을 팀이나 커뮤니티와 공유하려면 Plugin으로 패키징할 수 있습니다.

Plugin과 독립 Skill의 차이

독립 Skill (.claude/)	Plugin
단일 프로젝트 전용	여러 프로젝트에서 재사용
/hello로 호출	/plugin-name:hello로 호출
Git으로 수동 공유	Marketplace로 배포

Plugin 구조 예시

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # 플러그인 메타데이터
├── skills/
│   └── code-review/
│       └── SKILL.md      # Agent Skill
├── commands/
│   └── hello.md          # 슬래시 명령어
├── agents/
│   └── debugger.md       # 커스텀 에이전트
├── hooks/
│   └── hooks.json        # 이벤트 핸들러
└── .mcp.json             # MCP 서버 설정

Plugin 로컬 테스트

claude --plugin-dir ./my-plugin

자세한 내용은 Plugin 공식 문서를 참고하세요.

---

🧪 실전 Skill 예제

예제 1: 코드 리뷰어

---
name: review
description: 코드 변경사항을 리뷰합니다. 코드 작성 후 자동으로 사용하세요.
allowed-tools: Read, Grep, Glob, Bash
---

코드 리뷰를 수행합니다:

1. `git diff`로 변경사항 확인
2. 수정된 파일 분석

## 리뷰 체크리스트
- [ ] 코드가 명확하고 읽기 쉬운가?
- [ ] 함수/변수 이름이 적절한가?
- [ ] 중복 코드는 없는가?
- [ ] 에러 처리가 되어 있는가?
- [ ] 보안 취약점은 없는가?
- [ ] 테스트가 충분한가?

## 출력 형식
우선순위별로 피드백 정리:
- 🔴 Critical (필수 수정)
- 🟡 Warning (권장 수정)
- 🟢 Suggestion (개선 제안)

예제 2: 커밋 생성기

---
name: commit
description: 변경사항으로 Git 커밋 생성
disable-model-invocation: true
allowed-tools: Bash, Read
---

커밋을 생성합니다:

1. `git status`와 `git diff`로 변경사항 파악
2. Conventional Commits 형식으로 메시지 작성
   - feat: 새 기능
   - fix: 버그 수정
   - refactor: 리팩토링
   - docs: 문서
   - test: 테스트
3. 커밋 실행

메시지는 한글로 작성하되, 타입은 영어로:
예: `feat: 로그인 기능 추가`

예제 3: 코드베이스 시각화 (외부 스크립트)

---
name: visualize
description: 코드베이스를 인터랙티브 HTML로 시각화
allowed-tools: Bash(python *)
---

시각화 스크립트를 실행합니다:

```bash
python ~/.claude/skills/visualize/scripts/visualize.py .

이 스크립트는 codebase-map.html을 생성하고 브라우저에서 엽니다.

시각화 내용

• 접을 수 있는 디렉토리 트리
• 파일 크기 표시
• 파일 타입별 색상 구분 ```

Skill은 보조 파일을 가질 수 있습니다:

visualize/
├── SKILL.md
└── scripts/
    └── visualize.py

---

🔐 Skill 권한 제어

도구 제한

---
name: safe-reader
description: 파일 읽기만 가능한 안전 모드
allowed-tools: Read, Grep, Glob
---

Edit, Write, Bash 등을 제외하여 읽기 전용으로 만듭니다.

Skill 비활성화

설정에서 특정 Skill을 차단:

{
  "permissions": {
    "deny": ["Skill(deploy)"]
  }
}

---

📝 오늘 배운 것 정리

✅ Skill = /slash-command로 호출하는 재사용 지시서

✅ SKILL.md = Frontmatter(메타) + Markdown(지시)

✅ 호출 제어: disable-model-invocation, user-invocable

✅ 인자 전달: $ARGUMENTS, $ARGUMENTS[0], $0…

✅ 동적 컨텍스트: !command``로 실시간 데이터 주입

✅ Subagent 실행: context: fork로 독립 실행

---

🔗 다음 편 미리보기

#12편: Subagents로 AI 분업하기

Skill보다 더 강력한 AI 작업 분담:

• 내장 Subagent (Explore, Plan, general-purpose)
• 커스텀 Subagent 만들기
• 포그라운드 vs 백그라운드 실행
• 영속 메모리로 학습하는 에이전트

---

🔗 시리즈 전체 보기

#	제목	상태
01	Claude AI란? 첫 대화 시작하기	✅ 완료
02	프롬프트 엔지니어링 기초	✅ 완료
03	Claude의 다양한 모델과 선택 가이드	✅ 완료
04	API 활용 첫걸음	✅ 완료
05	고급 프롬프트 테크닉	✅ 완료
06	Claude Projects 활용하기	✅ 완료
07	Claude Code 시작하기	✅ 완료
08	Claude Code 작동 원리	✅ 완료
09	실전 워크플로우	✅ 완료
10	CLAUDE.md 완전 정복	✅ 완료
11	Skills: 나만의 명령어 만들기	📖 현재 글
12	Subagents로 AI 분업하기	✅ 완료
13	MCP로 외부 도구 연결하기	✅ 완료
14	IDE 통합 완벽 가이드	✅ 완료
15	GitHub Actions와 CI/CD 자동화	✅ 완료

---

🔗 참고 자료

• Skills Documentation
• Agent Skills Open Standard

---

🚀 자주 쓰는 작업은 Skill로 만들어두세요!