요약

Skills는 Claude를 전문가로 변환하는 재사용 가능한 파일시스템 기반 기능이다. 프롬프트(한 번용 대화 지시)와 달리 Skills는 맥락을 보고 자동으로 로드되며, 매 대화마다 같은 지식을 반복 제공할 필요가 없다. Commands를 포함하는 상위 개념이다.

---

개념 정리

Commands와의 관계 — 결정적 구분

Commands (.claude/commands/)   →  내가 /명령어로 직접 호출만 가능
Skills (.claude/skills/)       →  Claude가 맥락 보고 자동 로드 + /명령어로도 호출 가능

Skills가 Commands를 포함하는 상위 개념이다. 같은 이름이 있으면 항상 Skill이 우선한다.

.claude/commands/review.md    (Command)
.claude/skills/review/SKILL.md (Skill)
→ 둘 다 있으면 SKILL.md가 실행됨

최신 Claude Code(v2.1.101+)에서는 .claude/commands/가 계속 동작하지만 .claude/skills/가 공식 권장 방식이다.

---

Skills 폴더 구조

~/.claude/skills/skill-name/
├── SKILL.md         ← 핵심 파일 (지시사항 + 프론트매터)
├── scripts/         ← 헬퍼 스크립트
└── templates/       ← 출력 템플릿

레포 실습 파일 3개:

03-skills/
├── code-review/     ← 코드 리뷰 자동화
├── brand-voice/     ← 브랜드 톤/보이스 일관성
└── doc-generator/   ← 문서 자동 생성
    └── generate-docs.py

---

SKILL.md 구조

---
name: code-review
description: 코드 작성 또는 수정 후 자동으로 리뷰. 품질, 보안, 유지보수성 확인.
version: "1.0.0"
tags:
  - code-quality
  - security
---

# Code Review Skill

코드 리뷰 시 항상 이 순서로 확인:
1. 보안 취약점
2. 성능 문제
3. 코드 가독성
4. 테스트 커버리지

description 필드가 핵심이다. Claude가 이 설명을 읽고 자동 호출 여부를 판단한다.

---

description 작성 주의사항

description을 너무 광범위하게 쓰면 문제가 생긴다.

# 나쁜 예
description: Use PROACTIVELY when working with any code
→ 코드 관련 작업마다 무조건 로드
→ 불필요한 토큰 낭비 + 원치 않는 상황에서 선제 반응

# 좋은 예
description: 코드 작성 또는 수정 완료 후 품질, 보안, 유지보수성 리뷰가 필요할 때
→ 정확한 상황에서만 로드됨

---

호출 방법 3가지

# 방법 1: 자동 감지 (description 기반, Claude가 판단)
> 이 코드 리뷰해줘
→ Claude가 code-review skill 자동 로드

# 방법 2: 슬래시 커맨드로 직접 호출
> /code-review

# 방법 3: disable-model-invocation: true 설정 시
→ 사람이 /명령어로만 실행 가능, Claude 자동 실행 불가

---

Skills vs Subagents — 가장 헷갈리는 차이

Skills        →  Claude의 현재 컨텍스트 안에서 실행
                 "이렇게 해줘"라는 지시를 로드하는 것

Subagents     →  독립된 컨텍스트 윈도우에서 실행
                 별도의 AI 인스턴스를 띄우는 것

실무 기준:

간단한 작업 방식 지정, 반복 워크플로우  →  Skill
복잡한 병렬 작업, 깊은 전문화         →  Subagent

---

실습 — code-review Skill 설치

# 전역 설치
cp -r 03-skills/code-review ~/.claude/skills/

# 프로젝트 전용 설치
cp -r 03-skills/code-review .claude/skills/

# 설치 확인 후 테스트
claude
> 이 코드 리뷰해줘   # → 자동으로 code-review skill 로드됨

---

10개 모듈 전체 관계 — 완성형

CLAUDE.md       기억 — 세션 간 컨텍스트 유지
Skills          전문화 — 맥락 기반 자동 로드
Hooks           강제 — 이벤트 발생 시 자동 실행
MCP             연결 — 외부 도구 직접 접근
Subagents       위임 — 독립 컨텍스트 병렬 작업
Checkpoints     안전 — 언제든 되돌리기
CLI             실행 — 모든 걸 터미널에서 제어
Plugins         배포 — 전부 묶어서 팀에 공유
Planning Mode   계획 — 실행 전 검토
Slash Commands  단축 — 반복 작업 한 줄로

---

핵심 요약 (TL;DR)

• Skills = Commands의 상위 개념, 자동 감지 + 수동 호출 모두 가능
• 같은 이름이면 SKILL.md가 .claude/commands/ 파일보다 항상 우선
• description은 구체적으로 써야 함 — 너무 광범위하면 불필요한 토큰 낭비
• Skills는 현재 컨텍스트 안에서 실행, Subagents는 독립 컨텍스트에서 실행
• 10개 모듈 완료 — 이제 전체 구조를 조합해서 실제 자동화를 만들 수 있음

---

다음에 알아볼 것

• 10개 모듈을 조합한 실제 프로젝트 자동화 구축
• 나만의 Skills + Subagents + Hooks + Plugin 직접 제작
• /self-assessment로 전체 학습 수준 자가 진단

---

---

[Series] Claude Code Fundamentals - Skills (Final Module)

Summary

Skills are reusable, filesystem-based capabilities that transform Claude into a specialist. Unlike prompts (one-off conversation instructions), Skills load automatically based on context and eliminate the need to provide the same guidance repeatedly. Skills are a superset of Commands.

---

Key Concepts

Relationship with Commands — The Definitive Distinction

Commands (.claude/commands/)   →  Only invoked when you type /command directly
Skills (.claude/skills/)       →  Auto-loaded by Claude based on context + /command also works

Skills are the superset of Commands. When names conflict, Skills always win.

.claude/commands/review.md      (Command)
.claude/skills/review/SKILL.md  (Skill)
→ If both exist, SKILL.md is executed

In Claude Code v2.1.101+, .claude/commands/ still works but .claude/skills/ is the officially recommended approach.

---

Skills Folder Structure

~/.claude/skills/skill-name/
├── SKILL.md         ← Core file (instructions + frontmatter)
├── scripts/         ← Helper scripts
└── templates/       ← Output templates

Repo practice files:

03-skills/
├── code-review/     ← Automated code review
├── brand-voice/     ← Brand tone/voice consistency
└── doc-generator/   ← Automated documentation
    └── generate-docs.py

---

SKILL.md Structure

---
name: code-review
description: Auto-review after writing or modifying code. Check quality, security, and maintainability.
version: "1.0.0"
tags:
  - code-quality
  - security
---

# Code Review Skill

Always check in this order:
1. Security vulnerabilities
2. Performance issues
3. Code readability
4. Test coverage

The description field is the key. Claude reads it to decide when to auto-invoke the Skill.

---

Writing description — What to Watch Out For

Writing the description too broadly causes problems.

# Bad example
description: Use PROACTIVELY when working with any code
→ Loads on every code-related action
→ Unnecessary token waste + reactive in unwanted situations

# Good example
description: When quality, security, and maintainability review is needed after writing or modifying code
→ Only loads in the right situations

---

3 Ways to Invoke

# Method 1: Auto-detection (based on description, Claude decides)
> Review this code
→ Claude auto-loads code-review skill

# Method 2: Direct slash command
> /code-review

# Method 3: With disable-model-invocation: true
→ Only runs when a person explicitly types the command
→ Claude cannot auto-invoke it

---

Skills vs Subagents — The Most Confusing Difference

Skills     →  Runs within Claude's current context window
              Loads instructions: "do it this way"

Subagents  →  Runs in an isolated context window
              Spawns a separate AI instance

In practice:

Simple workflow specification, repeated tasks  →  Skill
Complex parallel work, deep specialization    →  Subagent

---

Practice — Installing code-review Skill

# Global installation
cp -r 03-skills/code-review ~/.claude/skills/

# Project-specific installation
cp -r 03-skills/code-review .claude/skills/

# Test after installation
claude
> Review this code   # → code-review skill auto-loads

---

All 10 Modules — Complete Picture

CLAUDE.md       Memory — context persists across sessions
Skills          Specialization — auto-loaded based on context
Hooks           Enforcement — auto-runs on lifecycle events
MCP             Connection — direct access to external tools
Subagents       Delegation — parallel work in isolated contexts
Checkpoints     Safety — rewind anytime
CLI             Execution — control everything from terminal
Plugins         Distribution — bundle everything for team sharing
Planning Mode   Planning — review before execution
Slash Commands  Shortcuts — repeat tasks in one line

---

TL;DR

• Skills = superset of Commands, supports both auto-detection and manual invocation
• When names conflict, SKILL.md always takes precedence over .claude/commands/ files
• Write description specifically — too broad causes unnecessary token waste and over-triggering
• Skills run inside the current context; Subagents run in an isolated context
• All 10 modules complete — ready to build real automation by combining them