클로드 스킬(Claude Skills) 이해하기(2) - Claude Code기준 Skills와 Plugins의 차이점 이해하기 : 언제 무엇을 사용할까?

안녕하세요! 갓대희 입니다. :- )

예전에 "클로드 스킬(Claude Skills)" 사용 방법에 대해 글을 작성한 적이 있었다. 

[AI/Claude] - 클로드 스킬(Claude Skills) 사용방법 - Docs,Pptx,Xlsx 스킬 활용 + Custom Skill 등록 해보기

 

요즘들어 이론적인 글을 자주 쓰게 되는 이유는, 실제 AI는 사용하는 개발자의 관련 이해도나 능력, 지시하는 프롬프트에 따라 결과물, 퀄리티가 달라지게 된다. 이런 차이점은 배경지식이 쌓이고 쌓이며, 이해도가 올라감에 따라 차별화가 된다고 생각한다. 그래서 잠깐 다시 Skills를 살펴보고 Plugins에 대한 내용도 짚고 넘어 가고자 글을 작서해 보려 한다.

Claude Code의 확장 시스템: Plugins vs Skills 
Claude Code의 두 가지 핵심 확장 방식인 Plugins과 Skills의 차이점을 공식 문서를 기반으로 분석하고, 실제로 따라 할 수 있는 튜토리얼과 함께 언제 무엇을 사용해야 하는지 살펴보자.

Claude Code는 단순한 AI 코딩 도구를 넘어 개발자가 직접 확장하고 커스터마이징할 수 있는 강력한 플랫폼으로 발전하고 있다. 특히 Plugins과 Skills라는 두 가지 확장 시스템은 개발자들이 반복 작업을 자동화하고, 팀 전체의 워크플로우를 표준화하는 데 핵심적인 역할을 한다.

하지만 이 두 개념의 차이점이 처음에는 명확하지 않을 수 있다. "Skills는 Plugins 안에 포함될 수 있다"는 공식 문서의 설명이 혼란을 줄 수도 있다. 이 글에서는 공식 문서를 기반으로 두 개념의 정확한 정의, 핵심 차이점, 그리고 실제 사용 예시를 통해 언제 무엇을 선택해야 하는지 명확하게 안내한다.

 

핵심 개념 : 한눈에 보는 차이점

본격적인 설명에 앞서, 두 개념의 가장 핵심적인 차이를 먼저 짚어보자.

특성	Skills	Plugins
정의	단일 능력(Capability)	여러 컴포넌트의 번들 패키지
호출 방식	Model-invoked (자동)	User-invoked (명시적)
핵심 파일	SKILL.md	plugin.json
구성요소	지침 + 예시 + 스크립트	Commands + Agents + Skills + Hooks + MCP
배포 범위	개인/프로젝트	마켓플레이스
복잡도	중간	높음

공식 문서 출처
"Skills package expertise into discoverable capabilities. Each Skill consists of a SKILL.md file with instructions that Claude reads when relevant."
(Skills는 전문 지식을 발견 가능한(capability) 형태로 묶어 제공합니다. 각 Skill은 SKILL.md 파일로 구성되며, 여기에는 Claude가 필요할 때 참고하는 지시사항이 포함됩니다.)
Claude Code Skills 공식 문서 →

공식 Skills vs 커스텀 Skills: 무엇이 다른가?

Skills를 사용하는 방법은 크게 두 가지가 있다. 혼동하기 쉬우니 먼저 차이점을 명확히 이해하자.

구분	공식 Plugin 제공 Skills	커스텀 Skills
예시	xlsx, pdf, docx, pptx	commit-helper, code-reviewer 등
Plugin 필요	필요 (document-skills 등)	불필요
사용 방법	/plugin install로 설치	SKILL.md 파일만 만들면 끝
다룬 글	이전 글	이번 글

요약: 이전 글에서 다룬 xlsx, docx 같은 Skills는 공식 Plugin에 포함된 것이라 Plugin 설치가 필요했다. 하지만 커스텀 Skills는 Plugin 없이 독립적으로 동작한다. 이번 글에서는 커스텀 Skills 만드는 법을 중심으로 다룬다.

 

Part 1: Claude Code Skills 이해하기

Skills란 무엇인가?

이전 글에서 작성했으니, 이번 챕터에서는 최대한 간단하게 살펴만 보자.

( 이전 글 참고 : 클로드 스킬(Claude Skills) 사용방법 - Docs,Pptx,Xlsx 스킬 활용 + Custom Skill 등록 해보기 )

 

Skills는 "전문성을 발견 가능한 능력으로 패키징"하는 시스템이다. 각 Skill은 Claude가 관련 상황에서 읽는 지침이 담긴 SKILL.md 파일과 선택적 지원 파일(스크립트, 템플릿 등)로 구성된다.

Model-invoked의 실제 동작
Skills의 가장 중요한 특징은 Claude가 자동으로 발견하고 사용한다는 점이다. 사용자가 "/skill" 같은 명령어를 입력할 필요가 없다.

기술적으로 보면 Claude는 사용자 요청을 분석한 후, 매칭되는 Skill이 있으면 내부적으로 Skill 도구를 호출하여 해당 Skill의 지침을 로드한다. Skill이 활성화되면 <command-message>{skill-name} is running…</command-message> 형태로 표시된다.

Skills 호출 흐름

1. 사용자 요청 입력: "PDF에서 텍스트 추출해줘"
2. description 매칭: Claude가 등록된 Skills의 description 분석
3. Skill 도구 호출: 매칭되는 Skill 발견 시 내부적으로 Skill 도구 실행
4. 지침 로드: SKILL.md + 지원 파일 컨텍스트에 로드
5. 작업 수행: 로드된 지침에 따라 작업 실행

 

Skill 저장 위치와 Location 속성

Skills는 세 가지 위치에 저장할 수 있으며, 각각 다른 사용 범위와 location 속성을 가진다. 이 location 속성은 Skill이 어디서 로드되었는지 표시한다.

저장 위치	Location 속성	사용 범위
~/.claude/skills/	user	모든 프로젝트 (개인 워크플로우)
.claude/skills/	managed	프로젝트 전용 (Git 공유)
Plugin 내부 skills/	plugin	Plugin 활성화 시 자동 로드

// Skill location 표시 예시

# user 위치 (개인 생성)
commit-helper (user)

# managed 위치 (프로젝트)
code-reviewer (project)

# plugin 위치 (번들 포함)
document-skills:xlsx (plugin:document-skills@anthropic-agent-skills)
document-skills:pdf (plugin:document-skills@anthropic-agent-skills)

 

Skill 디렉토리 구조

// Skill 디렉토리 구조 예시

my-skill/
├── SKILL.md          # 필수: Skill 정의 및 지침
├── REFERENCE.md      # 선택: 상세 참조 문서
├── EXAMPLES.md       # 선택: 사용 예시
├── scripts/
│   └── helper.py     # 선택: 유틸리티 스크립트
└── templates/
    └── template.txt  # 선택: 템플릿 파일

참조 파일 링크 활용법
SKILL.md 내에서 마크다운 링크로 다른 파일을 참조하면, Claude가 필요시 해당 파일도 함께 읽는다.

자세한 내용은 [REFERENCE.md](./REFERENCE.md)를 참조하세요.
양식 작성법은 [FORMS.md](./FORMS.md)에서 확인할 수 있습니다.

 

SKILL.md 파일 구조

SKILL.md 파일은 YAML 프론트매터로 시작하며, name과 description 필드가 핵심이다.

특히 description은 Claude의 자동 발견 메커니즘에서 가장 중요하다.

SKILL.md 기본 구조

---
name: your-skill-name
description: Brief description + when to use it (CRITICAL for discovery)
allowed-tools: Read, Grep, Glob  # 선택: 도구 접근 제한
---

# Your Skill Name

## Instructions
Provide clear, step-by-step guidance for Claude.

## Examples
Show concrete examples of using this Skill.

## References
For advanced usage, see [ADVANCED.md](./ADVANCED.md).

 

description 작성 Best Practices

효과적인 description 작성법
• 무엇을 하는지: "PDF 파일에서 텍스트 및 표 추출"
• 언제 사용하는지: "PDF 파일, 양식, 문서 추출 작업 시 사용"
• 트리거 키워드 포함: "PDF", "텍스트 추출", "문서" 등

description 언어 권장사항
영어로 작성을 권장한다. Claude의 자연어 매칭은 영어에서 가장 정확하게 동작한다. 한국어로 작성해도 동작하지만, 영어와 한국어를 혼용하면 매칭 정확도가 높아진다.

# 권장: 영어 + 핵심 한국어 키워드
description: "Generate commit messages from git diffs. 커밋 메시지 생성. Use when writing commits."

// description 작성 예시 비교

# ❌ 나쁜 예: 너무 일반적
description: "파일 처리"

# ❌ 나쁜 예: 키워드 부족
description: "Extract data from documents"

# 좋은 예: 구체적 + 키워드 풍부
description: "Extract text, tables, and form data from PDF files.
PDF 텍스트 추출. Use when working with PDF documents,
forms, or document extraction tasks. Requires pypdf."

# 좋은 예: 사용 시점 명확
description: "Generate conventional commit messages from git diffs.
커밋 메시지 작성. Use when writing commit messages, reviewing
staged changes, or asking for help with git commits."

Skill 충돌 주의
여러 Skill의 description이 유사하면 의도하지 않은 Skill이 활성화될 수 있다. 각 Skill의 description을 구체적이고 고유하게 작성해야 한다.

예를 들어, "파일 처리"라는 일반적인 description은 PDF Skill, Excel Skill, 이미지 Skill 모두와 충돌할 수 있다. 대신 "PDF 파일에서 텍스트 추출"처럼 구체적인 작업을 명시해야 한다.

 

튜토리얼 1 : 첫 번째 Skill 만들기

Git 커밋 메시지를 자동으로 생성하는 Skill을 만들어보자. 이 Skill은 사용자가 "커밋 메시지 작성해줘"라고 요청하면 Claude가 자동으로 활성화한다.

전역 vs 프로젝트 Skill: 어떤 것을 선택할까?

구분	전역 Skill (user)	프로젝트 Skill (managed)
저장 위치	~/.claude/skills/	.claude/skills/ (프로젝트 루트)
적용 범위	모든 프로젝트에서 사용 가능	해당 프로젝트에서만 사용
Git 공유	개인 설정 (공유 안 됨)	팀원과 Git으로 공유 가능
추천 용도	개인 워크플로우, 범용 도구	프로젝트별 컨벤션, 팀 표준

방법 A: 전역 Skill 등록 (모든 프로젝트에서 사용)

개인 워크플로우에 사용하거나, 모든 프로젝트에서 공통으로 활용할 Skill을 등록한다.

Step A-1: 디렉토리 생성

운영체제별 명령어

# macOS / Linux
mkdir -p ~/.claude/skills/commit-helper

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\skills\commit-helper"

# Windows (CMD)
mkdir %USERPROFILE%\.claude\skills\commit-helper

Step A-2: SKILL.md 파일 작성

~/.claude/skills/commit-helper/SKILL.md

---
name: commit-helper
description: |
  커밋 메시지 생성 스킬. 다음 상황에서 자동 호출:
  - "커밋", "commit", "커밋 메시지", "커밋해줘", "커밋 부탁"
  - "변경사항 커밋", "staged 커밋", "git commit"
---

# Commit Message Generator

## 자동 호출 트리거

커밋, commit, 커밋해줘, 커밋 부탁, 커밋 메시지

## Instructions

### 1: 프로젝트 컨벤션 확인

```bash
git log --oneline -5
```

분석 항목:
- 언어 (한글/영어)
- 타입 형식 (`feat:` vs `기능:`)
- Body 사용 여부

### 2: 변경사항 분석

```bash
git diff --staged --stat
```

### 3: Body 필요 여부 판단

**Body 포함 기준** (하나라도 해당 시):
- 파일 3개 이상
- 구체적 변경사항 나열 가능 (이름 변경, 설정 변경 등)
- 변경 이유 설명 필요

**한 줄만 사용**:
- 단순 오타 수정
- 한 가지 명확한 변경

### 4: 메시지 생성

**한 줄 형식**:
```
{타입}: {요약}
```

**Body 포함 형식**:
```
{타입}: {요약}

- {구체적 변경 1}
- {구체적 변경 2}
```

## 타입 (프로젝트 컨벤션 따름)

**한글**: 기능, 수정, 문서, 리팩토링, 테스트, 설정
**영어**: feat, fix, docs, refactor, test, chore

## 예시

**한 줄** (단순 변경):
```
fix: 로그인 버튼 오타 수정
```

**Body 포함** (구체적 변경사항 있음):
```
설정: 커밋 메시지 생성 스킬 개선

- Step 접두사 제거 (Step 1: → 1:)
- 프로젝트 특화 예시를 범용 예시로 교체
- Body 판단 기준 명확화
```

**Body 포함** (이름/구조 변경):
```
리팩토링: Ch 3 폴더 번호를 task.json과 일치시킴

- t08_conditionals_intent → t09_conditionals_intent
- t09_loops_batch → t10_loops_batch
- t10_exception_api_error → t11_exception_api_error
```

## 규칙

- 50자 이내 요약
- 현재 시제 ("추가" not "추가함")
- 프로젝트 기존 스타일 따르기

 

만약 상기 지침으로 자연스럽게 스킬 호출이 안된다면 직접 수정이 필요할 수도 있다.
(
아마 안되신다면 이 부분과 관련이 있을 것 같다. 
" Generate clear, conventional commit messages from git diffs.
  커밋 메시지 생성. Use when writing commit messages, reviewing staged
  changes, or asking for help with git commits."
여기서 "커밋 메세지 생성" 이라고 너무 예시에 간단한 조건으로 작성되어 있다.
)
아니면 실제 내가 사용하는 지침을 올려 두도록 하니 이 skills로 테스트 해보실수도 있을 것 같다. 

 

ex) 개인적으로 범용 프로젝트에 사용하고 있는 지침 참고

---
name: commit-helper
description: |
  커밋 메시지 생성 스킬. 다음 상황에서 자동 호출:
  - "커밋", "commit", "커밋 메시지", "커밋해줘", "커밋 부탁"
  - "변경사항 커밋", "staged 커밋", "git commit"
---

# Commit Message Generator

## 자동 호출 트리거

커밋, commit, 커밋해줘, 커밋 부탁, 커밋 메시지

## Instructions

### 1: 프로젝트 컨벤션 확인

```bash
git log --oneline -5
```

분석 항목:
- 언어 (한글/영어)
- 타입 형식 (`feat:` vs `기능:`)
- Body 사용 여부

### 2: 변경사항 분석

```bash
git diff --staged --stat
```

### 3: Body 필요 여부 판단

**Body 포함 기준** (하나라도 해당 시):
- 파일 3개 이상
- 구체적 변경사항 나열 가능 (이름 변경, 설정 변경 등)
- 변경 이유 설명 필요

**한 줄만 사용**:
- 단순 오타 수정
- 한 가지 명확한 변경

### 4: 메시지 생성

**한 줄 형식**:
```
{타입}: {요약}
```

**Body 포함 형식**:
```
{타입}: {요약}

- {구체적 변경 1}
- {구체적 변경 2}
```

## 타입 (프로젝트 컨벤션 따름)

**한글**: 기능, 수정, 문서, 리팩토링, 테스트, 설정
**영어**: feat, fix, docs, refactor, test, chore

## 예시

**한 줄** (단순 변경):
```
fix: 로그인 버튼 오타 수정
```

**Body 포함** (구체적 변경사항 있음):
```
설정: 커밋 메시지 생성 스킬 개선

- Step 접두사 제거 (Step 1: → 1:)
- 프로젝트 특화 예시를 범용 예시로 교체
- Body 판단 기준 명확화
```

**Body 포함** (이름/구조 변경):
```
리팩토링: Ch 3 폴더 번호를 task.json과 일치시킴

- t08_conditionals_intent → t09_conditionals_intent
- t09_loops_batch → t10_loops_batch
- t10_exception_api_error → t11_exception_api_error
```

## 규칙

- 50자 이내 요약
- 현재 시제 ("추가" not "추가함")
- 프로젝트 기존 스타일 따르기

 

방법 B: 프로젝트 Skill 등록

프로젝트별 컨벤션을 적용하거나, Git을 통해 Skill을 공유하고 싶을 때 사용한다.

Step B-1: 프로젝트 루트에 디렉토리 생성

프로젝트 루트에서 실행

# 프로젝트 루트 디렉토리에서 실행 (모든 OS 공통)
mkdir -p .claude/skills/commit-helper

# 디렉토리 구조 확인
# my-project/
# ├── .claude/
# │   └── skills/
# │       └── commit-helper/
# │           └── SKILL.md
# ├── src/
# └── package.json

Step B-2: 프로젝트 맞춤 SKILL.md 작성

claude/skills/commit-helper/SKILL.md (프로젝트 컨벤션 적용)

---
name: project-commit-generator
description: Generate commit messages following our team's conventions.
  프로젝트 커밋 메시지 생성. Use for commits in this project with team standards.
---

# Project Commit Message Generator

## Our Team's Commit Convention

이 프로젝트는 다음 커밋 컨벤션을 따릅니다:

1. Run `git diff --staged` to analyze staged changes
2. Use our project-specific prefixes:
   - ✨ feat: 새로운 기능
   - 🐛 fix: 버그 수정
   - 📝 docs: 문서 변경
   - ♻️ refactor: 리팩토링
   - ✅ test: 테스트 추가/수정
   - 🔧 chore: 설정 변경

3. Format:
   - 이모지 + 타입: 제목 (50자 이내, 한국어)
   - 본문: 변경 이유 설명

## Example Output (Our Style)

```
✨ feat: 사용자 인증 미들웨어 추가

- JWT 토큰 검증 구현
- 역할 기반 접근 제어 추가
- 인증 에러 핸들링 생성

Closes #123
```

## Project-Specific Rules
- 커밋 메시지는 한국어로 작성
- 이모지 prefix 필수
- Jira 티켓 번호 참조 권장

 

위 지침도 이전 내용과 동일하게 안된다면 하기 지침으로 참고하자.

ex) 개인적으로 범용 프로젝트에 사용하는 지침

---
name: commit-helper
description: |
  커밋 메시지 생성 스킬. 다음 상황에서 자동 호출:
  - "커밋", "commit", "커밋 메시지", "커밋해줘", "커밋 부탁"
  - "변경사항 커밋", "staged 커밋", "git commit"
---

# Commit Message Generator

## 자동 호출 트리거

커밋, commit, 커밋해줘, 커밋 부탁, 커밋 메시지

## Instructions

### 1: 프로젝트 컨벤션 확인

```bash
git log --oneline -5
```

분석 항목:
- 언어 (한글/영어)
- 타입 형식 (`feat:` vs `기능:`)
- Body 사용 여부

### 2: 변경사항 분석

```bash
git diff --staged --stat
```

### 3: Body 필요 여부 판단

**Body 포함 기준** (하나라도 해당 시):
- 파일 3개 이상
- 구체적 변경사항 나열 가능 (이름 변경, 설정 변경 등)
- 변경 이유 설명 필요

**한 줄만 사용**:
- 단순 오타 수정
- 한 가지 명확한 변경

### 4: 메시지 생성

**한 줄 형식**:
```
{타입}: {요약}
```

**Body 포함 형식**:
```
{타입}: {요약}

- {구체적 변경 1}
- {구체적 변경 2}
```

## 타입 (프로젝트 컨벤션 따름)

**한글**: 기능, 수정, 문서, 리팩토링, 테스트, 설정
**영어**: feat, fix, docs, refactor, test, chore

## 예시

**한 줄** (단순 변경):
```
fix: 로그인 버튼 오타 수정
```

**Body 포함** (구체적 변경사항 있음):
```
설정: 커밋 메시지 생성 스킬 개선

- Step 접두사 제거 (Step 1: → 1:)
- 프로젝트 특화 예시를 범용 예시로 교체
- Body 판단 기준 명확화
```

**Body 포함** (이름/구조 변경):
```
리팩토링: Ch 3 폴더 번호를 task.json과 일치시킴

- t08_conditionals_intent → t09_conditionals_intent
- t09_loops_batch → t10_loops_batch
- t10_exception_api_error → t11_exception_api_error
```

## 규칙

- 50자 이내 요약
- 현재 시제 ("추가" not "추가함")
- 프로젝트 기존 스타일 따르기

💡 전역 vs 프로젝트 Skill 우선순위
같은 이름의 Skill이 전역과 프로젝트에 모두 존재하면, 프로젝트 Skill이 우선 적용된다. 이를 활용해 전역 Skill을 프로젝트별로 커스터마이징할 수 있다.

 

공통: 사용해보기

Skill을 저장한 후, Claude Code에서 다음과 같이 요청하면 자동으로 활성화된다.

// Claude Code에서 요청 (Skill 자동 활성화)

> 커밋 메시지 작성해줘
> 스테이징된 변경사항에 대한 커밋 메시지 생성해줘
> help me write a commit message

# Skill 활성화 시 표시되는 메시지 (전역 또는 프로젝트에 따라 다름)
<command-message>commit-message-generator is running…</command-message>
# 또는
<command-message>project-commit-generator is running…</command-message>

ex) 스킬이 호출 되지 않았을때

 

ex) 스킬이 호출 되었을때 (내 설정은 글과 스킬명이 다르다. 예전에 사용중이던 스킬 : commit-message-generator)

 

공통: Skill 동작 확인 (디버깅)

💡 Skill 동작 확인하기
Skills는 Model-invoked 방식이므로 별도의 목록 조회 명령어 없이 실제 요청을 통해 테스트하는 것이 가장 확실한 확인 방법이다. Skill이 활성화되면 <command-message>{skill-name} is running…</command-message> 형태로 표시된다.

Skill이 제대로 인식되지 않는다면:
• 파일 경로가 정확한지 확인 (~/.claude/skills/ 또는 .claude/skills/)
• YAML 프론트매터 형식이 올바른지 확인 (들여쓰기, 콜론 뒤 공백)
• description에 트리거될 키워드가 충분히 포함되어 있는지 확인
• Claude Code를 재시작해보기

[실제 테스트 필요]
• Skill 자동 발견이 환경에 따라 다르게 동작할 수 있음
• Claude Code 버전에 따른 동작 차이 가능성
• description의 키워드 매칭 정확도는 실제 테스트로 확인 권장 한다.

 

Part 2 : Claude Code Plugins 이해하기

Plugins란 무엇인가?

공식 문서에 따르면, Plugins는 "커스텀 명령어, 에이전트, 훅, Skills, MCP 서버를 통해 Claude Code를 확장"하는 시스템이다. 즉, Plugins는 여러 확장 컴포넌트를 하나의 패키지로 묶어 배포하는 방식이다.

공식 문서 출처
"Extend Claude Code with custom commands, agents, hooks, Skills, and MCP servers through the plugin system."
(플러그인 시스템을 통해 커스텀 명령어(commands), 에이전트(agents), hooks, Skills, MCP 서버를 추가하여 Claude Code를 확장할 수 있습니다.)
Claude Code Plugins 공식 문서 →

 

Plugin의 5가지 구성요소 상세

Plugin 구성요소

1. Custom Commands: /명령어로 호출하는 슬래시 명령어
   예: /deploy, /review, /test
2. Agents: 복잡한 작업을 위임받는 특화된 서브에이전트
   예: DevOps Agent, Security Agent, QA Agent
3. Skills: Claude가 자동으로 발견하여 사용하는 능력
   예: PDF 처리, 코드 리뷰, 로그 분석
4. Hooks: 도구 호출 전/후에 실행되는 이벤트 핸들러
   예: 커밋 전 린트 검사, 파일 저장 시 포맷팅
5. MCP Servers: 외부 도구/서비스와의 연동
   예: AWS API, GitHub API, Slack API

 

Hooks 상세 설명

Hooks는 Plugin의 강력한 기능 중 하나로, 특정 이벤트가 발생할 때 자동으로 실행되는 스크립트다.

Hook 유형	실행 시점	활용 예시
PreToolCall	도구 실행 전	입력 검증, 권한 확인, 자동 백업
PostToolCall	도구 실행 후	결과 로깅, 자동 포맷팅, 알림 전송
Notification	알림 이벤트 시	Slack 알림, 이메일 전송, 로그 기록

hooks/hooks.json 예시

{
  "hooks": [
    {
      "event": "PreToolCall",
      "matcher": {
        "tool_name": "Write"
      },
      "command": "scripts/backup.sh"
    },
    {
      "event": "PostToolCall",
      "matcher": {
        "tool_name": "Bash",
        "command_pattern": "git commit"
      },
      "command": "scripts/notify-slack.sh"
    }
  ]
}

 

Plugin 디렉토리 구조

// Plugin 디렉토리 구조

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 필수: 플러그인 메타데이터
├── commands/                # 선택: 커스텀 슬래시 명령어
│   ├── deploy.md
│   └── rollback.md
├── agents/                  # 선택: 커스텀 서브에이전트
│   ├── devops-agent.md
│   └── security-agent.md
├── skills/                  # 선택: Agent Skills
│   └── log-analyzer/
│       └── SKILL.md
├── hooks/                   # 선택: 이벤트 핸들러
│   └── hooks.json
├── scripts/                 # 선택: Hook에서 사용할 스크립트
│   ├── backup.sh
│   └── notify-slack.sh
└── .mcp.json               # 선택: MCP 서버 정의

 

plugin.json 매니페스트

.claude-plugin/plugin.json

{
  "name": "my-plugin",
  "description": "Brief plugin description for marketplace discovery",
  "version": "1.0.0",
  "author": {
    "name": "Your Name",
    "email": "your@email.com"
  },
  "homepage": "https://github.com/your/plugin",
  "repository": "https://github.com/your/plugin",
  "license": "MIT",
  "keywords": ["devops", "automation", "deployment"]
}

Plugin 비활성화 시 주의
Plugin을 /plugin disable로 비활성화하면, 해당 Plugin 내의 모든 컴포넌트(Commands, Skills, Agents, Hooks, MCP 서버)가 함께 비활성화된다.

특정 컴포넌트만 비활성화하는 것은 불가능하므로, Plugin 설계 시 관련 기능끼리 묶어서 구성하는 것이 좋다.

 

Plugin 설치 방법

Plugins는 마켓플레이스를 통해 설치하거나, 로컬 경로에서 직접 설치할 수 있다.

// Claude Code 내에서 Plugin 관리

# 인터랙티브 메뉴 (권장)
/plugin

# 마켓플레이스 추가
/plugin marketplace add your-org/claude-plugins

# 직접 설치
/plugin install plugin-name@marketplace-name

# 활성화/비활성화
/plugin enable plugin-name@marketplace-name
/plugin disable plugin-name@marketplace-name

# 제거
/plugin uninstall plugin-name@marketplace-name

실제 존재하는 공식 Plugin 예시

Anthropic에서 공식적으로 제공하는 Plugin들이 있다. 이들은 anthropic-agent-skills 마켓플레이스에서 제공된다.

공식 Plugin 예시 (anthropic-agent-skills)

Plugin	포함된 Skills
document-skills	xlsx (스프레드시트), docx (문서), pptx (프레젠테이션), pdf (PDF 처리)
example-skills	skill-creator, mcp-builder, webapp-testing, canvas-design, algorithmic-art

// 공식 Plugin의 Skill 표시 예시

# document-skills Plugin의 Skills
document-skills:xlsx (plugin:document-skills@anthropic-agent-skills)
document-skills:docx (plugin:document-skills@anthropic-agent-skills)
document-skills:pptx (plugin:document-skills@anthropic-agent-skills)
document-skills:pdf (plugin:document-skills@anthropic-agent-skills)

# example-skills Plugin의 Skills
example-skills:skill-creator (plugin:example-skills@anthropic-agent-skills)
example-skills:mcp-builder (plugin:example-skills@anthropic-agent-skills)
example-skills:webapp-testing (plugin:example-skills@anthropic-agent-skills)

 

 

하기 Plugin까지 만들 필요는 없겠지만, 참고차 남겨둔다. 시간이 없으신분들은 바로 스킵 또는 눈으로 데충 보고 넘ㅇ ㅓ가자.

튜토리얼 2: 첫 번째 Plugin 만들기

간단한 인사말 Plugin을 만들어보자. 이 Plugin은 /hello 명령어와 자동 활성화되는 greeting Skill을 포함한다.

Step 1: 마켓플레이스 디렉토리 생성

운영체제별 명령어

# macOS / Linux
mkdir -p test-marketplace/my-first-plugin/.claude-plugin
mkdir -p test-marketplace/my-first-plugin/commands
mkdir -p test-marketplace/my-first-plugin/skills/greeting
mkdir -p test-marketplace/.claude-plugin

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "test-marketplace\my-first-plugin\.claude-plugin"
New-Item -ItemType Directory -Force -Path "test-marketplace\my-first-plugin\commands"
New-Item -ItemType Directory -Force -Path "test-marketplace\my-first-plugin\skills\greeting"
New-Item -ItemType Directory -Force -Path "test-marketplace\.claude-plugin"

Step 2: Plugin 매니페스트 생성

test-marketplace/my-first-plugin/.claude-plugin/plugin.json

{
  "name": "my-first-plugin",
  "description": "A simple greeting plugin with hello command and greeting skill",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  },
  "keywords": ["greeting", "hello", "starter", "tutorial"]
}

Step 3: 커스텀 명령어 추가 (User-invoked)

test-marketplace/my-first-plugin/commands/hello.md

---
description: Greet the user with a personalized message
---

# Hello Command

Greet the user warmly and ask how you can help them today.
Include a fun programming fact or tip to make it engaging.
Use the user's language (Korean if they spoke Korean).

Step 4: Skill 추가 (Model-invoked)

test-marketplace/my-first-plugin/skills/greeting/SKILL.md

---
name: friendly-greeting
description: Provide warm, friendly greetings and welcome messages.
  친근한 인사말 생성. Use when users say hello, hi, good morning,
  or ask for a greeting.
---

# Friendly Greeting Skill

## Instructions

When activated, provide a warm and engaging greeting that:
1. Acknowledges the user's greeting
2. Offers assistance in a friendly tone
3. Optionally includes a fun fact or tip

## Response Style
- Keep it concise but warm
- Match the user's language
- Be enthusiastic but professional

Step 5: 마켓플레이스 매니페스트 생성

test-marketplace/.claude-plugin/marketplace.json

{
  "name": "test-marketplace",
  "owner": {
    "name": "Test User"
  },
  "plugins": [
    {
      "name": "my-first-plugin",
      "source": "./my-first-plugin",
      "description": "My first test plugin with command and skill"
    }
  ]
}

Step 6: Plugin 설치 및 테스트

// Claude Code 실행 후 아래 명령어 입력

# 1. 로컬 마켓플레이스 등록 (절대 경로 권장)
/plugin marketplace add /path/to/test-marketplace

# 또는 상대 경로 (현재 디렉토리 기준)
/plugin marketplace add ./test-marketplace

# 2. Plugin 설치
/plugin install my-first-plugin@test-marketplace
# "Install now" 선택

# 3. Claude Code 재시작
# (일부 변경사항은 재시작 필요)

# 4. 테스트
/hello                    # Command 테스트 (User-invoked)
> 안녕하세요!              # Skill 테스트 (Model-invoked 자동 활성화)

# 5. 설치 확인
/help  # 새 명령어가 목록에 표시되는지 확인

[실제 테스트 필요]
• 마켓플레이스 경로는 절대 경로 사용을 권장 (상대 경로는 환경에 따라 다를 수 있음)
• Plugin 설치 후 Claude Code 재시작이 필요할 수 있음
• 환경에 따라 권한 문제가 발생할 수 있음 (chmod 필요)

 

Part 3: Skills vs Plugins vs Slash Commands 비교

Claude Code의 세 가지 확장 방식을 비교하여 언제 무엇을 사용해야 하는지 명확히 이해해보자.

특성	Slash Commands	Skills	Plugins
호출 방식	User-invoked (/명령)	Model-invoked (자동 발견)	User-invoked (/plugin)
파일 구조	단일 .md 파일	디렉토리 + SKILL.md	plugin.json + 여러 컴포넌트
저장 위치	.claude/commands/	.claude/skills/	마켓플레이스
복잡도	낮음	중간	높음
주요 용도	자주 쓰는 프롬프트	특정 작업 전문성	통합 도구 모음
공유 범위	프로젝트	개인/프로젝트	마켓플레이스/커뮤니티
지원 파일	없음	스크립트, 템플릿	전체 번들
도구 제한	불가	allowed-tools	Skill 내부에서

공식 문서 출처
"Slash commands are user-invoked, while Skills are model-invoked. This means Claude automatically discovers and uses Skills when they match the context."
(Slash commands는 사용자가 직접 호출하는 기능이고, Skills는 모델이 스스로 호출하는 기능입니다. 이는 곧 Claude가 현재 맥락과 일치하는 Skill을 자동으로 탐지하고 활용한다는 의미입니다.)
Skills vs Slash Commands 공식 문서 →

 

선택 가이드

Slash Commands를 선택해야 할 때
• 자주 사용하는 프롬프트를 저장하고 싶을 때
• 명시적으로 호출해야 하는 작업일 때
• 단순한 템플릿만 필요할 때
• 예: /review, /test, /deploy

Skills를 선택해야 할 때
• Claude가 자동으로 발견하고 사용해야 할 때
• 특정 도메인 전문성이 필요할 때
• 다중 파일 지원 자료가 필요할 때
• 도구 사용을 제한해야 할 때 (allowed-tools)
• 예: PDF 처리, Excel 분석, 코드 리뷰

Plugins를 선택해야 할 때
• 여러 기능을 통합 패키지로 제공해야 할 때
• 팀/커뮤니티와 마켓플레이스로 공유해야 할 때
• MCP 서버 연동이 필요할 때
• Commands + Agents + Skills + Hooks를 함께 제공할 때
• 예: 배포 자동화 도구 모음, 보안 감사 키트

 

Part 4: Skills과 Plugins의 관계

중요한 점은 Skills가 Plugins의 하위 컴포넌트가 될 수 있다는 것이다. 즉, Plugin 내부에 Skills를 포함시켜 배포할 수 있다.

Plugin 내부에 Skill 포함하기

enterprise-devops-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/              # User-invoked 명령어
│   ├── deploy.md          # /deploy로 호출
│   └── rollback.md        # /rollback으로 호출
├── agents/                # 특화된 서브에이전트
│   ├── devops-agent.md
│   └── security-agent.md
├── skills/                # Model-invoked Skills (자동 발견)
│   ├── kubernetes-deploy/
│   │   └── SKILL.md       # "K8s 배포해줘" → 자동 활성화
│   ├── security-scan/
│   │   └── SKILL.md       # "보안 스캔해줘" → 자동 활성화
│   └── log-analysis/
│       └── SKILL.md       # "로그 분석해줘" → 자동 활성화
├── hooks/
│   └── hooks.json         # 자동 백업, 알림 등
└── .mcp.json              # AWS, GitHub API 연동

이런 구조에서 사용자가 Plugin을 설치하면:

• Commands: /deploy, /rollback으로 명시적 호출 가능
• Skills: "쿠버네티스 배포해줘"라고 하면 자동으로 kubernetes-deploy Skill 활성화
• Agents: 복잡한 작업을 서브에이전트에 위임
• Hooks: 배포 전/후 자동 백업, Slack 알림 등 자동 실행

 

주의사항 및 Best Practices

Plugin 개발 시

💡 로컬 테스트 권장
마켓플레이스에 배포하기 전에 반드시 로컬 마켓플레이스에서 테스트해야 한다.

/plugin marketplace add /absolute/path/to/local-marketplace

절대 경로 사용을 권장한다. 상대 경로는 작업 디렉토리에 따라 달라질 수 있다.

 

allowed-tools로 권한 제한

Skill에서 사용할 수 있는 도구를 제한하여 안전성을 높일 수 있다.

도구 제한 예시

---
name: safe-code-reviewer
description: Review code for best practices without making any changes.
  코드 리뷰 전용. Read-only analysis.
allowed-tools: Read, Grep, Glob
---

# Safe Code Reviewer

This Skill can only read files, not modify them.
Provides analysis and recommendations without making changes.

[실제 테스트 필요]
• allowed-tools에 허용되지 않은 도구를 사용하려 하면 어떻게 되는지
• 도구 이름의 정확한 대소문자 (Read, Grep, Glob, Write, Edit, Bash 등)
• 모든 도구 이름 목록은 공식 문서 참조 권장

 

Plugin, 꼭 필요한가?

결론부터 말하면: 개인 개발자라면 Plugin 없이도 충분하다고 생각한다.
Skills, Commands, Hooks를 각각 만들어 사용하면 기능적으로 전혀 부족함이 없다.

Plugin의 본질은 "새로운 기능 추가"가 아니라 "번들링 + 배포 + 버전 관리"다.
이미 존재하는 컴포넌트들을 하나의 패키지로 묶어서 공유하고 관리하는 것이 목적이다.

상황	Plugin 필요?	이유
혼자 개발	불필요? 하지 않을까???	Skills/Commands/Hooks 개별 관리로 충분
팀 내 공유	선택적	Git으로 .claude/ 공유해도 되지만, Plugin이 더 깔끔
조직/커뮤니티 배포	권장	버전 관리, 마켓플레이스 배포, 일괄 활성화/비활성화

💡 핵심 포인트: Plugin은 "기능"이 아니라 "배포 메커니즘"이다.
    개인 사용 → 개별 컴포넌트로 충분 | 팀/조직 배포 → Plugin 패키징 권장

 

요약 정리

• Skills: Claude가 Skill 도구를 통해 자동으로 발견하고 사용하는 Model-invoked 단일 능력. SKILL.md 파일로 정의하며, 특정 도메인 전문성을 제공한다. location 속성으로 출처를 구분한다 (user, managed, plugin).
• Plugins: Commands, Agents, Skills, Hooks, MCP 서버를 묶은 확장 패키지. 마켓플레이스를 통해 팀/커뮤니티와 공유할 수 있다. 비활성화 시 모든 내부 컴포넌트가 함께 비활성화된다.
• Slash Commands: /명령으로 명시적으로 호출하는 User-invoked 프롬프트 템플릿. 가장 단순한 확장 방식이다.
• 계층적 관계: Skills는 독립적으로 사용하거나, Plugins 내부에 포함시켜 배포할 수 있다.
• Hooks: PreToolCall, PostToolCall, Notification 등의 이벤트에 자동으로 실행되는 스크립트를 정의할 수 있다.

 

자주 묻는 질문 ❓

Q: Skill과 Slash Command의 가장 큰 차이는 무엇인가요?

A: 호출 방식이다. Slash Command는 사용자가 /명령으로 명시적으로 호출하고, Skill은 Claude가 내부적으로 Skill 도구를 호출하여 문맥에 맞는 Skill을 자동으로 발견하고 사용한다. Skill의 description 필드가 자동 발견의 핵심이다.

Q: 이미 Slash Command로 만든 것을 Skill로 바꿀 수 있나요?

A: 가능하다. .claude/commands/ 에서 .claude/skills/ 로 옮기고, SKILL.md 형식으로 재작성하면 된다. 다만 Skill은 자동 발견 방식이므로 description을 상세하게 작성해야 한다. 영어로 작성하고 한국어 키워드를 혼용하면 매칭 정확도가 높아진다.

Q: Plugin 없이 Skill만 사용할 수 있나요?

A: 물론이다. ~/.claude/skills/ (개인) 또는 .claude/skills/ (프로젝트)에 Skill을 직접 생성하면 된다. Plugin은 여러 컴포넌트를 묶어 배포할 때 사용하는 것이다.

Q: Plugin은 어디서 찾을 수 있나요?

A: Claude Code 내에서 /plugin 명령어를 입력하고 "Browse Plugins"를 선택하면 마켓플레이스를 탐색할 수 있다. 공식 Plugin으로는 anthropic-agent-skills가 있으며, document-skills(PDF, Excel 등)와 example-skills(skill-creator, webapp-testing 등)를 제공한다.

Q: Plugin을 비활성화하면 내부 Skill도 비활성화되나요?

A: 그렇다. Plugin을 /plugin disable로 비활성화하면, 해당 Plugin 내의 모든 컴포넌트(Commands, Skills, Agents, Hooks, MCP 서버)가 함께 비활성화된다. 특정 컴포넌트만 비활성화하는 것은 불가능하다.

Q: Skill이 여러 개 매칭되면 어떻게 되나요?

A: description이 유사한 여러 Skill이 있으면 의도하지 않은 Skill이 활성화될 수 있다. 각 Skill의 description을 구체적이고 고유하게 작성하여 충돌을 방지해야 한다. 일반적인 키워드보다 특정 작업을 명시하는 것이 좋다.

참고 자료

• Claude Code Plugins 공식 문서 - Plugins 개요 및 Quickstart
• Claude Code Skills 공식 문서 - Skills 작성 가이드
• Plugin Reference - Plugin 스키마 및 상세 구조
• Slash Commands 공식 문서 - Skills vs Slash Commands 비교
• Plugin Marketplaces - 마켓플레이스 생성 및 관리
• Hooks 공식 문서 - 이벤트 핸들러 설정 가이드