Claude Code 공식문서 리뷰-Build with Claude Code[2] : Create plugins

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

Claude Code Docs 공식 문서 >> Build with Claude Code 섹션의 내용 중 [Create plugins]를 살펴 보려고 합니다.
https://code.claude.com/docs/en/plugins

Create plugins - Claude Code Docs

 

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다. 

 

 

Claude Code 플러그인

• 정의: Claude Code의 기능을 확장하는 재사용 가능한 패키지
• 포함 가능: 슬래시 명령, 에이전트, 훅, 스킬, MCP 서버
• 핵심 파일: .claude-plugin/plugin.json 매니페스트
• 원본: code.claude.com/docs/en/plugins

 

개요: 플러그인이란?

쉽게 이해하기

플러그인은 스마트폰의 앱과 같다. 스마트폰에 앱을 설치하면 새로운 기능이 추가되듯이, Claude Code에 플러그인을 설치하면 새로운 명령어와 기능이 추가된다.

예시:
• 스마트폰 + 카메라 앱 = 사진 촬영 가능
• Claude Code + 코드리뷰 플러그인 = /code-review:analyze 명령어 사용 가능

플러그인은 슬래시 명령, 에이전트, 훅, 스킬, MCP 서버 등의 커스텀 기능으로 Claude Code를 확장한다. 프로젝트와 팀 간에 공유할 수 있다.

 

핵심 용어 정리

용어	한마디 설명	예시
슬래시 명령	/이름으로 실행하는 명령어	/hello, /commit
에이전트	특정 작업을 수행하는 AI 도우미	코드 리뷰어, 테스트 작성자
훅	특정 이벤트 발생 시 자동 실행되는 코드	파일 저장 시 자동 린트
스킬	Claude가 특정 도메인에 대해 더 잘 대응하도록 가르치는 지식	React 베스트 프랙티스
MCP 서버	Claude가 외부 도구/서비스와 통신하는 방법	DB 조회, API 호출
매니페스트	플러그인의 "신분증" 역할을 하는 설정 파일	plugin.json

 

플러그인 vs 독립 설정: 언제 무엇을 사용할까?

나에게 맞는 선택은?

다른 사람과 공유한다?
↓
아니요 (나만 사용) 예 (팀/커뮤니티)
↓ ↓
독립 설정
.claude/ 폴더 플러그인
plugin.json

접근 방식	슬래시 명령 이름	적합한 용도
독립 설정 .claude/ 디렉토리	/hello	개인 워크플로우, 프로젝트별 커스터마이징, 빠른 실험
플러그인 .claude-plugin/plugin.json	/plugin-name:hello	팀원과 공유, 커뮤니티 배포, 버전 관리, 여러 프로젝트에서 재사용

플러그인을 사용해야 할 때:

• 팀이나 커뮤니티와 기능을 공유하고 싶을 때
• 여러 프로젝트에서 같은 슬래시 명령이 필요할 때
• 버전 관리와 쉬운 업데이트가 필요할 때
• 마켓플레이스를 통해 배포할 때
• /my-plugin:hello처럼 네임스페이스가 있는 명령어를 사용해도 괜찮을 때

초보자 팁

추천 학습 경로:
1. 먼저 .claude/ 폴더에서 독립 설정으로 실험해본다
2. 작동하는 것이 확인되면, 공유가 필요할 때 플러그인으로 변환한다

왜? 독립 설정은 설정이 간단하고, 네임스페이스 없이 /hello로 바로 실행 가능하다!

 

빠른 시작: 첫 번째 플러그인 만들기

이 튜토리얼의 목표
5분 안에 /my-first-plugin:hello 명령어가 작동하는 플러그인을 만든다.

사전 요구사항

• Claude Code 설치 및 인증 완료
• Claude Code 버전 1.0.33 이상 (확인: claude --version)

 

1단계: 플러그인 디렉토리 생성

mkdir my-first-plugin
cd my-first-plugin

 

2단계: 플러그인 매니페스트 생성

플러그인의 "신분증" 역할을 하는 .claude-plugin/plugin.json을 생성한다:

mkdir .claude-plugin
# .claude-plugin/plugin.json 파일 생성

{
  "name": "my-first-plugin",
  "description": "기본을 배우기 위한 인사 플러그인",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

 

매니페스트 필드 설명:

필드	용도	예시
name	고유 식별자이자 슬래시 명령 네임스페이스 (이 이름이 /my-first-plugin:hello의 앞부분이 됨)	"my-first-plugin"
description	플러그인 목록에 표시되는 설명	"코드 리뷰 자동화 도구"
version	시맨틱 버저닝 (major.minor.patch)	"1.0.0", "2.1.3"
author	선택적 저자 정보	{"name": "홍길동"}

 

3단계: 슬래시 명령 추가

commands/hello.md 생성:

mkdir commands
# commands/hello.md 파일 생성

---
description: 친근한 메시지로 사용자에게 인사
---

# Hello Command

사용자에게 따뜻하게 인사하고 오늘 어떻게 도움이 될 수 있는지 물어본다.

현재 폴더 구조

my-first-plugin/
├── .claude-plugin/
│   └── plugin.json      ← 플러그인 매니페스트
└── commands/
    └── hello.md         ← 슬래시 명령어

 

4단계: 플러그인 테스트

# 플러그인 폴더의 상위 디렉토리에서 실행
claude --plugin-dir ./my-first-plugin

 

Claude Code가 시작되면 명령어를 실행한다:

> /my-first-plugin:hello

안녕하세요!
오늘 어떤 일을 도와드릴까요? 코딩, 문서 작성, 아이디어 정리 등
무엇이든 함께 해결해 보겠습니다!

 

5단계: 슬래시 명령에 인자 추가

$ARGUMENTS 변수를 사용하면 사용자 입력을 받을 수 있다. hello.md를 업데이트:

---
description: 개인화된 메시지로 사용자에게 인사
---

# Hello Command

"$ARGUMENTS"라는 이름의 사용자에게 따뜻하게 인사하고 오늘 어떻게 도움이 될 수 있는지 물어본다. 인사를 개인적이고 격려하는 느낌으로 만든다.

 

인자와 함께 사용하면:

> /my-first-plugin:hello Alex

안녕하세요, Alex님!
오늘도 열심히 개발하고 계시군요! 어떤 프로젝트를 진행 중이신가요?
도움이 필요한 부분이 있다면 언제든 말씀해 주세요!

 

플러그인 구조 개요

my-plugin/
├── .claude-plugin/
│   └── plugin.json      # 매니페스트 (필수) - 플러그인의 "신분증"
├── commands/            # 슬래시 명령 (Markdown)
│   └── hello.md         # → /my-plugin:hello
├── agents/              # 커스텀 에이전트 정의
├── skills/              # 에이전트 스킬 (SKILL.md)
├── hooks/               # 이벤트 핸들러 (hooks.json)
├── .mcp.json            # MCP 서버 구성
└── .lsp.json            # LSP 서버 구성

흔한 실수 - 반드시 피하도록 하자.
commands/, agents/, skills/, hooks/를 .claude-plugin/ 안에 넣으면 안 된다.

✗ 잘못된 구조:

my-plugin/
└── .claude-plugin/
    ├── plugin.json
    └── commands/        ← 여기 있으면 안 됨!
        └── hello.md

✓ 올바른 구조:

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← 여기엔 plugin.json만!
└── commands/            ← 플러그인 루트에 위치
    └── hello.md

디렉토리	위치	용도
.claude-plugin/	플러그인 루트	plugin.json 매니페스트만 포함 (필수)
commands/	플러그인 루트	Markdown 파일로 된 슬래시 명령
agents/	플러그인 루트	커스텀 에이전트 정의
skills/	플러그인 루트	SKILL.md 파일이 포함된 에이전트 스킬
hooks/	플러그인 루트	hooks.json으로 된 이벤트 핸들러
.mcp.json	플러그인 루트	MCP 서버 구성
.lsp.json	플러그인 루트	코드 인텔리전스를 위한 LSP 서버 구성

ex) anthropic 에서 제공하는 공식 플러그인 구조도 살펴보자 : anthropic-agent-skills 플러그인

 

고급 플러그인 기능

플러그인에 스킬 추가

스킬은 Claude가 특정 도메인에 대해 더 잘 알도록 가르치는 지식 파일이다.

skills/ 디렉토리에 SKILL.md 파일이 포함된 스킬 폴더를 생성한다. 플러그인이 설치되면 스킬이 자동으로 사용 가능해진다.

my-plugin/
└── skills/
    └── react-best-practices/
        └── SKILL.md     # 스킬 정의

 

LSP 서버 추가

커스텀 언어 지원을 위해 .lsp.json 생성:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

 

로컬에서 플러그인 테스트

# 단일 플러그인
claude --plugin-dir ./my-plugin

# 여러 플러그인
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

개발 팁

변경사항 반영하기:
플러그인 파일을 수정한 후에는 Claude Code를 재시작해야 변경사항이 반영된다.

효율적인 디버깅:
각 명령, 에이전트, 훅을 개별적으로 테스트하면 문제를 빠르게 찾을 수 있다.

 

기존 설정을 플러그인으로 변환하기

이미 .claude/ 폴더에서 독립 설정을 사용 중이라면, 아래 단계로 플러그인으로 변환할 수 있다.

마이그레이션 단계

1. 플러그인 구조 생성:

mkdir -p my-plugin/.claude-plugin

2. 매니페스트 생성 (my-plugin/.claude-plugin/plugin.json)

3. 기존 파일 복사:

cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/
cp -r .claude/skills my-plugin/

4. 훅 마이그레이션:

기존 settings.json의 훅을 my-plugin/hooks/hooks.json으로 이동:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "npm run lint:fix $FILE" }]
      }
    ]
  }
}

5. 마이그레이션된 플러그인 테스트:

claude --plugin-dir ./my-plugin

마이그레이션 전후 비교

항목	독립 설정 (Before)	플러그인 (After)
사용 범위	단일 프로젝트	마켓플레이스를 통해 공유 가능
명령어 실행	/hello	/my-plugin:hello
명령어 위치	.claude/commands/	plugin-name/commands/
훅 위치	settings.json	hooks/hooks.json
배포 방식	수동 복사	/plugin install

 

플러그인 공유하기

1. 문서 추가 - 설치 및 사용 방법이 담긴 README.md 포함
2. 버전 관리 - plugin.json에서 시맨틱 버저닝 사용 (예: 1.0.0 → 1.0.1 → 1.1.0)
3. 마켓플레이스 생성 또는 사용 - 플러그인 마켓플레이스를 통해 배포
4. 다른 사람과 테스트 - 넓은 범위 배포 전에 팀원들과 테스트

 

자주 묻는 질문 (FAQ)

Q. 명령어가 인식되지 않아요

확인 사항:

1. 플러그인 이름에 네임스페이스를 포함했는가? → /my-plugin:hello (O), /hello (X)
2. .claude-plugin/plugin.json이 존재하는가?
3. commands/ 폴더가 .claude-plugin/ 밖에 있는가?
4. Claude Code를 재시작했는가?

Q. 변경사항이 반영되지 않아요

플러그인 파일을 수정한 후에는 Claude Code를 재시작해야 한다.
Ctrl+C로 종료 후 다시 claude --plugin-dir ./my-plugin 실행.

Q. 독립 설정과 플러그인을 동시에 사용할 수 있나요?

예! 프로젝트의 .claude/ 폴더 설정과 플러그인은 함께 작동한다.
• 독립 설정: /hello
• 플러그인: /my-plugin:hello
네임스페이스가 다르므로 충돌하지 않는다.

Q. $ARGUMENTS에 아무것도 전달하지 않으면 어떻게 되나요?

$ARGUMENTS는 빈 문자열이 된다. 명령어 작성 시 인자가 없는 경우도 고려하면 좋다:

$ARGUMENTS가 제공되면 해당 이름으로 인사하고,
없으면 일반적인 인사를 한다.

플러그인 문제 디버깅

1. 구조 확인 - 디렉토리가 플러그인 루트에 있는지, .claude-plugin/ 안에 있지 않은지 확인
2. 컴포넌트별 테스트 - 각 명령, 에이전트, 훅을 개별적으로 확인
3. 유효성 검사 도구 사용 - 디버깅 기법은 플러그인 레퍼런스 참조

디버깅 체크리스트

• ☐ plugin.json의 JSON 문법이 올바른가? (따옴표, 쉼표 확인)
• ☐ 파일 이름과 확장자가 정확한가? (hello.md, 대소문자 주의)
• ☐ 명령어 파일에 frontmatter(---로 감싼 부분)가 있는가?
• ☐ Claude Code 버전이 1.0.33 이상인가?

 

다음 단계

플러그인 사용자를 위한

문서	설명
플러그인 찾기	플러그인 검색 및 설치
팀 마켓플레이스 구성	팀 전용 마켓플레이스 설정

플러그인 개발자를 위한

문서	설명
마켓플레이스 만들기	마켓플레이스 생성 및 배포
플러그인 레퍼런스	상세 API 및 구성 옵션
슬래시 명령	명령어 작성 방법
서브에이전트	에이전트 정의 방법
스킬	에이전트 스킬 작성
훅	이벤트 핸들러 구성
MCP	MCP 서버 통합

참고 자료

• 공식 문서: Plugins
• 플러그인 찾기