File Deleted
View Diff
1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# 플러그인 참조
6
7> 스키마, CLI 명령어, 컴포넌트 사양을 포함한 Claude Code 플러그인 시스템의 완전한 기술 참조입니다.
8
9<Tip>
10 플러그인을 설치하려고 하시나요? [플러그인 발견 및 설치](/docs/ko/discover-plugins)를 참조하십시오. 플러그인 생성에 대해서는 [플러그인](/docs/ko/plugins)을 참조하십시오. 플러그인 배포에 대해서는 [플러그인 마켓플레이스](/docs/ko/plugin-marketplaces)를 참조하십시오.
11</Tip>
12
13**플러그인**은 Claude Code를 사용자 정의 기능으로 확장하는 자체 포함된 컴포넌트 디렉토리입니다. 플러그인 컴포넌트에는 skills, agents, hooks, MCP servers, LSP servers, 및 monitors가 포함됩니다.
14
15<h2 id="plugin-components-reference">
16 플러그인 컴포넌트 참조
17</h2>
18
19<h3 id="skills">
20 스킬
21</h3>
22
23플러그인은 Claude Code에 스킬을 추가하여 사용자나 Claude가 호출할 수 있는 `/name` 바로가기를 생성합니다.
24
25**위치**: 플러그인 루트의 `skills/` 또는 `commands/` 디렉토리, 또는 플러그인 루트의 단일 `SKILL.md` 파일
26
27**파일 형식**: 스킬은 `SKILL.md`가 있는 디렉토리이고, 명령어는 간단한 마크다운 파일입니다.
28
29**스킬 구조**:
30
31```text theme={null}
32skills/
33├── pdf-processor/
34│ ├── SKILL.md
35│ ├── reference.md (선택사항)
36│ └── scripts/ (선택사항)
37└── code-reviewer/
38 └── SKILL.md
39```
40
41스킬과 명령어는 플러그인이 설치될 때 자동으로 발견됩니다.
42
43플러그인에 `skills/` 디렉토리가 없고 `skills` 매니페스트 필드가 없으면, 플러그인 루트의 `SKILL.md`가 단일 스킬로 로드됩니다. 프론트매터 `name` 필드를 설정하여 스킬의 호출 이름을 제어합니다. 이 필드가 없으면 Claude Code는 설치 디렉토리 이름으로 폴백됩니다. [캐시에 복사된](#plugin-caching-and-file-resolution) 플러그인의 경우 해당 이름은 매번 업데이트할 때마다 변경되는 버전 문자열입니다. 둘 이상의 스킬을 제공하는 플러그인의 경우 위에 표시된 `skills/` 디렉토리 레이아웃을 사용합니다.
44
45플러그인 스킬과 명령어에서 `disable-model-invocation`과 같은 부울 프론트매터 필드는 `true` 및 `false` 외에도 `yes`, `no`, `on`, `off`, `1`, `0`을 모든 문자 케이스로 허용합니다. v2.1.218 이전에는 Claude Code가 `true`와 `false`만 인식했습니다.
46
47전체 세부 정보는 [스킬](/docs/ko/skills)을 참조하십시오.
48
49<h3 id="agents">
50 에이전트
51</h3>
52
53플러그인은 Claude가 적절할 때 자동으로 호출할 수 있는 특정 작업을 위한 특화된 서브에이전트를 제공할 수 있습니다.
54
55**위치**: 플러그인 루트의 `agents/` 디렉토리
56
57**파일 형식**: 에이전트 기능을 설명하는 마크다운 파일
58
59**에이전트 구조**:
60
61```markdown theme={null}
62name: agent-name
63description: 이 에이전트가 전문으로 하는 분야와 Claude가 언제 호출해야 하는지
64model: sonnet
65effort: medium
66maxTurns: 20
67disallowedTools: Write, Edit
68
69에이전트의 역할, 전문성, 동작을 설명하는 상세한 시스템 프롬프트입니다.
70```
71
72<h4 id="plugin-agent-frontmatter">
73 플러그인 에이전트 프론트매터
74</h4>
75
76플러그인 에이전트 파일은 [서브에이전트 파일과 동일한 프론트매터 필드](/docs/ko/sub-agents#supported-frontmatter-fields)를 사용하지만, Claude Code는 플러그인에서 제공되는 에이전트의 경우 일부만 인정합니다:
77
78* **지원됨**: `name`, `description`, `model`, `effort`, `maxTurns`, `tools`, `disallowedTools`, `skills`, `memory`, `background`, `omitClaudeMd`, `isolation`, `color`, 및 `experimental`. 유일한 유효한 `isolation` 값은 `"worktree"`입니다.
79* **보안상의 이유로 지원되지 않음**: `hooks`, `mcpServers`, 및 `permissionMode`. Claude Code는 플러그인에서 에이전트를 로드할 때 이들을 무시합니다. 이들을 사용하려면 에이전트 파일을 `.claude/agents/` 또는 `~/.claude/agents/`로 복사합니다.
80* **지원되지 않음**: `initialPrompt`.
81
82플러그인 에이전트 파일을 `agents/`의 하위 폴더에 배치할 수 있습니다. Claude Code는 [이들을 재귀적으로 로드](/docs/ko/sub-agents#choose-the-subagent-scope)하고 플러그인 이름, 각 하위 폴더 이름, 파일 이름을 콜론으로 결합하여 에이전트의 범위가 지정된 이름을 형성합니다. 예를 들어, `my-plugin`이라는 플러그인의 `agents/review/security.md`는 `my-plugin:review:security`로 로드됩니다. 두 가지 설정이 해당 이름을 변경합니다:
83
84* 프론트매터 `name`: 파일 이름만 바꾸므로, `agents/review/security.md`의 `name: audit`은 `my-plugin:review:audit`으로 로드됩니다.
85* 매니페스트 [`agents`](#component-path-fields) 필드: 여기에 나열한 파일은 하위 폴더 이름 없이 로드되므로, `"agents": "./custom/review/security.md"`는 `my-plugin:security`로 로드됩니다.
86
87Claude Code는 프론트매터에 `name`이 없거나 파싱되지 않는 경우에도 플러그인 에이전트를 로드합니다:
88
89* `name` 없음: Claude Code는 파일 이름으로 에이전트를 명명하므로, `my-plugin`이라는 플러그인의 `agents/reviewer.md`는 `my-plugin:reviewer`로 로드됩니다.
90* 파싱되지 않는 프론트매터: Claude Code는 파일 이름으로 에이전트를 명명하고, 설명으로 `Agent from my-plugin plugin`을 사용하며, 파일의 모든 필드를 무시합니다.
91
92반대로 Claude Code는 프론트매터에 `name`이 없거나 파싱되지 않는 프로젝트, 사용자 또는 관리 에이전트 파일을 건너뜁니다.
93
94프론트매터가 파싱되지 않는 플러그인의 기본 `agents/` 디렉토리에서 파일을 찾으려면 `claude plugin validate`를 실행합니다. 전달하는 경로는 플러그인에 매니페스트가 있는지 여부에 따라 다르며, 두 예제 모두 `./my-plugin`을 플러그인 디렉토리로 사용합니다:
95
96* 매니페스트가 있는 플러그인: `claude plugin validate ./my-plugin`
97* 매니페스트가 없는 플러그인: `claude plugin validate ./my-plugin/agents`. Claude Code v2.1.233 이상이 필요합니다.
98
99에이전트는 플러그인이 활성화되면 `my-plugin:code-reviewer`와 같은 범위가 지정된 이름으로 [@-mention 자동완성](/docs/ko/sub-agents#invoke-subagents-explicitly)에 나타납니다.
100
101전체 세부 정보는 [서브에이전트](/docs/ko/sub-agents)를 참조하십시오.
102
103<h3 id="hooks">
104 훅
105</h3>
106
107플러그인은 Claude Code 이벤트에 자동으로 응답하는 이벤트 핸들러를 제공할 수 있습니다.
108
109**위치**: 플러그인 루트의 `hooks/hooks.json`, 또는 plugin.json에 인라인
110
111**형식**: 이벤트 매처와 작업이 있는 JSON 구성
112
113`hooks/hooks.json`은 JSON Schema URL을 명명하는 최상위 `$schema` 키를 포함할 수 있으며, 이는 편집기 자동완성 및 검증을 위한 것입니다. Claude Code는 로드 시 키를 무시합니다.
114
115**훅 구성**:
116
117```json theme={null}
118{
119 "hooks": {
120 "PostToolUse": [
121 {
122 "matcher": "Write|Edit",
123 "hooks": [
124 {
125 "type": "command",
126 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"
127 }
128 ]
129 }
130 ]
131 }
132}
133```
134
135플러그인 훅은 [사용자 정의 훅](/docs/ko/hooks)과 동일한 라이프사이클 이벤트에 응답합니다:
136
137| 이벤트 | 발생 시점 |
138| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
139| `SessionStart` | 세션이 시작되거나 재개될 때 |
140| `Setup` | `--init-only`로 Claude Code를 시작하거나, `-p` 모드에서 `--init` 또는 `--maintenance`로 시작할 때. CI 또는 스크립트에서 일회성 준비를 위함 |
141| `UserPromptSubmit` | 프롬프트를 제출할 때, Claude가 처리하기 전 |
142| `UserPromptExpansion` | 사용자가 입력한 명령이 프롬프트로 확장될 때, Claude에 도달하기 전. 확장을 차단할 수 있음 |
143| `PreToolUse` | 도구 호출이 실행되기 전. 차단할 수 있음 |
144| `PermissionRequest` | 도구 호출이 권한 결정이 필요할 때 |
145| `PermissionDenied` | 자동 모드가 도구 호출을 거부할 때, 분류기 판정이 없는 거부 포함. JSON `hookSpecificOutput.retry: true`를 사용하여 모델이 거부된 도구 호출을 재시도할 수 있음을 알립니다. Claude Code는 분류기가 판정을 내리지 않았을 때 `retry`를 무시합니다 |
146| `PostToolUse` | 도구 호출이 성공한 후 |
147| `PostToolUseFailure` | 도구 호출이 실패한 후 |
148| `PostToolBatch` | 병렬 도구 호출의 전체 배치가 해결된 후, 다음 모델 호출 전 |
149| `Notification` | Claude Code가 알림을 보낼 때 |
150| `MessageDisplay` | 어시스턴트 메시지 텍스트가 표시되는 동안 |
151| `SubagentStart` | 서브에이전트가 생성될 때 |
152| `SubagentStop` | 서브에이전트가 완료될 때 |
153| `TaskCreated` | `TaskCreate`를 통해 작업이 생성될 때 |
154| `TaskCompleted` | 작업이 완료로 표시될 때 |
155| `Stop` | Claude가 응답을 마칠 때 |
156| `StopFailure` | API 오류로 인해 턴이 종료될 때 |
157| `TeammateIdle` | [에이전트 팀](/docs/ko/agent-teams) 팀원이 유휴 상태가 될 때 |
158| `InstructionsLoaded` | CLAUDE.md 또는 `.claude/rules/*.md` 파일이 컨텍스트에 로드될 때. 세션 시작 시 및 세션 중에 파일이 지연 로드될 때 발생 |
159| `ConfigChange` | 세션 중에 구성 파일이 변경될 때 |
160| `CwdChanged` | 작업 디렉토리가 변경될 때, 예를 들어 Claude가 `cd` 명령을 실행할 때. direnv와 같은 도구를 사용한 반응형 환경 관리에 유용 |
161| `DirectoryAdded` | 작업 디렉토리가 세션 중에 `/add-dir` 또는 SDK `register_repo_root` 제어 요청을 통해 추가될 때 |
162| `FileChanged` | 감시 중인 파일이 디스크에서 변경될 때. `matcher` 필드는 감시할 파일명을 지정합니다 |
163| `WorktreeCreate` | 워크트리가 `--worktree`, `isolation: "worktree"`를 통해 생성되거나 백그라운드 세션을 위해 생성될 때. 기본 git 동작을 대체합니다 |
164| `WorktreeRemove` | 워크트리가 세션 종료 시, 서브에이전트가 완료될 때, 또는 백그라운드 세션을 삭제할 때 제거될 때 |
165| `PreCompact` | 컨텍스트 압축 전 |
166| `PostCompact` | 컨텍스트 압축이 완료된 후 |
167| `PreModelSwitch` | Claude Code가 사용자 또는 클라이언트가 요청한 모델 전환을 적용하기 전. 전환을 차단할 수 있음 |
168| `PostModelSwitch` | 세션의 모델이 변경된 후, Claude Code가 자체적으로 수행하는 변경(예: 세션을 재개할 때 모델 복원) 포함 |
169| `Elicitation` | MCP 서버가 도구 호출 중에 사용자 입력을 요청할 때 |
170| `ElicitationResult` | 사용자가 MCP 유도에 응답한 후, 응답이 서버로 다시 전송되기 전 |
171| `SessionEnd` | 세션이 종료될 때 |
172
173**훅 유형**:
174
175* `command`: 셸 명령어 또는 스크립트 실행
176* `http`: 이벤트 JSON을 URL로 POST 요청으로 전송
177* `mcp_tool`: 구성된 [MCP 서버](/docs/ko/mcp)에서 도구 호출
178* `prompt`: LLM으로 프롬프트 평가 (컨텍스트에 `$ARGUMENTS` 플레이스홀더 사용)
179* `agent`: 복잡한 검증 작업을 위해 도구가 있는 에이전트 검증자 실행
180
181플러그인의 자체 [번들 MCP 서버](#mcp-servers)를 대상으로 하는 훅은 범위가 지정된 이름을 사용해야 합니다. 도구 매처와 `if` 필드는 범위가 지정된 도구 이름 `mcp__plugin_<plugin-name>_<server-name>__<tool>`을 사용하고, `mcp_tool` 훅의 `server` 필드는 `plugin:<plugin-name>:<server-name>`을 사용합니다. 베어 서버 키에 대해 작성된 매처는 절대 실행되지 않습니다. [MCP 도구 일치](/docs/ko/hooks#match-mcp-tools) 및 [플러그인 제공 MCP 서버](/docs/ko/mcp#plugin-provided-mcp-servers)를 참조하십시오.
182
183<h3 id="mcp-servers">
184 MCP 서버
185</h3>
186
187플러그인은 Claude Code를 외부 도구 및 서비스와 연결하기 위해 Model Context Protocol (MCP) 서버를 번들로 제공할 수 있습니다.
188
189**위치**: 플러그인 루트의 `.mcp.json`, 또는 plugin.json에 인라인
190
191**형식**: 표준 MCP 서버 구성
192
193**MCP 서버 구성**:
194
195```json theme={null}
196{
197 "mcpServers": {
198 "plugin-database": {
199 "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
200 "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
201 "env": {
202 "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
203 }
204 },
205 "plugin-api-client": {
206 "command": "npx",
207 "args": ["@company/mcp-server", "--plugin-mode"]
208 }
209 }
210}
211```
212
213**통합 동작**:
214
215* 플러그인 MCP 서버는 플러그인이 활성화될 때 자동으로 시작됩니다.
216* 서버는 Claude의 도구 키트에 표준 MCP 도구로 나타납니다.
217* 플러그인 서버는 사용자 MCP 서버와 독립적으로 구성할 수 있습니다.
218* 세션 중에 [`/reload-plugins`](/docs/ko/discover-plugins#apply-plugin-changes-without-restarting)를 실행하면, Claude Code는 구성이 변경되지 않은 서버의 라이브 연결을 유지합니다.
219
220<h3 id="lsp-servers">
221 LSP 서버
222</h3>
223
224<Tip>
225 LSP 플러그인을 사용하려고 하시나요? 공식 마켓플레이스에서 설치하십시오: `/plugin` 발견 탭에서 "lsp"를 검색하십시오. 이 섹션은 공식 마켓플레이스에서 다루지 않는 언어에 대한 LSP 플러그인을 만드는 방법을 설명합니다.
226</Tip>
227
228플러그인은 [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) 서버를 제공하여 Claude가 코드베이스에서 작업할 때 [실시간 코드 인텔리전스](/docs/ko/discover-plugins#code-intelligence)를 제공할 수 있습니다.
229
230**위치**: 플러그인 루트의 `.lsp.json`, 또는 `plugin.json`에 인라인
231
232**형식**: 언어 서버 이름을 해당 구성에 매핑하는 JSON 구성
233
234**`.lsp.json` 파일 형식**:
235
236```json theme={null}
237{
238 "go": {
239 "command": "gopls",
240 "args": ["serve"],
241 "extensionToLanguage": {
242 ".go": "go"
243 }
244 }
245}
246```
247
248**`plugin.json`에 인라인**:
249
250```json theme={null}
251{
252 "name": "my-plugin",
253 "lspServers": {
254 "go": {
255 "command": "gopls",
256 "args": ["serve"],
257 "extensionToLanguage": {
258 ".go": "go"
259 }
260 }
261 }
262}
263```
264
265**필수 필드:**
266
267| 필드 | 설명 |
268| :-------------------- | :------------------------- |
269| `command` | 실행할 LSP 바이너리 (PATH에 있어야 함) |
270| `extensionToLanguage` | 파일 확장자를 언어 식별자에 매핑 |
271
272**선택사항 필드:**
273
274| 필드 | 설명 |
275| :---------------------- | :------------------------------------------------------------------------------------------------------------------ |
276| `args` | LSP 서버의 명령줄 인수 |
277| `transport` | 통신 전송: `stdio` (기본값) 또는 `socket`. Claude Code는 `socket`을 허용하지만 모든 서버를 stdio를 통해 실행하므로 stdout 프로토콜 규칙이 모든 서버에 적용됩니다. |
278| `env` | 서버 시작 시 설정할 환경 변수 |
279| `initializationOptions` | 초기화 중에 서버에 전달되는 옵션 |
280| `settings` | `workspace/didChangeConfiguration`을 통해 전달되는 설정 |
281| `workspaceFolder` | 서버의 작업 공간 폴더 경로 |
282| `startupTimeout` | 서버 시작을 기다릴 최대 시간 (밀리초) |
283| `shutdownTimeout` | 정상 종료를 기다릴 최대 시간 (밀리초). 시간 초과가 경과하면 Claude Code는 서버 프로세스를 종료합니다. 설정하지 않으면 시간 초과가 적용되지 않습니다. |
284| `restartOnCrash` | 서버 충돌 후 다시 시작할지 여부. 기본값은 `true`입니다. 충돌한 서버를 다시 시작하지 않고 중지된 상태로 두려면 `false`로 설정합니다. |
285| `maxRestarts` | 포기하기 전 최대 재시작 시도 횟수 |
286| `diagnostics` | 편집 후 진단을 Claude의 컨텍스트에 푸시할지 여부 (기본값 `true`). 코드 네비게이션은 유지하되 자동 진단 주입을 억제하려면 `false`로 설정합니다. |
287
288`restartOnCrash` 및 `shutdownTimeout`은 Claude Code v2.1.205 이상이 필요합니다. v2.1.205 이전에는 구성 스키마가 두 옵션을 모두 허용했지만 둘 중 하나를 설정하면 Claude Code가 시작 시 해당 LSP 서버를 완전히 건너뛰었으며, 이유는 `claude --debug` 출력에서만 볼 수 있었습니다.
289
290**동일한 확장자에 대한 여러 서버**: 둘 이상의 활성화된 LSP 서버가 `extensionToLanguage`에서 동일한 파일 확장자를 선언할 때, 서버가 하나의 플러그인에서 오든 다른 플러그인에서 오든, 먼저 등록된 서버가 해당 확장자의 파일을 처리하고 다른 서버는 시작되지 않습니다. `/plugin` 인터페이스는 활성 서버인 플러그인의 이름을 지정하는 경고를 표시합니다.
291
292**초기화에 실패한 서버**: Claude Code는 `command` 또는 `extensionToLanguage`가 누락된 것처럼 구성이 유효하지 않은 서버를 건너뛰고, 다른 구성된 서버는 여전히 시작됩니다. `claude --debug`를 실행하여 서버가 건너뛰어진 이유를 확인합니다.
293
294건너뛴 서버는 파일 확장자를 요청하지 않으므로, 동일한 확장자를 선언하는 다른 유효한 서버(같은 플러그인 또는 다른 플러그인에서)가 여전히 해당 파일을 처리합니다.
295
296**로그 출력을 stderr로 보내기, stdout이 아님**: Claude Code는 서버의 stdout을 프로토콜 메시지로만 읽고, 메시지 헤더는 최대 64 KiB, 메시지 본문은 최대 32 MiB를 허용합니다. Claude Code는 한계를 초과하거나 stdout에 비프로토콜 출력을 작성하는 서버를 연결 해제하고, 연결 해제를 `restartOnCrash` 및 `maxRestarts`에 대한 충돌로 계산합니다. `--debug`로 실행하면 Claude Code는 원인을 명명하는 오류를 디버그 로그에 작성합니다.
297
298<Warning>
299 **언어 서버 바이너리를 별도로 설치해야 합니다.** LSP 플러그인은 Claude Code가 언어 서버에 연결하는 방법을 구성하지만, 서버 자체는 포함하지 않습니다. `/plugin` 오류 탭에서 `Executable not found in $PATH`를 보면, 언어에 필요한 바이너리를 설치합니다.
300</Warning>
301
302**사용 가능한 LSP 플러그인:**
303
304| 플러그인 | 언어 서버 | 설치 명령어 |
305| :------------------ | :------------------------- | :------------------------------------------------------------------------------ |
306| `pyright-lsp` | Pyright (Python) | `pip install pyright` 또는 `npm install -g pyright` |
307| `typescript-lsp` | TypeScript Language Server | `npm install -g typescript-language-server typescript` |
308| `rust-analyzer-lsp` | rust-analyzer | [rust-analyzer 설치 참조](https://rust-analyzer.github.io/manual.html#installation) |
309
310먼저 언어 서버를 설치한 다음 마켓플레이스에서 플러그인을 설치합니다.
311
312<h3 id="monitors">
313 모니터
314</h3>
315
316플러그인은 Claude Code가 플러그인이 활성화될 때 자동으로 시작하는 백그라운드 모니터를 선언할 수 있습니다. 각 모니터는 세션 동안 셸 명령어를 실행하고 모든 stdout 라인을 Claude에 알림으로 전달하므로, Claude는 자신이 시작하도록 요청받지 않고도 로그 항목, 상태 변경 또는 폴링된 이벤트에 반응할 수 있습니다.
317
318플러그인 모니터는 [모니터 도구](/docs/ko/tools-reference#monitor-tool)와 동일한 메커니즘을 사용하고 가용성 제약을 공유합니다. 이들은 대화형 CLI 세션에서만 실행되고, [훅](#hooks)과 동일한 신뢰 수준에서 샌드박스 없이 실행되며, 모니터 도구를 사용할 수 없는 호스트에서는 건너뜁니다.
319
320**위치**: 플러그인 루트의 `monitors/monitors.json`, 또는 plugin.json에 인라인
321
322**형식**: 모니터 항목의 JSON 배열
323
324다음 `monitors/monitors.json`은 배포 상태 엔드포인트와 로컬 오류 로그를 감시합니다:
325
326```json theme={null}
327[
328 {
329 "name": "deploy-status",
330 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
331 "description": "배포 상태 변경"
332 },
333 {
334 "name": "error-log",
335 "command": "tail -F ./logs/error.log",
336 "description": "애플리케이션 오류 로그",
337 "when": "on-skill-invoke:debug"
338 }
339]
340```
341
342모니터를 인라인으로 선언하려면 `plugin.json`에서 `experimental.monitors`를 동일한 배열로 설정합니다. 기본이 아닌 경로에서 로드하려면 `experimental.monitors`를 `"./config/monitors.json"`과 같은 상대 경로 문자열로 설정합니다. 모니터는 [실험적 컴포넌트](#experimental-components)입니다.
343
344**필수 필드:**
345
346| 필드 | 설명 |
347| :------------ | :------------------------------------------------------------ |
348| `name` | 플러그인 내에서 고유한 식별자. 플러그인이 다시 로드되거나 스킬이 다시 호출될 때 중복 프로세스를 방지합니다. |
349| `command` | 세션 작업 디렉토리에서 지속적인 백그라운드 프로세스로 실행되는 셸 명령어 |
350| `description` | 감시 중인 항목의 간단한 요약. 작업 패널 및 알림 요약에 표시됩니다. |
351
352**선택사항 필드:**
353
354| 필드 | 설명 |
355| :----- | :----------------------------------------------------------------------------------------------------------------------------------- |
356| `when` | 모니터가 시작될 때를 제어합니다. `"always"`는 세션 시작 및 플러그인 다시 로드 시 시작하며 기본값입니다. `"on-skill-invoke:<skill-name>"`은 이 플러그인의 명명된 스킬이 처음 디스패치될 때 시작합니다. |
357
358`command` 값은 [경로 대체](#environment-variables) `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}`, `${CLAUDE_PROJECT_DIR}` 및 환경의 모든 `${ENV_VAR}`을 지원합니다. 스크립트가 플러그인의 자체 디렉토리에서 실행되어야 하면 명령어 앞에 `cd "${CLAUDE_PLUGIN_ROOT}" && `를 붙입니다.
359
360모니터 `command`는 [`${user_config.*}`](#user-configuration) 값을 참조할 수 없습니다. 명령어는 셸을 통해 실행되므로 Claude Code는 값을 대체하는 대신 [오류](/docs/ko/errors#plugin-command-references-user-config)로 모니터를 거부합니다. 모니터 프로세스는 `CLAUDE_PLUGIN_OPTION_<KEY>` 환경 변수를 받지 않으므로, 모니터 스크립트가 자신이 소유한 구성 파일에서 값을 읽도록 합니다.
361
362세션 중에 플러그인을 비활성화하면, Claude Code는 이미 실행 중인 모니터를 중지하지 않습니다. 세션이 끝날 때 중지됩니다.
363
364<h3 id="themes">
365 테마
366</h3>
367
368플러그인은 `/theme`에 기본 제공 사전 설정 및 사용자의 로컬 테마와 함께 나타나는 색상 테마를 제공할 수 있습니다. 테마는 `themes/` 디렉토리의 JSON 파일로, `base` 사전 설정과 색상 토큰의 스파스 `overrides` 맵이 있습니다. 테마는 [실험적 컴포넌트](#experimental-components)입니다.
369
370```json theme={null}
371{
372 "name": "Dracula",
373 "base": "dark",
374 "overrides": {
375 "claude": "#bd93f9",
376 "error": "#ff5555",
377 "success": "#50fa7b"
378 }
379}
380```
381
382사용자가 플러그인 테마를 선택하면, Claude Code는 `custom:<plugin-name>:<slug>`을 해당 구성에 저장합니다. 플러그인 테마는 읽기 전용입니다: 사용자가 `/theme`에서 하나를 `Ctrl+E`로 누르면, Claude Code는 이를 `~/.claude/themes/`로 복사하여 사용자가 복사본을 편집할 수 있도록 합니다.
383
384***
385
386<h2 id="plugin-installation-scopes">
387 플러그인 설치 범위
388</h2>
389
390플러그인을 설치할 때 플러그인이 사용 가능한 위치와 다른 사용자가 사용할 수 있는지를 결정하는 **범위**를 선택합니다:
391
392| 범위 | 설정 파일 | 사용 사례 |
393| :-------- | :------------------------------ | :--------------------------------------------- |
394| `user` | `~/.claude/settings.json` | 모든 프로젝트에서 사용 가능한 개인 플러그인(기본값) |
395| `project` | `.claude/settings.json` | 버전 관리를 통해 공유되는 팀 플러그인 |
396| `local` | `.claude/settings.local.json` | 프로젝트별 플러그인, Claude Code가 설정을 저장할 때 gitignored됨 |
397| `managed` | [관리되는 설정](/docs/ko/managed-settings) | 관리되는 플러그인(읽기 전용, 업데이트만 가능) |
398
399플러그인은 다른 Claude Code 구성과 동일한 범위 시스템을 사용합니다. 설치 지침 및 범위 플래그는 [플러그인 설치](/docs/ko/discover-plugins#install-plugins)를 참조하십시오. 범위에 대한 완전한 설명은 [구성 범위](/docs/ko/settings#where-settings-live)를 참조하십시오.
400
401***
402
403<h2 id="skills-directory-plugins">
404 스킬 디렉토리 플러그인
405</h2>
406
407스킬 디렉토리 아래의 모든 폴더가 `.claude-plugin/plugin.json` 매니페스트를 포함하면 다음 세션에서 `<name>@skills-dir`이라는 이름의 플러그인으로 로드되며, 마켓플레이스나 설치 단계가 없습니다. [`plugin init`](#plugin-init)으로 스캐폴드를 생성할 수 있습니다. 복사된 마켓플레이스 설치와 달리, 플러그인은 플러그인 캐시로 복사되지 않고 제자리에서 발견됩니다.
408
409스킬 디렉토리 트리는 세 가지 서로 다른 것을 지원합니다:
410
411| 보유한 것 | 설명 |
412| :-------------------------------------------- | :--------------------------------------------------- |
413| 매니페스트가 없는 `<skills-dir>/foo/SKILL.md` | `foo`라는 이름의 일반 [스킬](/docs/ko/skills) |
414| `<skills-dir>/foo/.claude-plugin/plugin.json` | 자체 스킬, 에이전트, 훅 등을 번들로 제공할 수 있는 플러그인 `foo@skills-dir` |
415| `<plugin>/skills/bar/SKILL.md` | 플러그인 내에 패키징된 스킬 `bar` |
416
417<h3 id="choose-where-the-plugin-loads-from">
418 플러그인이 로드되는 위치 선택
419</h3>
420
421| 스킬 디렉토리 | 범위 | 로드 |
422| :---------------------- | :--- | :------------------------------------------------------------------------------------------ |
423| `~/.claude/skills/` | 개인 | 위치가 사용자 것이므로 모든 프로젝트에서 로드 |
424| `<cwd>/.claude/skills/` | 프로젝트 | 해당 폴더에 대한 워크스페이스 [신뢰 대화상자](/docs/ko/permissions#what-runs-before-you-trust-a-folder)를 수락한 후에만 로드 |
425
426프로젝트 범위 플러그인은 저장소에 체크인되며 이를 복제하는 모든 협력자에게 도달합니다. 해당 콘텐츠가 사용자가 아닌 저장소에서 오기 때문에, `.claude/settings.json`의 프로젝트 허용 규칙을 관리하는 것과 동일한 신뢰 게이트 이후에만 로드되므로, 상위 폴더를 신뢰하거나 `-p`로 실행하는 것만으로는 충분하지 않으며, 코드를 실행하는 구성 요소는 추가로 제한됩니다:
427
428* 선언하는 MCP 서버는 프로젝트 `.mcp.json`과 동일한 [서버별 승인](/docs/ko/mcp)을 거칩니다
429* LSP 서버는 워크스페이스를 신뢰한 후에만 시작됩니다
430* [백그라운드 모니터](#monitors)는 로드되지 않습니다
431
432개인 범위 플러그인에는 이러한 제한이 없습니다.
433
434<Warning>
435 프로젝트 범위 `@skills-dir` 플러그인은 세션의 [기본 작업 디렉토리](/docs/ko/permissions#working-directories)의 `.claude/skills/`에서만 로드됩니다. 일반 스킬 및 명령처럼 [저장소 루트까지 올라가지](/docs/ko/skills#discovery-from-parent-and-nested-directories) 않으므로, 하위 디렉토리에서 시작하면 저장소 루트에 있는 플러그인을 놓칩니다. 저장소 루트에서 시작하거나, [v2.1.246 이상에서 `/cd`로 세션을 이동](/docs/ko/permissions#move-the-session-to-another-directory)하십시오.
436</Warning>
437
438<h3 id="edit-reload-and-disable-a-skills-directory-plugin">
439 스킬 디렉토리 플러그인 편집, 다시 로드 및 비활성화
440</h3>
441
442스킬의 `SKILL.md`에 대한 변경 사항은 현재 세션에서 즉시 적용됩니다. `hooks/`, `.mcp.json`, `agents/`, `output-styles/` 등 플러그인의 다른 구성 요소에 대한 변경 사항은 적용되지 않습니다. `/reload-plugins`를 실행하거나 Claude Code를 다시 시작하여 이를 적용하십시오. [라이브 변경 감지](/docs/ko/skills#live-change-detection)를 참조하십시오.
443
444스킬 디렉토리 플러그인 로드를 중지하려면 해당 폴더를 삭제하거나 이름으로 비활성화하십시오. 마켓플레이스에서 아무것도 설치되지 않았으므로 `uninstall` 단계가 없습니다.
445
446```bash theme={null}
447claude plugin disable my-tool@skills-dir
448```
449
450***
451
452<h2 id="synced-plugins">
453 claude.ai에서 동기화된 플러그인
454</h2>
455
456Claude Code는 조직이 구성원을 위해 활성화하는 플러그인을 포함하여 claude.ai 계정에 대해 활성화된 플러그인을 마켓플레이스에서 설치하는 플러그인과 함께 로드합니다. 각 플러그인을 `~/.claude/plugins/synced/`로 다운로드하고 마켓플레이스 및 설치 기록 없이 `<name>@synced`로 로드합니다. 동기화된 플러그인은 설치한 마켓플레이스 플러그인과 동일한 신뢰도로 실행됩니다. 해당 skills, agents, hooks, MCP servers, LSP servers가 모두 로드됩니다.
457
458Claude Code가 이러한 플러그인을 동기화하는 위치는 세션에 따라 다릅니다:
459
460* [Cowork](https://claude.com/product/cowork) 및 [클라우드 세션](/docs/ko/cloud-environments#what-carries-over-from-your-setup)에서 Claude Code는 세션이 시작될 때 세션의 자체 환경으로 플러그인을 다운로드합니다. v2.1.239 이전에는 Claude Code가 이러한 플러그인을 `<name>@inline`으로 로드했으며, 이는 `--plugin-dir` 플러그인이 사용하는 ID입니다.
461* claude.ai 계정으로 로그인하는 터미널 세션에서 Claude Code는 시작할 때마다 계정을 한 번 확인한 다음 새로운 플러그인과 업데이트된 플러그인을 다운로드하고 사용자 또는 조직이 비활성화한 플러그인을 모두 백그라운드에서 제거합니다. 터미널 세션에서의 동기화에는 Claude Code v2.1.273 이상이 필요합니다.
462
463시작 확인은 백그라운드에서 실행되므로 세션이 시작된 후에 완료될 수 있습니다. 대화형 세션에서 동기화된 플러그인을 추가, 업데이트 또는 제거할 때 Claude Code는 `Plugins changed. Run /reload-plugins to activate.`를 표시합니다. [`/reload-plugins`](/docs/ko/discover-plugins#apply-plugin-changes-without-restarting)를 실행하여 해당 세션에서 변경 사항을 로드하거나 다음에 Claude Code를 시작할 때까지 기다립니다. claude.ai에서 세션이 실행 중인 동안 플러그인을 활성화하면 Claude Code는 다음에 시작할 때 플러그인을 다운로드합니다.
464
465터미널 세션의 플러그인 동기화는 [claude.ai에서 동기화된 skills](/docs/ko/skills#where-synced-skills-load)와 동일한 로그인 조건에서 실행됩니다. 또한 Claude Code가 계정의 플러그인에 액세스할 수 있도록 하는 로그인이 필요합니다.
466
467이전 버전의 Claude Code에서의 로그인은 Claude Code가 백그라운드에서 해당 로그인을 갱신할 때(몇 시간 이내) 또는 `/login`을 다시 실행하면 즉시 플러그인 액세스를 선택합니다. 플러그인 동기화는 그 이후 Claude Code를 시작할 때 시작됩니다.
468
469`claude plugin list`는 `Synced from claude.ai` 제목 아래에 동기화된 플러그인을 표시하고, `/plugin` **Installed** 탭은 `synced`를 소스로 하여 나열합니다. `claude plugin list`가 출력하는 `<name>@synced` ID로 동기화된 플러그인을 관리합니다:
470
471* **하나 끄기**: `claude plugin disable <name>@synced`를 실행하거나 `/plugin` **Installed** 탭에서 비활성화합니다. Claude Code는 선택을 사용자 수준 [`enabledPlugins`](/docs/ko/settings-reference#enabledplugins)에 `"<name>@synced": false`로 저장합니다. 플러그인을 다시 켜려면 `claude plugin enable <name>@synced`를 실행합니다.
472* **모든 곳에서 하나 제외하기**: [claude.ai 계정에서 플러그인을 끕니다](/docs/ko/desktop#extend-claude-code). 모든 환경에서 하나의 프로젝트에서 플러그인을 제외하려면 해당 프로젝트의 커밋된 `.claude/settings.json`의 `enabledPlugins` 아래에 `"<name>@synced": false`를 설정합니다.
473* **claude.ai에서 플러그인 자체 관리**: `claude plugin install`, `update`, `uninstall`은 동기화된 플러그인에 적용되지 않습니다. Claude Code는 다음 동기화에서 플러그인의 업데이트를 다운로드합니다. 플러그인을 제거하려면 claude.ai 계정에서 플러그인을 끄고 Claude Code는 다음 동기화에서 플러그인을 제거합니다.
474* **머신에서 동기화 중지**: 사용자 설정에서 [`syncClaudeAiPlugins`](/docs/ko/settings-reference#syncclaudeaiplugins)를 `false`로 설정합니다. Claude Code는 다운로드를 중지하고 다음에 시작할 때 이미 동기화한 플러그인을 `~/.claude/plugins/.trash/`로 이동하고 더 이상 로드하지 않습니다. 조직은 [관리 설정](/docs/ko/managed-settings)에서 동일한 키를 설정하거나 claude.ai에서 Skills를 끌 수 있으며, 이는 플러그인 동기화도 중지합니다.
475
476조직이 claude.ai에서 필수로 표시한 플러그인은 끌 수 없습니다. Claude Code는 이전에 비활성화했더라도 플러그인을 로드하고, `claude plugin disable`은 `Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.`로 거부합니다. `claude plugin list`에서 이러한 플러그인은 `required by your org`로 표시됩니다.
477
478다른 소스의 활성화된 플러그인이 동기화된 플러그인의 이름과 일치하면 Claude Code는 해당 플러그인을 로드하고 동기화된 복사본을 로드되지 않은 것으로 보고합니다. 다른 소스에는 마켓플레이스 설치, [skills-directory 플러그인](#skills-directory-plugins), `--plugin-dir` 플러그인, Claude Code에 내장된 플러그인이 포함됩니다. claude.ai 복사본을 대신 사용하려면 자신의 복사본을 비활성화합니다. v2.1.239 이전에는 Claude Code가 같은 이름의 마켓플레이스 설치 대신 동기화된 복사본을 로드했습니다.
479
480***
481
482<h2 id="plugin-manifest-schema">
483 플러그인 매니페스트 스키마
484</h2>
485
486`.claude-plugin/plugin.json` 파일은 플러그인의 메타데이터와 구성을 정의합니다.
487
488매니페스트는 선택 사항입니다. 생략하면 Claude Code는 [기본 위치](#file-locations-reference)에서 구성 요소를 자동으로 검색하고 디렉터리 이름에서 플러그인 이름을 파생합니다. 메타데이터를 제공하거나 사용자 정의 구성 요소 경로가 필요한 경우 매니페스트를 사용합니다.
489
490<h3 id="complete-schema">
491 완전한 스키마
492</h3>
493
494```json theme={null}
495{
496 "name": "plugin-name",
497 "displayName": "Plugin Name",
498 "version": "1.2.0",
499 "description": "Brief plugin description",
500 "author": {
501 "name": "Author Name",
502 "email": "author@example.com",
503 "url": "https://github.com/author"
504 },
505 "homepage": "https://docs.example.com/plugin",
506 "repository": "https://github.com/author/plugin",
507 "license": "MIT",
508 "keywords": ["keyword1", "keyword2"],
509 "metadata": { "catalogId": "cat-123", "tier": "pro" },
510 "skills": "./custom/skills/",
511 "commands": ["./custom/commands/special.md"],
512 "agents": ["./custom/agents/reviewer.md"],
513 "hooks": "./config/hooks.json",
514 "mcpServers": "./mcp-config.json",
515 "outputStyles": "./styles/",
516 "lspServers": "./.lsp.json",
517 "experimental": {
518 "themes": "./themes/",
519 "monitors": "./monitors.json",
520 "evals": "quality/evals"
521 },
522 "dependencies": [
523 "helper-lib",
524 { "name": "secrets-vault", "version": "~2.1.0" }
525 ]
526}
527```
528
529<h3 id="required-fields">
530 필수 필드
531</h3>
532
533매니페스트를 포함하는 경우 `name`이 유일한 필수 필드입니다.
534
535| 필드 | 유형 | 설명 | 예시 |
536| :----- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------- |
537| `name` | string | 공백, 제어 문자 또는 양방향 형식 문자가 없는 케밥 케이스의 고유 식별자입니다. [마켓플레이스 항목](/docs/ko/plugin-marketplaces#plugin-entries)이 플러그인을 다른 이름으로 나열할 때 마켓플레이스 항목 이름이 `enabledPlugins` 키와 `/plugin`에서 사용하는 이름입니다 | `"deployment-tools"` |
538
539이 이름은 구성 요소 네임스페이싱에 사용됩니다. 예를 들어 UI에서 이름이 `plugin-dev`인 플러그인의 에이전트 `agent-creator`는 `plugin-dev:agent-creator`로 표시됩니다.
540
541<h3 id="unrecognized-fields">
542 인식되지 않는 필드
543</h3>
544
545Claude Code는 인식하지 못하는 최상위 필드를 무시합니다. 다른 에코시스템의 메타데이터를 `plugin.json`에 유지할 수 있으며 플러그인은 여전히 로드됩니다. 이를 통해 VS Code 또는 Cursor 확장 매니페스트, npm `package.json` 또는 MCPB/DXT 번들 매니페스트로도 작동하는 하나의 매니페스트를 유지하는 것이 실용적입니다.
546
547`claude plugin validate`는 인식되지 않는 필드를 오류가 아닌 경고로 보고합니다. 필드가 인식된 필드와 한두 글자 차이나면 경고에서 의도된 이름을 제안합니다. 인식되지 않는 필드 경고만 있는 플러그인은 여전히 검증을 통과하고 런타임에 로드됩니다.
548
549Claude Code가 값의 유형이 잘못된 인식된 필드를 처리하는 방식은 필드에 따라 다릅니다.
550
551* **대부분의 필드**: 플러그인이 로드되지 않습니다. 예를 들어 `keywords` 값이 배열 대신 문자열인 경우 로드 오류이며 `claude plugin validate`는 이를 오류로 보고합니다.
552* **`experimental` 및 `metadata`**: Claude Code는 비객체 값을 무시하고 `claude plugin validate`는 경고를 보고합니다.
553
554`--strict`를 전달하여 경고를 오류로 처리합니다. CI에서 이를 사용하여 게시하기 전에 필드 이름 오타나 다른 도구의 매니페스트에서 남은 필드를 포착합니다. 플러그인은 런타임에 로드되지만 말입니다.
555
556```bash theme={null}
557claude plugin validate ./my-plugin --strict
558```
559
560<h3 id="metadata-fields">
561 메타데이터 필드
562</h3>
563
564| 필드 | 유형 | 설명 | 예시 |
565| :--------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |
566| `$schema` | string | 편집기 자동 완성 및 검증을 위한 JSON Schema URL입니다. Claude Code는 로드 시간에 이 필드를 무시합니다. | `"https://json.schemastore.org/claude-code-plugin-manifest.json"` |
567| `displayName` | string | `/plugin` 선택기 및 기타 UI 표면에 표시되는 사람이 읽을 수 있는 이름입니다. 마켓플레이스 설치 플러그인의 경우 [마켓플레이스 항목](/docs/ko/plugin-marketplaces#optional-plugin-fields)의 `displayName`이 이 값보다 우선합니다. 두 위치 모두에서 표시 이름이 설정되지 않으면 사용자는 `name`을 봅니다. `name`과 달리 공백과 모든 대소문자를 포함할 수 있습니다. 네임스페이싱이나 조회에 사용되지 않습니다. | `"Deployment Tools"` |
568| `version` | string | 선택 사항입니다. 의미 있는 버전입니다. 이를 설정하면 플러그인이 해당 버전 문자열로 고정되므로 사용자는 이를 범프할 때만 업데이트를 받습니다. [`command` 소스](/docs/ko/plugin-marketplaces#command-sources) 또는 [로드된 플러그인](#plugin-caching-and-file-resolution) 제외; [버전 관리](#version-management)를 참조합니다. 마켓플레이스 항목에도 설정된 경우 `plugin.json`이 우선합니다. 생략하면 버전은 [버전 관리](#version-management)의 다음 소스에서 옵니다. | `"2.1.0"` |
569| `description` | string | 플러그인 목적에 대한 간단한 설명 | `"Deployment automation tools"` |
570| `author` | object | 작성자 정보 | `{"name": "Dev Team", "email": "dev@company.com"}` |
571| `homepage` | string | 문서 URL | `"https://docs.example.com"` |
572| `repository` | string | 소스 코드 URL | `"https://github.com/user/plugin"` |
573| `license` | string | 라이선스 식별자 | `"MIT"`, `"Apache-2.0"` |
574| `keywords` | array | 검색 태그 | `["deployment", "ci-cd"]` |
575| `metadata` | object | 자격 또는 카탈로그 필드와 같은 자신의 데이터를 위한 자유 형식 객체입니다. Claude Code는 이를 읽지 않으므로 값이 플러그인 동작에 영향을 주지 않습니다. Claude Code는 비객체 값을 무시하고 `claude plugin validate`는 이를 경고로 보고합니다. v2.1.222 이전에는 Claude Code가 키를 [인식되지 않는 필드](#unrecognized-fields)로 처리했습니다. | `{"catalogId": "cat-123"}` |
576| `defaultEnabled` | boolean | 사용자가 설정하지 않았을 때 플러그인이 활성화된 상태로 시작되는지 여부입니다. 기본값은 `true`입니다. [기본 활성화](#default-enablement)를 참조합니다. | `false` |
577
578<h3 id="default-enablement">
579 기본 활성화
580</h3>
581
582`plugin.json`에서 `defaultEnabled: false`를 설정하여 비활성화된 상태로 설치되는 플러그인을 배포합니다. 사용자는 `claude plugin enable <plugin>` 또는 `/plugin` 인터페이스로 이를 켭니다. 외부 서비스에 연결하는 것과 같이 사용자가 옵트인해야 하는 비용이나 범위를 추가하는 플러그인에 이를 사용합니다.
583
584`defaultEnabled`는 다른 것이 플러그인의 상태를 결정하지 않았을 때의 폴백입니다. 사용자의 설정과 종속성 요구 사항이 이를 우선합니다.
585
586* **사용자의 설정**: 모든 설정 범위에서 플러그인의 `enabledPlugins` 항목입니다. 작성되면 플러그인 업데이트 및 재설치 전체에서 지속되므로 나중 릴리스에서 `defaultEnabled`를 변경해도 기존 사용자를 뒤집지 않습니다.
587* **종속성 요구 사항**: 플러그인이 활성화된 다른 플러그인에 의해 필요할 때 Claude Code는 설치 또는 활성화 시간에 이에 대해 `true`를 작성합니다. 이는 명시적 설정을 제공하므로 자신의 기본값은 더 이상 적용되지 않습니다. [종속성이 있는 플러그인 활성화 또는 비활성화](/docs/ko/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)를 참조합니다.
588
589동일한 필드가 플러그인의 마켓플레이스 항목에 나타날 수 있으며, 여기서 `plugin.json`의 값보다 우선합니다. [선택적 플러그인 필드](/docs/ko/plugin-marketplaces#optional-plugin-fields)를 참조합니다.
590
591<h3 id="component-path-fields">
592 구성 요소 경로 필드
593</h3>
594
595| 필드 | 유형 | 설명 | 예시 |
596| :---------------------- | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |
597| `skills` | string\|array | `<name>/SKILL.md`를 포함하는 사용자 정의 스킬 디렉터리입니다. 기본 `skills/` 스캔에 추가됩니다. 마켓플레이스 루트 예외에 대해 [경로 동작 규칙](#path-behavior-rules)을 참조합니다 | `"./custom/skills/"` |
598| `commands` | string\|array | 사용자 정의 플랫 `.md` 스킬 파일 또는 디렉터리입니다(기본 `commands/` 대체) | `"./custom/cmd.md"` 또는 `["./cmd1.md"]` |
599| `agents` | string\|array | 사용자 정의 에이전트 파일입니다(기본 `agents/` 대체) | `"./custom/agents/reviewer.md"` |
600| `workflows` | string\|array | 사용자 정의 [워크플로우](/docs/ko/workflows) 스크립트 파일 또는 디렉터리입니다(기본 `workflows/` 대체) | `"./custom/workflows/"` |
601| `hooks` | string\|array\|object | 훅 구성 경로 또는 인라인 구성 | `"./my-extra-hooks.json"` |
602| `mcpServers` | string\|array\|object | MCP 구성 경로 또는 인라인 구성 | `"./my-extra-mcp-config.json"` |
603| `outputStyles` | string\|array | 사용자 정의 출력 스타일 파일/디렉터리입니다(기본 `output-styles/` 대체) | `"./styles/"` |
604| `lspServers` | string\|array\|object | 코드 인텔리전스(정의로 이동, 참조 찾기 등)를 위한 [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) 구성 | `"./.lsp.json"` |
605| `experimental.themes` | string\|array | 색상 테마 파일/디렉터리입니다(기본 `themes/` 대체). [테마](#themes)를 참조합니다 | `"./themes/"` |
606| `experimental.monitors` | string\|array | 플러그인이 활성화될 때 자동으로 시작되는 백그라운드 [Monitor](/docs/ko/tools-reference#monitor-tool) 구성입니다. [모니터](#monitors)를 참조합니다 | `"./monitors.json"` |
607| `experimental.evals` | string\|array | 플러그인의 [eval 사례](/docs/ko/plugin-evals#use-a-different-eval-directory)를 보유하는 플러그인 루트 아래의 디렉터리입니다. 기본값이 `evals/`가 아닐 때입니다. `claude plugin eval --eval-dir`이 이를 재정의합니다 | `"quality/evals"` |
608| `userConfig` | object | 활성화 시간에 사용자에게 프롬프트되는 사용자 구성 가능한 값입니다. [사용자 구성](#user-configuration)을 참조합니다 | |
609| `channels` | array | 메시지 주입을 위한 채널 선언입니다(Telegram, Slack, Discord 스타일). [채널](#channels)을 참조합니다 | |
610| `dependencies` | array | 이 플러그인이 필요로 하는 다른 플러그인입니다. 선택적으로 semver 버전 제약 조건이 있습니다. [플러그인 종속성 버전 제약](/docs/ko/plugin-dependencies)을 참조합니다 | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |
611
612<h3 id="experimental-components">
613 실험적 구성 요소
614</h3>
615
616`experimental` 키 아래의 구성 요소인 `themes` 및 `monitors`는 안정화되는 동안 릴리스 간에 변경될 수 있는 매니페스트 스키마를 가집니다. 이를 선언하는 위치는 별도의 마이그레이션입니다. 최상위 수준은 여전히 작동하고 `claude plugin validate`는 경고하며 향후 릴리스는 `experimental.*`를 요구할 것입니다.
617
618<h3 id="user-configuration">
619 사용자 구성
620</h3>
621
622`userConfig` 필드는 플러그인이 활성화될 때 Claude Code가 사용자에게 프롬프트하는 값을 선언합니다. 사용자가 `settings.json`을 수동으로 편집하도록 요구하는 대신 이를 사용합니다.
623
624```json theme={null}
625{
626 "userConfig": {
627 "api_endpoint": {
628 "type": "string",
629 "title": "API endpoint",
630 "description": "Your team's API endpoint"
631 },
632 "api_token": {
633 "type": "string",
634 "title": "API token",
635 "description": "API authentication token",
636 "sensitive": true
637 }
638 }
639}
640```
641
642키는 유효한 식별자여야 합니다. 각 옵션은 다음 필드를 지원합니다.
643
644| 필드 | 필수 | 설명 |
645| :------------ | :-- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
646| `type` | 예 | `string`, `number`, `boolean`, `directory` 또는 `file` 중 하나 |
647| `title` | 예 | 구성 대화 상자에 표시되는 레이블 |
648| `description` | 예 | 필드 아래에 표시되는 도움말 텍스트 |
649| `sensitive` | 아니오 | `true`인 경우 입력을 마스크하고 `settings.json` 대신 보안 저장소에 값을 저장합니다 |
650| `required` | 아니오 | `true`인 경우 필드가 비어 있을 때 검증이 실패합니다 |
651| `default` | 아니오 | 사용자가 아무것도 제공하지 않을 때 사용되는 값 |
652| `options` | 아니오 | `string` 유형의 경우 필드가 허용하는 값입니다. `/config`에서 선택기로 표시됩니다. [필드를 고정 옵션으로 제한](#limit-a-field-to-fixed-options)을 참조합니다. Claude Code v2.1.271 이상이 필요합니다 |
653| `multiple` | 아니오 | `string` 유형의 경우 문자열 배열을 허용합니다 |
654| `min` / `max` | 아니오 | `number` 유형의 경계 |
655
656`sensitive` 필드 및 `multiple` 목록을 제외하고 각 활성화된 플러그인의 각 필드는 `/config` 패널에 행으로도 나타납니다. 행에는 Claude Code v2.1.269 이상이 필요합니다.
657
658각 값은 MCP 및 LSP 서버 구성과 훅 명령에서 `${user_config.KEY}`로 대체할 수 있습니다. 민감하지 않은 값은 스킬 및 에이전트 콘텐츠에서도 대체할 수 있습니다. 모든 값은 훅 프로세스로 `CLAUDE_PLUGIN_OPTION_<KEY>` 환경 변수로 내보내집니다. 여기서 `<KEY>`는 대문자로 된 옵션 키입니다.
659
660셸에서 실행되는 필드는 `${user_config.*}`를 거부합니다. 구성된 값을 셸 명령에 대체하면 셸이 해당 값이 포함하는 모든 것을 실행할 수 있으므로 구성 요소는 [오류](/docs/ko/errors#plugin-command-references-user-config)로 실패합니다. 각 거부된 필드에는 값을 전달하는 대체 방법이 있습니다.
661
662| 거부된 필드 | 값을 전달하는 방법 |
663| :--------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- |
664| 셸 형식 훅 명령 | [exec 형식](/docs/ko/hooks#exec-form-and-shell-form)을 `args`와 함께 사용하거나 훅의 환경에서 `CLAUDE_PLUGIN_OPTION_<KEY>`를 읽습니다 |
665| [Monitor](#monitors) 명령 | 스크립트의 구성 파일에서 값을 읽습니다 |
666| MCP [`headersHelper`](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication) | 스크립트의 구성 파일에서 값을 읽습니다 |
667
668v2.1.207 이전에는 이러한 필드가 `${user_config.KEY}` 값을 대체했습니다. 이에 의존하는 플러그인을 업데이트합니다.
669
670민감하지 않은 값은 사용자 `settings.json`의 [`pluginConfigs`](/docs/ko/settings-reference#pluginconfigs) 키 아래 `pluginConfigs[<plugin-id>].options`로 저장됩니다.
671
672macOS에서 Claude Code는 민감한 값을 macOS Keychain에 저장하고 Keychain이 쓰기를 거부할 때 `~/.claude/.credentials.json`으로 폴백합니다. 지원되는 키체인이 없는 플랫폼에서는 `~/.claude/.credentials.json`에 저장합니다. 키체인 저장소는 OAuth 토큰과 공유되며 약 2 KB의 총 제한이 있으므로 민감한 값을 작게 유지합니다.
673
674Claude Code는 세 가지 설정 소스에서만 모든 `pluginConfigs` 값을 읽습니다.
675
676* **사용자 설정**: `~/.claude/settings.json`, 활성화 시간 프롬프트가 작성하는 파일
677* **`--settings`**: CLI 플래그 또는 SDK 인라인 설정
678* **관리되는 설정**: [조직 제어 정책](/docs/ko/permissions#managed-settings)
679
680둘 이상의 소스가 동일한 키를 설정할 때 관리되는 설정이 가장 우선하고, 그다음 `--settings`, 그다음 사용자 설정 순입니다. 이 목록에서 제거할 수 있는 유일한 소스는 사용자 설정입니다. `user` 없이 [`--setting-sources`](/docs/ko/cli-reference#cli-flags)를 전달하면 Claude Code는 이를 건너뜁니다. 관리되는 설정과 `--settings`는 무엇을 전달하든 그대로 유지됩니다. SDK의 [`settingSources`](/docs/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control) 옵션은 동일한 목록을 설정합니다.
681
682프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`의 항목은 무시됩니다. 두 파일 모두 작업 공간에 있으므로 복제된 저장소가 거기에 값을 제공할 수 있으며 이러한 값은 플러그인 훅 명령, MCP 서버 구성, LSP 명령 및 모니터 명령으로 흐릅니다. v2.1.207 이전에는 이러한 항목이 읽혔습니다. 제한은 `pluginConfigs`에만 해당됩니다. [`enabledPlugins`](/docs/ko/settings-reference#enabledplugins)는 여전히 프로젝트 및 로컬 설정을 준수합니다.
683
684<h4 id="limit-a-field-to-fixed-options">
685 필드를 고정 옵션으로 제한
686</h4>
687
688`userConfig` 필드에 `options`를 설정하여 사용자가 고정 목록에서 값을 선택하도록 합니다.
689
690`tone` 필드를 세 가지 옵션으로 제한하려면 `options`에 나열하고 `default`를 그 중 하나로 설정합니다.
691
692```json theme={null}
693{
694 "userConfig": {
695 "tone": {
696 "type": "string",
697 "title": "Tone",
698 "description": "Voice for generated replies",
699 "options": ["neutral", "warm", "formal"],
700 "default": "neutral"
701 }
702 }
703}
704```
705
706모든 필드에 `options`를 선언하면 Claude Code v2.1.271 이전 버전의 사용자는 플러그인을 로드할 수 없습니다.
707
708필드에 `options`를 설정할 때 다음 규칙을 따릅니다.
709
710* `type`을 `string`으로 설정합니다
711* `multiple` 또는 `sensitive`을 `true`로 설정하지 않습니다
712* `default`를 옵션 중 하나로 설정합니다
713* `default`를 설정하지 않으면 `required`를 `true`로 설정합니다
714* 최소 하나의 옵션을 나열하고 각각 1\~64자 길이입니다
715* 옵션을 공백으로 시작하거나 끝내지 않습니다
716* 옵션에서 제어 문자, 보이지 않는 문자, 텍스트 방향을 변경하는 문자 또는 일반 공백 이외의 공백을 사용하지 않습니다
717* 다른 대소문자로 된 경우에도 동일한 옵션을 두 번 나열하지 않습니다
718
719이러한 규칙 중 하나라도 위반하면 플러그인이 로드되지 않습니다. `claude plugin validate`를 실행하여 어느 필드가 어느 규칙을 위반하는지 확인합니다.
720
721<h3 id="channels">
722 채널
723</h3>
724
725`channels` 필드를 사용하면 플러그인이 하나 이상의 메시지 채널을 선언하여 대화에 콘텐츠를 주입할 수 있습니다. 각 채널은 플러그인이 제공하는 MCP 서버에 바인딩됩니다.
726
727```json theme={null}
728{
729 "channels": [
730 {
731 "server": "telegram",
732 "userConfig": {
733 "bot_token": {
734 "type": "string",
735 "title": "Bot token",
736 "description": "Telegram bot token",
737 "sensitive": true
738 },
739 "owner_id": {
740 "type": "string",
741 "title": "Owner ID",
742 "description": "Your Telegram user ID"
743 }
744 }
745 }
746 ]
747}
748```
749
750`server` 필드는 필수이며 플러그인의 `mcpServers`의 키와 일치해야 합니다. 선택적 채널별 `userConfig`는 최상위 필드와 동일한 스키마를 사용하여 플러그인이 플러그인이 활성화될 때 봇 토큰 또는 소유자 ID를 프롬프트할 수 있습니다.
751
752<h3 id="path-behavior-rules">
753 경로 동작 규칙
754</h3>
755
756사용자 정의 경로가 플러그인의 기본 디렉터리를 대체하는지 확장하는지는 필드에 따라 다릅니다.
757
758* **기본값 대체**: `commands`, `agents`, `workflows`, `outputStyles`, `experimental.themes`, `experimental.monitors`. 예를 들어 매니페스트가 `commands`를 지정할 때 기본 `commands/` 디렉터리는 스캔되지 않습니다. 기본값을 유지하고 더 추가하려면 명시적으로 나열합니다. `"commands": ["./commands/", "./extras/"]`
759* **기본값에 추가**: `skills`. 기본 `skills/` 디렉터리는 항상 스캔되고 `skills`에 나열된 디렉터리는 함께 로드됩니다. 예외: [소스가 마켓플레이스 루트로 확인되는 마켓플레이스 항목](/docs/ko/plugin-marketplaces#advanced-plugin-entries)의 경우 특정 하위 디렉터리를 선언하면 기본 `skills/` 스캔을 대체합니다
760* **자신의 병합 규칙**: [훅](#hooks), [MCP 서버](#mcp-servers) 및 [LSP 서버](#lsp-servers). 여러 소스가 결합되는 방식에 대해 각 섹션을 참조합니다
761
762플러그인에 기본 폴더와 일치하는 매니페스트 키가 모두 있을 때 Claude Code는 `claude plugin list` 및 `/plugin` 세부 정보 보기에서 무시된 폴더에 대해 경고합니다. 플러그인은 여전히 매니페스트 경로를 사용하여 로드됩니다. Claude Code는 매니페스트 키가 기본 폴더를 가리킬 때 경고하지 않습니다. 예를 들어 `"commands": ["./commands/deploy.md"]`는 폴더를 명시적으로 이름 지정하기 때문입니다.
763
764모든 경로 필드의 경우:
765
766* 모든 경로는 플러그인 루트에 상대적이어야 하고 `./`로 시작해야 합니다. 단, `skills` 필드는 `"."`도 허용합니다
767 * `"."`과 `"./"`는 모두 플러그인 루트 자체를 나타냅니다
768 * v2.1.221 이전에는 `"."`이 매니페스트 검증에 실패했고 플러그인이 로드되지 않았으므로 이전 버전을 지원하려면 `"./"`를 사용합니다
769* 사용자 정의 경로의 구성 요소는 동일한 명명 및 네임스페이싱 규칙을 사용합니다. 에이전트 파일은 제외됩니다. [에이전트](#agents)를 참조하여 에이전트 이름이 어떻게 작동하는지 알아봅니다
770* 여러 경로를 배열로 지정할 수 있습니다
771* 스킬 경로는 `SKILL.md`를 직접 포함하는 디렉터리를 가리킬 수 있습니다. 예를 들어 플러그인 루트의 경우 `"skills": ["."]`
772 * Claude Code는 `SKILL.md`의 프론트매터 `name` 필드에서 스킬의 호출 이름을 가져오므로 설치 디렉터리의 이름이 무엇이든 이름은 안정적으로 유지됩니다
773 * 프론트매터에 `name`이 설정되지 않으면 Claude Code는 디렉터리 기본 이름으로 폴백합니다
774
775루트에 `SKILL.md`가 있고 `skills/` 하위 디렉터리가 없으며 `skills` 매니페스트 필드가 없는 플러그인은 자동으로 단일 스킬 플러그인으로 로드됩니다. 이 레이아웃에 대해 `plugin.json`에서 `"skills": ["./"]`를 설정할 필요가 없습니다.
776
777**경로 예시**:
778
779```json theme={null}
780{
781 "commands": [
782 "./specialized/deploy.md",
783 "./utilities/batch-process.md"
784 ],
785 "agents": [
786 "./custom-agents/reviewer.md",
787 "./custom-agents/tester.md"
788 ]
789}
790```
791
792<h3 id="environment-variables">
793 환경 변수
794</h3>
795
796Claude Code는 경로를 참조하기 위한 세 가지 변수를 제공합니다.
797
798| 변수 | 확인 대상 | 사용 목적 |
799| :---------------------- | :----------------------------------------------------------------- | :------------------------------------------------------ |
800| `${CLAUDE_PLUGIN_ROOT}` | 플러그인의 설치 디렉터리의 절대 경로 | 플러그인과 함께 번들된 스크립트, 바이너리 및 구성 파일 |
801| `${CLAUDE_PLUGIN_DATA}` | 플러그인 업데이트를 유지하고 첫 참조 시 생성되는 [지속적 디렉터리](#persistent-data-directory) | `node_modules` 또는 Python 가상 환경과 같은 설치된 종속성, 생성된 코드 및 캐시 |
802| `${CLAUDE_PROJECT_DIR}` | 프로젝트 루트 | 프로젝트 로컬 스크립트 및 구성 파일 |
803
804세 가지 모두 훅 프로세스 및 MCP 및 LSP 서버 하위 프로세스로 환경 변수로 내보내집니다. 어느 필드가 인라인으로 대체하는지는 플러그인 구성 요소에 따라 다릅니다.
805
806| 플러그인 구성 요소 | 자리 표시자가 확인되는 필드 |
807| :------------------------- | :------------------------------------------ |
808| 스킬 및 에이전트 콘텐츠 | 자리 표시자가 나타나는 모든 곳 |
809| 훅 및 모니터 명령 | 자리 표시자가 나타나는 모든 곳 |
810| MCP `stdio` 서버 | `command`, `args`, `env` |
811| MCP `http`, `sse`, `ws` 서버 | `url`, `headers`, `headersHelper` |
812| LSP 서버 | `command`, `args`, `env`, `workspaceFolder` |
813
814훅 명령에서 [exec 형식](/docs/ko/hooks#exec-form-and-shell-form)을 `args`와 함께 사용하여 각 경로가 따옴표 없이 하나의 인수로 전달되도록 합니다. 셸 형식 훅 및 모니터 명령에서 변수를 큰따옴표로 래핑합니다. 예: `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`. 이 셸 형식 훅은 플러그인과 함께 번들된 스크립트를 실행합니다.
815
816```json theme={null}
817{
818 "hooks": {
819 "PostToolUse": [
820 {
821 "hooks": [
822 {
823 "type": "command",
824 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"
825 }
826 ]
827 }
828 ]
829 }
830}
831```
832
833`${CLAUDE_PLUGIN_ROOT}`는 플러그인이 업데이트될 때 변경됩니다. 이전 버전의 디렉터리는 업데이트 후 일정 기간 동안 디스크에 남아 있지만 이를 임시로 취급하고 거기에 상태를 작성하지 마십시오. 정리 의미론에 대해 [플러그인 캐싱](#plugin-caching-and-file-resolution)을 참조합니다.
834
835플러그인이 세션 중간에 업데이트될 때 훅 명령, 모니터, MCP 서버 및 LSP 서버는 이전 버전의 경로를 계속 사용합니다. `/reload-plugins`를 실행하여 훅, MCP 서버 및 LSP 서버를 새 경로로 전환합니다. 모니터는 세션 재시작이 필요합니다. 대화형 터미널이 없는 세션에서 다시 로드는 플러그인 MCP 서버를 다음 세션까지 이전 경로에 남겨 둡니다.
836
837`command` 소스가 있는 플러그인의 경우 Claude Code는 [플러그인 자체를 다시 로드할 수 있습니다](/docs/ko/plugin-marketplaces#when-claude-code-re-runs-the-command).
838
839MCP 서버는 또한 `roots/list` 요청을 호출하여 런타임에 세션의 작업 디렉터리를 읽을 수 있습니다. [`roots/list`가 반환하는 것과 Claude Code가 서버에 변경을 알리는 시기](/docs/ko/mcp#option-3-add-a-local-stdio-server)를 참조합니다.
840
841<h4 id="persistent-data-directory">
842 지속적 데이터 디렉터리
843</h4>
844
845`${CLAUDE_PLUGIN_DATA}` 디렉터리는 `~/.claude/plugins/data/{id}/`로 확인됩니다. 여기서 `{id}`는 `a-z`, `A-Z`, `0-9`, `_` 및 `-` 외부의 문자가 `-`로 대체된 플러그인 식별자입니다. `formatter@my-marketplace`로 설치된 플러그인의 경우 디렉터리는 `~/.claude/plugins/data/formatter-my-marketplace/`입니다.
846
847일반적인 사용은 언어 종속성을 한 번 설치하고 세션 및 플러그인 업데이트 전체에서 재사용하는 것입니다. Python 종속성, Yarn 또는 pnpm으로 잠긴 종속성 및 수명 주기 스크립트를 실행해야 하는 패키지에 이를 사용합니다. 마켓플레이스 설치 플러그인의 경우 전혀 필요하지 않을 수 있습니다. Claude Code는 플러그인을 캐시할 때 적격 [Node.js 패키지 종속성](#node-js-package-dependencies)을 자동으로 설치합니다.
848
849데이터 디렉터리는 단일 플러그인 버전보다 오래 지속되므로 디렉터리 존재 여부만으로는 업데이트가 플러그인의 종속성 매니페스트를 변경하는 시기를 감지할 수 없습니다. 권장 패턴은 번들된 매니페스트를 데이터 디렉터리의 복사본과 비교하고 다를 때 재설치합니다.
850
851이 `SessionStart` 훅은 첫 실행 시 `node_modules`를 설치하고 플러그인 업데이트가 변경된 `package.json`을 포함할 때마다 다시 설치합니다.
852
853```json theme={null}
854{
855 "hooks": {
856 "SessionStart": [
857 {
858 "hooks": [
859 {
860 "type": "command",
861 "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\""
862 }
863 ]
864 }
865 ]
866 }
867}
868```
869
870`diff`는 저장된 복사본이 누락되거나 번들된 복사본과 다를 때 0이 아닌 값으로 종료되어 첫 실행과 종속성 변경 업데이트를 모두 다룹니다. `npm install`이 실패하면 후행 `rm`은 복사된 매니페스트를 제거하여 다음 세션이 재시도합니다.
871
872`${CLAUDE_PLUGIN_ROOT}`에 번들된 스크립트는 지속된 `node_modules`에 대해 실행할 수 있습니다.
873
874```json theme={null}
875{
876 "mcpServers": {
877 "routines": {
878 "command": "node",
879 "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
880 "env": {
881 "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
882 }
883 }
884 }
885}
886```
887
888데이터 디렉터리는 마지막 범위에서 플러그인을 제거할 때 자동으로 삭제됩니다. `/plugin` 인터페이스는 디렉터리 크기를 표시하고 삭제하기 전에 프롬프트합니다. CLI는 기본적으로 삭제합니다. [`--keep-data`](#plugin-uninstall)를 전달하여 보존합니다.
889
890***
891
892<h2 id="plugin-caching-and-file-resolution">
893 플러그인 캐싱 및 파일 해석
894</h2>
895
896플러그인은 다음 세 가지 방법 중 하나로 지정됩니다:
897
898* `claude --plugin-dir` 또는 `claude --plugin-url`을 통해 세션 기간 동안 지정합니다.
899* 마켓플레이스를 통해 설치하여 향후 세션에서 사용합니다.
900* claude.ai 계정을 통해 `~/.claude/plugins/synced/`로 [동기화](#synced-plugins)됩니다.
901
902보안 및 검증 목적으로 Claude Code는 마켓플레이스 플러그인을 사용자의 로컬 **플러그인 캐시**(`~/.claude/plugins/cache`)로 복사합니다. 단, 플러그인이 제자리에 로드되는 경우는 예외입니다. [링크 모드의 `command` 소스](/docs/ko/plugin-marketplaces#copy-mode-and-link-mode)는 캐시 항목의 링크를 통해 제자리에 로드됩니다. 로컬 디렉토리에서 추가된 마켓플레이스의 [상대 경로 소스](/docs/ko/plugin-marketplaces#relative-paths)는 마켓플레이스 폴더에서 제자리에 로드됩니다.
903
904로컬 디렉토리 마켓플레이스에서 제자리에 로드된 플러그인의 경우, 소스 디렉토리에 대한 편집 사항은 다음 세션 시작 또는 `/reload-plugins`에서 적용됩니다. 버전 범프가 필요하지 않습니다. 플러그인의 hook 프로세스와 MCP 및 LSP 서버는 소스 디렉토리를 가리키는 `CLAUDE_PLUGIN_ROOT`를 받습니다. Claude Code는 플러그인의 [Node.js 패키지 종속성](#node-js-package-dependencies)을 소스 디렉토리에 설치하지 않습니다. 이를 직접 설치하거나 [영구 데이터 디렉토리](#persistent-data-directory)의 hook에서 설치하세요.
905
906복사된 플러그인의 경우, 설치된 각 버전은 캐시의 별도 디렉토리이며, 마켓플레이스 및 플러그인별로 그룹화되고 해석된 버전으로 명명되며, 플러그인의 파일과 [Node.js 패키지 종속성](#node-js-package-dependencies)의 자체 복사본을 포함합니다. [릴리스 태그](/docs/ko/plugin-dependencies#tag-plugin-releases-for-version-resolution)에서 해석된 종속성은 커밋-SHA 접미사가 있는 디렉토리 이름을 가집니다.
907
908플러그인을 업데이트하거나 제거할 때 Claude Code는 이전 버전 디렉토리를 고아 상태로 표시하고 대략 14일 후 백그라운드 스윕에서 제거합니다. 유예 기간을 통해 이미 이전 버전을 로드한 동시 Claude Code 세션이 오류 없이 계속 실행될 수 있습니다. Claude Code는 최소한 하나의 플러그인이 설치되어 있는 동안에만 스윕을 실행합니다. 마지막 플러그인을 제거한 후 고아 디렉토리는 플러그인을 다시 설치할 때까지 디스크에 남아 있습니다.
909
910Claude Code는 더 이상 디렉토리나 심볼릭 링크를 포함하지 않는 경우에만 캐시에서 플러그인 또는 마켓플레이스 폴더를 제거합니다. 개발 체크아웃을 캐시에 플러그인의 버전 항목으로 심볼릭 링크하면 Claude Code는 링크를 고아 상태로 표시하지 않으며 링크나 이를 포함하는 폴더를 제거하지 않습니다. Claude Code는 또한 링크된 체크아웃 내부에 버전 추적 파일을 작성하지 않습니다.
911
912Claude의 Glob 및 Grep 도구는 검색 중에 고아 버전 디렉토리를 건너뛰므로 파일 결과에는 오래된 플러그인 코드가 포함되지 않습니다.
913
914<h3 id="node-js-package-dependencies">
915 Node.js 패키지 종속성
916</h3>
917
918Claude Code가 플러그인을 캐시로 복사할 때 플러그인의 Node.js 패키지 종속성도 여기에 설치하므로 플러그인의 hooks 및 MCP 서버가 이를 로드할 수 있습니다. 이 섹션은 플러그인이 자체 `package.json`에서 선언하는 npm 및 Bun 패키지를 다룹니다. 다른 플러그인에 종속된 플러그인의 경우 [플러그인 종속성 버전](/docs/ko/plugin-dependencies)을 참조하세요.
919
920Claude Code는 복사된 버전 디렉토리 내에서 설치를 실행합니다. 플러그인을 설치할 때, Claude Code가 플러그인을 새 버전으로 업데이트할 때, 그리고 새 머신에서와 같이 활성화된 플러그인이 아직 캐시되지 않은 경우 세션 시작 시에 실행됩니다. 설치는 플러그인의 루트 디렉토리에 `package.json`과 지원되는 lockfile이 모두 포함된 경우에만 실행됩니다:
921
922| Lockfile | 명령 |
923| :------------------------------------------- | :----------------------------------------------- |
924| `bun.lock` 또는 `bun.lockb` | `bun install --frozen-lockfile --ignore-scripts` |
925| `npm-shrinkwrap.json` 또는 `package-lock.json` | `npm ci --ignore-scripts` |
926
927플러그인에 이러한 lockfile 중 두 개 이상이 포함된 경우 Claude Code는 첫 번째 일치를 사용하며, 다음 순서로 확인합니다: `bun.lock`, `bun.lockb`, `npm-shrinkwrap.json`, `package-lock.json`.
928
929Claude Code는 두 가지 경우에 설치를 건너뜁니다. 각각 자체 해결 방법이 있습니다:
930
931* 플러그인이 `yarn.lock` 또는 `pnpm-lock.yaml`만 제공하는 경우 npm lockfile로 바꾸세요.
932* bun lockfile 옆에 `bunfig.toml`이 있는 경우 `bunfig.toml`을 제거하거나 bun lockfile을 npm lockfile로 바꾸세요.
933
934가장 광범위한 도달을 위해 npm lockfile을 제공하세요. Claude Code는 사용자의 PATH에서 일치하는 lockfile의 패키지 관리자를 실행하며 lockfile이 누락된 경우 다른 lockfile로 폴백하지 않습니다. npm 소스를 통해 배포된 플러그인의 경우 `npm-shrinkwrap.json`을 사용하세요. npm은 게시된 패키지에서 `package-lock.json`을 제외합니다.
935
936Claude Code는 이 종속성 설치를 제한하여 설치 중에 플러그인 또는 해당 패키지의 코드가 실행되지 않도록 하고 실행 시간을 제한합니다:
937
938* **고정된 해석:** Bun 및 npm은 lockfile이 고정한 것을 정확히 설치하며, `package.json`과 lockfile이 불일치할 때 버전을 다시 해석하는 대신 실패합니다.
939* **라이프사이클 스크립트 없음:** `--ignore-scripts`는 `preinstall`, `install`, 및 `postinstall` 스크립트가 실행되지 않도록 하므로 이러한 스크립트에서 네이티브 모듈을 빌드하는 종속성은 다운로드되지만 이 설치 중에는 컴파일되지 않습니다.
940* **60초 타임아웃:** Claude Code는 더 오래 실행되는 설치를 중지하고 실패로 처리합니다.
941
942Claude Code는 이 종속성 설치 전에 npm 소스 플러그인을 가져오며, 패키지의 자체 설치 스크립트는 가져오기 중에 실행되지 않습니다. [npm 패키지](/docs/ko/plugin-marketplaces#npm-packages)를 참조하세요.
943
944실패하거나 건너뛴 설치는 플러그인을 차단하지 않습니다. 설치가 실패하거나 Claude Code가 yarn 또는 pnpm lockfile을 건너뛸 때 또는 `bunfig.toml`이 있는 경우 이유를 [디버그 출력](#debugging-commands)에 경고로 기록합니다. `package.json`이 있고 lockfile이 없는 플러그인은 로그 항목 없이 건너뜁니다. 시간 초과된 설치는 캐시된 복사본에 부분적인 `node_modules` 트리를 남길 수 있습니다.
945
946자동 설치를 끌 수 없습니다. 설정이나 환경 변수로 비활성화할 수 없습니다. 제한된 네트워크에서는 [네트워크 액세스 요구 사항](/docs/ko/network-config#network-access-requirements)을 참조하여 허용할 호스트를 확인하세요.
947
948자동 설치가 제공할 수 없는 종속성(예: 라이프사이클 스크립트를 빌드해야 하는 패키지, Python 종속성, 또는 Yarn 또는 pnpm으로 잠긴 플러그인)의 경우 [영구 데이터 디렉토리](#persistent-data-directory)의 hook에서 설치하세요.
949
950<h3 id="path-traversal-limitations">
951 경로 순회 제한
952</h3>
953
954Claude Code는 플러그인이 자체 디렉토리 외부의 파일을 참조하도록 허용하지 않습니다. `plugin.json`에서 선언되거나 [마켓플레이스 항목](/docs/ko/plugin-marketplaces#plugin-entries)에서 선언된 플러그인 루트 외부로 해석되는 구성 요소 경로를 거부합니다. 여기에는 `../shared-utils`와 같이 작성된 플러그인 외부를 가리키는 경로와 [마켓플레이스 내 링크](#share-files-within-a-marketplace-with-symlinks)를 제외한 플러그인 외부로 이어지는 심볼릭 링크가 포함됩니다.
955
956macOS 및 Linux에서 Claude Code는 경로가 플러그인 내부에 남아 있더라도 경로의 어디든 백슬래시를 포함하는 구성 요소 경로도 거부합니다. 백슬래시 경로로 선언된 구성 요소는 따라서 Windows에서만 로드됩니다. `./commands/deploy.md`와 같이 정방향 슬래시를 사용하여 구성 요소 경로를 작성하세요.
957
958Claude Code가 경로를 거부하면 [`path escapes plugin directory`](/docs/ko/errors#path-escapes-plugin-directory) 오류를 보고하고 해당 구성 요소 없이 플러그인을 로드합니다.
959
960Claude Code는 플러그인을 설치할 때 플러그인 디렉토리 외부의 파일을 캐시로 복사하지 않으므로 복사된 플러그인 내부의 스크립트가 플러그인 루트 위의 경로를 읽을 때 해당 파일을 찾지 못합니다.
961
962<h3 id="share-files-within-a-marketplace-with-symlinks">
963 심볼릭 링크를 사용하여 마켓플레이스 내에서 파일 공유
964</h3>
965
966플러그인이 동일한 마켓플레이스의 다른 부분과 파일을 공유해야 하는 경우 플러그인 디렉토리 내에 심볼릭 링크를 만들 수 있습니다. 플러그인이 캐시로 복사될 때 심볼릭 링크가 처리되는 방식은 해당 대상이 해석되는 위치에 따라 달라집니다:
967
968* **플러그인의 자체 디렉토리 내:** 심볼릭 링크는 캐시에서 상대 심볼릭 링크로 유지되므로 런타임에 복사된 대상으로 계속 해석됩니다.
969* **동일한 마켓플레이스 내의 다른 곳:** 심볼릭 링크는 역참조됩니다. 대상의 콘텐츠는 그 자리에 캐시로 복사됩니다. 이를 통해 메타 플러그인의 `skills/` 디렉토리가 마켓플레이스의 다른 플러그인에서 정의한 skills에 링크할 수 있습니다.
970* **마켓플레이스 외부:** 심볼릭 링크는 보안상 건너뜁니다. 이는 플러그인이 시스템 경로와 같은 임의의 호스트 파일을 캐시로 가져오는 것을 방지합니다.
971
972`--plugin-dir`으로 설치된 플러그인, 로컬 경로에서 설치된 플러그인, 또는 [복사 모드의 `command` 소스](/docs/ko/plugin-marketplaces#copy-mode-and-link-mode)에서 설치된 플러그인의 경우 플러그인의 자체 디렉토리 내에서 해석되는 심볼릭 링크만 유지됩니다. 다른 모든 링크는 건너뜁니다.
973
974다음 명령은 마켓플레이스 플러그인 내부에서 형제 플러그인에서 정의한 공유 skill로의 링크를 만듭니다. Windows에서는 상승된 명령 프롬프트에서 `mklink /D`를 사용하거나 개발자 모드를 활성화하세요:
975
976```bash theme={null}
977ln -s ../../shared-plugin/skills/foo ./skills/foo
978```
979
980***
981
982<h2 id="plugin-directory-structure">
983 플러그인 디렉토리 구조
984</h2>
985
986<h3 id="standard-plugin-layout">
987 표준 플러그인 레이아웃
988</h3>
989
990완전한 플러그인은 다음과 같은 구조를 따릅니다:
991
992```text theme={null}
993enterprise-plugin/
994├── .claude-plugin/ # 메타데이터 디렉토리 (선택사항)
995│ └── plugin.json # 플러그인 매니페스트
996├── skills/ # Skills
997│ ├── code-reviewer/
998│ │ └── SKILL.md
999│ └── pdf-processor/
1000│ ├── SKILL.md
1001│ └── scripts/
1002├── commands/ # Skills as flat .md files
1003│ ├── status.md
1004│ └── logs.md
1005├── agents/ # Subagent 정의
1006│ ├── security-reviewer.md
1007│ ├── performance-tester.md
1008│ ├── compliance-checker.md
1009│ └── review/ # 여기의 Agents는 enterprise-plugin:review:<name>으로 로드됩니다
1010│ └── accessibility.md
1011├── workflows/ # 워크플로우 스크립트
1012│ └── release-audit.js
1013├── output-styles/ # 출력 스타일 정의
1014│ └── terse.md
1015├── themes/ # 색상 테마 정의
1016│ └── dracula.json
1017├── monitors/ # 백그라운드 모니터 구성
1018│ └── monitors.json
1019├── hooks/ # Hook 구성
1020│ ├── hooks.json # 주요 hook 구성
1021│ └── security-hooks.json # 추가 hooks
1022├── bin/ # 플러그인 실행 파일이 PATH에 추가됨
1023│ └── my-tool # Bash 도구에서 명령어로 호출 가능
1024├── settings.json # 플러그인의 기본 설정
1025├── .mcp.json # MCP 서버 정의
1026├── .lsp.json # LSP 서버 구성
1027├── scripts/ # Hook 및 유틸리티 스크립트
1028│ ├── security-scan.sh
1029│ ├── format-code.py
1030│ └── deploy.js
1031├── LICENSE # 라이선스 파일
1032└── CHANGELOG.md # 버전 히스토리
1033```
1034
1035<Warning>
1036 `.claude-plugin/` 디렉토리에는 `plugin.json` 파일이 포함됩니다. 다른 모든 디렉토리(commands/, agents/, skills/, workflows/, output-styles/, themes/, monitors/, hooks/)는 `.claude-plugin/` 내부가 아닌 플러그인 루트에 있어야 합니다.
1037</Warning>
1038
1039플러그인 루트의 `CLAUDE.md` 파일은 프로젝트 컨텍스트로 로드되지 않습니다. 플러그인은 CLAUDE.md가 아닌 skills, agents, hooks를 통해 컨텍스트를 제공합니다. Claude의 컨텍스트에 로드되는 지침을 제공하려면 [skill](#skills)에 배치하십시오.
1040
1041<h3 id="file-locations-reference">
1042 파일 위치 참조
1043</h3>
1044
1045| 구성 요소 | 기본 위치 | 목적 |
1046| :------------ | :--------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1047| **매니페스트** | `.claude-plugin/plugin.json` | 플러그인 메타데이터 및 구성 (선택사항) |
1048| **Skills** | `skills/` | `<name>/SKILL.md` 구조의 Skills |
1049| **Commands** | `commands/` | Markdown 파일로서의 Skills. 새 플러그인의 경우 `skills/` 사용 |
1050| **Agents** | `agents/` | Subagent Markdown 파일. 하위 폴더는 [agent 이름](#agents)의 일부입니다 |
1051| **Workflows** | `workflows/` | [Workflow](/docs/ko/workflows) 스크립트 파일 |
1052| **출력 스타일** | `output-styles/` | 출력 스타일 정의 |
1053| **테마** | `themes/` | 색상 테마 정의 |
1054| **Hooks** | `hooks/hooks.json` | Hook 구성 |
1055| **MCP 서버** | `.mcp.json` | MCP 서버 정의 |
1056| **LSP 서버** | `.lsp.json` | 언어 서버 구성 |
1057| **모니터** | `monitors/monitors.json` | 백그라운드 모니터 구성 |
1058| **실행 파일** | `bin/` | Bash 도구의 `PATH`에 추가되고 플러그인이 활성화된 동안 명령어로 호출 가능한 실행 파일. [Claude.ai 조직 설정을 통해 배포하는 플러그인에는 이 디렉토리를 포함할 수 없습니다](/docs/ko/plugin-marketplaces#keep-executables-out-of-the-top-level-bin-directory) |
1059| **설정** | `settings.json` | 플러그인이 활성화될 때 적용되는 기본 구성. [`agent`](/docs/ko/sub-agents) 및 [`subagentStatusLine`](/docs/ko/statusline#subagent-status-lines) 키만 지원됩니다 |
1060
1061***
1062
1063<h2 id="cli-commands-reference">
1064 CLI 명령어 참조
1065</h2>
1066
1067Claude Code는 비대화형 플러그인 관리를 위한 CLI 명령어를 제공하며, 스크립팅 및 자동화에 유용합니다.
1068
1069<h3 id="plugin-init">
1070 plugin init
1071</h3>
1072
1073`~/.claude/skills/<name>/`에 새 플러그인을 스캐폴드합니다. 다음 Claude Code 세션에서 `<name>@skills-dir`로 자동으로 로드되며 `/plugin` 및 `claude plugin list`에 설치 단계 없이 나타납니다.
1074
1075[Skills-directory plugins](#skills-directory-plugins)에서 범위 및 신뢰 요구사항을 참조하십시오.
1076
1077```bash theme={null}
1078claude plugin init <name> [options]
1079```
1080
1081명령어는 다음 인수를 사용합니다:
1082
1083* `<name>`: 플러그인 이름입니다. 스킬 네임스페이스 및 `~/.claude/skills/` 아래의 디렉터리 이름이 되므로 공백이나 경로 구분자를 포함할 수 없습니다.
1084
1085명령어는 다음 옵션을 허용합니다:
1086
1087| 옵션 | 설명 | 기본값 |
1088| :----------------------- | :-------------------------------------------------------------------------------------------- | :---------------------- |
1089| `--description <text>` | 매니페스트 설명 | |
1090| `--author <name>` | 작성자 이름 | `git config user.name` |
1091| `--author-email <email>` | 작성자 이메일 | `git config user.email` |
1092| `--with <components...>` | 컴포넌트 폴더도 스캐폴드합니다. 유효한 값: `skills`, `agents`, `hooks`, `mcp`, `lsp`, `output-style`, `channel` | |
1093| `-f, --force` | 대상의 기존 `.claude-plugin/`을 덮어씁니다 | |
1094| `-h, --help` | 명령어에 대한 도움말을 표시합니다 | |
1095
1096`claude plugin new`는 이 명령어의 별칭입니다.
1097
1098각 `--with` 값은 해당 컴포넌트에 대한 스타터 파일을 추가하며, 편집할 준비가 되어 있습니다:
1099
1100| 컴포넌트 | 스캐폴드되는 항목 |
1101| :------------- | :-------------------------------------------------------------------------------------- |
1102| `skills` | 기본 스킬과 함께 추가 네임스페이스 `<name>:example` 스킬 |
1103| `agents` | `agents/` 서브에이전트 정의 |
1104| `hooks` | 샘플 이벤트 핸들러가 포함된 `hooks/hooks.json` |
1105| `mcp` | HTTP 및 stdio 서버 예제가 포함된 `.mcp.json` |
1106| `lsp` | `.lsp.json` 언어 서버 예제 |
1107| `output-style` | 플러그인이 활성화된 동안 자동으로 적용되는 `output-styles/<name>.md` |
1108| `channel` | MCP 기반 [channel](/docs/ko/channels): stdio 서버(`server.ts`), 해당 `.mcp.json`, 및 `package.json` |
1109
1110스캐폴드된 플러그인은 마켓플레이스가 아닌 `@skills-dir` 소스를 사용합니다. 관리자는 `strictKnownMarketplaces`를 사용하거나 [관리 설정](/docs/ko/plugin-marketplaces#managed-marketplace-restrictions)의 `blockedMarketplaces`에 `{"source": "skills-dir"}`을 추가하여 이 소스를 차단할 수 있습니다. 차단되면 `plugin init`은 작성하기 전에 실패합니다.
1111
1112다음 예제는 일반적인 호출을 보여줍니다:
1113
1114```bash theme={null}
1115# 최소 플러그인 스캐폴드
1116claude plugin init my-helper
1117
1118# 스킬 및 훅 폴더를 포함하여 스캐폴드
1119claude plugin init my-helper --with skills hooks
1120
1121# 기존 스캐폴드 덮어쓰기
1122claude plugin init my-helper --force
1123```
1124
1125<h3 id="plugin-install">
1126 plugin install
1127</h3>
1128
1129사용 가능한 마켓플레이스에서 플러그인을 설치합니다.
1130
1131```bash theme={null}
1132claude plugin install <plugin> [options]
1133```
1134
1135명령어는 다음 인수를 사용합니다:
1136
1137* `<plugin>`: 플러그인 이름 또는 특정 마켓플레이스의 경우 `plugin-name@marketplace-name`
1138
1139명령어는 다음 옵션을 허용합니다:
1140
1141| 옵션 | 설명 | 기본값 |
1142| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |
1143| `-s, --scope <scope>` | 설치 범위: `user`, `project`, 또는 `local` | `user` |
1144| `--config <key=value>` | 플러그인의 매니페스트에 선언된 [`userConfig`](#user-configuration) 옵션을 설정합니다. 여러 옵션을 설정하려면 플래그를 반복합니다 | |
1145| `-y, --yes` | 확인 프롬프트 없이 플러그인의 마켓플레이스가 선언한 명령어를 수락합니다: [`command` source](/docs/ko/plugin-marketplaces#command-sources)를 사용하는 플러그인을 생성하는 명령어 또는 아카이브 다운로드를 인증하는 [`headersHelper`](/docs/ko/plugin-marketplaces#authenticate-archive-downloads). `headersHelper`를 수락하려면 Claude Code v2.1.238 이상이 필요합니다. Claude Code는 여전히 명령어를 먼저 인쇄합니다. stdin 또는 stdout이 TTY가 아닐 때 필수입니다. Claude Code 세션 내에서는 효과가 없으므로 자신의 터미널에서 명령어를 실행하십시오 | |
1146| `--accept-command <sha256>` | 이전 [`--json` 실행](#plugin-json-result)이 `shownCommand`에서 보고한 `sha256`을 가진 마켓플레이스 선언 명령어를 `-y` 대신 수락합니다. 수락은 정확히 그 명령어, 플러그인, 및 마켓플레이스 카탈로그에 대해 계산됩니다. 실행의 자체 마켓플레이스 새로고침을 포함하여 명령어가 표시된 이후 이들 중 하나라도 변경되면, Claude Code는 다이제스트를 수락하지 않고 명령어를 다시 표시합니다. `-y`와 결합할 수 없습니다. Claude Code 세션 내에서는 효과가 없으므로 자신의 터미널에서 명령어를 실행하십시오. Claude Code v2.1.271 이상 필요 | |
1147| `--json` | 스크립트에서 사용하기 위해 stdout의 마지막 줄에 하나의 JSON 객체로 결과를 인쇄합니다. [JSON 결과 형식](#plugin-json-result)을 참조하십시오. Claude Code v2.1.268 이상 필요 | |
1148| `-h, --help` | 명령어에 대한 도움말을 표시합니다 | |
1149
1150범위는 설치된 플러그인이 추가되는 설정 파일을 결정합니다. 예를 들어 `--scope project`는 .claude/settings.json의 `enabledPlugins`에 작성하여 프로젝트 저장소를 복제하는 모든 사람이 플러그인을 사용할 수 있도록 합니다.
1151
1152<span id="plugin-json-result" />`--json`을 사용하면 stdout의 마지막 줄은 하나의 JSON 객체입니다. Claude Code가 마켓플레이스가 선언한 명령어를 앞에 인쇄하기 때문에 해당 줄만 파싱하십시오. 세 개의 필드는 항상 존재합니다:
1153
1154* `command`: 실행된 서브명령어(예: `install`)
1155* `outcome`: `ok` 또는 `failed`
1156* `message`: 결과에 대한 사람이 읽을 수 있는 설명
1157
1158`pluginId`, `scope`, `failureCode`와 같은 다른 필드는 적용될 때만 나타납니다. `plugin uninstall`, `plugin update`, `plugin enable`, `plugin disable`의 `--json` 옵션은 해당 서브명령어의 자체 필드를 가진 동일한 객체를 인쇄합니다. 잘못된 `--scope`와 같은 사용 오류는 결과 줄을 인쇄하지 않고 stderr의 이유와 함께 1로 종료됩니다.
1159
1160실행이 마켓플레이스 선언 명령어를 표시하고 실행하지 않으면, `failed` 결과는 또한 표시된 명령어, 해당 명령어가 속한 플러그인, 및 명령어의 `sha256`을 포함하는 필드를 가진 `shownCommand` 객체를 포함합니다. 정확히 그 명령어를 수락하려면 그 `sha256`을 `--accept-command`로 하여 다시 실행하십시오. Claude Code v2.1.271 이상 필요합니다.
1161
1162`shownCommand.acceptCommandMatched`가 `false`이면, 전달한 다이제스트가 현재 표시된 명령어와 일치하지 않습니다. 그 명령어를 사람에게 표시한 후 해당 `sha256`을 전달하십시오.
1163
1164다음 예제는 일반적인 호출을 보여줍니다:
1165
1166```bash theme={null}
1167# 사용자 범위에 설치(기본값)
1168claude plugin install formatter@my-marketplace
1169
1170# 프로젝트 범위에 설치(팀과 공유)
1171claude plugin install formatter@my-marketplace --scope project
1172
1173# 로컬 범위에 설치(팀과 공유하지 않음)
1174claude plugin install formatter@my-marketplace --scope local
1175```
1176
1177<h3 id="plugin-uninstall">
1178 plugin uninstall
1179</h3>
1180
1181설치된 플러그인을 제거합니다.
1182
1183```bash theme={null}
1184claude plugin uninstall <plugin> [options]
1185```
1186
1187명령어는 다음 인수를 사용합니다:
1188
1189* `<plugin>`: 플러그인 이름 또는 `plugin-name@marketplace-name`
1190
1191명령어는 다음 옵션을 허용합니다:
1192
1193| 옵션 | 설명 | 기본값 |
1194| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |
1195| `-s, --scope <scope>` | 범위에서 제거: `user`, `project`, 또는 `local` | `user` |
1196| `--keep-data` | 플러그인의 [persistent data directory](#persistent-data-directory)를 보존합니다 | |
1197| `--prune` | 다른 플러그인이 필요하지 않은 자동 설치된 종속성도 제거합니다. [plugin prune](#plugin-prune) 참조 | |
1198| `-y, --yes` | `--prune` 확인 프롬프트를 건너뜁니다. stdin 또는 stdout이 TTY가 아닐 때 필수입니다 | |
1199| `--json` | stdout의 마지막 줄에 하나의 JSON 객체로 결과를 인쇄합니다. [`plugin install --json`](#plugin-json-result)과 동일한 형식입니다. `--prune`과 결합할 수 없습니다. Claude Code v2.1.268 이상 필요 | |
1200| `-h, --help` | 명령어에 대한 도움말을 표시합니다 | |
1201
1202`claude plugin remove` 및 `claude plugin rm`은 이 명령어의 별칭입니다.
1203
1204기본적으로 마지막 남은 범위에서 제거하면 플러그인의 `${CLAUDE_PLUGIN_DATA}` 디렉터리도 삭제됩니다. `--keep-data`를 사용하여 보존하십시오. 예를 들어 새 버전 테스트 후 재설치할 때입니다.
1205
1206<Note>
1207 다른 마켓플레이스의 설치된 플러그인이 이름을 공유할 때, `plugin-name@marketplace-name` 형식은 명명된 마켓플레이스의 플러그인만 제거합니다. v2.1.212 이전에는 정규화된 형식이 다른 마켓플레이스의 동일한 이름의 플러그인과 일치하여 제거할 수 있었습니다.
1208</Note>
1209
1210<h3 id="plugin-prune">
1211 plugin prune
1212</h3>
1213
1214더 이상 설치된 플러그인이 필요하지 않은 자동 설치된 플러그인 종속성을 제거합니다. Claude Code가 다른 플러그인의 [`dependencies`](/docs/ko/plugin-dependencies) 필드를 충족하기 위해 가져온 종속성이 제거됩니다. 직접 설치한 플러그인은 절대 건드리지 않습니다.
1215
1216```bash theme={null}
1217claude plugin prune [options]
1218```
1219
1220명령어는 다음 옵션을 허용합니다:
1221
1222| 옵션 | 설명 | 기본값 |
1223| :-------------------- | :----------------------------------------------- | :----- |
1224| `-s, --scope <scope>` | 범위에서 정리: `user`, `project`, 또는 `local` | `user` |
1225| `--dry-run` | 제거하지 않고 제거될 항목을 나열합니다 | |
1226| `-y, --yes` | 확인 프롬프트를 건너뜁니다. stdin 또는 stdout이 TTY가 아닐 때 필수입니다 | |
1227| `-h, --help` | 명령어에 대한 도움말을 표시합니다 | |
1228
1229`claude plugin autoremove`는 이 명령어의 별칭입니다.
1230
1231명령어는 고아 종속성을 나열하고 제거하기 전에 확인을 요청합니다. 플러그인을 제거하고 한 단계에서 종속성을 정리하려면 `claude plugin uninstall <plugin> --prune`을 실행하십시오.
1232
1233<h3 id="plugin-enable">
1234 plugin enable
1235</h3>
1236
1237비활성화된 플러그인을 활성화합니다. 대상이 마켓플레이스에서 설치되고 [dependencies](/docs/ko/plugin-dependencies)를 선언할 때, Claude Code는 동일한 범위에서 이들을 전이적으로 활성화합니다. 명령어는 [Enable or disable a plugin with dependencies](/docs/ko/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)가 나열하는 조건에서 실패합니다.
1238
1239```bash theme={null}
1240claude plugin enable <plugin> [options]
1241```
1242
1243명령어는 다음 인수를 사용합니다:
1244
1245* `<plugin>`: 플러그인 이름, `plugin-name@marketplace-name`, 또는 [synced plugin](#synced-plugins)의 경우 `plugin-name@synced`
1246
1247명령어는 다음 옵션을 허용합니다:
1248
1249| 옵션 | 설명 | 기본값 |
1250| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------- | :---- |
1251| `-s, --scope <scope>` | 활성화할 범위: `user`, `project`, 또는 `local`. 생략하면 Claude Code는 플러그인이 설치된 범위를 감지합니다 | 자동 감지 |
1252| `--json` | stdout의 마지막 줄에 하나의 JSON 객체로 결과를 인쇄합니다. [`plugin install --json`](#plugin-json-result)과 동일한 형식입니다. Claude Code v2.1.268 이상 필요 | |
1253| `-h, --help` | 명령어에 대한 도움말을 표시합니다 | |
1254
1255<h3 id="plugin-disable">
1256 plugin disable
1257</h3>
1258
1259플러그인을 제거하지 않고 비활성화합니다.
1260
1261대상이 마켓플레이스에서 설치될 때, 다른 활성화된 플러그인이 이에 [의존](/docs/ko/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)하면 명령어가 실패합니다. 오류 메시지에는 이에 의존하는 모든 플러그인을 먼저 비활성화하는 연결된 명령어가 포함됩니다.
1262
1263조직에서 필요로 하는 [synced plugin](#synced-plugins)의 경우 명령어가 실패하고 아무것도 저장하지 않습니다.
1264
1265```bash theme={null}
1266claude plugin disable [plugin] [options]
1267```
1268
1269명령어는 다음 인수를 사용합니다:
1270
1271* `[plugin]`: 플러그인 이름, `plugin-name@marketplace-name`, 또는 [synced plugin](#synced-plugins)의 경우 `plugin-name@synced`. `--all`을 사용할 때 선택 사항입니다.
1272
1273명령어는 다음 옵션을 허용합니다:
1274
1275| 옵션 | 설명 | 기본값 |
1276| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------- | :---- |
1277| `-a, --all` | 모든 활성화된 플러그인을 비활성화합니다. `--scope`와 결합할 수 없습니다 | |
1278| `-s, --scope <scope>` | 비활성화할 범위: `user`, `project`, 또는 `local`. 생략하면 Claude Code는 플러그인이 설치된 범위를 감지합니다 | 자동 감지 |
1279| `--json` | stdout의 마지막 줄에 하나의 JSON 객체로 결과를 인쇄합니다. [`plugin install --json`](#plugin-json-result)과 동일한 형식입니다. Claude Code v2.1.268 이상 필요 | |
1280| `-h, --help` | 명령어에 대한 도움말을 표시합니다 | |
1281
1282<h3 id="plugin-update">
1283 plugin update
1284</h3>
1285
1286플러그인을 최신 버전으로 업데이트합니다.
1287
1288```bash theme={null}
1289claude plugin update <plugin> [options]
1290```
1291
1292명령어는 다음 인수를 사용합니다:
1293
1294* `<plugin>`: 플러그인 이름 또는 `plugin-name@marketplace-name`
1295
1296명령어는 다음 옵션을 허용합니다:
1297
1298| 옵션 | 설명 | 기본값 |
1299| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |
1300| `-s, --scope <scope>` | 업데이트할 범위: `user`, `project`, `local`, 또는 `managed` | `user` |
1301| `-y, --yes` | 확인 프롬프트 없이 플러그인의 마켓플레이스가 선언한 명령어를 수락합니다: [`command` source](/docs/ko/plugin-marketplaces#command-sources)를 사용하는 플러그인을 생성하는 명령어 또는 아카이브 다운로드를 인증하는 [`headersHelper`](/docs/ko/plugin-marketplaces#authenticate-archive-downloads). `headersHelper`를 수락하려면 Claude Code v2.1.238 이상이 필요합니다. Claude Code는 여전히 명령어를 먼저 인쇄합니다. stdin 또는 stdout이 TTY가 아닐 때 필수입니다. Claude Code 세션 내에서는 효과가 없으므로 자신의 터미널에서 명령어를 실행하십시오 | |
1302| `--accept-command <sha256>` | 이전 [`--json` 실행](#plugin-json-result)이 `shownCommand`에서 보고한 `sha256`을 가진 마켓플레이스 선언 명령어를 `-y` 대신 수락합니다. 수락은 정확히 그 명령어, 플러그인, 및 마켓플레이스 카탈로그에 대해 계산됩니다. 실행의 자체 마켓플레이스 새로고침을 포함하여 명령어가 표시된 이후 이들 중 하나라도 변경되면, Claude Code는 다이제스트를 수락하지 않고 명령어를 다시 표시합니다. `-y`와 결합할 수 없습니다. Claude Code 세션 내에서는 효과가 없으므로 자신의 터미널에서 명령어를 실행하십시오. Claude Code v2.1.271 이상 필요 | |
1303| `--json` | stdout의 마지막 줄에 하나의 JSON 객체로 결과를 인쇄합니다. [`plugin install --json`](#plugin-json-result)과 동일한 형식입니다. Claude Code v2.1.268 이상 필요 | |
1304| `-h, --help` | 명령어에 대한 도움말을 표시합니다 | |
1305
1306<Note>
1307 Claude Code는 설치된 플러그인에 대해 베어 플러그인 이름을 확인합니다. 다른 마켓플레이스의 설치된 플러그인이 이름을 공유할 때, Claude Code는 업데이트를 거부하고 대신 실행할 정규화된 `plugin-name@marketplace-name` 명령어를 나열합니다. v2.1.246 이전에는 Claude Code가 정규화된 형식만 수락하고 베어 이름을 찾을 수 없는 것으로 거부했습니다.
1308</Note>
1309
1310***
1311
1312<h3 id="plugin-list">
1313 plugin list
1314</h3>
1315
1316설치된 플러그인을 버전, 소스 마켓플레이스 및 활성화 상태와 함께 나열합니다.
1317
1318```bash theme={null}
1319claude plugin list [options]
1320```
1321
1322명령어는 다음 옵션을 허용합니다:
1323
1324| 옵션 | 설명 | 기본값 |
1325| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-- |
1326| `--json` | JSON으로 출력합니다. 로드 문제 또는 작성 경고가 있는 플러그인 행은 `errors` 또는 `notes` 문자열 배열을 포함합니다. Claude Code v2.1.268 이상에서 병렬 `errorDetails` 및 `noteDetails` 배열은 각 항목의 진단 `type` 및 플러그인, 마켓플레이스, 서버 또는 파일과 같이 참조하는 이름을 제공합니다 | |
1327| `--available` | 마켓플레이스의 사용 가능한 플러그인을 포함합니다. `--json` 필요 | |
1328| `-h, --help` | 명령어에 대한 도움말을 표시합니다 | |
1329
1330대화형 세션 내에서 `/plugin list`는 유사한 목록을 인라인으로 인쇄하지만, 마켓플레이스 설치 플러그인만 포함합니다:
1331
1332* 스킬 디렉터리에서 로드된 플러그인은 `/plugin` 인터페이스 및 `claude plugin list`에 나타나지만 인라인 `/plugin list` 출력에는 나타나지 않습니다.
1333* [claude.ai에서 동기화된 플러그인](#synced-plugins)은 Claude Code v2.1.239 이상에서 `claude plugin list`에 나타나며 `/plugin` 인터페이스에도 나타나지만, 인라인 `/plugin list` 출력에는 나타나지 않습니다.
1334* `--plugin-dir` 또는 `--plugin-url`로 세션에 로드된 플러그인은 `/plugin` 인터페이스에 나타나며, `claude --plugin-dir <dir> plugin list`와 같이 동일한 플래그가 서브명령어 앞에 올 때만 `claude plugin list`에 나타납니다. 플래그만이 해당 위치를 지정하므로, Claude Code가 고정 디렉터리를 스캔하는 동기화된 플러그인 및 스킬 디렉터리 플러그인과 달리, 베어 `claude plugin list`는 이들을 찾을 수 없습니다.
1335
1336대화형 형식은 `--enabled` 또는 `--disabled`를 수락하여 해당 상태의 플러그인만 표시하고, `ls`를 `list`의 약자로 수락합니다.
1337
1338<h3 id="plugin-details">
1339 plugin details
1340</h3>
1341
1342플러그인의 컴포넌트 인벤토리 및 예상 토큰 비용을 표시합니다. 출력은 플러그인이 기여하는 모든 컴포넌트를 Skills, Agents, Hooks, MCP servers, 및 LSP servers로 그룹화하여 나열하며, 각 세션에 추가하는 토큰 수의 추정치를 포함합니다. Skills 그룹에는 `skills/` 및 `commands/` 항목이 모두 포함됩니다.
1343
1344```bash theme={null}
1345claude plugin details <name>
1346```
1347
1348명령어는 다음 인수를 사용합니다:
1349
1350* `<name>`: 플러그인 이름 또는 `plugin-name@marketplace-name`
1351
1352명령어는 다음 옵션을 허용합니다:
1353
1354| 옵션 | 설명 | 기본값 |
1355| :----------- | :----------------- | :-- |
1356| `-h, --help` | 명령어에 대한 도움말을 표시합니다 | |
1357
1358출력은 각 컴포넌트에 대해 두 개의 비용 수치를 표시합니다:
1359
1360* **Always-on:** 스킬 설명, 에이전트 설명, 명령어 이름과 같은 플러그인의 목록 텍스트에 의해 모든 세션에 추가되는 토큰입니다. 어떤 컴포넌트도 실행되지 않는지 여부와 관계없이 추가됩니다.
1361* **On-invoke:** 컴포넌트가 실행될 때 비용이 드는 토큰입니다. 일반적인 세션이 컴포넌트의 부분 집합만 호출하기 때문에 플러그인 전체가 아닌 컴포넌트당 표시됩니다.
1362
1363이 예제는 두 개의 스킬이 있는 플러그인의 출력 모양을 보여줍니다:
1364
1365```
1366dependency-guard 1.2.0
1367 Dependency analysis for Claude Code sessions
1368 Source: dependency-guard@example-marketplace
1369
1370Component inventory
1371 Skills (2) scan-dependencies, review-changes
1372 Agents (0)
1373 Hooks (1) SessionStart (harness-only — no model context cost)
1374 MCP servers (0)
1375 LSP servers (0)
1376
1377Projected token cost
1378 Always-on: ~180 tok added to every session
1379
1380Per-component (rounded)
1381 component always-on on-invoke
1382 scan-dependencies ~100 ~2400
1383 review-changes ~80 ~1800
1384
1385 On-invoke cost is paid each time a skill or agent fires.
1386 Token counts are estimates and may differ from actual usage.
1387```
1388
1389always-on 합계는 활성 모델에 대한 `count_tokens` API를 통해 계산됩니다. 컴포넌트별 숫자는 해당 합계에서 비례적으로 확장됩니다. API에 도달할 수 없으면 명령어는 문자 기반 추정으로 폴백합니다.
1390
1391<h3 id="plugin-validate">
1392 plugin validate
1393</h3>
1394
1395플러그인 또는 마켓플레이스를 게시하기 전에 구문 및 스키마 오류를 확인합니다.
1396
1397명령어는 유효성 검사가 통과하면 0으로, 실패하면 1로, 경로를 읽을 수 없는 경우와 같이 유효성 검사 실행 자체가 실패하면 2로 종료됩니다.
1398
1399```bash theme={null}
1400claude plugin validate <path> [options]
1401```
1402
1403명령어는 다음 인수를 사용합니다:
1404
1405* `<path>`: 플러그인 디렉터리 또는 마켓플레이스 디렉터리의 경로입니다. 플러그인 실행이 포함하는 파일에 대해서는 [Validate a plugin or a directory without a manifest](/docs/ko/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)를 참조하십시오.
1406
1407명령어는 다음 옵션을 허용합니다:
1408
1409| 옵션 | 설명 | 기본값 |
1410| :----------- | :-------------------------------------------------------------------------------------------------------- | :-- |
1411| `--strict` | 경고를 오류로 취급하고 경고에서 1로 종료합니다. CI에서 사용하여 [unrecognized fields](#unrecognized-fields)와 같이 런타임이 허용하는 문제를 포착합니다 | |
1412| `--json` | 유효성 검사 보고서를 동일한 종료 코드를 가진 하나의 JSON 객체로 출력합니다. Claude Code v2.1.259 이상 필요 | |
1413| `-h, --help` | 명령어에 대한 도움말을 표시합니다 | |
1414
1415`--json`을 사용하면 Claude Code는 보고서를 stdout에 다음 최상위 필드를 가진 하나의 JSON 객체로 작성합니다:
1416
1417* `success`: 종료 코드가 제공하는 동일한 판정
1418* `strict`: 실행이 경고를 오류로 취급했는지 여부
1419* `target`: Claude Code가 유효성을 검사한 확인된 경로
1420* `manifest`: 매니페스트 자체의 결과 또는 [run without a manifest](/docs/ko/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)의 경우 `null`
1421* `contents`: 파일별 결과, 각각 `file`을 명명하고 `errors`, `warnings`, 및 `notes` 배열을 포함합니다
1422
1423종료 2에서 명령어는 stdout에 아무것도 작성하지 않습니다. 오류 메시지는 stderr로 이동합니다.
1424
1425대화형 세션 내에서 `/plugin validate <path>`는 동일한 검사를 인라인으로 실행합니다.
1426
1427<h3 id="plugin-eval">
1428 plugin eval
1429</h3>
1430
1431플러그인의 [eval cases](/docs/ko/plugin-evals)를 실행하고 점수가 매겨진 결과를 보고합니다. Claude Code v2.1.269 이상 필요합니다. 각 경우는 프롬프트와 채점자입니다. Claude Code는 대상 플러그인만 로드된 격리된 세션에서 여러 번 실행하며, 기본적으로 플러그인 없이도 실행하므로 보고서는 차이를 보여줍니다. 경우 형식, 채점자, 결과 및 CI 사용에 대해서는 [Test plugins with evals](/docs/ko/plugin-evals)를 참조하십시오.
1432
1433```bash theme={null}
1434claude plugin eval [target] [options]
1435```
1436
1437선택적 `target`은 플러그인 디렉터리, 단일 `prompt.md` 또는 `case.yaml` 파일, `name` 또는 `name@marketplace`로 설치된 플러그인, 또는 `name@skills-dir`이며, 기본값은 현재 디렉터리입니다. `--tag`, `--allow-tools`, `--json` 앞에 배치합니다.
1438
1439이 표는 대부분의 실행이 사용하는 옵션을 나열합니다. `claude plugin eval --help`를 실행하여 `--case`, `--tag`, `--output-dir`, `--report`, `--allow-real-servers`, `--keep-temp`, `--verbose`를 포함한 전체 집합을 확인하십시오.
1440
1441| 옵션 | 설명 | 기본값 |
1442| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------- |
1443| `--runs <n>` | 팔당 경우당 실행 | 각 경우의 `runs`, 그렇지 않으면 3 |
1444| `-j, --concurrency <n>` | 동시에 실행할 에이전트 세션, 1\~8. 속도 제한을 공유합니다 | `1` |
1445| `--model <model>` | 테스트 중인 에이전트의 모델 | 각 경우의 `model`, 그렇지 않으면 `ANTHROPIC_MODEL`이 설정되면, 그렇지 않으면 Claude Code의 기본값 |
1446| `--judge-model <model>` | `llm` 및 `baseline` 채점자의 모델 | 작은 빠른 모델 |
1447| `--ablation <mode>` | `none` 또는 `with-without`. [Compare against a no-plugin baseline](/docs/ko/plugin-evals#compare-against-a-no-plugin-baseline) 참조 | 플러그인이 확인되면 `with-without`, 그렇지 않으면 `none` |
1448| `--threshold <0..1>` | 어떤 경우든 이 아래로 점수가 매겨지면 1로 종료 | `1.0` |
1449| `--max-cost-usd <usd>` | 지출이 이에 도달하면 다음 실행 전에 중지하고, 2로 종료하고, 부분 결과를 보고합니다 | 상한 없음 |
1450| `--allow-tools <tools...>` | 읽기 전용 집합 이상의 도구를 부여합니다(예: `Bash`, `Write`, `Edit`, 또는 `"mcp__plugin_<plugin>_<server>__*"`). [Grant tools](/docs/ko/plugin-evals#grant-tools) 참조 | |
1451| `--scaffold` | 각 경우의 [`scaffold_script`](/docs/ko/plugin-evals#add-setup-or-history-with-case-yaml) 실행 | 꺼짐 |
1452| `--trust-plugin` | 첫 실행 신뢰 프롬프트를 건너뜁니다(CI용). [What a run can access](/docs/ko/plugin-evals#security) 참조 | 꺼짐 |
1453| `--mocks <mode>` | `record` 또는 `off`. [Mock MCP servers](/docs/ko/plugin-evals#mock-mcp-servers) 참조 | `record` |
1454| `--eval-dir <dir>` | 경우를 보유하는 플러그인 아래의 디렉터리 | 매니페스트의 `experimental.evals`, 그렇지 않으면 `evals` |
1455| `--json [path]` | [result document](/docs/ko/plugin-evals#json-result)를 stdout으로 인쇄하거나 `.json` 경로에 작성합니다 | |
1456| `--no-publish` | HTML 보고서를 로컬로 유지합니다 | |
1457| `-h, --help` | 명령어에 대한 도움말을 표시합니다 | |
1458
1459명령어는 모든 경우가 임계값을 충족하면 0으로, 실패한 경우, 로드 오류 또는 신뢰할 수 없는 플러그인 디렉터리에서 1로, 부분 실행에서 2로, 중단되면 130으로, 종료되면 143으로 종료됩니다. [Run evals in CI](/docs/ko/plugin-evals#run-evals-in-ci)를 참조하십시오.
1460
1461<h3 id="plugin-eval-init">
1462 plugin eval init
1463</h3>
1464
1465현재 디렉터리의 플러그인에 대한 eval 스위트를 생성합니다. Claude Code v2.1.269 이상 필요합니다. 터미널에서 이것은 플러그인을 읽고, 경우와 채점자를 제안하고, 파일럿하고, 파일을 작성하는 작성 인터뷰를 시작합니다. `--bare`를 사용하거나 터미널 없이 대신 빈 단일 경우 템플릿을 작성합니다. 대화형 Claude Code 세션 내에서 실행하면 해당 세션이 따를 인터뷰 지침을 인쇄합니다. [Create your first eval suite](/docs/ko/plugin-evals#create-your-first-eval-suite)를 참조하십시오.
1466
1467```bash theme={null}
1468claude plugin eval init [name] [options]
1469```
1470
1471선택적 `name`은 경우 이름입니다: 인터뷰는 필요하지 않지만 `--bare` 및 터미널 없는 템플릿 경로는 필요합니다. 이러한 옵션을 수락합니다:
1472
1473| 옵션 | 설명 | 기본값 |
1474| :------------------ | :------------------------------------------------------------------- | :------------------------------------------- |
1475| `--bare` | `<name>`에 대해 빈 `prompt.md` 및 `graders/criteria.md`를 작성합니다(인터뷰 실행 대신) | |
1476| `-i, --interactive` | 인터뷰를 요구합니다. 템플릿을 작성하는 대신 터미널 없이 실패합니다 | |
1477| `--eval-dir <dir>` | 경우를 작성할 현재 디렉터리 아래의 디렉터리 | 매니페스트의 `experimental.evals`, 그렇지 않으면 `evals` |
1478| `-h, --help` | 명령어에 대한 도움말을 표시합니다 | |
1479
1480<h3 id="plugin-tag">
1481 plugin tag
1482</h3>
1483
1484플러그인에 대한 릴리스 git 태그를 생성합니다. 기본적으로 명령어는 현재 디렉터리의 플러그인에 태그를 지정합니다. 다른 곳의 플러그인에 태그를 지정하려면 경로를 전달합니다. [Tag plugin releases](/docs/ko/plugin-dependencies#tag-plugin-releases-for-version-resolution)를 참조하십시오.
1485
1486```bash theme={null}
1487claude plugin tag [path] [options]
1488```
1489
1490명령어는 다음 인수를 사용합니다:
1491
1492* `[path]`: 플러그인 디렉터리의 경로입니다. 기본값은 현재 디렉터리입니다.
1493
1494명령어는 다음 옵션을 허용합니다:
1495
1496| 옵션 | 설명 | 기본값 |
1497| :-------------------- | :------------------------------------ | :------- |
1498| `--push` | 태그를 생성한 후 원격으로 푸시합니다 | |
1499| `--dry-run` | 태그를 생성하지 않고 태그될 항목을 인쇄합니다 | |
1500| `-f, --force` | 작업 트리가 더티하거나 태그가 이미 존재하더라도 태그를 생성합니다 | |
1501| `-m, --message <msg>` | 태그 주석 메시지입니다. 버전의 자리 표시자로 `%s`를 사용합니다 | |
1502| `--remote <name>` | `--push`로 푸시할 원격입니다 | `origin` |
1503| `-h, --help` | 명령어에 대한 도움말을 표시합니다 | |
1504
1505***
1506
1507<h2 id="debugging-and-development-tools">
1508 디버깅 및 개발 도구
1509</h2>
1510
1511<h3 id="debugging-commands">
1512 디버깅 명령어
1513</h3>
1514
1515`claude --debug`를 사용하여 플러그인 로딩 세부 정보를 확인합니다:
1516
1517다음을 표시합니다:
1518
1519* 로드되는 플러그인
1520* 플러그인 매니페스트의 오류
1521* Skill, agent, hook 등록
1522* MCP 서버 초기화
1523
1524<h3 id="common-issues">
1525 일반적인 문제
1526</h3>
1527
1528| 문제 | 원인 | 해결 방법 |
1529| :---------------------------------- | :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1530| 플러그인이 로드되지 않음 | 잘못된 `plugin.json` | `claude plugin validate ./my-plugin` 또는 `/plugin validate ./my-plugin`을 실행합니다. 여기서 `./my-plugin`은 플러그인 디렉토리이며, `plugin.json`, `hooks/hooks.json`, 플러그인의 기본 디렉토리에 있는 skills, agents, commands의 frontmatter에서 구문 및 스키마 오류를 확인합니다. 실행 범위에 대해서는 [플러그인 또는 매니페스트 없는 디렉토리 검증](/docs/ko/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)을 참조하십시오 |
1531| Skills가 나타나지 않음 | 잘못된 디렉토리 구조 | `skills/` 또는 `commands/`가 플러그인 루트에 있는지 확인하고, `.claude-plugin/` 내부에 있지 않은지 확인합니다 |
1532| Hooks가 실행되지 않음 | 스크립트가 실행 가능하지 않음 | `chmod +x script.sh`를 실행합니다 |
1533| MCP 서버 실패 | `${CLAUDE_PLUGIN_ROOT}` 누락 | 모든 플러그인 경로에 변수를 사용합니다 |
1534| 경로 오류 | 절대 경로 사용됨 | 경로를 상대 경로로 변경하고 `./`로 시작합니다. [경로 동작 규칙](#path-behavior-rules)을 참조하십시오. 이는 `skills` 필드의 `"."` 예외를 다룹니다 |
1535| LSP `Executable not found in $PATH` | 언어 서버가 설치되지 않음 | 바이너리를 설치합니다 (예: `npm install -g typescript-language-server typescript`) |
1536
1537<h3 id="example-error-messages">
1538 예제 오류 메시지
1539</h3>
1540
1541**매니페스트 검증 오류**:
1542
1543* `Invalid JSON syntax: Unexpected token } in JSON at position 142`: 누락된 쉼표, 추가 쉼표 또는 따옴표 없는 문자열이 있는지 확인합니다
1544* `Plugin <name> has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Invalid input: expected string, received undefined`: 필수 필드가 누락되었습니다
1545* `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이 다른 방식으로는 유효했더라도 말입니다.
1546
1547**플러그인 로딩 오류**:
1548
1549* `Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.`: 명령 경로가 존재하지만 유효한 명령 파일이 포함되지 않습니다
1550* `Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.`: marketplace.json의 `source` 경로가 존재하지 않는 디렉토리를 가리킵니다
1551* `Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.`: 중복 구성 요소 정의를 제거하거나 marketplace 항목에서 `strict: false`를 제거합니다
1552
1553<h3 id="hook-troubleshooting">
1554 Hook 문제 해결
1555</h3>
1556
1557**Hook 스크립트가 실행되지 않음**:
1558
15591. 스크립트가 실행 가능한지 확인합니다: `chmod +x ./scripts/your-script.sh`
15602. shebang 줄을 확인합니다: 첫 번째 줄은 `#!/bin/bash` 또는 `#!/usr/bin/env bash`여야 합니다
15613. 경로가 `${CLAUDE_PLUGIN_ROOT}`를 사용하는지 확인합니다: `"command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"`
15624. 스크립트를 수동으로 테스트합니다: `./scripts/your-script.sh`
1563
1564**Hook이 예상 이벤트에서 트리거되지 않음**:
1565
15661. 이벤트 이름이 올바른지 확인합니다 (대소문자 구분): `postToolUse`가 아닌 `PostToolUse`
15672. matcher 패턴이 도구와 일치하는지 확인합니다: 파일 작업의 경우 `"matcher": "Write|Edit"`
15683. hook 유형이 유효한지 확인합니다: `command`, `http`, `mcp_tool`, `prompt`, 또는 `agent`
1569
1570<h3 id="mcp-server-troubleshooting">
1571 MCP 서버 문제 해결
1572</h3>
1573
1574**서버가 시작되지 않음**:
1575
15761. 명령이 존재하고 실행 가능한지 확인합니다
15772. 모든 경로가 `${CLAUDE_PLUGIN_ROOT}` 변수를 사용하는지 확인합니다
15783. MCP 서버 로그를 확인합니다: `claude --debug`는 초기화 오류를 표시합니다
15794. Claude Code 외부에서 서버를 수동으로 테스트합니다
1580
1581**서버 도구가 나타나지 않음**:
1582
15831. 서버가 `.mcp.json` 또는 `plugin.json`에서 올바르게 구성되었는지 확인합니다
15842. 서버가 MCP 프로토콜을 올바르게 구현하는지 확인합니다
15853. 디버그 출력에서 연결 시간 초과를 확인합니다
1586
1587<h3 id="directory-structure-mistakes">
1588 디렉토리 구조 오류
1589</h3>
1590
1591**증상**: 플러그인이 로드되지만 구성 요소(skills, agents, hooks)가 누락되었습니다.
1592
1593**올바른 구조**: 구성 요소는 플러그인 루트에 있어야 하며, `.claude-plugin/` 내부에 있지 않아야 합니다. `plugin.json`만 `.claude-plugin/`에 속합니다.
1594
1595**디버그 체크리스트**:
1596
15971. `claude --debug`를 실행하고 "loading plugin" 메시지를 찾습니다
15982. 각 구성 요소 디렉토리가 디버그 출력에 나열되어 있는지 확인합니다
15993. 파일 권한이 플러그인 파일 읽기를 허용하는지 확인합니다
1600
1601***
1602
1603<h2 id="distribution-and-versioning-reference">
1604 배포 및 버전 관리 참고자료
1605</h2>
1606
1607<h3 id="version-management">
1608 버전 관리
1609</h3>
1610
1611Claude Code는 플러그인의 버전을 캐시 키로 사용하여 업데이트 가능 여부를 결정합니다. `/plugin update`를 실행하거나 자동 업데이트가 실행될 때, Claude Code는 현재 버전을 계산하고 이미 설치된 버전과 일치하면 업데이트를 건너뜁니다. [로컬 디렉터리 마켓플레이스에서 제자리에 로드](#plugin-caching-and-file-resolution)된 플러그인은 버전 문자열이 무엇이든 상관없이 매 세션 시작 시 현재 소스 파일을 로드합니다.
1612
1613`command` 외의 모든 소스 유형에 대해 Claude Code는 다음 중 설정된 첫 번째 항목에서 버전을 확인합니다:
1614
16151. 플러그인의 `plugin.json`에 있는 `version` 필드
16162. `marketplace.json`의 플러그인 마켓플레이스 항목에 있는 `version` 필드
16173. git 호스팅 마켓플레이스의 `github`, `url`, `git-subdir`, 상대 경로 소스에 대한 플러그인 소스의 git 커밋 SHA
16184. [`archive` 소스](/docs/ko/plugin-marketplaces#zip-archives)의 경우 SHA-256 다이제스트: 마켓플레이스 항목의 `sha256` 핀 또는 핀을 설정하지 않았을 때 다운로드된 파일의 다이제스트입니다. Claude Code는 이를 처음 12자로 단축합니다.
16195. `npm` 소스 또는 git 저장소 내에 있지 않은 로컬 디렉터리의 경우 `unknown`
1620
1621[`command` 소스](/docs/ko/plugin-marketplaces#command-sources)의 경우 Claude Code는 항상 명령이 생성한 내용에서 버전을 파생합니다: 자체적으로 12자 콘텐츠 해시이거나, 하나가 설정되어 있을 때 `<version>-<hash>` 형식으로 `plugin.json` 버전에 추가됩니다. Claude Code는 command 소스에 대해 마켓플레이스 항목의 `version` 필드를 무시합니다. 해시된 출력이 변경되는 명령은 작성된 버전 문자열이 동일하게 유지되더라도 새 버전을 생성합니다. [링크 모드](/docs/ko/plugin-marketplaces#copy-mode-and-link-mode)에서 해시는 인쇄된 디렉터리의 실제 경로와 파일 콘텐츠가 아닌 최상위 항목을 포함합니다.
1622
1623이러한 소스 유형의 경우 플러그인을 버전 관리하는 세 가지 방법이 있습니다:
1624
1625| 접근 방식 | 방법 | 업데이트 동작 | 최적 사용 |
1626| :------------ | :--------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------- |
1627| **명시적 버전** | `plugin.json`에서 `"version": "2.1.0"`을 설정합니다. | 사용자는 이 필드를 업데이트할 때만 업데이트를 받습니다. 이를 업데이트하지 않고 새 커밋을 푸시하면 효과가 없으며, `/plugin update`는 "이미 최신 버전입니다"를 보고합니다. [제자리에 로드](#plugin-caching-and-file-resolution)된 플러그인의 경우 새 콘텐츠가 어쨌든 로드됩니다. | 안정적인 릴리스 주기를 가진 게시된 플러그인 |
1628| **커밋-SHA 버전** | `plugin.json`과 마켓플레이스 항목 모두에서 `version`을 생략합니다. | 사용자는 소스의 확인된 커밋이 변경될 때마다 업데이트를 받습니다. | 활발한 개발 중인 내부 또는 팀 플러그인 |
1629| **다이제스트 버전** | [`archive` 소스](/docs/ko/plugin-marketplaces#zip-archives)를 사용하고 `plugin.json`과 마켓플레이스 항목 모두에서 `version`을 생략합니다. | `sha256` 핀을 사용하면 사용자는 핀을 변경할 때 업데이트를 받습니다. 핀이 없으면 사용자는 호스팅된 zip 파일의 바이트가 변경될 때마다 업데이트를 받습니다. | 정적 서버 또는 아티팩트 저장소에 zip 파일로 게시된 플러그인 |
1630
1631명시적 버전을 사용하는 경우 [의미 있는 버전 관리](https://semver.org)(`MAJOR.MINOR.PATCH`)를 따릅니다: 주요 변경 사항의 경우 MAJOR를 업데이트하고, 새 기능의 경우 MINOR를 업데이트하고, 버그 수정의 경우 PATCH를 업데이트합니다. `CHANGELOG.md`에서 변경 사항을 문서화합니다.
1632
1633***
1634
1635<h2 id="see-also">
1636 참고 항목
1637</h2>
1638
1639* [플러그인](/docs/ko/plugins) - 튜토리얼 및 실제 사용
1640* [플러그인 마켓플레이스](/docs/ko/plugin-marketplaces) - 마켓플레이스 생성 및 관리
1641* [Skills](/docs/ko/skills) - Skill 개발 세부 정보
1642* [Subagents](/docs/ko/sub-agents) - Agent 구성 및 기능
1643* [Hooks](/docs/ko/hooks) - 이벤트 처리 및 자동화
1644* [MCP](/docs/ko/mcp) - 외부 도구 통합
1645* [설정](/docs/ko/settings) - 플러그인의 구성 옵션
