플러그인 레퍼런스

Claude Code 플러그인 시스템의 완전한 기술 레퍼런스로, 스키마, CLI 명령어, 컴포넌트 사양을 포함합니다.

팁: 플러그인을 설치하고 싶으신가요? 플러그인 검색 및 설치를 참조하세요. 플러그인을 만들려면 플러그인을 참조하세요. 플러그인을 배포하려면 플러그인 마켓플레이스를 참조하세요.

이 레퍼런스는 Claude Code 플러그인 시스템의 완전한 기술 사양을 제공하며, 컴포넌트 스키마, CLI 명령어, 개발 도구를 포함합니다.

플러그인은 Claude Code를 커스텀 기능으로 확장하는 자체 포함된 컴포넌트 디렉터리입니다. 플러그인 컴포넌트에는 스킬, 에이전트, 훅, MCP 서버, LSP 서버가 포함됩니다.

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

Skills

플러그인은 Claude Code에 스킬을 추가하여 사용자 또는 Claude가 호출할 수 있는 /name 단축키를 생성합니다.

위치: 플러그인 루트의 skills/ 또는 commands/ 디렉터리

파일 형식: 스킬은 SKILL.md가 포함된 디렉터리이며, 커맨드는 단순한 마크다운 파일입니다

스킬 구조:

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (optional)
│   └── scripts/ (optional)
└── code-reviewer/
    └── SKILL.md

통합 동작:

• 스킬과 커맨드는 플러그인 설치 시 자동으로 검색됩니다
• Claude는 작업 컨텍스트에 따라 자동으로 호출할 수 있습니다
• 스킬은 SKILL.md와 함께 지원 파일을 포함할 수 있습니다

자세한 내용은 Skills를 참조하세요.

Agents

플러그인은 특정 작업을 위한 전문 서브에이전트를 제공할 수 있으며, Claude가 적절한 상황에서 자동으로 호출할 수 있습니다.

위치: 플러그인 루트의 agents/ 디렉터리

파일 형식: 에이전트 기능을 설명하는 마크다운 파일

에이전트 구조:

---
name: agent-name
description: What this agent specializes in and when Claude should invoke it
---

Detailed system prompt for the agent describing its role, expertise, and behavior.

통합 포인트:

• 에이전트는 /agents 인터페이스에 표시됩니다
• Claude는 작업 컨텍스트에 따라 에이전트를 자동으로 호출할 수 있습니다
• 사용자가 에이전트를 수동으로 호출할 수 있습니다
• 플러그인 에이전트는 내장 Claude 에이전트와 함께 작동합니다

자세한 내용은 서브에이전트를 참조하세요.

Hooks

플러그인은 Claude Code 이벤트에 자동으로 응답하는 이벤트 핸들러를 제공할 수 있습니다.

위치: 플러그인 루트의 hooks/hooks.json 또는 plugin.json 내 인라인

형식: 이벤트 매처와 액션이 포함된 JSON 설정

훅 설정:

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

사용 가능한 이벤트:

• PreToolUse: Claude가 도구를 사용하기 전
• PostToolUse: Claude가 도구를 성공적으로 사용한 후
• PostToolUseFailure: Claude 도구 실행이 실패한 후
• PermissionRequest: 권한 대화상자가 표시될 때
• UserPromptSubmit: 사용자가 프롬프트를 제출할 때
• Notification: Claude Code가 알림을 보낼 때
• Stop: Claude가 중지를 시도할 때
• SubagentStart: 서브에이전트가 시작될 때
• SubagentStop: 서브에이전트가 중지를 시도할 때
• SessionStart: 세션이 시작될 때
• SessionEnd: 세션이 종료될 때
• TeammateIdle: 에이전트 팀의 팀원이 유휴 상태가 되려 할 때
• TaskCompleted: 작업이 완료로 표시될 때
• PreCompact: 대화 기록이 압축되기 전

훅 유형:

• command: 셸 명령어 또는 스크립트 실행
• prompt: LLM으로 프롬프트 평가 (컨텍스트를 위해 $ARGUMENTS 플레이스홀더 사용)
• agent: 복잡한 검증 작업을 위해 도구를 갖춘 에이전틱 검증기 실행

MCP 서버

플러그인은 Model Context Protocol (MCP) 서버를 번들로 제공하여 Claude Code를 외부 도구 및 서비스와 연결할 수 있습니다.

위치: 플러그인 루트의 .mcp.json 또는 plugin.json 내 인라인

형식: 표준 MCP 서버 설정

MCP 서버 설정:

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

통합 동작:

• 플러그인 MCP 서버는 플러그인이 활성화되면 자동으로 시작됩니다
• 서버는 Claude의 도구 모음에서 표준 MCP 도구로 표시됩니다
• 서버 기능은 Claude의 기존 도구와 원활하게 통합됩니다
• 플러그인 서버는 사용자 MCP 서버와 독립적으로 설정할 수 있습니다

LSP 서버

팁: LSP 플러그인을 사용하고 싶으신가요? 공식 마켓플레이스에서 설치하세요: /plugin Discover 탭에서 "lsp"를 검색하세요. 이 섹션은 공식 마켓플레이스에서 다루지 않는 언어를 위한 LSP 플러그인 생성 방법을 문서화합니다.

플러그인은 Language Server Protocol (LSP) 서버를 제공하여 코드베이스 작업 중 Claude에게 실시간 코드 인텔리전스를 제공할 수 있습니다.

LSP 통합은 다음을 제공합니다:

• 즉각적인 진단: Claude가 편집 직후 오류와 경고를 즉시 확인
• 코드 탐색: 정의로 이동, 참조 찾기, 호버 정보
• 언어 인식: 코드 심볼에 대한 타입 정보와 문서

위치: 플러그인 루트의 .lsp.json 또는 plugin.json 내 인라인

형식: 언어 서버 이름을 설정에 매핑하는 JSON 설정

.lsp.json 파일 형식:

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

plugin.json 내 인라인:

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

필수 필드:

필드	설명
command	실행할 LSP 바이너리 (PATH에 있어야 함)
extensionToLanguage	파일 확장자를 언어 식별자에 매핑

선택 필드:

필드	설명
args	LSP 서버의 커맨드라인 인수
transport	통신 전송 방식: stdio (기본값) 또는 socket
env	서버 시작 시 설정할 환경 변수
initializationOptions	초기화 중 서버에 전달되는 옵션
settings	workspace/didChangeConfiguration을 통해 전달되는 설정
workspaceFolder	서버의 워크스페이스 폴더 경로
startupTimeout	서버 시작 대기 최대 시간 (밀리초)
shutdownTimeout	정상 종료 대기 최대 시간 (밀리초)
restartOnCrash	서버 충돌 시 자동 재시작 여부
maxRestarts	포기하기 전 최대 재시작 시도 횟수

주의: 언어 서버 바이너리는 별도로 설치해야 합니다. LSP 플러그인은 Claude Code가 언어 서버에 연결하는 방법을 설정하지만, 서버 자체를 포함하지는 않습니다. /plugin Errors 탭에서 Executable not found in $PATH가 표시되면, 해당 언어에 필요한 바이너리를 설치하세요.

사용 가능한 LSP 플러그인:

플러그인	언어 서버	설치 명령어
pyright-lsp	Pyright (Python)	pip install pyright 또는 npm install -g pyright
typescript-lsp	TypeScript Language Server	npm install -g typescript-language-server typescript
rust-lsp	rust-analyzer	rust-analyzer 설치 안내 참조

먼저 언어 서버를 설치한 후 마켓플레이스에서 플러그인을 설치하세요.

---

플러그인 설치 스코프

플러그인을 설치할 때 플러그인이 사용 가능한 위치와 다른 사람이 사용할 수 있는지를 결정하는 스코프를 선택합니다:

스코프	설정 파일	사용 사례
user	~/.claude/settings.json	모든 프로젝트에서 사용 가능한 개인 플러그인 (기본값)
project	.claude/settings.json	버전 관리를 통해 공유되는 팀 플러그인
local	.claude/settings.local.json	프로젝트별 플러그인, gitignore 대상
managed	관리형 설정	관리형 플러그인 (읽기 전용, 업데이트만 가능)

플러그인은 다른 Claude Code 설정과 동일한 스코프 시스템을 사용합니다. 설치 안내와 스코프 플래그는 플러그인 설치를 참조하세요. 스코프에 대한 완전한 설명은 설정 스코프를 참조하세요.

---

플러그인 매니페스트 스키마

.claude-plugin/plugin.json 파일은 플러그인의 메타데이터와 설정을 정의합니다. 이 섹션에서는 지원되는 모든 필드와 옵션을 문서화합니다.

매니페스트는 선택 사항입니다. 생략하면 Claude Code가 기본 위치에서 컴포넌트를 자동 검색하고 디렉터리 이름에서 플러그인 이름을 추출합니다. 메타데이터나 커스텀 컴포넌트 경로를 제공해야 할 때 매니페스트를 사용하세요.

전체 스키마

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "[email protected]",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "commands": ["./custom/commands/special.md"],
  "agents": "./custom/agents/",
  "skills": "./custom/skills/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json"
}

필수 필드

매니페스트를 포함하는 경우 name이 유일한 필수 필드입니다.

필드	타입	설명	예시
name	string	고유 식별자 (kebab-case, 공백 불가)	"deployment-tools"

이 이름은 컴포넌트의 네임스페이싱에 사용됩니다. 예를 들어, UI에서 plugin-dev라는 이름의 플러그인에 속한 agent-creator 에이전트는 plugin-dev:agent-creator로 표시됩니다.

메타데이터 필드

필드	타입	설명	예시
version	string	시맨틱 버전. 마켓플레이스 항목에도 설정된 경우 plugin.json이 우선합니다. 한 곳에만 설정하면 됩니다.	"2.1.0"
description	string	플러그인 목적에 대한 간단한 설명	"Deployment automation tools"
author	object	작성자 정보	{"name": "Dev Team", "email": "[email protected]"}
homepage	string	문서 URL	"https://docs.example.com"
repository	string	소스 코드 URL	"https://github.com/user/plugin"
license	string	라이선스 식별자	"MIT", "Apache-2.0"
keywords	array	검색 태그	["deployment", "ci-cd"]

컴포넌트 경로 필드

필드	타입	설명	예시
commands	string|array	추가 커맨드 파일/디렉터리	"./custom/cmd.md" 또는 ["./cmd1.md"]
agents	string|array	추가 에이전트 파일	"./custom/agents/reviewer.md"
skills	string|array	추가 스킬 디렉터리	"./custom/skills/"
hooks	string|array|object	훅 설정 경로 또는 인라인 설정	"./my-extra-hooks.json"
mcpServers	string|array|object	MCP 설정 경로 또는 인라인 설정	"./my-extra-mcp-config.json"
outputStyles	string|array	추가 출력 스타일 파일/디렉터리	"./styles/"
lspServers	string|array|object	코드 인텔리전스(정의로 이동, 참조 찾기 등)를 위한 Language Server Protocol 설정	"./.lsp.json"

경로 동작 규칙

중요: 커스텀 경로는 기본 디렉터리를 대체하지 않고 보충합니다.

• commands/가 존재하면, 커스텀 커맨드 경로와 함께 추가로 로드됩니다
• 모든 경로는 플러그인 루트에 대한 상대 경로여야 하며 ./로 시작해야 합니다
• 커스텀 경로의 커맨드도 동일한 네이밍 및 네임스페이싱 규칙을 사용합니다
• 유연성을 위해 여러 경로를 배열로 지정할 수 있습니다

경로 예시:

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

환경 변수

${CLAUDE_PLUGIN_ROOT}: 플러그인 디렉터리의 절대 경로를 포함합니다. 설치 위치에 관계없이 올바른 경로를 보장하기 위해 훅, MCP 서버, 스크립트에서 이 변수를 사용하세요.

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

---

플러그인 캐싱과 파일 해석

플러그인은 두 가지 방법 중 하나로 지정됩니다:

• claude --plugin-dir을 통해 세션 동안 지정
• 마켓플레이스를 통해 향후 세션을 위해 설치

보안 및 검증 목적으로, Claude Code는 마켓플레이스 플러그인을 제자리에서 사용하지 않고 사용자의 로컬 플러그인 캐시 (~/.claude/plugins/cache)로 복사합니다. 이 동작을 이해하는 것은 외부 파일을 참조하는 플러그인을 개발할 때 중요합니다.

경로 순회 제한

설치된 플러그인은 자체 디렉터리 외부의 파일을 참조할 수 없습니다. 플러그인 루트 외부로 순회하는 경로(예: ../shared-utils)는 설치 후 작동하지 않습니다. 해당 외부 파일이 캐시에 복사되지 않기 때문입니다.

외부 의존성 작업

플러그인이 자체 디렉터리 외부의 파일에 접근해야 하는 경우, 플러그인 디렉터리 내에 외부 파일에 대한 심볼릭 링크를 생성할 수 있습니다. 심볼릭 링크는 복사 과정에서 유지됩니다:

# Inside your plugin directory
ln -s /path/to/shared-utils ./shared-utils

심볼릭 링크된 콘텐츠는 플러그인 캐시에 복사됩니다. 이를 통해 캐싱 시스템의 보안 이점을 유지하면서 유연성을 제공합니다.

---

플러그인 디렉터리 구조

표준 플러그인 레이아웃

완전한 플러그인은 다음 구조를 따릅니다:

enterprise-plugin/
├── .claude-plugin/           # 메타데이터 디렉터리 (선택 사항)
│   └── plugin.json             # 플러그인 매니페스트
├── commands/                 # 기본 커맨드 위치
│   ├── status.md
│   └── logs.md
├── agents/                   # 기본 에이전트 위치
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── skills/                   # 에이전트 스킬
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── hooks/                    # 훅 설정
│   ├── hooks.json           # 메인 훅 설정
│   └── security-hooks.json  # 추가 훅
├── settings.json            # 플러그인 기본 설정
├── .mcp.json                # MCP 서버 정의
├── .lsp.json                # LSP 서버 설정
├── scripts/                 # 훅 및 유틸리티 스크립트
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # 라이선스 파일
└── CHANGELOG.md             # 버전 기록

주의: .claude-plugin/ 디렉터리에는 plugin.json 파일이 포함됩니다. 다른 모든 디렉터리(commands/, agents/, skills/, hooks/)는 .claude-plugin/ 내부가 아닌 플러그인 루트에 있어야 합니다.

파일 위치 레퍼런스

컴포넌트	기본 위치	용도
매니페스트	.claude-plugin/plugin.json	플러그인 메타데이터 및 설정 (선택 사항)
커맨드	commands/	스킬 마크다운 파일 (레거시; 새 스킬은 skills/ 사용)
에이전트	agents/	서브에이전트 마크다운 파일
스킬	skills/	<name>/SKILL.md 구조의 스킬
훅	hooks/hooks.json	훅 설정
MCP 서버	.mcp.json	MCP 서버 정의
LSP 서버	.lsp.json	언어 서버 설정
설정	settings.json	플러그인 활성화 시 적용되는 기본 설정. 현재 agent 설정만 지원됩니다

---

CLI 명령어 레퍼런스

Claude Code는 비대화형 플러그인 관리를 위한 CLI 명령어를 제공하며, 스크립팅과 자동화에 유용합니다.

plugin install

사용 가능한 마켓플레이스에서 플러그인을 설치합니다.

claude plugin install <plugin> [options]

인수:

• <plugin>: 플러그인 이름 또는 특정 마켓플레이스를 지정하는 plugin-name@marketplace-name

옵션:

옵션	설명	기본값
-s, --scope <scope>	설치 스코프: user, project, 또는 local	user
-h, --help	명령어 도움말 표시

스코프는 설치된 플러그인이 추가되는 설정 파일을 결정합니다. 예를 들어, --scope project는 .claude/settings.json의 enabledPlugins에 기록하여 프로젝트 저장소를 클론하는 모든 사람이 플러그인을 사용할 수 있게 합니다.

예시:

# Install to user scope (default)
claude plugin install formatter@my-marketplace

# Install to project scope (shared with team)
claude plugin install formatter@my-marketplace --scope project

# Install to local scope (gitignored)
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

설치된 플러그인을 제거합니다.

claude plugin uninstall <plugin> [options]

인수:

• <plugin>: 플러그인 이름 또는 plugin-name@marketplace-name

옵션:

옵션	설명	기본값
-s, --scope <scope>	제거할 스코프: user, project, 또는 local	user
-h, --help	명령어 도움말 표시

별칭: remove, rm

plugin enable

비활성화된 플러그인을 활성화합니다.

claude plugin enable <plugin> [options]

인수:

• <plugin>: 플러그인 이름 또는 plugin-name@marketplace-name

옵션:

옵션	설명	기본값
-s, --scope <scope>	활성화할 스코프: user, project, 또는 local	user
-h, --help	명령어 도움말 표시

plugin disable

플러그인을 제거하지 않고 비활성화합니다.

claude plugin disable <plugin> [options]

인수:

• <plugin>: 플러그인 이름 또는 plugin-name@marketplace-name

옵션:

옵션	설명	기본값
-s, --scope <scope>	비활성화할 스코프: user, project, 또는 local	user
-h, --help	명령어 도움말 표시

plugin update

플러그인을 최신 버전으로 업데이트합니다.

claude plugin update <plugin> [options]

인수:

• <plugin>: 플러그인 이름 또는 plugin-name@marketplace-name

옵션:

옵션	설명	기본값
-s, --scope <scope>	업데이트할 스코프: user, project, local, 또는 managed	user
-h, --help	명령어 도움말 표시

---

디버깅 및 개발 도구

디버깅 명령어

플러그인 로딩 세부 정보를 확인하려면 claude --debug(또는 TUI 내에서 /debug)를 사용하세요:

다음 정보가 표시됩니다:

• 로드 중인 플러그인
• 플러그인 매니페스트의 오류
• 커맨드, 에이전트, 훅 등록 상태
• MCP 서버 초기화 상태

일반적인 문제

문제	원인	해결 방법
플러그인이 로드되지 않음	잘못된 plugin.json	claude plugin validate 또는 /plugin validate로 JSON 구문 검증
커맨드가 표시되지 않음	잘못된 디렉터리 구조	commands/가 .claude-plugin/ 내부가 아닌 루트에 있는지 확인
훅이 실행되지 않음	스크립트에 실행 권한 없음	chmod +x script.sh 실행
MCP 서버 실패	${CLAUDE_PLUGIN_ROOT} 누락	모든 플러그인 경로에 변수 사용
경로 오류	절대 경로 사용	모든 경로는 상대 경로여야 하며 ./로 시작해야 함
LSP Executable not found in $PATH	언어 서버 미설치	바이너리 설치 (예: npm install -g typescript-language-server typescript)

오류 메시지 예시

매니페스트 유효성 검사 오류:

• Invalid JSON syntax: Unexpected token } in JSON at position 142: 누락된 쉼표, 여분의 쉼표, 또는 따옴표 없는 문자열 확인
• Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required: 필수 필드가 누락됨
• Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: JSON 구문 오류

플러그인 로딩 오류:

• Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.: 커맨드 경로가 존재하지만 유효한 커맨드 파일이 없음
• Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.: marketplace.json의 source 경로가 존재하지 않는 디렉터리를 가리킴
• Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.: 중복 컴포넌트 정의를 제거하거나 마켓플레이스 항목에서 strict: false를 제거

훅 문제 해결

훅 스크립트가 실행되지 않는 경우:

1. 스크립트에 실행 권한이 있는지 확인: chmod +x ./scripts/your-script.sh
2. 셔뱅 라인 확인: 첫 줄이 #!/bin/bash 또는 #!/usr/bin/env bash여야 함
3. 경로에 ${CLAUDE_PLUGIN_ROOT}가 사용되었는지 확인: "command": "${CLAUDE_PLUGIN_ROOT}/scripts/your-script.sh"
4. 스크립트를 수동으로 테스트: ./scripts/your-script.sh

훅이 예상 이벤트에서 트리거되지 않는 경우:

1. 이벤트 이름이 정확한지 확인 (대소문자 구분): PostToolUse이며 postToolUse가 아님
2. 매처 패턴이 도구와 일치하는지 확인: 파일 작업의 경우 "matcher": "Write|Edit"
3. 훅 유형이 유효한지 확인: command, prompt, 또는 agent

MCP 서버 문제 해결

서버가 시작되지 않는 경우:

1. 명령어가 존재하고 실행 가능한지 확인
2. 모든 경로에 ${CLAUDE_PLUGIN_ROOT} 변수가 사용되었는지 확인
3. MCP 서버 로그 확인: claude --debug에서 초기화 오류 표시
4. Claude Code 외부에서 서버를 수동으로 테스트

서버 도구가 표시되지 않는 경우:

1. 서버가 .mcp.json 또는 plugin.json에 올바르게 설정되었는지 확인
2. 서버가 MCP 프로토콜을 올바르게 구현했는지 확인
3. 디버그 출력에서 연결 타임아웃 확인

디렉터리 구조 실수

증상: 플러그인이 로드되지만 컴포넌트(커맨드, 에이전트, 훅)가 누락됨.

올바른 구조: 컴포넌트는 .claude-plugin/ 내부가 아닌 플러그인 루트에 있어야 합니다. plugin.json만 .claude-plugin/에 속합니다.

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← 매니페스트만 여기에
├── commands/            ← 루트 레벨에
├── agents/              ← 루트 레벨에
└── hooks/               ← 루트 레벨에

컴포넌트가 .claude-plugin/ 내부에 있다면 플러그인 루트로 이동하세요.

디버그 체크리스트:

1. claude --debug를 실행하고 "loading plugin" 메시지를 확인
2. 각 컴포넌트 디렉터리가 디버그 출력에 나열되는지 확인
3. 파일 권한이 플러그인 파일 읽기를 허용하는지 확인

---

배포 및 버전 관리 레퍼런스

버전 관리

플러그인 릴리스에는 시맨틱 버전 관리를 따르세요:

{
  "name": "my-plugin",
  "version": "2.1.0"
}

버전 형식: MAJOR.MINOR.PATCH

• MAJOR: 호환성을 깨는 변경 (호환되지 않는 API 변경)
• MINOR: 새 기능 (하위 호환 가능한 추가)
• PATCH: 버그 수정 (하위 호환 가능한 수정)

모범 사례:

• 첫 번째 안정 릴리스는 1.0.0부터 시작
• 변경 사항을 배포하기 전에 plugin.json의 버전을 업데이트
• CHANGELOG.md 파일에 변경 사항을 문서화
• 테스트를 위해 2.0.0-beta.1과 같은 프리릴리스 버전 사용

주의: Claude Code는 버전을 사용하여 플러그인을 업데이트할지 결정합니다. 플러그인 코드를 변경했지만 plugin.json의 버전을 올리지 않으면, 캐싱으로 인해 기존 사용자에게 변경 사항이 표시되지 않습니다.

플러그인이 마켓플레이스 디렉터리 내에 있는 경우, marketplace.json을 통해 버전을 관리하고 plugin.json에서 version 필드를 생략할 수 있습니다.

---

관련 문서

• 플러그인 - 튜토리얼 및 실제 사용법
• 플러그인 마켓플레이스 - 마켓플레이스 생성 및 관리
• Skills - 스킬 개발 세부 사항
• 서브에이전트 - 에이전트 설정 및 기능
• Hooks - 이벤트 처리 및 자동화
• MCP - 외부 도구 통합
• 설정 - 플러그인 설정 옵션