Claude Code 공식문서 리뷰-참고자료(Reference)[6] : 플러그인 참조(Plugins reference)

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

Claude Code Docs 공식 문서 >> [참고자료(Reference)] 섹션의 내용 중 [플러그인 참조(Plugins reference)]를 살펴 보려고 합니다.

이번 섹션 부터는 영문, 한글번역본이 모두 공식문서로 존재하는 섹션이니 한글 문서를 편하게 참고 하셔도 될 것 같습니다.

https://code.claude.com/docs/en/plugins-reference

Plugins reference - Claude Code Docs

 

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

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

 

플러그인 레퍼런스

원본: Claude Code Plugins Reference

플러그인을 만들고 싶은가?

이 문서는 플러그인 개발자를 위한 상세 기술 문서이다. Claude Code의 기능을 확장하는 커스텀 명령어, 에이전트, 스킬, 훅을 만들고 싶다면 이 레퍼런스를 참고하자.

이 문서가 필요한 경우

• 팀 전용 커스텀 슬래시 명령어를 만들고 싶다
• 특정 작업에 특화된 AI 에이전트를 정의하고 싶다
• 코드 작성 후 자동으로 린트/포맷을 실행하고 싶다
• 외부 도구(Jira, Slack 등)와 연동하고 싶다

다른 문서 찾고 있나요?
- 플러그인 사용법이 궁금하다면 → Plugins
- 마켓플레이스에서 플러그인을 찾고 설치하려면 → Discover plugins

 

시작하기 전에 준비할 것들

플러그인 개발을 시작하기 전에 다음 사항을 확인하자.

필수 항목

• Claude Code 설치 - 최신 버전 권장
  → claude --version으로 확인
• Markdown 기본 문법 - 명령어, 에이전트, 스킬은 모두 Markdown 파일
  → 프론트매터(YAML) 작성법도 알아두면 좋음
• JSON 기본 문법 - plugin.json, hooks.json 등 설정 파일 작성에 필요
  → 문법 오류 시 플러그인이 로딩되지 않음

선택 항목 (있으면 편리)

• 셸 스크립트 기본 - 훅에서 스크립트 실행 시 필요
• MCP(Model Context Protocol) 이해 - 외부 서비스 연동 시 필요

 

플러그인 컴포넌트 개요

플러그인은 6가지 컴포넌트로 구성된다

모든 컴포넌트를 사용할 필요는 없다. 필요한 것만 선택해서 조합하면 된다.

컴포넌트	한 줄 설명	언제 사용?
Commands	슬래시 명령어 (/deploy)	사용자가 직접 호출하는 작업
Agents	전문 분야별 AI 에이전트	Claude가 자동으로 판단해서 호출
Skills	특정 도메인 지식/도구 모음	PDF 처리, 코드 리뷰 등 전문 기능
Hooks	이벤트 기반 자동 실행	파일 저장 시 린트 실행 등
MCP Servers	외부 서비스 연동	DB, API, 외부 도구 연결
LSP Servers	언어별 코드 인텔리전스	실시간 진단, 코드 탐색

 

첫 플러그인 만들기

가장 간단한 플러그인부터 시작하자

복잡한 설정 없이, 커스텀 슬래시 명령어 하나만 있는 플러그인을 만들어보자.

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

# 플러그인 디렉토리 생성
mkdir -p my-first-plugin/.claude-plugin
mkdir -p my-first-plugin/commands

# 디렉토리 구조 확인
tree my-first-plugin/
# my-first-plugin/
# ├── .claude-plugin/
# │   └── plugin.json    ← 필수: 플러그인 메타데이터
# └── commands/
#     └── hello.md       ← 슬래시 명령어 정의

2단계: plugin.json 작성

// .claude-plugin/plugin.json
{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "나의 첫 번째 Claude Code 플러그인"
}

3단계: 명령어 파일 작성

# commands/hello.md
---
description: 팀원들에게 인사하는 명령어
---

# /hello 명령어

사용자에게 친근하게 인사하고, 오늘 도와줄 수 있는 작업 목록을 제안해주세요.

## 인사 스타일
- 친근하고 전문적인 톤
- 이모지는 사용하지 않음
- 간결하게 3-4줄 이내로

## 제안할 작업 예시
- 코드 리뷰
- 버그 수정
- 새 기능 구현
- 문서 작성

4단계: 플러그인 설치 및 테스트

# 로컬 플러그인 설치
claude plugin install ./my-first-plugin

# Claude Code 실행 후 명령어 테스트
claude
> /hello

성공!

/hello 명령어가 작동한다면 첫 플러그인 개발에 성공한 것이다. 이제 아래 컴포넌트 레퍼런스를 참고해서 더 복잡한 기능을 추가해보자.

 

플러그인 컴포넌트 상세 레퍼런스

1. Commands (명령어)

언제 사용하나?

• 반복 작업 자동화: /deploy, /test 같은 자주 쓰는 명령
• 팀 표준화: 모든 팀원이 동일한 방식으로 작업하도록
• 복잡한 프롬프트 저장: 긴 지시사항을 명령어로 저장

항목	내용
위치	플러그인 루트의 commands/ 디렉토리
파일 형식	프론트매터가 있는 Markdown 파일 (.md)
명령어 이름	파일명이 곧 명령어 이름 (예: deploy.md → /deploy)
호출 방식	사용자가 /명령어로 직접 호출

실전 예시 - 배포 명령어:

# commands/deploy.md
---
description: 프로덕션 배포 체크리스트 실행
allowed-tools: ["Bash", "Read"]
---

# 배포 전 체크리스트

다음 항목을 순서대로 확인하고 실행하세요:

1. **테스트 실행**: `npm test` 실행하고 모든 테스트 통과 확인
2. **빌드 확인**: `npm run build` 성공 여부 확인
3. **버전 확인**: package.json 버전이 올바른지 확인
4. **변경사항 요약**: 이번 배포에 포함된 주요 변경사항 정리

## 주의사항
- main 브랜치에서만 배포
- 금요일 오후에는 배포 자제

2. Agents (에이전트)

언제 사용하나?

• 전문 분야 위임: 보안 검토, 성능 분석 등 특화된 작업
• 자동 판단 필요: 작업 컨텍스트에 따라 Claude가 알아서 호출
• 복잡한 멀티스텝 작업: 여러 단계를 거치는 분석 작업

항목	내용
위치	agents/ 디렉토리
파일 형식	에이전트 기능을 설명하는 프론트매터가 있는 Markdown
호출 방식	Claude가 작업 컨텍스트에 따라 자동 호출
Commands와 차이	Commands는 사용자가 호출, Agents는 Claude가 판단해서 호출

실전 예시 - 보안 검토 에이전트:

# agents/security-reviewer.md
---
description: 코드의 보안 취약점을 분석하는 전문 에이전트
capabilities: ["security-analysis", "vulnerability-detection", "owasp-check"]
---

# Security Reviewer Agent

이 에이전트는 코드의 보안 취약점을 분석합니다.

## 전문 분야
- SQL Injection 탐지
- XSS 취약점 분석
- 인증/인가 로직 검토
- 민감 정보 노출 확인

## 언제 호출되나요?
- 사용자가 "보안 검토해줘"라고 요청할 때
- 인증 관련 코드를 작성할 때
- API 엔드포인트를 구현할 때

## 출력 형식
발견된 취약점을 심각도(Critical/High/Medium/Low)와 함께 보고합니다.

3. Skills (스킬)

언제 사용하나?

• 도메인 전문 지식: PDF 처리, 엑셀 조작, 특정 프레임워크 지식
• 도구 + 지식 조합: 참조 문서와 스크립트가 함께 필요한 경우
• 재사용 가능한 기능: 여러 프로젝트에서 공통으로 사용

항목	내용
위치	skills/ 디렉토리 내 하위 디렉토리
필수 파일	SKILL.md 파일 (대문자)
추가 파일	참조 문서, 스크립트, 템플릿 등 자유롭게 포함 가능
호출 방식	Claude가 작업 컨텍스트에 따라 자율적으로 호출

스킬 디렉토리 구조:

skills/
├── pdf-processor/
│   ├── SKILL.md           # 필수: 스킬 정의
│   ├── reference.md       # 선택: 참조 문서
│   └── scripts/           # 선택: 유틸리티 스크립트
│       └── extract-text.py
└── code-reviewer/
    ├── SKILL.md
    └── checklists/        # 선택: 체크리스트 템플릿
        └── security.md

4. Hooks (훅)

언제 사용하나?

• 자동 포매팅: 파일 저장 시 코드 포맷터 실행
• 검증: 커밋 전 린트 체크
• 알림: 작업 완료 시 Slack 알림
• 로깅: 모든 도구 사용 기록

항목	내용
위치	hooks/hooks.json 또는 plugin.json에 인라인
기능	Claude Code 이벤트에 자동 응답
실행	이벤트에 의해 트리거되는 셸 명령어나 스크립트

사용 가능한 훅 이벤트:

이벤트	언제 발생?	사용 예시
PreToolUse	Claude가 도구 사용 전	위험한 명령어 차단
PostToolUse	도구 실행 성공 후	파일 저장 시 포맷팅
UserPromptSubmit	사용자 프롬프트 제출 시	프롬프트 로깅
Notification	Claude Code 알림 전송 시	Slack 알림 연동
SessionStart/End	세션 시작/종료 시	환경 초기화/정리

훅 타입:

타입	설명	사용 예시
command	셸 명령어나 스크립트 실행	prettier --write
prompt	LLM으로 프롬프트 평가	보안 검증 프롬프트
agent	도구가 있는 에이전트 검증자 실행	복잡한 검증 로직

실전 예시 - 코드 저장 시 자동 포맷팅:

// hooks/hooks.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

5. MCP Servers

언제 사용하나?

• 외부 API 연동: Jira, Slack, GitHub API 등
• 데이터베이스 접근: PostgreSQL, MongoDB 등
• 커스텀 도구: 내부 시스템 연동

항목	내용
위치	.mcp.json 또는 plugin.json에 인라인
기능	Claude Code를 외부 도구 및 서비스와 연결
시작	플러그인 활성화 시 자동 시작

MCP 서버 설정 예시:

// .mcp.json
{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    }
  }
}

6. LSP Servers

언제 사용하나?

• 실시간 진단: 타입 에러, 문법 오류 즉시 감지
• 코드 탐색: 정의로 이동, 참조 찾기
• 언어별 인텔리전스: Go, Rust 등 언어 서버 연동

필드	필수	설명
command	O	실행할 LSP 바이너리 (PATH에 있어야 함)
extensionToLanguage	O	파일 확장자를 언어 식별자에 매핑
args	X	명령줄 인수
transport	X	stdio (기본) 또는 socket
restartOnCrash	X	충돌 시 자동 재시작

LSP 설정 예시 - Go 언어:

// .lsp.json
{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    },
    "restartOnCrash": true
  }
}

 

플러그인 매니페스트 스키마 (plugin.json)

plugin.json이란?

모든 플러그인의 필수 파일이다. 플러그인의 이름, 버전, 어떤 컴포넌트를 포함하는지 정의한다. 위치는 .claude-plugin/plugin.json이다.

최소 필수 구성

{
  "name": "plugin-name"  // 이것만 있으면 됨!
}

완전한 매니페스트 예시

{
  // 필수
  "name": "my-team-plugin",

  // 메타데이터 (선택)
  "version": "1.2.0",
  "description": "우리 팀을 위한 커스텀 플러그인",
  "author": {
    "name": "개발팀",
    "email": "dev@example.com"
  },
  "license": "MIT",
  "keywords": ["deployment", "ci-cd"],

  // 컴포넌트 경로 (선택 - 기본 위치와 다를 때만)
  "commands": "./custom/commands/",
  "agents": "./custom/agents/",
  "skills": "./custom/skills/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./.mcp.json",
  "lspServers": "./.lsp.json"
}

필드 상세 설명

필드	타입	설명
name *	string	플러그인 고유 이름 (필수)
version	string	시맨틱 버전 (예: "2.1.0")
description	string	플러그인 설명
commands	string | array	명령어 경로 (기본: commands/)
agents	string | array	에이전트 경로 (기본: agents/)
skills	string | array	스킬 경로 (기본: skills/)
hooks	string | object	훅 설정 경로 또는 인라인
mcpServers	string | object	MCP 설정 경로 또는 인라인
lspServers	string | object	LSP 설정 경로 또는 인라인

 

플러그인 설치 범위 - 어디에 설치할까?

설치 범위에 따라 사용 범위가 달라진다

개인용인지, 팀 공유용인지, 프로젝트 전용인지에 따라 설치 범위를 선택하자.

범위	설정 파일	언제 사용?
user (기본)	~/.claude/settings.json	개인용 - 모든 프로젝트에서 사용
project	.claude/settings.json	팀 공유 - Git으로 버전 관리됨
local	.claude/settings.local.json	프로젝트별 개인 설정 (gitignored)
managed	managed-settings.json	엔터프라이즈 관리 (읽기 전용)

# user 범위에 설치 (기본값)
claude plugin install ./my-plugin

# project 범위에 설치 (팀 공유)
claude plugin install ./my-plugin --scope project

# local 범위에 설치 (개인 + 이 프로젝트만)
claude plugin install ./my-plugin --scope local

 

환경 변수

필수로 알아야 할 변수

${CLAUDE_PLUGIN_ROOT}: 플러그인 디렉토리의 절대 경로.

훅, MCP 서버, 스크립트에서 플러그인 내부 파일을 참조할 때 반드시 사용하자. 이렇게 하면 어디에 설치되든 올바르게 작동한다.

// 올바른 사용
{
  "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
}

// 잘못된 사용 (절대 경로)
{
  "command": "/Users/me/plugins/my-plugin/scripts/format.sh"  // ❌
}

 

플러그인 디렉토리 구조

표준 플러그인 레이아웃

my-plugin/
├── .claude-plugin/           # 메타데이터 디렉토리
│   └── plugin.json          # ⭐ 필수: 플러그인 매니페스트
├── commands/                 # 슬래시 명령어
│   ├── deploy.md
│   └── test.md
├── agents/                   # AI 에이전트
│   ├── security-reviewer.md
│   └── code-analyzer.md
├── skills/                   # 스킬 (하위 디렉토리로 구성)
│   ├── pdf-processor/
│   │   ├── SKILL.md         # ⭐ 스킬 정의 (대문자)
│   │   └── scripts/
│   └── code-reviewer/
│       └── SKILL.md
├── hooks/                    # 훅 설정
│   └── hooks.json
├── .mcp.json                # MCP 서버 설정
├── .lsp.json                # LSP 서버 설정
├── scripts/                 # 유틸리티 스크립트
│   └── format-code.sh
└── README.md

 

CLI 명령어 레퍼런스

명령어	설명
claude plugin install <path>	로컬 또는 마켓플레이스에서 플러그인 설치
claude plugin uninstall <name>	플러그인 제거 (별칭: remove, rm)
claude plugin enable <name>	비활성화된 플러그인 활성화
claude plugin disable <name>	제거 없이 플러그인 비활성화
claude plugin update <name>	최신 버전으로 업데이트
claude --debug	디버그 모드로 실행 (플러그인 로딩 상태 확인)

설치 옵션:

# 로컬 디렉토리에서 설치
claude plugin install ./my-plugin

# 마켓플레이스에서 설치
claude plugin install formatter@my-marketplace

# 범위 지정
claude plugin install ./my-plugin --scope project  # user, project, local

 

문제 해결 - 자주 겪는 문제와 해결 방법

문제 1: 플러그인이 로딩되지 않음

증상

- 설치했는데 명령어가 나타나지 않음
- claude --debug에서 플러그인 관련 메시지 없음

원인

1. plugin.json에 JSON 문법 오류
2. .claude-plugin/plugin.json 경로가 잘못됨
3. name 필드 누락

해결 방법

# JSON 문법 검증
cat .claude-plugin/plugin.json | python -m json.tool

# 디버그 모드로 확인
claude --debug

문제 2: 명령어가 나타나지 않음

증상

- 플러그인은 로딩되는데 /mycommand가 안 됨

원인

1. commands/ 디렉토리가 루트에 없음
2. Markdown 파일에 프론트매터 누락
3. plugin.json에서 다른 경로를 지정했는데 해당 경로에 파일이 없음

해결 방법

# 디렉토리 구조 확인
ls -la ./my-plugin/commands/

# 프론트매터 확인 (파일 상단에 ---로 감싼 YAML)
head -10 ./my-plugin/commands/mycommand.md

문제 3: 훅이 실행되지 않음

증상

- PostToolUse 훅을 설정했는데 스크립트가 실행 안 됨

원인

1. 스크립트에 실행 권한이 없음
2. ${CLAUDE_PLUGIN_ROOT} 대신 절대 경로 사용
3. hooks.json에 JSON 문법 오류

해결 방법

# 스크립트 실행 권한 부여
chmod +x ./my-plugin/scripts/format-code.sh

# 경로 확인 (${CLAUDE_PLUGIN_ROOT} 사용해야 함)
grep -r "CLAUDE_PLUGIN_ROOT" ./my-plugin/

문제 4: MCP 서버 연결 실패

증상

- MCP 도구가 사용 불가
- "Server not found" 에러

원인

1. ${CLAUDE_PLUGIN_ROOT} 변수 미사용
2. 서버 바이너리가 PATH에 없음
3. 필요한 환경 변수 미설정

해결 방법

# 서버 실행 테스트
./my-plugin/servers/db-server --help

# .mcp.json에서 경로 확인
cat ./my-plugin/.mcp.json | python -m json.tool

 

핵심 요약 - 플러그인 개발 체크리스트

빠르게 확인하자

플러그인 개발 전후로 이 체크리스트를 확인하자.

항목	확인 사항
필수 파일	.claude-plugin/plugin.json 존재 → 최소한 "name" 필드 필수
JSON 문법	모든 JSON 파일 문법 검증 → python -m json.tool로 확인
Markdown 프론트매터	commands, agents, skills에 YAML 프론트매터 포함 → ---로 시작하고 끝
경로 참조	${CLAUDE_PLUGIN_ROOT} 사용 → 절대 경로 사용 금지
스크립트 권한	훅 스크립트에 실행 권한 → chmod +x script.sh
버전 관리	시맨틱 버전 사용 (MAJOR.MINOR.PATCH) → 첫 안정 버전은 1.0.0부터

 

참고 자료

• Plugins - 플러그인 사용 가이드
• Discover plugins - 마켓플레이스 탐색
• Skills - 스킬 작성 가이드
• Hooks - 훅 상세 레퍼런스
• MCP - Model Context Protocol 가이드