SpyBara
Go Premium

plugins-reference.md 2026-05-02 18:14 UTC to 2026-05-04 22:58 UTC

1011 added, 0 removed.

2026
Sun 31 06:39 Sat 30 06:23 Fri 29 06:38 Thu 28 06:37 Wed 27 06:42 Tue 26 06:33 Sun 24 06:25 Sat 23 06:18 Fri 22 06:33 Thu 21 06:36 Wed 20 06:35 Tue 19 06:34 Mon 18 23:59 Sun 17 01:01 Fri 15 22:58 Thu 14 17:02 Wed 13 23:01 Tue 12 22:57 Mon 11 23:00 Sun 10 23:03 Sat 9 04:57 Fri 8 22:00 Thu 7 22:59 Tue 5 23:00 Mon 4 22:58 Sat 2 18:14 Fri 1 18:19

플러그인 참조

Claude Code 플러그인 시스템의 완전한 기술 참조, 스키마, CLI 명령어 및 컴포넌트 사양 포함.

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

플러그인은 Claude Code를 사용자 정의 기능으로 확장하는 자체 포함된 컴포넌트 디렉토리입니다. 플러그인 컴포넌트에는 skills, agents, hooks, MCP servers, LSP servers 및 monitors가 포함됩니다.

플러그인 컴포넌트 참조

Skills

플러그인은 Claude Code에 skills를 추가하여 사용자나 Claude가 호출할 수 있는 /name 바로가기를 생성합니다.

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

파일 형식: Skills는 SKILL.md가 있는 디렉토리이고, commands는 간단한 마크다운 파일입니다.

Skill 구조:

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (선택사항)
│   └── scripts/ (선택사항)
└── code-reviewer/
    └── SKILL.md

통합 동작:

  • Skills와 commands는 플러그인이 설치될 때 자동으로 발견됩니다.
  • Claude는 작업 컨텍스트에 따라 자동으로 이들을 호출할 수 있습니다.
  • Skills는 SKILL.md와 함께 지원 파일을 포함할 수 있습니다.

완전한 세부 정보는 Skills를 참조하세요.

Agents

플러그인은 Claude가 적절할 때 자동으로 호출할 수 있는 특정 작업을 위한 특화된 subagents를 제공할 수 있습니다.

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

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

Agent 구조:

---
name: agent-name
description: 이 에이전트가 전문으로 하는 분야와 Claude가 이를 호출해야 할 때
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

에이전트의 역할, 전문성 및 동작을 설명하는 상세한 시스템 프롬프트입니다.

플러그인 agents는 name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background 및 isolation frontmatter 필드를 지원합니다. 유일한 유효한 isolation 값은 "worktree"입니다. 보안상의 이유로 hooks, mcpServers 및 permissionMode는 플러그인 제공 agents에서 지원되지 않습니다.

통합 지점:

  • Agents는 /agents 인터페이스에 나타납니다.
  • Claude는 작업 컨텍스트에 따라 agents를 자동으로 호출할 수 있습니다.
  • Agents는 사용자가 수동으로 호출할 수 있습니다.
  • 플러그인 agents는 기본 제공 Claude agents와 함께 작동합니다.

완전한 세부 정보는 Subagents를 참조하세요.

Hooks

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

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

형식: 이벤트 매처 및 작업이 있는 JSON 구성

Hook 구성:

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

플러그인 hooks는 사용자 정의 hooks와 동일한 라이프사이클 이벤트에 응답합니다:

Event When it fires
SessionStart When a session begins or resumes
Setup When you start Claude Code with --init-only, or with --init or --maintenance in -p mode. For one-time preparation in CI or scripts
UserPromptSubmit When you submit a prompt, before Claude processes it
UserPromptExpansion When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion
PreToolUse Before a tool call executes. Can block it
PermissionRequest When a permission dialog appears
PermissionDenied When a tool call is denied by the auto mode classifier. Return {retry: true} to tell the model it may retry the denied tool call
PostToolUse After a tool call succeeds
PostToolUseFailure After a tool call fails
PostToolBatch After a full batch of parallel tool calls resolves, before the next model call
Notification When Claude Code sends a notification
SubagentStart When a subagent is spawned
SubagentStop When a subagent finishes
TaskCreated When a task is being created via TaskCreate
TaskCompleted When a task is being marked as completed
Stop When Claude finishes responding
StopFailure When the turn ends due to an API error. Output and exit code are ignored
TeammateIdle When an agent team teammate is about to go idle
InstructionsLoaded When a CLAUDE.md or .claude/rules/*.md file is loaded into context. Fires at session start and when files are lazily loaded during a session
ConfigChange When a configuration file changes during a session
CwdChanged When the working directory changes, for example when Claude executes a cd command. Useful for reactive environment management with tools like direnv
FileChanged When a watched file changes on disk. The matcher field specifies which filenames to watch
WorktreeCreate When a worktree is being created via --worktree or isolation: "worktree". Replaces default git behavior
WorktreeRemove When a worktree is being removed, either at session exit or when a subagent finishes
PreCompact Before context compaction
PostCompact After context compaction completes
Elicitation When an MCP server requests user input during a tool call
ElicitationResult After a user responds to an MCP elicitation, before the response is sent back to the server
SessionEnd When a session terminates

Hook 유형:

  • command: 셸 명령어 또는 스크립트 실행
  • http: 이벤트 JSON을 URL로 POST 요청으로 전송
  • mcp_tool: 구성된 MCP server에서 도구 호출
  • prompt: LLM으로 프롬프트 평가 (컨텍스트에 대해 $ARGUMENTS 플레이스홀더 사용)
  • agent: 복잡한 검증 작업을 위해 도구가 있는 에이전트 검증자 실행

MCP servers

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

위치: 플러그인 루트의 .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 servers는 플러그인이 활성화될 때 자동으로 시작됩니다.
  • Servers는 Claude의 도구 키트에서 표준 MCP 도구로 나타납니다.
  • 서버 기능은 Claude의 기존 도구와 원활하게 통합됩니다.
  • 플러그인 servers는 사용자 MCP servers와 독립적으로 구성할 수 있습니다.

LSP servers

플러그인은 Language Server Protocol (LSP) servers를 제공하여 코드베이스에서 작업할 때 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 플러그인:

플러그인 언어 서버 설치 명령어
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 설치 참조

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

Monitors

플러그인은 플러그인이 활성화될 때 Claude Code가 자동으로 시작하는 백그라운드 monitors를 선언할 수 있습니다. 각 monitor는 세션 동안 셸 명령어를 실행하고 모든 stdout 라인을 Claude에게 알림으로 전달하므로 Claude는 로그 항목, 상태 변경 또는 폴링된 이벤트에 반응할 수 있으며 자신이 watch를 시작하도록 요청받을 필요가 없습니다.

플러그인 monitors는 Monitor tool과 동일한 메커니즘을 사용하며 해당 가용성 제약을 공유합니다. 이들은 대화형 CLI 세션에서만 실행되고, hooks와 동일한 신뢰 수준에서 샌드박스 없이 실행되며, Monitor tool을 사용할 수 없는 호스트에서는 건너뜁니다.

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

형식: monitor 항목의 JSON 배열

다음 monitors/monitors.json은 배포 상태 엔드포인트와 로컬 오류 로그를 감시합니다:

[
  {
    "name": "deploy-status",
    "command": "${CLAUDE_PLUGIN_ROOT}/scripts/poll-deploy.sh ${user_config.api_endpoint}",
    "description": "배포 상태 변경"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "애플리케이션 오류 로그",
    "when": "on-skill-invoke:debug"
  }
]

monitors를 인라인으로 선언하려면 plugin.json의 monitors 키를 동일한 배열로 설정하세요. 기본이 아닌 경로에서 로드하려면 monitors를 "./config/monitors.json"과 같은 상대 경로 문자열로 설정하세요.

필수 필드:

필드 설명
name 플러그인 내에서 고유한 식별자. 플러그인이 다시 로드되거나 skill이 다시 호출될 때 중복 프로세스를 방지합니다.
command 세션 작업 디렉토리에서 영구 백그라운드 프로세스로 실행되는 셸 명령어
description 감시 중인 항목에 대한 간단한 요약. 작업 패널 및 알림 요약에 표시됩니다.

선택사항 필드:

필드 설명
when monitor가 시작되는 시기를 제어합니다. "always"는 세션 시작 및 플러그인 다시 로드 시 시작하며 기본값입니다. "on-skill-invoke:<skill-name>"은 이 플러그인의 명명된 skill이 처음 발송될 때 시작합니다.

command 값은 MCP 및 LSP 서버 구성과 동일한 변수 대체를 지원합니다: ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}, ${user_config.*} 및 환경의 모든 ${ENV_VAR}. 스크립트가 플러그인 자체 디렉토리에서 실행되어야 하는 경우 명령어 앞에 cd "${CLAUDE_PLUGIN_ROOT}" && 를 붙이세요.

세션 중간에 플러그인을 비활성화해도 이미 실행 중인 monitors는 중지되지 않습니다. 세션이 끝날 때 중지됩니다.

Themes

플러그인은 /theme에 기본 제공 프리셋 및 사용자의 로컬 테마와 함께 나타나는 색상 테마를 제공할 수 있습니다. 테마는 themes/ 디렉토리의 JSON 파일로, base 프리셋과 색상 토큰의 sparse overrides 맵을 포함합니다.

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

플러그인 테마를 선택하면 사용자의 구성에 custom:<plugin-name>:<slug>이 유지됩니다. 플러그인 테마는 읽기 전용입니다. /theme에서 하나에 Ctrl+E를 누르면 ~/.claude/themes/로 복사되어 사용자가 복사본을 편집할 수 있습니다.

플러그인 설치 범위

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

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

플러그인은 다른 Claude Code 구성과 동일한 범위 시스템을 사용합니다. 설치 지침 및 범위 플래그는 플러그인 설치를 참조하세요. 범위에 대한 완전한 설명은 구성 범위를 참조하세요.

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

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

매니페스트는 선택사항입니다. 생략하면 Claude Code는 기본 위치에서 컴포넌트를 자동으로 발견하고 디렉토리 이름에서 플러그인 이름을 파생합니다. 메타데이터를 제공하거나 사용자 정의 컴포넌트 경로가 필요할 때 매니페스트를 사용하세요.

완전한 스키마

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "간단한 플러그인 설명",
  "author": {
    "name": "작성자 이름",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "themes": "./themes/",
  "lspServers": "./.lsp.json",
  "monitors": "./monitors.json",
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

필수 필드

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

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

이 이름은 컴포넌트 네임스페이싱에 사용됩니다. 예를 들어 UI에서 이름이 plugin-dev인 플러그인의 agent agent-creator는 plugin-dev:agent-creator로 나타납니다.

메타데이터 필드

필드 타입 설명 예시
$schema string 편집기 자동 완성 및 검증을 위한 JSON Schema URL. Claude Code는 로드 시 이 필드를 무시합니다. "https://json.schemastore.org/claude-code-plugin-manifest.json"
version string 선택사항. 의미 있는 버전. 이를 설정하면 플러그인이 해당 버전 문자열로 고정되므로 사용자는 버전을 올릴 때만 업데이트를 받습니다. 생략하면 Claude Code는 git 커밋 SHA로 폴백되므로 모든 커밋이 새 버전으로 취급됩니다. 마켓플레이스 항목에도 설정된 경우 plugin.json이 우선합니다. 버전 관리를 참조하세요. "2.1.0"
description string 플러그인 목적에 대한 간단한 설명 "배포 자동화 도구"
author object 작성자 정보 {"name": "Dev Team", "email": "dev@company.com"}
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"]

컴포넌트 경로 필드

필드 타입 설명 예시
skills string|array <name>/SKILL.md를 포함하는 사용자 정의 skill 디렉토리 (기본 skills/ 대체) "./custom/skills/"
commands string|array 사용자 정의 평면 .md skill 파일 또는 디렉토리 (기본 commands/ 대체) "./custom/cmd.md" 또는 ["./cmd1.md"]
agents string|array 사용자 정의 agent 파일 (기본 agents/ 대체) "./custom/agents/reviewer.md"
hooks string|array|object Hook 구성 경로 또는 인라인 구성 "./my-extra-hooks.json"
mcpServers string|array|object MCP 구성 경로 또는 인라인 구성 "./my-extra-mcp-config.json"
outputStyles string|array 사용자 정의 출력 스타일 파일/디렉토리 (기본 output-styles/ 대체) "./styles/"
themes string|array 색상 테마 파일/디렉토리 (기본 themes/ 대체). 테마 참조 "./themes/"
lspServers string|array|object Language Server Protocol 코드 인텔리전스 구성 (정의로 이동, 참조 찾기 등) "./.lsp.json"
monitors string|array 플러그인이 활성화될 때 자동으로 시작되는 백그라운드 Monitor 구성. Monitors 참조 "./monitors.json"
userConfig object 플러그인이 활성화될 때 사용자에게 프롬프트하는 사용자 구성 가능 값. 사용자 구성 참조 아래 참조
channels array 메시지 주입을 위한 채널 선언 (Telegram, Slack, Discord 스타일). 채널 참조 아래 참조
dependencies array 이 플러그인이 필요로 하는 다른 플러그인, 선택적으로 semver 버전 제약 포함. 플러그인 종속성 버전 제약 참조 [{ "name": "secrets-vault", "version": "~2.1.0" }]

사용자 구성

userConfig 필드는 플러그인이 활성화될 때 Claude Code가 사용자에게 프롬프트하는 값을 선언합니다. 사용자가 settings.json을 수동으로 편집하도록 요구하는 대신 이를 사용하세요.

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API 엔드포인트",
      "description": "팀의 API 엔드포인트"
    },
    "api_token": {
      "type": "string",
      "title": "API 토큰",
      "description": "API 인증 토큰",
      "sensitive": true
    }
  }
}

키는 유효한 식별자여야 합니다. 각 옵션은 다음 필드를 지원합니다:

필드 필수 설명
type 예 string, number, boolean, directory 또는 file 중 하나
title 예 구성 대화에 표시되는 레이블
description 예 필드 아래에 표시되는 도움말 텍스트
sensitive 아니오 true인 경우 입력을 마스킹하고 값을 settings.json 대신 보안 저장소에 저장합니다.
required 아니오 true인 경우 필드가 비어 있으면 검증이 실패합니다.
default 아니오 사용자가 아무것도 제공하지 않을 때 사용되는 값
multiple 아니오 string 타입의 경우 문자열 배열 허용
min / max 아니오 number 타입의 범위

각 값은 MCP 및 LSP 서버 구성, hook 명령어 및 monitor 명령어에서 ${user_config.KEY}로 대체할 수 있습니다. 민감하지 않은 값은 skill 및 agent 콘텐츠에서도 대체할 수 있습니다. 모든 값은 플러그인 서브프로세스에 CLAUDE_PLUGIN_OPTION_<KEY> 환경 변수로 내보내집니다.

민감하지 않은 값은 settings.json의 pluginConfigs[<plugin-id>].options 아래에 저장됩니다. 민감한 값은 시스템 키체인 (또는 키체인을 사용할 수 없는 경우 ~/.claude/.credentials.json)으로 이동합니다. 키체인 저장소는 OAuth 토큰과 공유되며 약 2 KB의 총 제한이 있으므로 민감한 값을 작게 유지하세요.

채널

channels 필드를 사용하면 플러그인이 하나 이상의 메시지 채널을 선언하여 대화에 콘텐츠를 주입할 수 있습니다. 각 채널은 플러그인이 제공하는 MCP 서버에 바인딩됩니다.

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "봇 토큰",
          "description": "Telegram 봇 토큰",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "소유자 ID",
          "description": "Telegram 사용자 ID"
        }
      }
    }
  ]
}

server 필드는 필수이며 플러그인의 mcpServers의 키와 일치해야 합니다. 선택사항인 채널별 userConfig는 최상위 필드와 동일한 스키마를 사용하여 플러그인이 플러그인이 활성화될 때 봇 토큰 또는 소유자 ID를 프롬프트할 수 있습니다.

경로 동작 규칙

skills, commands, agents, outputStyles, themes 및 monitors의 경우 사용자 정의 경로는 기본값을 대체합니다. 매니페스트가 skills를 지정하면 기본 skills/ 디렉토리는 스캔되지 않습니다. 매니페스트가 monitors를 지정하면 기본 monitors/monitors.json은 로드되지 않습니다. Hooks, MCP servers 및 LSP servers는 여러 소스를 처리하기 위한 다른 의미를 가집니다.

  • 모든 경로는 플러그인 루트에 상대적이어야 하며 ./로 시작해야 합니다.
  • 사용자 정의 경로의 컴포넌트는 동일한 명명 및 네임스페이싱 규칙을 사용합니다.
  • 여러 경로를 배열로 지정할 수 있습니다.
  • skills, commands, agents 또는 output styles의 기본 디렉토리를 유지하고 더 많은 경로를 추가하려면 배열에 기본값을 포함하세요: "skills": ["./skills/", "./extras/"]
  • skill 경로가 SKILL.md를 직접 포함하는 디렉토리를 가리킬 때 (예: 플러그인 루트를 가리키는 "skills": ["./"]), frontmatter의 name 필드가 skill의 호출 이름을 결정합니다. 이는 설치 디렉토리와 관계없이 안정적인 이름을 제공합니다. name이 frontmatter에 설정되지 않으면 디렉토리 basename이 폴백으로 사용됩니다.

경로 예시:

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

환경 변수

Claude Code는 플러그인 경로를 참조하기 위한 두 가지 변수를 제공합니다. 둘 다 skill 콘텐츠, agent 콘텐츠, hook 명령어, monitor 명령어 및 MCP 또는 LSP 서버 구성에 나타나는 모든 곳에서 인라인으로 대체됩니다. 둘 다 hook 프로세스 및 MCP 또는 LSP 서버 서브프로세스에 환경 변수로 내보내집니다.

${CLAUDE_PLUGIN_ROOT}: 플러그인 설치 디렉토리의 절대 경로입니다. 플러그인과 함께 번들로 제공되는 스크립트, 바이너리 및 구성 파일을 참조하는 데 사용하세요. 이 경로는 플러그인이 업데이트될 때 변경되므로 여기에 작성하는 파일은 업데이트 후 유지되지 않습니다.

${CLAUDE_PLUGIN_DATA}: 업데이트 후에도 유지되는 플러그인 상태를 위한 영구 디렉토리입니다. node_modules 또는 Python 가상 환경과 같은 설치된 종속성, 생성된 코드, 캐시 및 플러그인 버전 전체에서 유지되어야 하는 기타 파일에 사용하세요. 이 변수가 처음 참조될 때 디렉토리가 자동으로 생성됩니다.

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

영구 데이터 디렉토리

${CLAUDE_PLUGIN_DATA} 디렉토리는 ~/.claude/plugins/data/{id}/로 확인되며, 여기서 {id}는 a-z, A-Z, 0-9, _ 및 - 외부의 문자가 -로 대체된 플러그인 식별자입니다. formatter@my-marketplace로 설치된 플러그인의 경우 디렉토리는 ~/.claude/plugins/data/formatter-my-marketplace/입니다.

일반적인 사용은 언어 종속성을 한 번 설치하고 세션 및 플러그인 업데이트 전체에서 재사용하는 것입니다. 데이터 디렉토리가 단일 플러그인 버전보다 오래 지속되므로 디렉토리 존재 여부만 확인하면 업데이트가 플러그인의 종속성 매니페스트를 변경할 때를 감지할 수 없습니다. 권장 패턴은 번들된 매니페스트를 데이터 디렉토리의 복사본과 비교하고 다를 때 다시 설치합니다.

이 SessionStart hook은 첫 실행 시 node_modules를 설치하고 플러그인 업데이트가 변경된 package.json을 포함할 때마다 다시 설치합니다:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

diff는 저장된 복사본이 누락되거나 번들된 복사본과 다를 때 0이 아닌 값으로 종료되어 첫 실행과 종속성 변경 업데이트를 모두 다룹니다. npm install이 실패하면 후행 rm은 복사된 매니페스트를 제거하므로 다음 세션이 다시 시도합니다.

${CLAUDE_PLUGIN_ROOT}에 번들된 스크립트는 지속된 node_modules에 대해 실행할 수 있습니다:

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

데이터 디렉토리는 플러그인을 설치한 마지막 범위에서 제거할 때 자동으로 삭제됩니다. /plugin 인터페이스는 디렉토리 크기를 표시하고 삭제 전에 프롬프트합니다. CLI는 기본적으로 삭제합니다. --keep-data를 전달하여 유지하세요.

플러그인 캐싱 및 파일 해석

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

  • claude --plugin-dir을 통해, 세션 기간 동안.
  • 마켓플레이스를 통해, 향후 세션을 위해 설치됨.

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

각 설치된 버전은 캐시의 별도 디렉토리입니다. 플러그인을 업데이트하거나 제거하면 이전 버전 디렉토리는 고아로 표시되고 7일 후 자동으로 제거됩니다. 유예 기간을 통해 이미 이전 버전을 로드한 동시 Claude Code 세션이 오류 없이 계속 실행될 수 있습니다.

Claude의 Glob 및 Grep 도구는 검색 중에 고아 버전 디렉토리를 건너뛰므로 파일 결과에는 오래된 플러그인 코드가 포함되지 않습니다.

경로 순회 제한

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

외부 종속성 작업

플러그인이 디렉토리 외부의 파일에 액세스해야 하는 경우 플러그인 디렉토리 내에서 외부 파일에 대한 심볼릭 링크를 만들 수 있습니다. 심볼릭 링크는 캐시에 보존되며 런타임에 해당 대상으로 확인됩니다. 다음 명령어는 플러그인 디렉토리 내부에서 공유 유틸리티 위치로의 링크를 만듭니다:

ln -s /path/to/shared-utils ./shared-utils

이는 캐싱 시스템의 보안 이점을 유지하면서 유연성을 제공합니다.

플러그인 디렉토리 구조

표준 플러그인 레이아웃

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

enterprise-plugin/
├── .claude-plugin/           # 메타데이터 디렉토리 (선택사항)
│   └── plugin.json             # 플러그인 매니페스트
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # 평면 .md 파일로서의 Skills
│   ├── status.md
│   └── logs.md
├── agents/                   # Subagent 정의
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── output-styles/            # 출력 스타일 정의
│   └── terse.md
├── themes/                   # 색상 테마 정의
│   └── dracula.json
├── monitors/                 # 백그라운드 모니터 구성
│   └── monitors.json
├── hooks/                    # Hook 구성
│   ├── hooks.json           # 주 hook 구성
│   └── security-hooks.json  # 추가 hooks
├── bin/                      # PATH에 추가된 플러그인 실행 파일
│   └── my-tool               # Bash tool에서 bare 명령어로 호출 가능
├── settings.json            # 플러그인의 기본 설정
├── .mcp.json                # MCP 서버 정의
├── .lsp.json                # LSP 서버 구성
├── scripts/                 # Hook 및 유틸리티 스크립트
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # 라이선스 파일
└── CHANGELOG.md             # 버전 기록

파일 위치 참조

컴포넌트 기본 위치 목적
매니페스트 .claude-plugin/plugin.json 플러그인 메타데이터 및 구성 (선택사항)
Skills skills/ <name>/SKILL.md 구조의 Skills
Commands commands/ 평면 마크다운 파일로서의 Skills. 새 플러그인에는 skills/ 사용
Agents agents/ Subagent 마크다운 파일
Output styles output-styles/ 출력 스타일 정의
Themes themes/ 색상 테마 정의
Hooks hooks/hooks.json Hook 구성
MCP servers .mcp.json MCP 서버 정의
LSP servers .lsp.json 언어 서버 구성
Monitors monitors/monitors.json 백그라운드 모니터 구성
Executables bin/ Bash tool의 PATH에 추가된 실행 파일. 여기의 파일은 플러그인이 활성화된 동안 모든 Bash tool 호출에서 bare 명령어로 호출 가능
Settings settings.json 플러그인이 활성화될 때 적용되는 기본 구성. 현재 agent 및 subagentStatusLine 키만 지원됩니다

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에 쓰므로 프로젝트 저장소를 복제하는 모든 사람이 플러그인을 사용할 수 있습니다.

예시:

# 사용자 범위에 설치 (기본값)
claude plugin install formatter@my-marketplace

# 프로젝트 범위에 설치 (팀과 공유)
claude plugin install formatter@my-marketplace --scope project

# 로컬 범위에 설치 (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
--keep-data 플러그인의 영구 데이터 디렉토리 유지
--prune 다른 플러그인이 필요로 하지 않는 자동 설치된 종속성도 제거합니다. plugin prune 참조
-y, --yes --prune 확인 프롬프트 건너뛰기. stdin이 TTY가 아닐 때 필수
-h, --help 명령어 도움말 표시

별칭: remove, rm

기본적으로 마지막 남은 범위에서 제거하면 플러그인의 ${CLAUDE_PLUGIN_DATA} 디렉토리도 삭제됩니다. 새 버전 테스트 후 재설치할 때와 같이 유지하려면 --keep-data를 사용하세요.

plugin prune

더 이상 설치된 플러그인에서 필요로 하지 않는 자동 설치된 플러그인 종속성을 제거합니다. Claude Code가 다른 플러그인의 dependencies 필드를 만족하기 위해 가져온 종속성은 제거되며, 직접 설치한 플러그인은 절대 건드리지 않습니다.

claude plugin prune [options]

옵션:

옵션 설명 기본값
-s, --scope <scope> 범위에서 정리: user, project 또는 local user
--dry-run 제거될 항목을 나열하되 실제로 제거하지 않음
-y, --yes 확인 프롬프트 건너뛰기. stdin이 TTY가 아닐 때 필수
-h, --help 명령어 도움말 표시

별칭: autoremove

명령어는 고아 종속성을 나열하고 제거하기 전에 확인을 요청합니다. 플러그인을 제거하고 한 단계에서 종속성을 정리하려면 claude plugin uninstall <plugin> --prune을 실행하세요.

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 명령어 도움말 표시

plugin list

설치된 플러그인을 버전, 소스 마켓플레이스 및 활성화 상태와 함께 나열합니다.

claude plugin list [options]

옵션:

옵션 설명 기본값
--json JSON으로 출력
--available 마켓플레이스에서 사용 가능한 플러그인 포함. --json 필요
-h, --help 명령어 도움말 표시

plugin tag

현재 디렉토리의 플러그인에 대한 릴리스 git 태그를 생성합니다. 플러그인의 폴더 내에서 실행하세요. 플러그인 릴리스 태그 지정을 참조하세요.

claude plugin tag [options]

옵션:

옵션 설명 기본값
--push 태그를 생성한 후 원격으로 푸시
--dry-run 태그를 생성하지 않고 태그 지정될 내용 출력
-f, --force 작업 트리가 더티하거나 태그가 이미 존재해도 태그 생성
-h, --help 명령어 도움말 표시

디버깅 및 개발 도구

디버깅 명령어

claude --debug를 사용하여 플러그인 로딩 세부 정보를 확인하세요:

이는 다음을 표시합니다:

  • 로드되는 플러그인
  • 플러그인 매니페스트의 오류
  • Skill, agent 및 hook 등록
  • MCP 서버 초기화

일반적인 문제

문제 원인 해결책
플러그인이 로드되지 않음 잘못된 plugin.json claude plugin validate 또는 /plugin validate를 실행하여 plugin.json, skill/agent/command frontmatter 및 hooks/hooks.json의 구문 및 스키마 오류 확인
Skills가 나타나지 않음 잘못된 디렉토리 구조 skills/ 또는 commands/가 플러그인 루트에 있는지 확인, .claude-plugin/ 내부가 아님
Hooks가 실행되지 않음 스크립트가 실행 가능하지 않음 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.: 중복 컴포넌트 정의 제거 또는 marketplace 항목에서 strict: false 제거

Hook 문제 해결

Hook 스크립트가 실행되지 않음:

  1. 스크립트가 실행 가능한지 확인: chmod +x ./scripts/your-script.sh
  2. shebang 라인 확인: 첫 번째 줄은 #!/bin/bash 또는 #!/usr/bin/env bash여야 함
  3. 경로가 ${CLAUDE_PLUGIN_ROOT} 사용하는지 확인: "command": "${CLAUDE_PLUGIN_ROOT}/scripts/your-script.sh"
  4. 스크립트를 수동으로 테스트: ./scripts/your-script.sh

Hook이 예상 이벤트에서 트리거되지 않음:

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

MCP 서버 문제 해결

서버가 시작되지 않음:

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

서버 도구가 나타나지 않음:

  1. 서버가 .mcp.json 또는 plugin.json에 올바르게 구성되었는지 확인
  2. 서버가 MCP 프로토콜을 올바르게 구현하는지 확인
  3. 디버그 출력에서 연결 시간 초과 확인

디렉토리 구조 실수

증상: 플러그인이 로드되지만 컴포넌트 (skills, agents, hooks)가 누락됨.

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

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

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

디버그 체크리스트:

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

배포 및 버전 관리 참조

버전 관리

Claude Code는 플러그인의 버전을 캐시 키로 사용하여 업데이트를 사용할 수 있는지 여부를 결정합니다. /plugin update를 실행하거나 자동 업데이트가 실행되면 Claude Code는 현재 버전을 계산하고 이미 설치된 버전과 일치하면 업데이트를 건너뜁니다.

버전은 다음 중 설정된 첫 번째 항목에서 확인됩니다:

  1. 플러그인의 plugin.json에 있는 version 필드
  2. marketplace.json의 플러그인 마켓플레이스 항목에 있는 version 필드
  3. git 호스팅 마켓플레이스의 github, url, git-subdir 및 상대 경로 소스에 대한 플러그인 소스의 git 커밋 SHA
  4. git 저장소 내에 있지 않은 npm 소스 또는 로컬 디렉토리의 경우 unknown

이는 플러그인을 버전 관리하는 두 가지 방법을 제공합니다:

접근 방식 방법 업데이트 동작 최적 사용
명시적 버전 plugin.json에서 "version": "2.1.0"으로 설정 사용자는 이 필드를 범프할 때만 업데이트를 받습니다. 이를 범프하지 않고 새 커밋을 푸시하면 효과가 없으며 /plugin update는 "이미 최신 버전입니다"를 보고합니다. 안정적인 릴리스 주기가 있는 게시된 플러그인
커밋-SHA 버전 plugin.json 및 마켓플레이스 항목 모두에서 version 생략 사용자는 플러그인의 git 소스에 대한 모든 새 커밋에서 업데이트를 받습니다 활발히 개발 중인 내부 또는 팀 플러그인

명시적 버전을 사용하는 경우 의미 있는 버전 관리(MAJOR.MINOR.PATCH)를 따르세요: 주요 변경 사항의 경우 MAJOR를 범프하고, 새로운 기능의 경우 MINOR를 범프하고, 버그 수정의 경우 PATCH를 범프하세요. CHANGELOG.md에서 변경 사항을 문서화하세요.

참고 항목