plugins.md +0 −527 deleted
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> skills, agents, hooks, MCP servers를 사용하여 Claude Code를 확장하는 사용자 정의 플러그인을 만듭니다.
8
9플러그인을 사용하면 프로젝트와 팀 전체에서 공유할 수 있는 사용자 정의 기능으로 Claude Code를 확장할 수 있습니다. 이 가이드에서는 skills, agents, hooks, MCP servers를 사용하여 자신의 플러그인을 만드는 방법을 다룹니다.
10
11기존 플러그인을 설치하려고 하시나요? [플러그인 발견 및 설치](/docs/ko/discover-plugins)를 참조하세요. 완전한 기술 사양은 [플러그인 참조](/docs/ko/plugins-reference)를 참조하세요.
12
13<h2 id="when-to-use-plugins-vs-standalone-configuration">
14 플러그인 대 독립 실행형 구성 사용 시기
15</h2>
16
17Claude Code는 사용자 정의 skills, agents, hooks를 추가하는 두 가지 방법을 지원합니다:
18
19| 접근 방식 | Skill 이름 | 최적 용도 |
20| :---------------------------------------------------------------------------------------- | :------------------- | :-------------------------------------- |
21| **독립 실행형** (`.claude/` 디렉토리) | `/hello` | 개인 워크플로우, 프로젝트별 사용자 정의, 빠른 실험 |
22| **플러그인** (skills, agents, hooks를 포함하거나 `.claude-plugin/plugin.json` 매니페스트가 있는 자체 포함 디렉토리) | `/plugin-name:hello` | 팀원과 공유, 커뮤니티에 배포, 버전 관리 릴리스, 프로젝트 간 재사용 |
23
24<Tip>
25 빠른 반복을 위해 `.claude/`의 독립 실행형 구성으로 시작한 다음, 공유할 준비가 되면 [기존 구성을 플러그인으로 변환](#convert-existing-configurations-to-plugins)하세요.
26</Tip>
27
28<h2 id="quickstart">
29 빠른 시작
30</h2>
31
32이 빠른 시작은 사용자 정의 skill을 사용하여 플러그인을 만드는 과정을 안내합니다. 매니페스트(플러그인을 정의하는 구성 파일)를 만들고, skill을 추가하고, `--plugin-dir` 플래그를 사용하여 로컬에서 테스트합니다.
33
34<h3 id="prerequisites">
35 필수 조건
36</h3>
37
38* Claude Code [설치 및 인증](/docs/ko/quickstart#step-1-install-claude-code)
39
40<h3 id="create-your-first-plugin">
41 첫 번째 플러그인 만들기
42</h3>
43
44<Steps>
45 <Step title="플러그인 디렉토리 만들기">
46 모든 플러그인은 skills, agents 또는 hooks를 포함하는 자체 디렉토리에 있으며, 선택적으로 `.claude-plugin/plugin.json` 매니페스트와 함께 있습니다. 이 빠른 시작에서는 `--plugin-dir`을 사용하여 테스트 단계에서 Claude Code가 디렉토리를 가리키기 때문에 위치는 중요하지 않습니다. 스크래치 폴더나 프로젝트 디렉토리와 같이 편리한 곳 어디든 만들 수 있습니다:
47
48 ```bash theme={null}
49 mkdir my-first-plugin
50 ```
51
52 나머지 단계는 상위 디렉토리에서 실행되며 `my-first-plugin/...`과 같은 경로를 상대 경로로 참조합니다.
53 </Step>
54
55 <Step title="플러그인 매니페스트 만들기">
56 `.claude-plugin/plugin.json`의 매니페스트 파일은 플러그인의 정체성을 정의합니다: 이름, 설명, 버전. Claude Code는 이 메타데이터를 사용하여 플러그인 관리자에서 플러그인을 표시합니다.
57
58 플러그인 폴더 내에 `.claude-plugin` 디렉토리를 만듭니다:
59
60 ```bash theme={null}
61 mkdir my-first-plugin/.claude-plugin
62 ```
63
64 그런 다음 다음 내용으로 `my-first-plugin/.claude-plugin/plugin.json`을 만듭니다:
65
66 ```json my-first-plugin/.claude-plugin/plugin.json theme={null}
67 {
68 "name": "my-first-plugin",
69 "description": "A greeting plugin to learn the basics",
70 "version": "1.0.0",
71 "author": {
72 "name": "Your Name"
73 }
74 }
75 ```
76
77 | 필드 | 목적 |
78 | :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
79 | `name` | 고유 식별자 및 skill 네임스페이스. Skills는 이것으로 접두사가 붙습니다 (예: `/my-first-plugin:hello`). |
80 | `description` | 플러그인을 검색하거나 설치할 때 플러그인 관리자에 표시됩니다. |
81 | `version` | 선택 사항. 설정된 경우 사용자는 이 필드를 변경할 때만 업데이트를 받습니다. [`command` source](/docs/ko/plugin-marketplaces#command-sources) 또는 [제자리에 로드된](/docs/ko/plugins-reference#plugin-caching-and-file-resolution) 플러그인 제외; [버전 관리](/docs/ko/plugins-reference#version-management)를 참조하세요. 생략되면 [버전 관리](/docs/ko/plugins-reference#version-management)의 다음 소스에서 버전이 제공됩니다. |
82 | `author` | 선택 사항. 속성에 유용합니다. |
83
84 `homepage`, `repository`, `license`와 같은 추가 필드는 [전체 매니페스트 스키마](/docs/ko/plugins-reference#plugin-manifest-schema)를 참조하세요.
85 </Step>
86
87 <Step title="Skill 추가">
88 Skills는 `skills/` 디렉토리에 있습니다. 각 skill은 `SKILL.md` 파일을 포함하는 폴더입니다. 폴더 이름은 skill 이름이 되며, 플러그인의 네임스페이스가 접두사로 붙습니다 (`my-first-plugin`이라는 플러그인의 `hello/`는 `/my-first-plugin:hello`를 만듭니다).
89
90 플러그인 폴더에 skill 디렉토리를 만듭니다:
91
92 ```bash theme={null}
93 mkdir -p my-first-plugin/skills/hello
94 ```
95
96 그런 다음 다음 내용으로 `my-first-plugin/skills/hello/SKILL.md`를 만듭니다:
97
98 ```markdown my-first-plugin/skills/hello/SKILL.md theme={null}
99 ---
100 description: Greet the user with a friendly message
101 disable-model-invocation: true
102 ---
103
104 Greet the user warmly and ask how you can help them today.
105 ```
106 </Step>
107
108 <Step title="플러그인 테스트">
109 `--plugin-dir` 플래그를 사용하여 Claude Code를 실행하여 플러그인을 로드합니다:
110
111 ```bash theme={null}
112 claude --plugin-dir ./my-first-plugin
113 ```
114
115 Claude Code가 시작되면 새 skill을 시도해보세요:
116
117 ```shell theme={null}
118 /my-first-plugin:hello
119 ```
120
121 Claude가 인사말로 응답하는 것을 볼 수 있습니다. `/help`를 실행하고 **사용자 정의 명령** 탭을 열어 플러그인 네임스페이스 아래에 나열된 skill을 확인하세요.
122
123 <Note>
124 **네임스페이싱이 필요한 이유?** 플러그인 skills는 항상 네임스페이스가 지정됩니다 (예: `/my-first-plugin:hello`). 여러 플러그인이 동일한 이름의 skills를 가질 때 충돌을 방지합니다.
125
126 네임스페이스 접두사를 변경하려면 `plugin.json`의 `name` 필드를 업데이트하세요.
127 </Note>
128 </Step>
129
130 <Step title="Skill 인수 추가">
131 사용자 입력을 수락하여 skill을 동적으로 만듭니다. `$ARGUMENTS` 자리 표시자는 사용자가 skill 이름 뒤에 제공하는 모든 텍스트를 캡처합니다.
132
133 `SKILL.md` 파일을 업데이트합니다:
134
135 ```markdown my-first-plugin/skills/hello/SKILL.md theme={null}
136 ---
137 description: Greet the user with a personalized message
138 ---
139
140 # Hello Skill
141
142 Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.
143 ```
144
145 `/reload-plugins`를 실행하여 변경 사항을 적용한 다음 이름으로 skill을 시도해보세요:
146
147 ```shell theme={null}
148 /my-first-plugin:hello Alex
149 ```
150
151 Claude가 이름으로 인사할 것입니다. skills에 인수를 전달하는 방법에 대한 자세한 내용은 [Skills](/docs/ko/skills#pass-arguments-to-skills)를 참조하세요.
152 </Step>
153</Steps>
154
155<Tip>
156 `--plugin-dir` 플래그는 개발 및 테스트에 유용합니다. 플러그인을 다른 사람과 공유할 준비가 되면 [플러그인 마켓플레이스 만들기 및 배포](/docs/ko/plugin-marketplaces)를 참조하세요.
157</Tip>
158
159<h2 id="develop-a-plugin-in-your-skills-directory">
160 기술 디렉토리에서 플러그인 개발
161</h2>
162
163매번 시작할 때 `--plugin-dir`을 전달하는 대신 기술 디렉토리에 플러그인을 유지하고 Claude Code가 자동으로 로드하도록 할 수 있습니다. `claude plugin init`이 스캐폴딩합니다:
164
165```bash theme={null}
166claude plugin init my-tool
167```
168
169이는 `.claude-plugin/plugin.json` 매니페스트와 시작 `SKILL.md`를 포함하는 `~/.claude/skills/my-tool/`을 만듭니다. 다음 세션에서는 마켓플레이스나 설치 단계 없이 `my-tool@skills-dir`로 로드됩니다.
170
171자동 로드 규칙, 개인 대 프로젝트 범위, 작업 공간 신뢰 요구 사항, 업데이트 또는 제거 방법은 [기술 디렉토리 플러그인](/docs/ko/plugins-reference#skills-directory-plugins)을 참조하세요.
172
173<h2 id="plugin-structure-overview">
174 플러그인 구조 개요
175</h2>
176
177skill을 사용하여 플러그인을 만들었지만, 플러그인에는 훨씬 더 많은 것이 포함될 수 있습니다: 사용자 정의 agents, hooks, MCP servers, LSP servers, 백그라운드 모니터.
178
179<Warning>
180 **일반적인 실수**: `commands/`, `agents/`, `skills/`, `hooks/`를 `.claude-plugin/` 디렉토리 내에 넣지 마세요. `.claude-plugin/` 내에는 `plugin.json`만 들어갑니다. 다른 모든 디렉토리는 플러그인 루트 수준에 있어야 합니다.
181
182 플러그인 루트는 개별 플러그인의 자체 디렉토리입니다(예: [빠른 시작](#quickstart)의 `my-first-plugin/`). 절대 `~/.claude/`가 아닙니다. 예를 들어, Claude Code는 `~/.claude/.mcp.json`에 배치된 `.mcp.json`을 읽지 않습니다.
183</Warning>
184
185| 디렉토리 | 위치 | 목적 |
186| :---------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
187| `.claude-plugin/` | 플러그인 루트 | `plugin.json` 매니페스트를 포함합니다 (구성 요소가 기본 위치를 사용하는 경우 선택 사항) |
188| `skills/` | 플러그인 루트 | `<name>/SKILL.md` 디렉토리로서의 Skills |
189| `commands/` | 플러그인 루트 | Markdown 파일로서의 Skills. 새 플러그인의 경우 `skills/`를 사용하세요 |
190| `agents/` | 플러그인 루트 | 사용자 정의 agent 정의 |
191| `hooks/` | 플러그인 루트 | `hooks.json`의 이벤트 핸들러 |
192| `.mcp.json` | 플러그인 루트 | MCP server 구성 |
193| `.lsp.json` | 플러그인 루트 | 코드 인텔리전스를 위한 LSP server 구성 |
194| `monitors/` | 플러그인 루트 | `monitors.json`의 백그라운드 모니터 구성 |
195| `bin/` | 플러그인 루트 | 플러그인이 활성화된 동안 Bash tool의 `PATH`에 추가되는 실행 파일. 플러그인을 [claude.ai 조직 설정을 통해 배포](/docs/ko/plugin-marketplaces#keep-executables-out-of-the-top-level-bin-directory)하는 경우 이 디렉토리를 포함할 수 없습니다 |
196| `settings.json` | 플러그인 루트 | 플러그인이 활성화될 때 적용되는 기본 [설정](/docs/ko/settings) |
197
198정확히 하나의 skill을 제공하는 플러그인은 `skills/` 디렉토리를 만드는 대신 `SKILL.md`를 플러그인 루트에 직접 배치할 수 있습니다. Claude Code는 이를 단일 skill로 로드하고 frontmatter `name` 필드를 호출 이름으로 사용합니다. 플러그인이 하나 이상의 skill로 성장할 수 있는 경우 `skills/` 레이아웃을 사용하세요.
199
200<h2 id="develop-more-complex-plugins">
201 더 복잡한 플러그인 개발
202</h2>
203
204기본 플러그인에 익숙해지면 더 정교한 확장 기능을 만들 수 있습니다.
205
206<h3 id="add-skills-to-your-plugin">
207 플러그인에 Skills 추가
208</h3>
209
210플러그인은 Claude의 기능을 확장하기 위해 [Agent Skills](/docs/ko/skills)를 포함할 수 있습니다. Skills는 모델 호출입니다: Claude는 작업 컨텍스트에 따라 자동으로 사용합니다.
211
212플러그인 루트에 `SKILL.md` 파일을 포함하는 Skill 폴더가 있는 `skills/` 디렉토리를 추가합니다:
213
214```text theme={null}
215my-plugin/
216├── .claude-plugin/
217│ └── plugin.json
218└── skills/
219 └── code-review/
220 └── SKILL.md
221```
222
223각 `SKILL.md`는 YAML 프론트매터와 지침을 포함합니다. Claude가 skill을 언제 사용할지 알 수 있도록 `description`을 포함하세요:
224
225```yaml theme={null}
226description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
227
228When reviewing code, check for:
2291. Code organization and structure
2302. Error handling
2313. Security concerns
2324. Test coverage
233```
234
235플러그인을 설치한 후 설치 요약을 확인합니다: `Run /reload-plugins to activate.`를 보고하면 [플러그인 변경 사항을 다시 시작하지 않고 적용](/docs/ko/discover-plugins#apply-plugin-changes-without-restarting)을 참조하여 현재 세션에서 Skills를 로드합니다. 점진적 공개 및 도구 제한을 포함한 완전한 Skill 작성 지침은 [Agent Skills](/docs/ko/skills)를 참조하세요.
236
237<h3 id="add-lsp-servers-to-your-plugin">
238 플러그인에 LSP servers 추가
239</h3>
240
241<Tip>
242 TypeScript, Python, Rust와 같은 일반적인 언어의 경우 공식 마켓플레이스에서 미리 빌드된 LSP 플러그인을 설치하세요. 이미 다루어진 언어가 아닌 언어에 대한 지원이 필요한 경우에만 사용자 정의 LSP 플러그인을 만드세요.
243</Tip>
244
245LSP (Language Server Protocol) 플러그인은 Claude에 실시간 코드 인텔리전스를 제공합니다. 아직 공식 LSP 플러그인이 없는 언어를 지원해야 하는 경우 플러그인에 `.lsp.json` 파일을 추가하여 자신의 플러그인을 만들 수 있습니다:
246
247```json .lsp.json theme={null}
248{
249 "go": {
250 "command": "gopls",
251 "args": ["serve"],
252 "extensionToLanguage": {
253 ".go": "go"
254 }
255 }
256}
257```
258
259플러그인을 설치하는 사용자는 자신의 머신에 언어 server 바이너리를 설치해야 합니다.
260
261서버가 시작되는지 확인하려면 플러그인이 활성화된 상태에서 Claude Code를 시작하고 `/plugin` Errors 탭을 확인합니다: 시작에 실패한 언어 server는 바이너리가 설치되지 않았을 때 `Executable not found in $PATH`와 같은 오류와 함께 나타납니다. 잘못된 구성이 있는 항목은 건너뛰어집니다. 이유를 확인하려면 `claude --debug`를 실행하세요.
262
263완전한 LSP 구성 옵션은 [LSP servers](/docs/ko/plugins-reference#lsp-servers)를 참조하세요.
264
265<h3 id="add-background-monitors-to-your-plugin">
266 플러그인에 백그라운드 모니터 추가
267</h3>
268
269백그라운드 모니터를 사용하면 플러그인이 로그, 파일 또는 외부 상태를 백그라운드에서 감시하고 이벤트가 도착할 때 Claude에 알릴 수 있습니다. Claude Code는 플러그인이 활성화될 때 각 모니터를 자동으로 시작하므로 Claude에 감시를 시작하도록 지시할 필요가 없습니다.
270
271플러그인 루트에 `monitors/monitors.json` 파일을 추가하고 모니터 항목의 배열을 포함합니다:
272
273```json monitors/monitors.json theme={null}
274[
275 {
276 "name": "error-log",
277 "command": "tail -F ./logs/error.log",
278 "description": "Application error log"
279 }
280]
281```
282
283`command`의 각 stdout 줄은 세션 중에 Claude에 알림으로 전달됩니다. `when` 트리거 및 변수 대체를 포함한 전체 스키마는 [Monitors](/docs/ko/plugins-reference#monitors)를 참조하세요.
284
285<h3 id="ship-default-settings-with-your-plugin">
286 플러그인과 함께 기본 설정 제공
287</h3>
288
289플러그인은 플러그인 루트에 `settings.json` 파일을 포함하여 플러그인이 활성화될 때 기본 구성을 적용할 수 있습니다. 현재 `agent` 및 `subagentStatusLine` 키만 지원됩니다.
290
291`agent`를 설정하면 플러그인의 [사용자 정의 agents](/docs/ko/sub-agents) 중 하나를 주 스레드로 활성화하여 시스템 프롬프트, 도구 제한, 모델을 적용합니다. 이를 통해 플러그인은 활성화될 때 Claude Code의 동작 방식을 기본적으로 변경할 수 있습니다.
292
293```json settings.json theme={null}
294{
295 "agent": "security-reviewer"
296}
297```
298
299이 예제는 플러그인의 `agents/` 디렉토리에 정의된 `security-reviewer` agent를 활성화합니다. `settings.json`의 설정은 `plugin.json`에 선언된 `settings`보다 우선합니다. 알 수 없는 키는 자동으로 무시됩니다.
300
301<h3 id="organize-complex-plugins">
302 복잡한 플러그인 구성
303</h3>
304
305많은 구성 요소가 있는 플러그인의 경우 기능별로 디렉토리 구조를 구성합니다. 완전한 디렉토리 레이아웃 및 구성 패턴은 [플러그인 디렉토리 구조](/docs/ko/plugins-reference#plugin-directory-structure)를 참조하세요.
306
307<h3 id="test-your-plugins-locally">
308 플러그인을 로컬에서 테스트
309</h3>
310
311개발 중에 플러그인을 테스트하려면 `--plugin-dir` 플래그를 사용합니다. 이는 설치를 요구하지 않고 플러그인을 직접 로드합니다.
312
313```bash theme={null}
314claude --plugin-dir ./my-plugin
315```
316
317플래그는 플러그인 디렉토리의 `.zip` 아카이브도 허용합니다.
318
319```bash theme={null}
320claude --plugin-dir ./my-plugin.zip
321```
322
323`--plugin-dir` 플러그인이 설치된 마켓플레이스 플러그인과 동일한 이름을 가진 경우 로컬 복사본이 해당 세션에 우선합니다. 이를 통해 먼저 제거하지 않고도 이미 설치한 플러그인의 변경 사항을 테스트할 수 있습니다. 관리 설정에 의해 강제로 활성화되거나 비활성화된 플러그인은 유일한 예외이며 `--plugin-dir`로 재정의할 수 없습니다.
324
325플러그인을 변경할 때 `/reload-plugins`를 실행하여 다시 시작하지 않고 업데이트를 적용합니다. 이는 플러그인, skills, agents, hooks, 플러그인 MCP servers, 플러그인 LSP servers를 다시 로드합니다. 대화형 터미널이 없는 세션에서 플러그인 MCP server 변경 사항은 [다음 세션을 기다립니다](/docs/ko/discover-plugins#apply-plugin-changes-without-restarting). 플러그인 구성 요소를 테스트합니다:
326
327* `/plugin-name:skill-name`으로 skills를 시도해보세요
328* agents가 `/context`의 Custom Agents 아래에 나타나는지 확인하거나 범위가 지정된 이름으로 @-mention하세요
329* 각 hook이 일치하는 이벤트를 트리거합니다(예: 파일을 편집하도록 Claude에 요청하여 `PostToolUse` hook을 트리거하고 그 효과를 확인합니다). Claude Code는 일치한 hooks, 종료 코드, 출력을 [debug log](/docs/ko/hooks#debug-hooks)에 기록합니다.
330
331<Tip>
332 플래그를 여러 번 지정하여 한 번에 여러 플러그인을 로드할 수 있습니다:
333
334 ```bash theme={null}
335 claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two
336 ```
337
338 플러그인과 그것이 의존하는 플러그인을 함께 테스트하려면 [플러그인과 그 종속성을 로컬에서 테스트](/docs/ko/plugin-dependencies#test-a-plugin-and-its-dependency-locally)를 참조하세요.
339</Tip>
340
341플래그를 추가할 수 없는 세션에서 플러그인을 로드하려면 대신 [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/ko/env-vars#variables) 환경 변수에 절대 경로를 나열하세요. Claude Code는 각 경로를 `--plugin-dir` 경로로 로드합니다. 이러한 플러그인은 `--plugin-dir`로 전달하는 플러그인에 추가로 로드됩니다. [프로젝트 및 로컬 설정은 이 변수를 설정할 수 없습니다](/docs/ko/settings-reference#variables-claude-code-ignores-in-env). `CLAUDE_CODE_PLUGIN_DIRS`는 Claude Code v2.1.280 이상이 필요합니다.
342
343`--plugin-dir`로 플러그인을 시도하면 작동할 수 있음을 알 수 있습니다. Claude가 실제로 얼마나 자주 도달하고 올바른 결과를 얻는지 알아보려면 [`claude plugin eval`](/docs/ko/plugin-evals)을 사용하여 테스트 프롬프트 세트에 대해 실행하세요. 각 프롬프트는 플러그인이 로드된 상태와 로드되지 않은 상태에서 여러 번 실행되므로 플러그인이 기여하는 바를 확인하고 변경하거나 새 모델이 출시될 때 회귀를 포착할 수 있습니다.
344
345한 곳에서 여러 플러그인을 로드하려면 플러그인을 보유한 폴더를 전달합니다(예: `--plugin-dir ./plugins`). 플러그인 폴더를 로드하려면 Claude Code v2.1.265 이상이 필요합니다. Claude Code는 폴더의 최상위 수준을 읽어 어떤 플러그인을 로드할지 결정하며, 대화형 세션에서는 나중에 변경 사항을 위해 폴더를 감시합니다:
346
347* **로드되는 항목**: 폴더에 최상위 수준의 매니페스트 또는 플러그인 구성 요소가 없으면 Claude Code는 이를 플러그인 폴더로 취급합니다. `.claude-plugin/plugin.json` 매니페스트가 있는 각 즉시 하위 폴더는 별도의 플러그인으로 로드됩니다. Claude Code는 오류를 보고하지 않고 매니페스트가 없는 플러그인을 포함하여 폴더의 다른 모든 항목을 건너뜁니다.
348* **대화형 세션 중 변경 사항**: 추가하는 하위 폴더는 매니페스트가 준비되면 새 플러그인으로 로드되며, 하위 폴더를 제거하면 해당 플러그인이 언로드됩니다. Claude Code는 각 변경에 대해 세션에 줄을 출력합니다. 변경 사항을 중간 대화에 적용하면 [프롬프트 캐시가 무효화](/docs/ko/prompt-caching#enabling-or-disabling-a-plugin)될 경우 Claude Code는 이를 보류하고 줄에서 `/reload-plugins`를 실행하도록 말합니다.
349
350URL에서 호스팅되는 `.zip` 아카이브로 이미 패키징된 플러그인을 테스트하려면(예: CI 빌드 아티팩트) 대신 `--plugin-url`을 사용하세요. Claude Code는 시작 시 아카이브를 가져오고 해당 세션에만 로드합니다. Claude Code가 아카이브를 가져올 수 없거나 아카이브가 유효하지 않으면 플러그인 없이 시작하고 `/plugin` 관리자의 **Errors** 탭에서 검토할 수 있는 플러그인 로드 오류를 기록합니다. 모든 플러그인 소스에 대해 동일한 [신뢰 고려 사항](/docs/ko/discover-plugins#security)이 적용됩니다: 이 플래그를 제어하거나 신뢰하는 아카이브에만 지정하세요.
351
352여러 플러그인을 로드하려면 각 URL에 대해 플래그를 반복합니다:
353
354```bash theme={null}
355claude --plugin-url https://example.com/my-plugin.zip --plugin-url https://example.com/other.zip
356```
357
358또는 공백으로 구분된 URL을 하나의 따옴표로 묶인 인수로 전달합니다:
359
360```bash theme={null}
361claude --plugin-url "https://example.com/my-plugin.zip https://example.com/other.zip"
362```
363
364<h3 id="debug-plugin-issues">
365 플러그인 문제 디버깅
366</h3>
367
368플러그인이 예상대로 작동하지 않는 경우:
369
3701. **구조 확인**: 디렉토리가 `.claude-plugin/` 내부가 아닌 플러그인 루트에 있는지 확인하세요
3712. **구성 요소를 개별적으로 테스트**: 각 skill, agent, hook을 별도로 확인하세요
3723. **검증 및 디버깅 도구 사용**: CLI 명령 및 문제 해결 기법은 [디버깅 및 개발 도구](/docs/ko/plugins-reference#debugging-and-development-tools)를 참조하세요
373
374<h3 id="share-your-plugins">
375 플러그인 공유
376</h3>
377
378플러그인을 공유할 준비가 되면:
379
3801. **문서 추가**: 설치 및 사용 지침이 포함된 `README.md`를 포함하세요
3812. **버전 관리 전략 선택**: 명시적 `version`을 설정할지 또는 [버전 관리](/docs/ko/plugins-reference#version-management)에 설명된 폴백에 의존할지 결정하세요.
3823. **마켓플레이스 만들기 또는 사용**: [플러그인 마켓플레이스](/docs/ko/plugin-marketplaces)를 통해 배포하여 설치하세요
3834. **다른 사람과 테스트**: 더 광범위한 배포 전에 팀원이 플러그인을 테스트하도록 하세요
384
385플러그인이 마켓플레이스에 있으면 다른 사람들이 [플러그인 발견 및 설치](/docs/ko/discover-plugins)의 지침을 사용하여 설치할 수 있습니다. 플러그인을 팀 내부로만 유지하려면 [비공개 저장소](/docs/ko/plugin-marketplaces#private-repositories)에서 마켓플레이스를 호스팅하세요.
386
387<h3 id="submit-your-plugin-to-the-community-marketplace">
388 플러그인을 커뮤니티 마켓플레이스에 제출
389</h3>
390
391Anthropic은 Claude Code 플러그인을 위한 두 개의 공개 마켓플레이스를 유지합니다:
392
393* **`claude-plugins-official`**: Anthropic에서 유지 관리하는 엄선된 플러그인 세트입니다. Claude Code를 처음 대화형으로 시작할 때 자동으로 등록됩니다. 첫 번째 시작 전에 Claude Code를 비대화형으로 실행하거나 [마켓플레이스 정책](/docs/ko/plugin-marketplaces#managed-marketplace-restrictions)이 이전 시도를 차단한 경우 `claude plugin marketplace add anthropics/claude-plugins-official`로 직접 등록하세요.
394* **`claude-community`**: 검토 후 타사 제출이 도착하는 공개 커뮤니티 마켓플레이스입니다. 사용자는 `/plugin marketplace add anthropics/claude-plugins-community`로 추가하고 `@claude-community`로 설치합니다.
395
396커뮤니티 마켓플레이스 검토를 위해 플러그인을 제출하려면 다음 앱 내 양식 중 하나를 사용하세요:
397
398* **claude.ai**: [claude.ai/admin-settings/directory/submissions/plugins/new](https://claude.ai/admin-settings/directory/submissions/plugins/new)
399* **Console**: [platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit)
400
401claude.ai 양식은 Team 또는 Enterprise 조직과 디렉토리 관리 액세스가 필요합니다. 조직 소유자는 기본적으로 이 액세스 권한을 가집니다. Team 또는 Enterprise 조직에 속하지 않은 개별 작성자는 대신 Console 양식을 사용할 수 있습니다.
402
403제출하기 전에 로컬에서 `claude plugin validate ./your-plugin`을 실행하세요. 플러그인 디렉토리의 경로로 `./your-plugin`을 바꾸세요. 검토 파이프라인은 모든 제출에 대해 동일한 검사를 실행하며, 자동화된 안전 검사도 함께 수행합니다. 검증이 통과하면 Claude Code는 `✔ Validation passed` 또는 경고가 있는 경우 `✔ Validation passed with warnings`를 출력합니다. 경고는 검증을 실패하지 않습니다. `--strict`를 추가하여 경고를 오류로 취급하세요.
404
405승인된 플러그인은 [`anthropics/claude-plugins-community`](https://github.com/anthropics/claude-plugins-community) 카탈로그의 특정 커밋 SHA에 고정되며, CI는 저장소에 새 커밋을 푸시할 때 자동으로 핀을 업데이트합니다. 공개 카탈로그는 검토 파이프라인에서 매일 밤 동기화되므로 승인과 플러그인이 `marketplace.json`에 나타나는 사이에 지연이 있을 수 있습니다. 플러그인이 설치 가능한지 확인하려면 [커뮤니티 카탈로그](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)에서 이름을 검색하세요.
406
407공식 마켓플레이스인 `claude-plugins-official`은 별도로 엄선됩니다. Anthropic은 자신의 재량에 따라 포함할 플러그인을 결정합니다. 신청 절차가 없으며, 제출 양식은 플러그인을 공식 마켓플레이스에 추가하지 않습니다.
408
409Anthropic이 플러그인을 공식 마켓플레이스에 나열하면 CLI에서 Claude Code 사용자에게 설치를 권장할 수 있습니다. [CLI에서 플러그인 권장](/docs/ko/plugin-hints)을 참조하세요.
410
411<h2 id="convert-existing-configurations-to-plugins">
412 기존 구성을 플러그인으로 변환
413</h2>
414
415`.claude/` 디렉토리에 이미 skills 또는 hooks가 있는 경우 더 쉬운 공유 및 배포를 위해 플러그인으로 변환할 수 있습니다.
416
417<h3 id="migration-steps">
418 마이그레이션 단계
419</h3>
420
421<Steps>
422 <Step title="플러그인 구조 만들기">
423 프로젝트 루트에 새 플러그인 디렉토리를 만듭니다. 기존 `.claude/` 폴더와 함께 배치하여 다음 단계의 상대 `cp` 경로가 올바르게 해석되도록 합니다:
424
425 ```bash theme={null}
426 mkdir -p my-plugin/.claude-plugin
427 ```
428
429 `my-plugin/.claude-plugin/plugin.json`에 매니페스트 파일을 만듭니다:
430
431 ```json my-plugin/.claude-plugin/plugin.json theme={null}
432 {
433 "name": "my-plugin",
434 "description": "Migrated from standalone configuration",
435 "version": "1.0.0"
436 }
437 ```
438 </Step>
439
440 <Step title="기존 파일 복사">
441 각 구성 디렉토리를 플러그인 루트에 복사합니다. 세 개 모두를 가지고 있지 않을 수 있습니다. 디렉토리가 없으면 `cp`는 `No such file or directory`를 출력하고 아무것도 복사하지 않으므로 해당 명령을 건너뛰거나 오류를 무시합니다.
442
443 ```bash theme={null}
444 cp -r .claude/commands my-plugin/
445
446 cp -r .claude/agents my-plugin/
447
448 cp -r .claude/skills my-plugin/
449 ```
450
451 플러그인에는 이제 `.claude/` 아래에 있던 디렉토리의 복사본이 포함됩니다. `ls my-plugin`을 실행하여 확인합니다. 복사한 각 디렉토리가 표시되어야 합니다.
452 </Step>
453
454 <Step title="Hooks 마이그레이션">
455 설정에 hooks가 있는 경우 hooks 디렉토리를 만듭니다:
456
457 ```bash theme={null}
458 mkdir my-plugin/hooks
459 ```
460
461 `my-plugin/hooks/hooks.json`을 hooks 구성으로 만듭니다. `.claude/settings.json` 또는 `settings.local.json`에서 `hooks` 객체를 복사합니다. 형식이 동일하기 때문입니다. 명령은 stdin에서 JSON으로 hook 입력을 받으므로 `jq`를 사용하여 파일 경로를 추출합니다:
462
463 ```json my-plugin/hooks/hooks.json theme={null}
464 {
465 "hooks": {
466 "PostToolUse": [
467 {
468 "matcher": "Write|Edit",
469 "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]
470 }
471 ]
472 }
473 }
474 ```
475 </Step>
476
477 <Step title="마이그레이션된 플러그인 테스트">
478 플러그인을 로드하여 모든 것이 작동하는지 확인합니다:
479
480 ```bash theme={null}
481 claude --plugin-dir ./my-plugin
482 ```
483
484 각 구성 요소를 테스트합니다. 명령을 실행하고, agents가 `/context`에 나타나는지 확인하고, 각 hook이 일치하는 이벤트를 트리거하여 그 효과를 확인합니다. Claude Code는 어떤 hooks가 일치했는지와 어떻게 종료되었는지를 [디버그 로그](/docs/ko/hooks#debug-hooks)에 기록합니다.
485 </Step>
486</Steps>
487
488<h3 id="what-changes-when-migrating">
489 마이그레이션 시 변경되는 사항
490</h3>
491
492| 독립 실행형 (`.claude/`) | 플러그인 |
493| :---------------------- | :-------------------------- |
494| 한 프로젝트에서만 사용 가능 | 마켓플레이스를 통해 공유 가능 |
495| `.claude/commands/`의 파일 | `plugin-name/commands/`의 파일 |
496| `settings.json`의 Hooks | `hooks/hooks.json`의 Hooks |
497| 공유하려면 수동으로 복사해야 함 | `/plugin install`로 설치 |
498
499<Note>
500 마이그레이션 후 중복을 피하기 위해 `.claude/`에서 원본 파일을 제거합니다. 프로젝트 및 사용자 `.claude/agents/` 정의는 같은 이름의 플러그인 agents를 재정의하므로, 원본이 제거되면 플러그인 버전만 적용됩니다. 플러그인 skills는 `/plugin-name:skill-name`으로 네임스페이스되므로, 원본 `/skill-name`과 플러그인 복사본이 모두 사용 가능하게 유지되며 하나가 다른 하나를 재정의하지 않습니다.
501</Note>
502
503<h2 id="next-steps">
504 다음 단계
505</h2>
506
507이제 Claude Code의 플러그인 시스템을 이해했으므로 다양한 목표에 대한 제안된 경로는 다음과 같습니다:
508
509<h3 id="for-plugin-users">
510 플러그인 사용자의 경우
511</h3>
512
513* [플러그인 발견 및 설치](/docs/ko/discover-plugins): 마켓플레이스를 검색하고 플러그인을 설치합니다
514* [팀 마켓플레이스 구성](/docs/ko/discover-plugins#configure-team-marketplaces): 팀을 위한 저장소 수준 플러그인을 설정합니다
515
516<h3 id="for-plugin-developers">
517 플러그인 개발자의 경우
518</h3>
519
520* [evals를 사용하여 플러그인 테스트](/docs/ko/plugin-evals): 플러그인이 변경하는 내용을 측정하고 CI에서 이를 제어합니다
521* [마켓플레이스 만들기 및 배포](/docs/ko/plugin-marketplaces): 플러그인을 패키징하고 공유합니다
522* [플러그인 참조](/docs/ko/plugins-reference): 완전한 기술 사양
523* 특정 플러그인 구성 요소에 대해 더 깊이 있게 살펴보세요:
524 * [Skills](/docs/ko/skills): skill 개발 세부 사항
525 * [Subagents](/docs/ko/sub-agents): agent 구성 및 기능
526 * [Hooks](/docs/ko/hooks): 이벤트 처리 및 자동화
527 * [MCP](/docs/ko/mcp): 외부 도구 통합