SpyBara
Go Premium

plugins-reference.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 500 additions and 377 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Tue 22 23:59 Fri 25 23:58

플러그인 참조

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

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

플러그인 컴포넌트 참조

스킬

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

위치: 플러그인 루트의 skills/ 또는 commands/ 디렉토리, 또는 플러그인 루트의 단일 SKILL.md 파일

파일 형식: 스킬은 SKILL.md가 있는 디렉토리이고, 명령어는 간단한 마크다운 파일입니다.

스킬 구조:

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

스킬과 명령어는 플러그인이 설치될 때 자동으로 발견됩니다.

플러그인에 skills/ 디렉토리가 없고 skills 매니페스트 필드가 없으면, 플러그인 루트의 SKILL.md가 단일 스킬로 로드됩니다. 프론트매터 name 필드를 설정하여 스킬의 호출 이름을 제어합니다. 이 필드가 없으면 Claude Code는 설치 디렉토리 이름으로 폴백되며, 마켓플레이스에서 설치된 플러그인의 경우 매번 업데이트할 때마다 변경되는 버전 문자열입니다. 둘 이상의 스킬을 제공하는 플러그인의 경우 위에 표시된 skills/ 디렉토리 레이아웃을 사용합니다.

플러그인 스킬과 명령어에서 disable-model-invocation과 같은 부울 프론트매터 필드는 true 및 false 외에도 yes, no, on, off, 1, 0을 모든 문자 케이스로 허용합니다. v2.1.218 이전에는 Claude Code가 true와 false만 인식했습니다.

전체 세부 정보는 스킬을 참조하십시오.

에이전트

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

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

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

에이전트 구조:

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

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

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

Claude Code는 프론트매터에 name이 없거나 파싱되지 않는 경우에도 플러그인 에이전트를 로드합니다:

  • name 없음: Claude Code는 파일 이름으로 에이전트를 명명하므로, my-plugin이라는 플러그인의 agents/reviewer.md는 my-plugin:reviewer로 로드됩니다.
  • 파싱되지 않는 프론트매터: Claude Code는 파일 이름으로 에이전트를 명명하고, 설명으로 Agent from my-plugin plugin을 사용하며, 파일의 모든 필드를 무시합니다.

반대로 Claude Code는 프론트매터에 name이 없거나 파싱되지 않는 프로젝트, 사용자 또는 관리 에이전트 파일을 건너뜁니다.

프론트매터가 파싱되지 않는 플러그인의 기본 agents/ 디렉토리에서 파일을 찾으려면 claude plugin validate를 실행합니다. 전달하는 경로는 플러그인에 매니페스트가 있는지 여부에 따라 다르며, 두 예제 모두 ./my-plugin을 플러그인 디렉토리로 사용합니다:

  • 매니페스트가 있는 플러그인: claude plugin validate ./my-plugin
  • 매니페스트가 없는 플러그인: claude plugin validate ./my-plugin/agents. Claude Code v2.1.233 이상이 필요합니다.

에이전트는 플러그인이 활성화되면 my-plugin:code-reviewer와 같은 범위가 지정된 이름으로 @-mention 자동완성에 나타납니다.

전체 세부 정보는 서브에이전트를 참조하십시오.

훅

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

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

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

훅 구성:

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

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

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 tool call needs a permission decision
PermissionDenied When auto mode denies a tool call, including denials without a classifier verdict. Use JSON hookSpecificOutput.retry: true to tell the model it may retry the denied tool call. Claude Code ignores retry when the classifier produced no verdict
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
MessageDisplay While assistant message text is displayed
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
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
DirectoryAdded When a working directory is added mid-session via /add-dir or the SDK register_repo_root control request
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, isolation: "worktree", or for a background session. Replaces default git behavior
WorktreeRemove When a worktree is being removed at session exit, when a subagent finishes, or when you delete a background session
PreCompact Before context compaction
PostCompact After context compaction completes
PreModelSwitch Before Claude Code applies a model switch that you or a client requested. Can block the switch
PostModelSwitch After the session's model changes, including changes Claude Code makes on its own, such as restoring the model when you resume a session
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

훅 유형:

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

플러그인의 자체 번들 MCP 서버를 대상으로 하는 훅은 범위가 지정된 이름을 사용해야 합니다. 도구 매처와 if 필드는 범위가 지정된 도구 이름 mcp__plugin_<plugin-name>_<server-name>__<tool>을 사용하고, mcp_tool 훅의 server 필드는 plugin:<plugin-name>:<server-name>을 사용합니다. 베어 서버 키에 대해 작성된 매처는 절대 실행되지 않습니다. MCP 도구 일치 및 플러그인 제공 MCP 서버를 참조하십시오.

MCP 서버

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

위치: 플러그인 루트의 .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"]
    }
  }
}

통합 동작:

  • 플러그인 MCP 서버는 플러그인이 활성화될 때 자동으로 시작됩니다.
  • 서버는 Claude의 도구 키트에 표준 MCP 도구로 나타납니다.
  • 플러그인 서버는 사용자 MCP 서버와 독립적으로 구성할 수 있습니다.
  • 세션 중에 /reload-plugins를 실행하면, Claude Code는 구성이 변경되지 않은 서버의 라이브 연결을 유지합니다.

LSP 서버

플러그인은 Language Server Protocol (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. Claude Code는 socket을 허용하지만 모든 서버를 stdio를 통해 실행하므로 stdout 프로토콜 규칙이 모든 서버에 적용됩니다.
env 서버 시작 시 설정할 환경 변수
initializationOptions 초기화 중에 서버에 전달되는 옵션
settings workspace/didChangeConfiguration을 통해 전달되는 설정
workspaceFolder 서버의 작업 공간 폴더 경로
startupTimeout 서버 시작을 기다릴 최대 시간 (밀리초)
shutdownTimeout 정상 종료를 기다릴 최대 시간 (밀리초). 시간 초과가 경과하면 Claude Code는 서버 프로세스를 종료합니다. 설정하지 않으면 시간 초과가 적용되지 않습니다.
restartOnCrash 서버 충돌 후 다시 시작할지 여부. 기본값은 true입니다. 충돌한 서버를 다시 시작하지 않고 중지된 상태로 두려면 false로 설정합니다.
maxRestarts 포기하기 전 최대 재시작 시도 횟수
diagnostics 편집 후 진단을 Claude의 컨텍스트에 푸시할지 여부 (기본값 true). 코드 네비게이션은 유지하되 자동 진단 주입을 억제하려면 false로 설정합니다.

restartOnCrash 및 shutdownTimeout은 Claude Code v2.1.205 이상이 필요합니다. v2.1.205 이전에는 구성 스키마가 두 옵션을 모두 허용했지만 둘 중 하나를 설정하면 Claude Code가 시작 시 해당 LSP 서버를 완전히 건너뛰었으며, 이유는 claude --debug 출력에서만 볼 수 있었습니다.

동일한 확장자에 대한 여러 서버: 둘 이상의 활성화된 LSP 서버가 extensionToLanguage에서 동일한 파일 확장자를 선언할 때, 서버가 하나의 플러그인에서 오든 다른 플러그인에서 오든, 먼저 등록된 서버가 해당 확장자의 파일을 처리하고 다른 서버는 시작되지 않습니다. /plugin 인터페이스는 활성 서버인 플러그인의 이름을 지정하는 경고를 표시합니다.

초기화에 실패한 서버: Claude Code는 command 또는 extensionToLanguage가 누락된 것처럼 구성이 유효하지 않은 서버를 건너뛰고, 다른 구성된 서버는 여전히 시작됩니다. claude --debug를 실행하여 서버가 건너뛰어진 이유를 확인합니다.

건너뛴 서버는 파일 확장자를 요청하지 않으므로, 동일한 확장자를 선언하는 다른 유효한 서버(같은 플러그인 또는 다른 플러그인에서)가 여전히 해당 파일을 처리합니다.

로그 출력을 stderr로 보내기, stdout이 아님: Claude Code는 서버의 stdout을 프로토콜 메시지로만 읽고, 메시지 헤더는 최대 64 KiB, 메시지 본문은 최대 32 MiB를 허용합니다. Claude Code는 한계를 초과하거나 stdout에 비프로토콜 출력을 작성하는 서버를 연결 해제하고, 연결 해제를 restartOnCrash 및 maxRestarts에 대한 충돌로 계산합니다. --debug로 실행하면 Claude Code는 원인을 명명하는 오류를 디버그 로그에 작성합니다.

사용 가능한 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-analyzer-lsp rust-analyzer rust-analyzer 설치 참조

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

모니터

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

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

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

형식: 모니터 항목의 JSON 배열

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

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

모니터를 인라인으로 선언하려면 plugin.json에서 experimental.monitors를 동일한 배열로 설정합니다. 기본이 아닌 경로에서 로드하려면 experimental.monitors를 "./config/monitors.json"과 같은 상대 경로 문자열로 설정합니다. 모니터는 실험적 컴포넌트입니다.

필수 필드:

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

선택사항 필드:

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

command 값은 경로 대체 ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}, ${CLAUDE_PROJECT_DIR} 및 환경의 모든 ${ENV_VAR}을 지원합니다. 스크립트가 플러그인의 자체 디렉토리에서 실행되어야 하면 명령어 앞에 cd "${CLAUDE_PLUGIN_ROOT}" && 를 붙입니다.

모니터 command는 ${user_config.*} 값을 참조할 수 없습니다. 명령어는 셸을 통해 실행되므로 Claude Code는 값을 대체하는 대신 오류로 모니터를 거부합니다. 모니터 프로세스는 CLAUDE_PLUGIN_OPTION_<KEY> 환경 변수를 받지 않으므로, 모니터 스크립트가 자신이 소유한 구성 파일에서 값을 읽도록 합니다.

세션 중에 플러그인을 비활성화하면, Claude Code는 이미 실행 중인 모니터를 중지하지 않습니다. 세션이 끝날 때 중지됩니다.

테마

플러그인은 /theme에 기본 제공 사전 설정 및 사용자의 로컬 테마와 함께 나타나는 색상 테마를 제공할 수 있습니다. 테마는 themes/ 디렉토리의 JSON 파일로, base 사전 설정과 색상 토큰의 스파스 overrides 맵이 있습니다. 테마는 실험적 컴포넌트입니다.

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

사용자가 플러그인 테마를 선택하면, Claude Code는 custom:<plugin-name>:<slug>을 해당 구성에 저장합니다. 플러그인 테마는 읽기 전용입니다: 사용자가 /theme에서 하나를 Ctrl+E로 누르면, Claude Code는 이를 ~/.claude/themes/로 복사하여 사용자가 복사본을 편집할 수 있도록 합니다.

플러그인 설치 범위

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

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

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

스킬 디렉토리 플러그인

스킬 디렉토리 아래의 모든 폴더가 .claude-plugin/plugin.json 매니페스트를 포함하면 다음 세션에서 <name>@skills-dir이라는 이름의 플러그인으로 로드되며, 마켓플레이스나 설치 단계가 없습니다. plugin init으로 스캐폴드를 생성할 수 있습니다. 복사된 마켓플레이스 설치와 달리, 플러그인은 플러그인 캐시로 복사되지 않고 제자리에서 발견됩니다.

스킬 디렉토리 트리는 세 가지 서로 다른 것을 지원합니다:

보유한 것 설명
매니페스트가 없는 <skills-dir>/foo/SKILL.md foo라는 이름의 일반 스킬
<skills-dir>/foo/.claude-plugin/plugin.json 자체 스킬, 에이전트, 훅 등을 번들로 제공할 수 있는 플러그인 foo@skills-dir
<plugin>/skills/bar/SKILL.md 플러그인 내에 패키징된 스킬 bar

플러그인이 로드되는 위치 선택

스킬 디렉토리 범위 로드
~/.claude/skills/ 개인 위치가 사용자 것이므로 모든 프로젝트에서 로드
<cwd>/.claude/skills/ 프로젝트 해당 폴더에 대한 워크스페이스 신뢰 대화상자를 수락한 후에만 로드

프로젝트 범위 플러그인은 저장소에 체크인되며 이를 복제하는 모든 협력자에게 도달합니다. 해당 콘텐츠가 사용자가 아닌 저장소에서 오기 때문에, .claude/settings.json의 프로젝트 허용 규칙을 관리하는 것과 동일한 신뢰 게이트 이후에만 로드되므로, 상위 폴더를 신뢰하거나 -p로 실행하는 것만으로는 충분하지 않으며, 코드를 실행하는 구성 요소는 추가로 제한됩니다:

  • 선언하는 MCP 서버는 프로젝트 .mcp.json과 동일한 서버별 승인을 거칩니다
  • LSP 서버는 워크스페이스를 신뢰한 후에만 시작됩니다
  • 백그라운드 모니터는 로드되지 않습니다

개인 범위 플러그인에는 이러한 제한이 없습니다.

스킬 디렉토리 플러그인 편집, 다시 로드 및 비활성화

스킬의 SKILL.md에 대한 변경 사항은 현재 세션에서 즉시 적용됩니다. hooks/, .mcp.json, agents/, output-styles/ 등 플러그인의 다른 구성 요소에 대한 변경 사항은 적용되지 않습니다. /reload-plugins를 실행하거나 Claude Code를 다시 시작하여 이를 적용하십시오. 라이브 변경 감지를 참조하십시오.

스킬 디렉토리 플러그인 로드를 중지하려면 해당 폴더를 삭제하거나 이름으로 비활성화하십시오. 마켓플레이스에서 아무것도 설치되지 않았으므로 uninstall 단계가 없습니다.

claude plugin disable my-tool@skills-dir

claude.ai에서 동기화된 플러그인

Cowork 및 클라우드 세션에서 Claude Code는 claude.ai 계정에 대해 활성화된 플러그인을 세션의 자체 환경에 있는 ~/.claude/plugins/synced/로 다운로드하고 각 플러그인을 <name>@synced로 로드합니다. 마켓플레이스 및 설치 기록이 없습니다. Claude Code는 자신의 터미널에서 시작하는 세션에서는 이러한 플러그인을 로드하지 않습니다. 해당 Cowork 또는 클라우드 환경 내에서 claude plugin list는 다운로드된 복사본을 Synced from claude.ai 제목 아래에 표시합니다. v2.1.239 이전에는 Claude Code가 이러한 플러그인을 <name>@inline으로 로드했으며, 이는 --plugin-dir 플러그인이 사용하는 ID입니다.

claude plugin list가 출력하는 <name>@synced ID로 동기화된 플러그인을 관리합니다:

  • 하나 끄기: 동기화된 세션에서 claude plugin disable <name>@synced를 실행하거나 Claude에 실행하도록 요청합니다. Claude Code는 선택을 해당 환경의 사용자 수준 enabledPlugins에 "<name>@synced": false로 저장합니다. 플러그인을 다시 켜려면 같은 세션에서 claude plugin enable <name>@synced를 실행합니다. 모든 동기화된 세션에서 플러그인을 제외하려면 claude.ai 계정에서 플러그인을 끕니다. 모든 환경에서 하나의 프로젝트의 동기화된 세션에서 플러그인을 제외하려면 해당 프로젝트의 커밋된 .claude/settings.json의 enabledPlugins 아래에 "<name>@synced": false를 설정합니다.
  • claude.ai에서 플러그인 자체 관리: claude plugin install, update, uninstall은 동기화된 플러그인에 적용되지 않습니다. 플러그인을 제거하려면 claude.ai 계정에서 플러그인을 끕니다. 다음 동기화된 세션은 플러그인 없이 시작됩니다.

마켓플레이스 설치, skills-directory 플러그인 또는 --plugin-dir 플러그인과 같은 다른 소스의 활성화된 플러그인이 동기화된 플러그인의 이름과 일치하면 Claude Code는 해당 플러그인을 로드하고 동기화된 복사본을 로드되지 않은 것으로 보고합니다. claude.ai 복사본을 대신 사용하려면 자신의 복사본을 비활성화합니다. v2.1.239 이전에는 Claude Code가 같은 이름의 마켓플레이스 설치 대신 동기화된 복사본을 로드했습니다.

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

.claude-plugin/plugin.json 파일은 플러그인의 메타데이터와 구성을 정의합니다.

매니페스트는 선택 사항입니다. 생략하면 Claude Code는 기본 위치에서 구성 요소를 자동으로 검색하고 디렉터리 이름에서 플러그인 이름을 파생합니다. 메타데이터를 제공하거나 사용자 정의 구성 요소 경로가 필요한 경우 매니페스트를 사용합니다.

완전한 스키마 

{
  "name": "plugin-name",
  "displayName": "Plugin Name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "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"],
  "metadata": { "catalogId": "cat-123", "tier": "pro" },
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

필수 필드

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

필드 유형 설명 예시
name string 공백, 제어 문자 또는 양방향 형식 문자가 없는 케밥 케이스의 고유 식별자입니다. 마켓플레이스 항목이 플러그인을 다른 이름으로 나열할 때 마켓플레이스 항목 이름이 enabledPlugins 키와 /plugin에서 사용하는 이름입니다 "deployment-tools"

이 이름은 구성 요소 네임스페이싱에 사용됩니다. 예를 들어 UI에서 이름이 plugin-dev인 플러그인의 에이전트 agent-creator는 plugin-dev:agent-creator로 표시됩니다.

인식되지 않는 필드

Claude Code는 인식하지 못하는 최상위 필드를 무시합니다. 다른 에코시스템의 메타데이터를 plugin.json에 유지할 수 있으며 플러그인은 여전히 로드됩니다. 이를 통해 VS Code 또는 Cursor 확장 매니페스트, npm package.json 또는 MCPB/DXT 번들 매니페스트로도 작동하는 하나의 매니페스트를 유지하는 것이 실용적입니다.

claude plugin validate는 인식되지 않는 필드를 오류가 아닌 경고로 보고합니다. 필드가 인식된 필드와 한두 글자 차이나면 경고에서 의도된 이름을 제안합니다. 인식되지 않는 필드 경고만 있는 플러그인은 여전히 검증을 통과하고 런타임에 로드됩니다.

Claude Code가 값의 유형이 잘못된 인식된 필드를 처리하는 방식은 필드에 따라 다릅니다.

  • 대부분의 필드: 플러그인이 로드되지 않습니다. 예를 들어 keywords 값이 배열 대신 문자열인 경우 로드 오류이며 claude plugin validate는 이를 오류로 보고합니다.
  • experimental 및 metadata: Claude Code는 비객체 값을 무시하고 claude plugin validate는 경고를 보고합니다.

--strict를 전달하여 경고를 오류로 처리합니다. CI에서 이를 사용하여 게시하기 전에 필드 이름 오타나 다른 도구의 매니페스트에서 남은 필드를 포착합니다. 플러그인은 런타임에 로드되지만 말입니다.

claude plugin validate ./my-plugin --strict

메타데이터 필드

필드 유형 설명 예시
$schema string 편집기 자동 완성 및 검증을 위한 JSON Schema URL입니다. Claude Code는 로드 시간에 이 필드를 무시합니다. "https://json.schemastore.org/claude-code-plugin-manifest.json"
displayName string /plugin 선택기 및 기타 UI 표면에 표시되는 사람이 읽을 수 있는 이름입니다. 생략하면 name으로 폴백됩니다. name과 달리 공백과 모든 대소문자를 포함할 수 있습니다. 네임스페이싱이나 조회에 사용되지 않습니다. "Deployment Tools"
version string 선택 사항입니다. 의미 있는 버전입니다. 이를 설정하면 플러그인이 해당 버전 문자열로 고정되므로 사용자는 이를 범프할 때만 업데이트를 받습니다. command 소스 제외; 버전 관리를 참조합니다. 마켓플레이스 항목에도 설정된 경우 plugin.json이 우선합니다. 생략하면 버전은 버전 관리의 다음 소스에서 옵니다. "2.1.0"
description string 플러그인 목적에 대한 간단한 설명 "Deployment automation tools"
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"]
metadata object 자격 또는 카탈로그 필드와 같은 자신의 데이터를 위한 자유 형식 객체입니다. Claude Code는 이를 읽지 않으므로 값이 플러그인 동작에 영향을 주지 않습니다. Claude Code는 비객체 값을 무시하고 claude plugin validate는 이를 경고로 보고합니다. v2.1.222 이전에는 Claude Code가 키를 인식되지 않는 필드로 처리했습니다. {"catalogId": "cat-123"}
defaultEnabled boolean 사용자가 설정하지 않았을 때 플러그인이 활성화된 상태로 시작되는지 여부입니다. 기본값은 true입니다. 기본 활성화를 참조합니다. false

기본 활성화

plugin.json에서 defaultEnabled: false를 설정하여 비활성화된 상태로 설치되는 플러그인을 배포합니다. 사용자는 claude plugin enable <plugin> 또는 /plugin 인터페이스로 이를 켭니다. 외부 서비스에 연결하는 것과 같이 사용자가 옵트인해야 하는 비용이나 범위를 추가하는 플러그인에 이를 사용합니다.

defaultEnabled는 다른 것이 플러그인의 상태를 결정하지 않았을 때의 폴백입니다. 두 가지가 이를 우선합니다.

  • 사용자의 설정: 모든 설정 범위에서 플러그인의 enabledPlugins 항목입니다. 작성되면 플러그인 업데이트 및 재설치 전체에서 지속되므로 나중 릴리스에서 defaultEnabled를 변경해도 기존 사용자를 뒤집지 않습니다.
  • 종속성 요구 사항: 플러그인이 활성화된 다른 플러그인에 의해 필요할 때 Claude Code는 설치 또는 활성화 시간에 이에 대해 true를 작성합니다. 이는 명시적 설정을 제공하므로 자신의 기본값은 더 이상 적용되지 않습니다. 종속성이 있는 플러그인 활성화 또는 비활성화를 참조합니다.

동일한 필드가 플러그인의 마켓플레이스 항목에 나타날 수 있으며, 여기서 plugin.json의 값보다 우선합니다. 선택적 플러그인 필드를 참조합니다.

구성 요소 경로 필드

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

실험적 구성 요소

experimental 키 아래의 구성 요소인 themes 및 monitors는 안정화되는 동안 릴리스 간에 변경될 수 있는 매니페스트 스키마를 가집니다. 이를 선언하는 위치는 별도의 마이그레이션입니다. 최상위 수준은 여전히 작동하고 claude plugin validate는 경고하며 향후 릴리스는 experimental.*를 요구할 것입니다.

사용자 구성

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

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Your team's API endpoint"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "API authentication token",
      "sensitive": true
    }
  }
}

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

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

각 값은 MCP 및 LSP 서버 구성과 훅 명령에서 ${user_config.KEY}로 대체할 수 있습니다. 민감하지 않은 값은 스킬 및 에이전트 콘텐츠에서도 대체할 수 있습니다. 모든 값은 훅 프로세스로 CLAUDE_PLUGIN_OPTION_<KEY> 환경 변수로 내보내집니다. 여기서 <KEY>는 대문자로 된 옵션 키입니다.

셸에서 실행되는 필드는 ${user_config.*}를 거부합니다. 구성된 값을 셸 명령에 대체하면 셸이 해당 값이 포함하는 모든 것을 실행할 수 있으므로 구성 요소는 오류로 실패합니다. 각 거부된 필드에는 값을 전달하는 대체 방법이 있습니다.

거부된 필드 값을 전달하는 방법
셸 형식 훅 명령 exec 형식을 args와 함께 사용하거나 훅의 환경에서 CLAUDE_PLUGIN_OPTION_<KEY>를 읽습니다
Monitor 명령 스크립트의 구성 파일에서 값을 읽습니다
MCP headersHelper 스크립트의 구성 파일에서 값을 읽습니다

v2.1.207 이전에는 이러한 필드가 ${user_config.KEY} 값을 대체했습니다. 이에 의존하는 플러그인을 업데이트합니다.

민감하지 않은 값은 사용자 settings.json의 pluginConfigs 키 아래 pluginConfigs[<plugin-id>].options로 저장됩니다.

macOS에서 Claude Code는 민감한 값을 macOS Keychain에 저장하고 Keychain이 쓰기를 거부할 때 ~/.claude/.credentials.json으로 폴백합니다. 지원되는 키체인이 없는 플랫폼에서는 ~/.claude/.credentials.json에 저장합니다. 키체인 저장소는 OAuth 토큰과 공유되며 약 2 KB의 총 제한이 있으므로 민감한 값을 작게 유지합니다.

Claude Code는 세 가지 설정 소스에서만 모든 pluginConfigs 값을 읽습니다.

  • 사용자 설정: ~/.claude/settings.json, 활성화 시간 프롬프트가 작성하는 파일
  • --settings: CLI 플래그 또는 SDK 인라인 설정
  • 관리되는 설정: 조직 제어 정책

둘 이상의 소스가 동일한 키를 설정할 때 관리되는 설정이 우선하고 --settings가 우선하고 사용자 설정이 우선합니다. 이 목록에서 제거할 수 있는 유일한 소스는 사용자 설정입니다. user 없이 --setting-sources를 전달하면 Claude Code는 이를 건너뜁니다. 관리되는 설정과 --settings는 전달하는 모든 것을 유지합니다. SDK의 settingSources 옵션은 동일한 목록을 설정합니다.

프로젝트의 .claude/settings.json 또는 .claude/settings.local.json의 항목은 무시됩니다. 두 파일 모두 작업 공간에 있으므로 복제된 저장소가 거기에 값을 제공할 수 있으며 이러한 값은 플러그인 훅 명령, MCP 서버 구성, LSP 명령 및 모니터 명령으로 흐릅니다. v2.1.207 이전에는 이러한 항목이 읽혔습니다. 제한은 pluginConfigs에만 해당됩니다. enabledPlugins는 여전히 프로젝트 및 로컬 설정을 준수합니다.

채널

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

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Your Telegram user ID"
        }
      }
    }
  ]
}

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

경로 동작 규칙

사용자 정의 경로가 플러그인의 기본 디렉터리를 대체하는지 확장하는지는 필드에 따라 다릅니다.

  • 기본값 대체: commands, agents, workflows, outputStyles, experimental.themes, experimental.monitors. 예를 들어 매니페스트가 commands를 지정할 때 기본 commands/ 디렉터리는 스캔되지 않습니다. 기본값을 유지하고 더 추가하려면 명시적으로 나열합니다. "commands": ["./commands/", "./extras/"]
  • 기본값에 추가: skills. 기본 skills/ 디렉터리는 항상 스캔되고 skills에 나열된 디렉터리는 함께 로드됩니다. 예외: 소스가 마켓플레이스 루트로 확인되는 마켓플레이스 항목의 경우 특정 하위 디렉터리를 선언하면 기본 skills/ 스캔을 대체합니다
  • 자신의 병합 규칙: 훅, MCP 서버 및 LSP 서버. 여러 소스가 결합되는 방식에 대해 각 섹션을 참조합니다

플러그인에 기본 폴더와 일치하는 매니페스트 키가 모두 있을 때 Claude Code는 claude plugin list 및 /plugin 세부 정보 보기에서 무시된 폴더에 대해 경고합니다. 플러그인은 여전히 매니페스트 경로를 사용하여 로드됩니다. Claude Code는 매니페스트 키가 기본 폴더를 가리킬 때 경고하지 않습니다. 예를 들어 "commands": ["./commands/deploy.md"]는 폴더를 명시적으로 이름 지정하기 때문입니다.

모든 경로 필드의 경우:

  • 모든 경로는 플러그인 루트에 상대적이어야 하고 ./로 시작해야 합니다. 단, skills 필드는 "."도 허용합니다
    • "."과 "./"는 모두 플러그인 루트 자체를 나타냅니다
    • v2.1.221 이전에는 "."이 매니페스트 검증에 실패했고 플러그인이 로드되지 않았으므로 이전 버전을 지원하려면 "./"를 사용합니다
  • 사용자 정의 경로의 구성 요소는 동일한 명명 및 네임스페이싱 규칙을 사용합니다
  • 여러 경로를 배열로 지정할 수 있습니다
  • 스킬 경로는 SKILL.md를 직접 포함하는 디렉터리를 가리킬 수 있습니다. 예를 들어 플러그인 루트의 경우 "skills": ["."]
    • Claude Code는 SKILL.md의 프론트매터 name 필드에서 스킬의 호출 이름을 가져오므로 설치 디렉터리의 이름이 무엇이든 이름은 안정적으로 유지됩니다
    • 프론트매터에 name이 설정되지 않으면 Claude Code는 디렉터리 기본 이름으로 폴백합니다

루트에 SKILL.md가 있고 skills/ 하위 디렉터리가 없으며 skills 매니페스트 필드가 없는 플러그인은 자동으로 단일 스킬 플러그인으로 로드됩니다. 이 레이아웃에 대해 plugin.json에서 "skills": ["./"]를 설정할 필요가 없습니다.

경로 예시:

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

환경 변수

Claude Code는 경로를 참조하기 위한 세 가지 변수를 제공합니다.

변수 확인 대상 사용 목적
${CLAUDE_PLUGIN_ROOT} 플러그인의 설치 디렉터리의 절대 경로 플러그인과 함께 번들된 스크립트, 바이너리 및 구성 파일
${CLAUDE_PLUGIN_DATA} 플러그인 업데이트를 유지하고 첫 참조 시 생성되는 지속적 디렉터리 node_modules 또는 Python 가상 환경과 같은 설치된 종속성, 생성된 코드 및 캐시
${CLAUDE_PROJECT_DIR} 프로젝트 루트 프로젝트 로컬 스크립트 및 구성 파일

세 가지 모두 훅 프로세스 및 MCP 및 LSP 서버 하위 프로세스로 환경 변수로 내보내집니다. 어느 필드가 인라인으로 대체하는지는 플러그인 구성 요소에 따라 다릅니다.

플러그인 구성 요소 자리 표시자가 확인되는 필드
스킬 및 에이전트 콘텐츠 자리 표시자가 나타나는 모든 곳
훅 및 모니터 명령 자리 표시자가 나타나는 모든 곳
MCP stdio 서버 command, args, env
MCP http, sse, ws 서버 url, headers, headersHelper
LSP 서버 command, args, env, workspaceFolder

훅 명령에서 exec 형식을 args와 함께 사용하여 각 경로가 따옴표 없이 하나의 인수로 전달되도록 합니다. 셸 형식 훅 및 모니터 명령에서 변수를 큰따옴표로 래핑합니다. 예: "${CLAUDE_PROJECT_DIR}/scripts/server.sh". 이 셸 형식 훅은 플러그인과 함께 번들된 스크립트를 실행합니다.

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

${CLAUDE_PLUGIN_ROOT}는 플러그인이 업데이트될 때 변경됩니다. 이전 버전의 디렉터리는 업데이트 후 일정 기간 동안 디스크에 남아 있지만 이를 임시로 취급하고 거기에 상태를 작성하지 마십시오. 정리 의미론에 대해 플러그인 캐싱을 참조합니다.

플러그인이 세션 중간에 업데이트될 때 훅 명령, 모니터, MCP 서버 및 LSP 서버는 이전 버전의 경로를 계속 사용합니다. /reload-plugins를 실행하여 훅, MCP 서버 및 LSP 서버를 새 경로로 전환합니다. 모니터는 세션 재시작이 필요합니다. 대화형 터미널이 없는 세션에서 다시 로드는 플러그인 MCP 서버를 다음 세션까지 이전 경로에 남겨 둡니다.

command 소스가 있는 플러그인의 경우 Claude Code는 플러그인 자체를 다시 로드할 수 있습니다.

MCP 서버는 또한 roots/list 요청을 호출하여 런타임에 세션의 작업 디렉터리를 읽을 수 있습니다. roots/list가 반환하는 것과 Claude Code가 서버에 변경을 알리는 시기를 참조합니다.

지속적 데이터 디렉터리

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

일반적인 사용은 언어 종속성을 한 번 설치하고 세션 및 플러그인 업데이트 전체에서 재사용하는 것입니다. Python 종속성, Yarn 또는 pnpm으로 잠긴 종속성 및 수명 주기 스크립트를 실행해야 하는 패키지에 이를 사용합니다. 마켓플레이스 설치 플러그인의 경우 전혀 필요하지 않을 수 있습니다. Claude Code는 플러그인을 캐시할 때 적격 Node.js 패키지 종속성을 자동으로 설치합니다.

데이터 디렉터리는 단일 플러그인 버전보다 오래 지속되므로 디렉터리 존재 여부만으로는 업데이트가 플러그인의 종속성 매니페스트를 변경하는 시기를 감지할 수 없습니다. 권장 패턴은 번들된 매니페스트를 데이터 디렉터리의 복사본과 비교하고 다를 때 재설치합니다.

이 SessionStart 훅은 첫 실행 시 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 --plugin-url을 통해 세션 기간 동안 지정합니다.
  • 마켓플레이스를 통해 설치하여 향후 세션에서 사용합니다.

보안 및 검증 목적으로 Claude Code는 마켓플레이스 플러그인을 사용자의 로컬 플러그인 캐시(~/.claude/plugins/cache)에 복사합니다. 단, command 소스가 링크 모드인 경우는 제외하며, 이 경우 Claude Code는 캐시 항목의 링크를 통해 제자리에서 사용합니다.

복사된 플러그인의 경우, 설치된 각 버전은 캐시의 별도 디렉토리이며, 마켓플레이스 및 플러그인별로 그룹화되고 해석된 버전으로 명명되며, 플러그인의 파일과 Node.js 패키지 종속성의 자체 복사본을 포함합니다. 릴리스 태그에서 해석된 종속성은 커밋-SHA 접미사가 있는 디렉토리 이름을 가집니다.

플러그인을 업데이트하거나 제거할 때 Claude Code는 이전 버전 디렉토리를 고아 상태로 표시하고 대략 14일 후 백그라운드 스윕에서 제거합니다. 유예 기간을 통해 이미 이전 버전을 로드한 동시 Claude Code 세션이 오류 없이 계속 실행될 수 있습니다. Claude Code는 최소한 하나의 플러그인이 설치되어 있는 동안에만 스윕을 실행합니다. 마지막 플러그인을 제거한 후 고아 디렉토리는 플러그인을 다시 설치할 때까지 디스크에 남아 있습니다.

Claude Code는 더 이상 디렉토리나 심볼릭 링크를 포함하지 않을 때만 캐시에서 플러그인 또는 마켓플레이스 폴더를 제거합니다. 개발 체크아웃을 캐시에 플러그인의 버전 항목으로 심볼릭 링크하면 Claude Code는 링크를 고아 상태로 표시하지 않으며 링크나 링크를 포함하는 폴더를 제거하지 않습니다. Claude Code는 또한 링크된 체크아웃 내부에 버전 추적 파일을 작성하지 않습니다.

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

Node.js 패키지 종속성

Claude Code가 플러그인을 캐시에 복사할 때 플러그인의 Node.js 패키지 종속성도 여기에 설치하므로 플러그인의 hooks 및 MCP 서버가 이를 로드할 수 있습니다. 이 섹션은 플러그인이 자체 package.json에서 선언하는 npm 및 Bun 패키지를 다룹니다. 다른 플러그인에 종속된 플러그인의 경우 플러그인 종속성 버전을 참조하세요.

Claude Code는 복사된 버전 디렉토리 내에서 설치를 실행합니다. 플러그인을 설치할 때, Claude Code가 플러그인을 새 버전으로 업데이트할 때, 그리고 새 머신에서와 같이 활성화된 플러그인이 아직 캐시되지 않았을 때 세션 시작 시에 실행됩니다. 설치는 플러그인의 루트 디렉토리에 package.json과 지원되는 lockfile이 모두 포함되어 있을 때만 실행됩니다.

Lockfile 명령
bun.lock 또는 bun.lockb bun install --frozen-lockfile --ignore-scripts
npm-shrinkwrap.json 또는 package-lock.json npm ci --ignore-scripts

플러그인에 이러한 lockfile 중 하나 이상이 포함되어 있으면 Claude Code는 첫 번째 일치를 사용하며, 다음 순서로 확인합니다. bun.lock, bun.lockb, npm-shrinkwrap.json, package-lock.json. Claude Code는 yarn.lock 및 pnpm-lock.yaml을 건너뜁니다. Yarn 및 pnpm은 --ignore-scripts를 우회하는 해석 시간 구성 hooks를 지원하기 때문입니다.

가장 광범위한 도달을 위해 npm lockfile을 제공하세요. Claude Code는 사용자의 PATH에서 일치하는 lockfile의 패키지 관리자를 실행하며 lockfile이 누락된 경우 다른 lockfile로 폴백하지 않습니다. npm 소스를 통해 배포된 플러그인의 경우 npm-shrinkwrap.json을 사용하세요. npm은 게시된 패키지에서 package-lock.json을 제외합니다.

Claude Code는 이 종속성 설치를 제한하여 설치 중에 플러그인 또는 해당 패키지의 코드가 실행되지 않도록 하고 실행 시간을 제한합니다.

  • 고정된 해석: Bun 및 npm은 lockfile이 고정한 것을 정확히 설치하며, package.json과 lockfile이 불일치할 때 버전을 다시 해석하지 않고 실패합니다.
  • 라이프사이클 스크립트 없음: --ignore-scripts는 preinstall, install, 및 postinstall 스크립트가 실행되지 않도록 하므로 이러한 스크립트에서 네이티브 모듈을 빌드하는 종속성은 다운로드되지만 이 설치 중에는 컴파일되지 않습니다.
  • 60초 타임아웃: Claude Code는 더 오래 실행되는 설치를 중지하고 실패로 처리합니다.

npm 소스 플러그인 자체를 가져오면 이 종속성 설치가 실행되기 전에 라이프사이클 스크립트가 활성화된 상태에서 npm install을 실행합니다.

실패하거나 건너뛴 설치는 플러그인을 차단하지 않습니다. 설치가 실패하거나 Claude Code가 yarn 또는 pnpm lockfile을 건너뛸 때 이유를 디버그 출력의 경고로 기록합니다. package.json이 있고 lockfile이 없는 플러그인은 로그 항목 없이 건너뜁니다. 시간 초과된 설치는 캐시된 복사본에 부분 node_modules 트리를 남길 수 있습니다.

자동 설치를 끌 수 없습니다. 설정이나 환경 변수가 이를 비활성화하지 않습니다. 제한된 네트워크에서는 네트워크 액세스 요구 사항을 참조하여 허용할 호스트를 확인하세요.

자동 설치가 제공할 수 없는 종속성(예: 라이프사이클 스크립트를 빌드해야 하는 패키지, Python 종속성, 또는 Yarn 또는 pnpm으로 잠긴 플러그인)의 경우 영구 데이터 디렉토리의 hook에서 설치하세요.

경로 순회 제한

Claude Code는 플러그인이 자체 디렉토리 외부의 파일을 참조하도록 허용하지 않습니다. plugin.json에서 선언되거나 마켓플레이스 항목에서 선언된 플러그인 루트 외부로 해석되는 구성 요소 경로를 거부합니다. 이는 ../shared-utils와 같이 작성된 대로 플러그인 외부를 가리키는 경로와 마켓플레이스 내 링크를 제외한 플러그인 외부로 이어지는 심볼릭 링크를 포함합니다.

Claude Code가 경로를 거부하면 path escapes plugin directory 오류를 보고하고 해당 구성 요소 없이 플러그인을 로드합니다.

Claude Code는 플러그인을 설치할 때 플러그인 디렉토리 외부의 파일을 캐시에 복사하지 않으므로 복사된 플러그인 내부의 스크립트가 플러그인 루트 위의 경로를 읽을 때 해당 파일을 찾지 못합니다.

플러그인이 동일한 마켓플레이스의 다른 부분과 파일을 공유해야 하는 경우 플러그인 디렉토리 내에 심볼릭 링크를 만들 수 있습니다. 플러그인이 캐시에 복사될 때 심볼릭 링크가 처리되는 방식은 대상이 해석되는 위치에 따라 달라집니다.

  • 플러그인 자체 디렉토리 내: 심볼릭 링크는 캐시에서 상대 심볼릭 링크로 유지되므로 런타임에 복사된 대상으로 계속 해석됩니다.
  • 동일한 마켓플레이스 내 다른 곳: 심볼릭 링크는 역참조됩니다. 대상의 내용이 캐시에 복사됩니다. 이를 통해 메타 플러그인의 skills/ 디렉토리가 마켓플레이스의 다른 플러그인으로 정의된 skills에 링크할 수 있습니다.
  • 마켓플레이스 외부: 심볼릭 링크는 보안상 건너뜁니다. 이는 플러그인이 시스템 경로와 같은 임의의 호스트 파일을 캐시로 가져오는 것을 방지합니다.

--plugin-dir으로 설치된 플러그인, 로컬 경로에서 설치된 플러그인, 또는 복사 모드의 command 소스에서 설치된 플러그인의 경우 플러그인 자체 디렉토리 내에서 해석되는 심볼릭 링크만 유지됩니다. 다른 모든 것은 건너뜁니다.

다음 명령은 마켓플레이스 플러그인 내부에서 형제 플러그인으로 정의된 공유 skill로의 링크를 만듭니다. Windows에서는 관리자 권한 명령 프롬프트에서 mklink /D를 사용하거나 개발자 모드를 활성화하세요.

ln -s ../../shared-plugin/skills/foo ./skills/foo

플러그인 디렉토리 구조

표준 플러그인 레이아웃

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

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

플러그인 루트의 CLAUDE.md 파일은 프로젝트 컨텍스트로 로드되지 않습니다. 플러그인은 CLAUDE.md가 아닌 skills, agents, hooks를 통해 컨텍스트를 제공합니다. Claude의 컨텍스트에 로드되는 지침을 제공하려면 skill에 배치하십시오.

파일 위치 참조

구성 요소 기본 위치 목적
매니페스트 .claude-plugin/plugin.json 플러그인 메타데이터 및 구성 (선택사항)
Skills skills/ <name>/SKILL.md 구조의 Skills
Commands commands/ Markdown 파일로서의 Skills. 새 플러그인의 경우 skills/ 사용
Agents agents/ Subagent Markdown 파일
Workflows workflows/ Workflow 스크립트 파일
출력 스타일 output-styles/ 출력 스타일 정의
테마 themes/ 색상 테마 정의
Hooks hooks/hooks.json Hook 구성
MCP 서버 .mcp.json MCP 서버 정의
LSP 서버 .lsp.json 언어 서버 구성
모니터 monitors/monitors.json 백그라운드 모니터 구성
실행 파일 bin/ Bash 도구의 PATH에 추가되고 플러그인이 활성화된 동안 명령어로 호출 가능한 실행 파일. Claude.ai 조직 설정을 통해 배포하는 플러그인에는 이 디렉토리를 포함할 수 없습니다
설정 settings.json 플러그인이 활성화될 때 적용되는 기본 구성. agent 및 subagentStatusLine 키만 지원됩니다

CLI 명령어 참조

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

plugin init

~/.claude/skills/<name>/에 새 플러그인을 스캐폴드합니다. 다음 Claude Code 세션에서 <name>@skills-dir로 자동으로 로드되며 /plugin 및 claude plugin list에 설치 단계 없이 나타납니다.

범위 및 신뢰 요구사항은 Skills-directory plugins를 참조하십시오.

claude plugin init <name> [options]

인수:

  • <name>: 플러그인 이름입니다. 스킬 네임스페이스 및 ~/.claude/skills/ 아래의 디렉터리 이름이 되므로 공백이나 경로 구분자를 포함할 수 없습니다.

옵션:

옵션 설명 기본값
--description <text> 매니페스트 설명
--author <name> 작성자 이름 git config user.name
--author-email <email> 작성자 이메일 git config user.email
--with <components...> 컴포넌트 폴더도 스캐폴드합니다. 유효한 값: skills, agents, hooks, mcp, lsp, output-style, channel
-f, --force 대상의 기존 .claude-plugin/을 덮어씁니다
-h, --help 명령어에 대한 도움말을 표시합니다

별칭: new

각 --with 값은 해당 컴포넌트에 대한 스타터 파일을 추가하며, 편집할 준비가 되어 있습니다:

컴포넌트 스캐폴드되는 항목
skills 기본 스킬과 함께 추가 네임스페이스 <name>:example 스킬
agents agents/ 서브에이전트 정의
hooks 샘플 이벤트 핸들러가 포함된 hooks/hooks.json
mcp HTTP 및 stdio 서버 예제가 포함된 .mcp.json
lsp .lsp.json 언어 서버 예제
output-style 플러그인이 활성화된 동안 자동으로 적용되는 output-styles/<name>.md
channel MCP 기반 channel: stdio 서버(server.ts), 해당 .mcp.json, 및 package.json

스캐폴드된 플러그인은 마켓플레이스가 아닌 @skills-dir 소스를 사용합니다. 관리자는 strictKnownMarketplaces를 사용하거나 관리 설정의 blockedMarketplaces에 {"source": "skills-dir"}을 추가하여 이 소스를 차단할 수 있습니다. 차단되면 plugin init은 작성하기 전에 실패합니다.

예제:

# 최소 플러그인 스캐폴드
claude plugin init my-helper

# 스킬 및 훅 폴더를 포함하여 스캐폴드
claude plugin init my-helper --with skills hooks

# 기존 스캐폴드 덮어쓰기
claude plugin init my-helper --force

plugin install

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

claude plugin install <plugin> [options]

인수:

  • <plugin>: 플러그인 이름 또는 특정 마켓플레이스의 경우 plugin-name@marketplace-name

옵션:

옵션 설명 기본값
-s, --scope <scope> 설치 범위: user, project, 또는 local user
--config <key=value> 플러그인의 매니페스트에 선언된 userConfig 옵션을 설정합니다. 여러 옵션을 설정하려면 플래그를 반복합니다
-y, --yes 확인 프롬프트 없이 플러그인의 마켓플레이스가 선언한 명령어를 수락합니다: command source를 사용하는 플러그인을 생성하는 명령어 또는 아카이브 다운로드를 인증하는 headersHelper. headersHelper를 수락하려면 Claude Code v2.1.238 이상이 필요합니다. Claude Code는 여전히 명령어를 먼저 인쇄합니다. stdin 또는 stdout이 TTY가 아닐 때 필수입니다. Claude Code 세션 내에서는 효과가 없으므로 자신의 터미널에서 명령어를 실행하십시오
-h, --help 명령어에 대한 도움말을 표시합니다

범위는 설치된 플러그인이 추가되는 설정 파일을 결정합니다. 예를 들어 --scope project는 .claude/settings.json의 enabledPlugins에 작성하여 프로젝트 저장소를 복제하는 모든 사람이 플러그인을 사용할 수 있도록 합니다.

예제:

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

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

# 로컬 범위에 설치(팀과 공유하지 않음)
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 플러그인의 persistent data directory를 보존합니다
--prune 다른 플러그인이 필요하지 않은 자동 설치된 종속성도 제거합니다. plugin prune 참조
-y, --yes --prune 확인 프롬프트를 건너뜁니다. stdin 또는 stdout이 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 또는 stdout이 TTY가 아닐 때 필수입니다
-h, --help 명령어에 대한 도움말을 표시합니다

별칭: autoremove

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

plugin enable

비활성화된 플러그인을 활성화합니다. 대상이 마켓플레이스에서 설치되고 dependencies를 선언할 때, Claude Code는 동일한 범위에서 이들을 전이적으로 활성화합니다. 명령어는 Enable or disable a plugin with dependencies가 나열하는 조건에서 실패합니다.

claude plugin enable <plugin> [options]

인수:

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

옵션:

옵션 설명 기본값
-s, --scope <scope> 활성화할 범위: user, project, 또는 local. 생략하면 Claude Code는 플러그인이 설치된 범위를 감지합니다 자동 감지
-h, --help 명령어에 대한 도움말을 표시합니다

plugin disable

플러그인을 제거하지 않고 비활성화합니다. 대상이 마켓플레이스에서 설치될 때, 다른 활성화된 플러그인이 depends on 하면 명령어가 실패합니다. 오류 메시지에는 먼저 모든 종속성을 비활성화하는 연결된 명령어가 포함됩니다.

claude plugin disable [plugin] [options]

인수:

  • [plugin]: 플러그인 이름 또는 plugin-name@marketplace-name. --all을 사용할 때 선택 사항입니다.

옵션:

옵션 설명 기본값
-a, --all 모든 활성화된 플러그인을 비활성화합니다. --scope와 결합할 수 없습니다
-s, --scope <scope> 비활성화할 범위: user, project, 또는 local. 생략하면 Claude Code는 플러그인이 설치된 범위를 감지합니다 자동 감지
-h, --help 명령어에 대한 도움말을 표시합니다

plugin update

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

claude plugin update <plugin> [options]

인수:

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

옵션:

옵션 설명 기본값
-s, --scope <scope> 업데이트할 범위: user, project, local, 또는 managed user
-y, --yes 확인 프롬프트 없이 플러그인의 마켓플레이스가 선언한 명령어를 수락합니다: command source를 사용하는 플러그인을 생성하는 명령어 또는 아카이브 다운로드를 인증하는 headersHelper. headersHelper를 수락하려면 Claude Code v2.1.238 이상이 필요합니다. Claude Code는 여전히 명령어를 먼저 인쇄합니다. stdin 또는 stdout이 TTY가 아닐 때 필수입니다. Claude Code 세션 내에서는 효과가 없으므로 자신의 터미널에서 명령어를 실행하십시오
-h, --help 명령어에 대한 도움말을 표시합니다

plugin list

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

claude plugin list [options]

옵션:

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

대화형 세션 내에서 /plugin list는 유사한 목록을 인라인으로 인쇄하지만, 마켓플레이스 설치 플러그인만 포함합니다:

  • 스킬 디렉터리에서 로드된 플러그인은 /plugin 인터페이스 및 claude plugin list에 나타나지만 인라인 /plugin list 출력에는 나타나지 않습니다.
  • Claude Code v2.1.239 이상에서 claude.ai에서 동기화된 플러그인은 동기화된 세션이 다운로드한 환경에서 claude plugin list를 실행할 때 나타납니다. 인라인 /plugin list 출력에는 나타나지 않습니다.
  • --plugin-dir 또는 --plugin-url로 세션에 로드된 플러그인은 /plugin 인터페이스에 나타나며, claude --plugin-dir <dir> plugin list와 같이 동일한 플래그가 서브명령어 앞에 올 때만 claude plugin list에 나타납니다. 플래그 이름만 위치를 지정하므로 베어 claude plugin list는 동기화된 플러그인 및 스킬 디렉터리 플러그인과 달리 고정 디렉터리를 스캔하는 Claude Code를 찾을 수 없습니다.

대화형 형식은 --enabled 또는 --disabled를 수락하여 해당 상태의 플러그인만 표시하고, ls를 list의 약자로 수락합니다.

plugin details

플러그인의 컴포넌트 인벤토리 및 예상 토큰 비용을 표시합니다. 출력은 플러그인이 기여하는 모든 컴포넌트를 Skills, Agents, Hooks, MCP servers, 및 LSP servers로 그룹화하여 나열하며, 각 세션에 추가하는 토큰 수의 추정치를 포함합니다. Skills 그룹에는 skills/ 및 commands/ 항목이 모두 포함됩니다.

claude plugin details <name>

인수:

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

옵션:

옵션 설명 기본값
-h, --help 명령어에 대한 도움말을 표시합니다

출력은 각 컴포넌트에 대해 두 개의 비용 수치를 표시합니다:

  • Always-on: 스킬 설명, 에이전트 설명, 명령어 이름과 같은 플러그인의 목록 텍스트에 의해 모든 세션에 추가되는 토큰입니다. 어떤 컴포넌트도 실행되지 않는지 여부와 관계없이 추가됩니다.
  • On-invoke: 컴포넌트가 실행될 때 비용이 드는 토큰입니다. 일반적인 세션이 컴포넌트의 부분 집합만 호출하기 때문에 플러그인 전체가 아닌 컴포넌트당 표시됩니다.

이 예제는 두 개의 스킬이 있는 플러그인의 출력 모양을 보여줍니다:

dependency-guard 1.2.0
  Dependency analysis for Claude Code sessions
  Source: dependency-guard@example-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  SessionStart  (harness-only — no model context cost)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~180 tok   added to every session

Per-component (rounded)
  component            always-on  on-invoke
  scan-dependencies        ~100      ~2400
  review-changes            ~80      ~1800

  On-invoke cost is paid each time a skill or agent fires.
  Token counts are estimates and may differ from actual usage.

always-on 합계는 활성 모델에 대한 count_tokens API를 통해 계산됩니다. 컴포넌트별 숫자는 해당 합계에서 비례적으로 확장됩니다. API에 도달할 수 없으면 명령어는 문자 기반 추정으로 폴백합니다.

plugin validate

플러그인 또는 마켓플레이스를 게시하기 전에 구문 및 스키마 오류를 확인합니다.

명령어는 유효성 검사가 통과하면 0으로, 실패하면 1로, 경로를 읽을 수 없는 경우와 같이 유효성 검사 실행 자체가 실패하면 2로 종료됩니다.

claude plugin validate <path> [options]

인수:

옵션:

옵션 설명 기본값
--strict 경고를 오류로 취급하고 경고에서 1로 종료합니다. CI에서 사용하여 unrecognized fields와 같이 런타임이 허용하는 문제를 포착합니다
--json 유효성 검사 보고서를 동일한 종료 코드를 가진 하나의 JSON 객체로 출력합니다. Claude Code v2.1.259 이상 필요
-h, --help 명령어에 대한 도움말을 표시합니다

--json을 사용하면 Claude Code는 보고서를 stdout에 다음 최상위 필드를 가진 하나의 JSON 객체로 작성합니다:

  • success: 종료 코드가 제공하는 동일한 판정
  • strict: 실행이 경고를 오류로 취급했는지 여부
  • target: Claude Code가 유효성을 검사한 확인된 경로
  • manifest: 매니페스트 자체의 결과 또는 run without a manifest의 경우 null
  • contents: 파일별 결과, 각각 file을 명명하고 errors, warnings, 및 notes 배열을 포함합니다

종료 2에서 명령어는 stdout에 아무것도 작성하지 않습니다. 오류 메시지는 stderr로 이동합니다.

대화형 세션 내에서 /plugin validate <path>는 동일한 검사를 인라인으로 실행합니다.

plugin tag

플러그인에 대한 릴리스 git 태그를 생성합니다. 기본적으로 명령어는 현재 디렉터리의 플러그인에 태그를 지정합니다. 다른 곳의 플러그인에 태그를 지정하려면 경로를 전달합니다. Tag plugin releases를 참조하십시오.

claude plugin tag [path] [options]

인수:

  • [path]: 플러그인 디렉터리의 경로입니다. 기본값은 현재 디렉터리입니다.

옵션:

옵션 설명 기본값
--push 태그를 생성한 후 원격으로 푸시합니다
--dry-run 태그를 생성하지 않고 태그될 항목을 인쇄합니다
-f, --force 작업 트리가 더티하거나 태그가 이미 존재하더라도 태그를 생성합니다
-m, --message <msg> 태그 주석 메시지입니다. 버전의 자리 표시자로 %s를 사용합니다
--remote <name> --push로 푸시할 원격입니다 origin
-h, --help 명령어에 대한 도움말을 표시합니다

디버깅 및 개발 도구

디버깅 명령어

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

다음을 표시합니다:

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

일반적인 문제

문제 원인 해결 방법
플러그인이 로드되지 않음 잘못된 plugin.json claude plugin validate ./my-plugin 또는 /plugin validate ./my-plugin을 실행합니다. 여기서 ./my-plugin은 플러그인 디렉토리이며, plugin.json, hooks/hooks.json, 플러그인의 기본 디렉토리에 있는 skills, agents, commands의 frontmatter에서 구문 및 스키마 오류를 확인합니다. 실행 범위에 대해서는 플러그인 또는 매니페스트 없는 디렉토리 검증을 참조하십시오
Skills가 나타나지 않음 잘못된 디렉토리 구조 skills/ 또는 commands/가 플러그인 루트에 있는지 확인하고, .claude-plugin/ 내부에 있지 않은지 확인합니다
Hooks가 실행되지 않음 스크립트가 실행 가능하지 않음 chmod +x script.sh를 실행합니다
MCP 서버 실패 ${CLAUDE_PLUGIN_ROOT} 누락 모든 플러그인 경로에 변수를 사용합니다
경로 오류 절대 경로 사용됨 경로를 상대 경로로 변경하고 ./로 시작합니다. 경로 동작 규칙을 참조하십시오. 이는 skills 필드의 "." 예외를 다룹니다
LSP Executable not found in $PATH 언어 서버가 설치되지 않음 바이너리를 설치합니다 (예: npm install -g typescript-language-server typescript)

예제 오류 메시지

매니페스트 검증 오류:

  • Invalid JSON syntax: Unexpected token } in JSON at position 142: 누락된 쉼표, 추가 쉼표 또는 따옴표 없는 문자열이 있는지 확인합니다
  • Plugin <name> has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Invalid input: expected string, received undefined: 필수 필드가 누락되었습니다
  • Plugin <name> has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: JSON 구문 오류입니다. v2.1.246 이전에는 Claude Code가 UTF-8로 저장되고 선행 바이트 순서 표시(BOM)가 있는 plugin.json에 대해서도 이 오류를 생성했습니다. 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 패턴이 도구와 일치하는지 확인합니다: 파일 작업의 경우 "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/에 속합니다.

디버그 체크리스트:

  1. claude --debug를 실행하고 "loading plugin" 메시지를 찾습니다
  2. 각 구성 요소 디렉토리가 디버그 출력에 나열되어 있는지 확인합니다
  3. 파일 권한이 플러그인 파일 읽기를 허용하는지 확인합니다

배포 및 버전 관리 참고자료

버전 관리

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

command 외의 모든 소스 유형에 대해 Claude Code는 다음 중 설정된 첫 번째 항목에서 버전을 확인합니다:

  1. 플러그인의 plugin.json에 있는 version 필드
  2. marketplace.json의 플러그인 마켓플레이스 항목에 있는 version 필드
  3. git 호스팅 마켓플레이스의 github, url, git-subdir, 상대 경로 소스에 대한 플러그인 소스의 git 커밋 SHA
  4. archive 소스의 경우 SHA-256 다이제스트: 마켓플레이스 항목의 sha256 핀 또는 핀을 설정하지 않았을 때 다운로드된 파일의 다이제스트입니다. Claude Code는 이를 처음 12자로 단축합니다.
  5. npm 소스 또는 git 저장소 내에 있지 않은 로컬 디렉터리의 경우 unknown

command 소스의 경우 Claude Code는 항상 명령이 생성한 내용에서 버전을 파생합니다: 자체적으로 12자 콘텐츠 해시이거나, 하나가 설정되어 있을 때 <version>-<hash> 형식으로 plugin.json 버전에 추가됩니다. Claude Code는 command 소스에 대해 마켓플레이스 항목의 version 필드를 무시합니다. 해시된 출력이 변경되는 명령은 작성된 버전 문자열이 동일하게 유지되더라도 새 버전을 생성합니다. 링크 모드에서 해시는 인쇄된 디렉터리의 실제 경로와 파일 콘텐츠가 아닌 최상위 항목을 포함합니다.

이러한 소스 유형의 경우 플러그인을 버전 관리하는 세 가지 방법이 있습니다:

접근 방식 방법 업데이트 동작 최적 사용
명시적 버전 plugin.json에서 "version": "2.1.0"을 설정합니다. 사용자는 이 필드를 업데이트할 때만 업데이트를 받습니다. 이를 업데이트하지 않고 새 커밋을 푸시하면 효과가 없으며, /plugin update는 "이미 최신 버전입니다"를 보고합니다. 안정적인 릴리스 주기를 가진 게시된 플러그인
커밋-SHA 버전 plugin.json과 마켓플레이스 항목 모두에서 version을 생략합니다. 사용자는 소스의 확인된 커밋이 변경될 때마다 업데이트를 받습니다. 활발한 개발 중인 내부 또는 팀 플러그인
다이제스트 버전 archive 소스를 사용하고 plugin.json과 마켓플레이스 항목 모두에서 version을 생략합니다. sha256 핀을 사용하면 사용자는 핀을 변경할 때 업데이트를 받습니다. 핀이 없으면 사용자는 호스팅된 zip 파일의 바이트가 변경될 때마다 업데이트를 받습니다. 정적 서버 또는 아티팩트 저장소에 zip 파일로 게시된 플러그인

명시적 버전을 사용하는 경우 의미 있는 버전 관리(MAJOR.MINOR.PATCH)를 따릅니다: 주요 변경 사항의 경우 MAJOR를 업데이트하고, 새 기능의 경우 MINOR를 업데이트하고, 버그 수정의 경우 PATCH를 업데이트합니다. CHANGELOG.md에서 변경 사항을 문서화합니다.

참고 항목