plugin-marketplaces.md 2026-09-24 22:57 UTC to 2026-09-25 23:58 UTC

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> Claude Code 확장 프로그램을 팀과 커뮤니티에 배포하기 위한 플러그인 마켓플레이스를 구축하고 호스팅합니다.

8 

9**플러그인 마켓플레이스**는 다른 사용자에게 플러그인을 배포할 수 있는 카탈로그입니다. 마켓플레이스는 중앙 집중식 검색, 버전 추적, 자동 업데이트 및 git 저장소와 로컬 경로를 포함한 여러 소스 유형을 지원합니다. 이 가이드에서는 팀이나 커뮤니티와 플러그인을 공유하기 위해 자신의 마켓플레이스를 만드는 방법을 보여줍니다.

10 

11기존 마켓플레이스에서 플러그인을 설치하려고 하시나요? [미리 빌드된 플러그인 검색 및 설치](/docs/ko/discover-plugins)를 참조하세요.

12 

13<h2 id="overview">

14 개요

15</h2>

16 

17마켓플레이스를 생성하고 배포하는 과정은 다음과 같습니다:

18 

191. **플러그인 생성**: skills, 에이전트, hooks, MCP 서버 또는 LSP 서버를 사용하여 하나 이상의 플러그인을 빌드합니다. 이 가이드에서는 배포할 플러그인이 이미 있다고 가정합니다. 플러그인 생성 방법에 대한 자세한 내용은 [플러그인 생성](/docs/ko/plugins)을 참조하세요.

202. **마켓플레이스 파일 생성**: 플러그인을 나열하고 플러그인을 찾을 위치를 정의하는 `marketplace.json`을 정의합니다. [마켓플레이스 파일 생성](#create-the-marketplace-file)을 참조하세요.

213. **마켓플레이스 호스팅**: GitHub, GitLab 또는 다른 git 호스트에 푸시합니다. [마켓플레이스 호스팅 및 배포](#host-and-distribute-marketplaces)를 참조하세요.

224. **사용자와 공유**: 사용자가 `/plugin marketplace add`로 마켓플레이스를 추가하고 개별 플러그인을 설치합니다. [플러그인 검색 및 설치](/docs/ko/discover-plugins)를 참조하세요.

23 

24마켓플레이스가 라이브 상태가 되면 저장소에 변경 사항을 푸시하여 업데이트할 수 있습니다. 사용자는 `/plugin marketplace update`로 로컬 복사본을 새로 고칩니다.

25 

26<h2 id="walkthrough-create-a-local-marketplace">

27 연습: 로컬 마켓플레이스 생성

28</h2>

29 

30이 예제에서는 하나의 플러그인으로 마켓플레이스를 생성합니다: 코드 리뷰를 위한 `quality-review` skill입니다. 디렉터리 구조를 생성하고, skill을 추가하고, 플러그인 매니페스트와 마켓플레이스 카탈로그를 생성한 다음, 설치하고 테스트합니다.

31 

32<Steps>

33 <Step title="디렉터리 구조 생성">

34 ```bash theme={null}

35 mkdir -p my-marketplace/.claude-plugin

36 mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin

37 mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review

38 ```

39 </Step>

40 

41 <Step title="skill 생성">

42 `quality-review` skill이 수행하는 작업을 정의하는 `SKILL.md` 파일을 생성합니다.

43 

44 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}

45 ---

46 description: Review code for bugs, security, and performance

47 ---

48 

49 선택한 코드 또는 최근 변경 사항을 다음 항목에 대해 검토합니다:

50 - 잠재적 버그 또는 엣지 케이스

51 - 보안 문제

52 - 성능 문제

53 - 가독성 개선

54 

55 간결하고 실행 가능한 내용을 제공합니다.

56 ```

57 </Step>

58 

59 <Step title="플러그인 매니페스트 생성">

60 플러그인을 설명하는 `plugin.json` 파일을 생성합니다. 매니페스트는 `.claude-plugin/` 디렉터리에 위치합니다.

61 

62 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}

63 {

64 "name": "quality-review-plugin",

65 "description": "Adds a quality-review skill for quick code reviews",

66 "version": "1.0.0",

67 "author": {

68 "name": "Your Name"

69 }

70 }

71 ```

72 

73 <Note>

74 `version`을 설정하면 사용자는 이 필드를 변경할 때만 업데이트를 받으므로, 모든 릴리스에서 이를 증가시킵니다. [`command` source](#command-sources)가 있는 플러그인은 이 필드로 고정되지 않습니다. [로컬 디렉터리에서 추가된 마켓플레이스에서 제자리에 로드](/docs/ko/plugins-reference#plugin-caching-and-file-resolution)되는 플러그인도 마찬가지입니다. `version`을 생략하면, 버전은 [버전 관리](/docs/ko/plugins-reference#version-management)의 다음 source에서 나옵니다.

75 </Note>

76 </Step>

77 

78 <Step title="마켓플레이스 파일 생성">

79 플러그인을 나열하는 마켓플레이스 카탈로그를 생성합니다.

80 

81 ```json my-marketplace/.claude-plugin/marketplace.json theme={null}

82 {

83 "name": "my-plugins",

84 "owner": {

85 "name": "Your Name"

86 },

87 "plugins": [

88 {

89 "name": "quality-review-plugin",

90 "source": "./plugins/quality-review-plugin",

91 "description": "Adds a quality-review skill for quick code reviews"

92 }

93 ]

94 }

95 ```

96 </Step>

97 

98 <Step title="추가 및 설치">

99 `my-marketplace`를 포함하는 디렉터리에서 Claude Code를 시작하고 다음 명령을 실행합니다. install 명령은 설치 범위를 선택하여 설치를 확인하는 플러그인 세부 정보 보기를 엽니다. 설치 요약을 확인합니다: `Run /reload-plugins to activate.`를 보고하면 [플러그인 변경 사항을 다시 시작하지 않고 적용](/docs/ko/discover-plugins#apply-plugin-changes-without-restarting)을 참조하세요.

100 

101 ```shell theme={null}

102 /plugin marketplace add ./my-marketplace

103 /plugin install quality-review-plugin@my-plugins

104 ```

105 </Step>

106 

107 <Step title="시도해보기">

108 편집기에서 일부 코드를 선택하고 새 skill을 실행합니다. 플러그인 skill은 플러그인 이름으로 네임스페이스됩니다.

109 

110 ```shell theme={null}

111 /quality-review-plugin:quality-review

112 ```

113 </Step>

114</Steps>

115 

116플러그인이 수행할 수 있는 작업(hooks, 에이전트, MCP 서버 및 LSP 서버 포함)에 대해 자세히 알아보려면 [플러그인](/docs/ko/plugins)을 참조하세요.

117 

118<Note>

119 **플러그인 설치 방법**: 사용자가 플러그인을 설치하면 Claude Code는 플러그인 디렉터리를 캐시 위치에 복사합니다. 플러그인이 제자리에 로드되지 않는 한 말입니다. link mode의 [`command` source](#copy-mode-and-link-mode)는 제자리에 로드되며, [로컬 디렉터리에서 추가된 마켓플레이스의 상대 경로 source](#relative-paths)도 마찬가지입니다. 복사된 플러그인은 `../shared-utils`와 같은 경로를 사용하여 디렉터리 외부의 파일을 참조할 수 없습니다. 왜냐하면 해당 파일이 복사되지 않기 때문입니다.

120 

121 플러그인 간에 파일을 공유해야 하는 경우 symlink를 사용합니다. 자세한 내용은 [플러그인 캐싱 및 파일 해석](/docs/ko/plugins-reference#plugin-caching-and-file-resolution)을 참조하세요.

122</Note>

123 

124<h2 id="create-the-marketplace-file">

125 마켓플레이스 파일 생성

126</h2>

127 

128저장소 루트에 `.claude-plugin/marketplace.json`을 생성합니다. 이 파일은 마켓플레이스의 이름, 소유자 정보 및 소스가 있는 플러그인 목록을 정의합니다.

129 

130각 플러그인 항목에는 최소한 `name`과 `source`(Claude Code가 가져올 위치를 알려주는)가 필요합니다. 사용 가능한 모든 필드는 아래의 [전체 스키마](#marketplace-schema)를 참조하세요.

131 

132```json theme={null}

133{

134 "name": "company-tools",

135 "owner": {

136 "name": "DevTools Team",

137 "email": "devtools@example.com"

138 },

139 "plugins": [

140 {

141 "name": "code-formatter",

142 "source": "./plugins/formatter",

143 "description": "저장 시 자동 코드 포맷팅",

144 "version": "2.1.0",

145 "author": {

146 "name": "DevTools Team"

147 }

148 },

149 {

150 "name": "deployment-tools",

151 "source": {

152 "source": "github",

153 "repo": "company/deploy-plugin"

154 },

155 "description": "배포 자동화 도구"

156 }

157 ]

158}

159```

160 

161<h2 id="marketplace-schema">

162 마켓플레이스 스키마

163</h2>

164 

165<h3 id="required-fields">

166 필수 필드

167</h3>

168 

169| 필드 | 유형 | 설명 | 예제 |

170| :-------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------- |

171| `name` | string | kebab-case의 마켓플레이스 식별자(공백, 제어 문자 또는 양방향 서식 문자 없음). 이는 공개 대면입니다: 사용자는 플러그인을 설치할 때 이를 봅니다(예: `/plugin install my-tool@your-marketplace`). 각 사용자는 이름당 하나의 마켓플레이스만 등록할 수 있습니다: 동일한 이름으로 두 번째 마켓플레이스를 추가하면 Claude Code가 첫 번째를 대체합니다. 하나의 마켓플레이스 이름 아래에 여러 플러그인을 게시하려면 [단일 `marketplace.json`](#create-the-marketplace-file)에 모두 나열하세요. | `"acme-tools"` |

172| `owner` | object | 마켓플레이스 유지 관리자 정보. [소유자 필드](#owner-fields) 참조 | |

173| `plugins` | array | 사용 가능한 플러그인 목록 | [플러그인 항목](#plugin-entries) 참조 |

174 

175<Note>

176 **예약된 이름**: 다음 마켓플레이스 이름은 공식 Anthropic 사용을 위해 예약되어 있으며 타사 마켓플레이스에서 사용할 수 없습니다: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `claude-plugins-community`, `claude-community`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `anthropic-agent-skills`, `knowledge-work-plugins`, `life-sciences`, `claude-for-legal`, `claude-for-financial-services`, `financial-services-plugins`, `first-party-plugins`, `claude-tag-plugins`, `healthcare`. 공식 마켓플레이스를 사칭하는 이름(예: `official-claude-plugins` 또는 `anthropic-plugins-v2`)도 차단됩니다. 이러한 이름을 예약하면 타사 마켓플레이스가 자신을 Anthropic 게시 소스로 제시하는 것을 방지합니다.

177 

178 Claude Code는 마켓플레이스를 추가할 때뿐만 아니라 마켓플레이스를 로드할 때마다 예약된 이름을 다시 확인합니다. 이름이 예약되기 전에 이러한 이름 중 하나로 등록된 마켓플레이스는 로드를 중지하고 [신뢰할 수 없는 소스에서 등록됨](/docs/ko/errors#marketplace-is-registered-from-an-untrusted-source)을 보고합니다. 해당 마켓플레이스를 제거하고 공식 Anthropic 소스에서 다시 추가하세요. 새로 예약된 이름의 영향을 받는 타사 마켓플레이스는 다른 이름으로 다시 추가하는 즉시 다시 로드됩니다. v2.1.205 이전에는 `first-party-plugins` 및 `healthcare`가 예약되지 않았으며, 예약된 이름으로 이미 등록된 마켓플레이스는 계속 로드되었습니다. v2.1.265 이전에는 `claude-tag-plugins`이 예약되지 않았습니다.

179 

180 마켓플레이스의 이름을 `npm`, `pip`, `uv`, `cargo`, `github`, 또는 `gh`로 지정할 수도 없습니다(대소문자 구분 없음). 이 확인은 Claude Code v2.1.275 이상이 필요합니다.

181</Note>

182 

183<h3 id="owner-fields">

184 소유자 필드

185</h3>

186 

187| 필드 | 유형 | 필수 | 설명 |

188| :------ | :----- | :-- | :------------------------- |

189| `name` | string | 예 | 유지 관리자 또는 팀의 이름 |

190| `email` | string | 아니오 | 유지 관리자의 연락처 이메일 |

191| `url` | string | 아니오 | 웹사이트, GitHub 프로필 또는 조직 URL |

192 

193<h3 id="optional-fields">

194 선택적 필드

195</h3>

196 

197| 필드 | 유형 | 설명 |

198| :------------------------------------ | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

199| `$schema` | string | 편집기 자동 완성 및 유효성 검사를 위한 JSON Schema URL입니다. Claude Code는 로드 시 이 필드를 무시합니다. |

200| `description` | string | 간단한 마켓플레이스 설명 |

201| `version` | string | 마켓플레이스 매니페스트 버전 |

202| `metadata.pluginRoot` | string | Claude Code가 베어 플러그인 소스 이름을 확인하는 디렉터리입니다. [상대 경로](#relative-paths)를 참조하세요. Claude Code v2.1.239 이상이 필요합니다. |

203| `allowCrossMarketplaceDependenciesOn` | array | 이 마켓플레이스의 플러그인이 의존할 수 있는 다른 마켓플레이스입니다. 여기에 나열되지 않은 마켓플레이스의 종속성은 설치 시 차단됩니다. [다른 마켓플레이스의 플러그인에 의존](/docs/ko/plugin-dependencies#depend-on-a-plugin-from-another-marketplace)을 참조하세요. |

204| `renames` | object | 이전 플러그인 `name`을 현재 이름으로 매핑하거나, 플러그인이 제거된 경우 `null`로 매핑합니다. `plugins`의 항목을 이름 변경하거나 제거할 때 기존 사용자가 자동으로 마이그레이션되도록 합니다. [플러그인 이름 변경 또는 제거](#rename-or-remove-a-plugin)를 참조하세요. Claude Code v2.1.193 이상이 필요합니다. |

205 

206`description` 및 `version`은 이전 버전과의 호환성을 위해 `metadata` 아래에서도 허용됩니다.

207 

208<h2 id="plugin-entries">

209 플러그인 항목

210</h2>

211 

212`plugins` 배열의 각 플러그인 항목은 플러그인과 플러그인을 찾을 위치를 설명합니다. [플러그인 매니페스트 스키마](/docs/ko/plugins-reference#plugin-manifest-schema)의 모든 필드(예: `description`, `version`, `author`, `commands`, `hooks` 등)와 이러한 마켓플레이스 특정 필드를 포함할 수 있습니다: `source`, `category`, `tags`, `strict`, `relevance`, `headers`, 및 `headersHelper`.

213 

214<h3 id="required-fields-2">

215 필수 필드

216</h3>

217 

218| 필드 | 유형 | 설명 |

219| :------- | :------------- | :--------------------------------------------------------------------------------------------------------------------------- |

220| `name` | string | kebab-case의 플러그인 식별자(공백, 제어 문자 또는 양방향 서식 문자 없음). 이는 공개 대면입니다: 사용자는 설치할 때 이를 봅니다(예: `/plugin install my-plugin@marketplace`). |

221| `source` | string\|object | 플러그인을 가져올 위치([아래 플러그인 소스](#plugin-sources) 참조) |

222 

223<h3 id="optional-plugin-fields">

224 선택적 플러그인 필드

225</h3>

226 

227**표준 메타데이터 필드:**

228 

229| 필드 | 유형 | 설명 |

230| :--------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

231| `displayName` | string | UI 표면에 표시되는 사람이 읽을 수 있는 이름입니다. 항목과 플러그인의 `plugin.json` 모두 설정하지 않으면 사용자는 플러그인의 `name`을 봅니다. 공백과 모든 대소문자를 포함할 수 있습니다. 네임스페이싱이나 조회에 사용되지 않습니다. |

232| `description` | string | 간단한 플러그인 설명 |

233| `version` | string | 플러그인 버전. 설정된 경우(여기 또는 `plugin.json`에서), 플러그인은 이 문자열로 고정되며 사용자는 변경될 때만 업데이트를 받습니다. [`command` 소스](#command-sources)가 있는 플러그인은 두 필드 모두에 의해 고정되지 않습니다. 마켓플레이스에서 로컬 디렉터리로 추가된 [제자리에 로드된](/docs/ko/plugins-reference#plugin-caching-and-file-resolution) 플러그인도 마찬가지입니다. 두 위치 모두에 설정되지 않은 경우, 버전은 [버전 관리](/docs/ko/plugins-reference#version-management)의 다음 소스에서 나옵니다. |

234| `author` | object | 플러그인 작성자 정보(`name` 필수; `email` 및 `url` 선택) |

235| `homepage` | string | 플러그인 홈페이지 또는 문서 URL |

236| `repository` | string | 소스 코드 저장소 URL |

237| `license` | string | SPDX 라이선스 식별자(예: MIT, Apache-2.0) |

238| `keywords` | array | 플러그인 검색 및 분류를 위한 태그 |

239| `metadata` | object | 자격 또는 카탈로그 데이터와 같은 자신의 필드를 위한 자유 형식 객체입니다. Claude Code는 이를 읽지 않습니다. v2.1.222 이전에는 `claude plugin validate`가 키를 인식되지 않은 필드로 보고했습니다. |

240| `category` | string | 조직을 위한 플러그인 카테고리 |

241| `tags` | array | 검색 가능성을 위한 태그 |

242| `strict` | boolean | `plugin.json`이 구성 요소 정의의 권한인지 여부를 제어합니다(기본값: true). 아래의 [Strict 모드](#strict-mode)를 참조하세요. |

243| `relevance` | object | Claude Code가 사용자에게 이 플러그인을 제안할 시기를 알려주는 신호입니다. 관리자가 관리 설정에서 허용 목록에 추가한 마켓플레이스에만 적용됩니다. [조직을 위한 플러그인 권장](/docs/ko/plugin-relevance)을 참조하세요. |

244| `defaultEnabled` | boolean | 플러그인이 설치 후 활성화되는지 여부(기본값: true). 사용자가 옵트인할 때까지 플러그인을 비활성화된 상태로 설치하려면 `false`로 설정합니다. 플러그인의 `plugin.json`에 있는 동일한 필드보다 우선합니다. [기본 활성화](/docs/ko/plugins-reference#default-enablement)를 참조하세요. |

245 

246항목과 플러그인의 자체 `plugin.json` 모두 표시 필드 `displayName`, `description`, `author`, `homepage`, `repository`, `license`, 및 `keywords`를 설정할 수 있습니다. 플러그인 목록 및 세부 정보에서 설치 전후:

247 

248* 항목에 설정한 필드의 경우, 사용자는 `plugin.json`이 다른 값을 설정하더라도 항목의 값을 봅니다.

249* 항목이 설정하지 않은 필드의 경우, 사용자는 `plugin.json` 값을 봅니다.

250 

251설치 전에 Claude Code는 `plugin.json`을 [상대 경로 소스](#relative-paths)가 있는 항목에 대해서만 읽을 수 있으며, 이 항목의 플러그인 파일은 마켓플레이스 내부에 있습니다. 다른 소스 유형이 있는 항목의 경우, 사용자는 플러그인을 설치할 때까지 항목의 자체 필드만 봅니다.

252 

253**구성 요소 구성 필드:**

254 

255| 필드 | 유형 | 설명 |

256| :----------- | :------------- | :-------------------------------------------- |

257| `skills` | string\|array | `<name>/SKILL.md`를 포함하는 skill 디렉터리의 사용자 정의 경로 |

258| `commands` | string\|array | 평면 `.md` skill 파일 또는 디렉터리의 사용자 정의 경로 |

259| `agents` | string\|array | 에이전트 파일의 사용자 정의 경로 |

260| `hooks` | string\|object | 사용자 정의 hooks 구성 또는 hooks 파일 경로 |

261| `mcpServers` | string\|object | MCP 서버 구성 또는 MCP 구성 경로 |

262| `lspServers` | string\|object | LSP 서버 구성 또는 LSP 구성 경로 |

263 

264**아카이브 인증 필드:**

265 

266항목에 자격 증명이 필요한 서버의 [`archive` 소스](#zip-archives)가 있을 때 이를 설정합니다.

267 

268| 필드 | 유형 | 설명 |

269| :-------------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

270| `headers` | object | Claude Code가 이 항목의 아카이브를 다운로드할 때 보내는 HTTP 헤더입니다. 동일한 이름의 마켓플레이스 헤더를 재정의합니다. Claude Code v2.1.238 이상이 필요합니다. |

271| `headersHelper` | string | 만료되는 자격 증명에 대해 이 항목의 아카이브 다운로드를 위한 HTTP 헤더를 하나의 JSON 객체로 인쇄하는 명령입니다. [아카이브 다운로드 인증](#authenticate-archive-downloads)을 참조하세요. 항목은 또한 [`"strict": false`](#strict-mode)를 설정해야 합니다. Claude Code v2.1.238 이상이 필요합니다. |

272 

273<h2 id="plugin-sources">

274 플러그인 소스

275</h2>

276 

277플러그인 소스는 Claude Code에 마켓플레이스에 나열된 각 개별 플러그인을 가져올 위치를 알려줍니다. 이는 `marketplace.json`의 각 플러그인 항목의 `source` 필드에 설정됩니다.

278 

279Claude Code는 설치된 각 플러그인을 `~/.claude/plugins/cache`의 로컬 버전 관리 플러그인 캐시에 복사합니다. 단, 플러그인이 제자리에서 로드되는 경우는 제외됩니다. [링크 모드의 `command` 소스](#copy-mode-and-link-mode)는 제자리에서 로드되며, [상대 경로 소스](#relative-paths)도 로컬 디렉터리에서 추가된 마켓플레이스에서 제자리에 로드됩니다. Claude Code는 또한 [플러그인의 적격 Node.js 패키지 종속성](/docs/ko/plugins-reference#node-js-package-dependencies)을 캐시된 복사본에 설치합니다. [플러그인 캐싱 및 파일 해석](/docs/ko/plugins-reference#plugin-caching-and-file-resolution)을 참조하여 로컬 디렉터리 마켓플레이스에서 제자리에 로드된 플러그인이 편집 내용을 선택하는 방법을 알아보세요.

280 

281| 소스 | 유형 | 필드 | 참고 |

282| ------------ | ----------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

283| 상대 경로 | `string` (예: `"./my-plugin"`) | 없음 | 마켓플레이스 저장소 내의 로컬 디렉터리. `./`로 시작해야 합니다. [`metadata.pluginRoot`](#relative-paths) 아래에 bare name을 작성하지 않는 한. Claude Code는 `.claude-plugin/` 디렉터리가 아닌 마켓플레이스 루트에 상대적으로 경로를 해석합니다 |

284| `github` | object | `repo`, `ref?`, `sha?` | |

285| `url` | object | `url`, `ref?`, `sha?` | Git URL 소스 |

286| `git-subdir` | object | `url`, `path`, `ref?`, `sha?` | git 저장소 내의 하위 디렉터리. 모노레포의 대역폭을 최소화하기 위해 희소하게 복제합니다 |

287| `npm` | object | `package`, `version?`, `registry?` | npm 패키지. npm 클라이언트로 가져오고 설치 스크립트를 실행하지 않고 압축 해제됩니다 |

288| `archive` | object | `url`, `sha256?` | HTTPS를 통해 다운로드된 Zip 아카이브. 사용자의 머신에 git 또는 npm 없이 작동합니다. Claude Code v2.1.224 이상 필요 |

289| `command` | object | `command`, `timeout?`, `mode?` | 로컬 명령어를 실행하여 생성된 플러그인 디렉터리. 변경 사항을 선택하기 위해 세션당 한 번 다시 실행됩니다. Claude Code v2.1.229 이상 필요 |

290 

291<Note>

292 **마켓플레이스 소스 vs 플러그인 소스**: 이는 다양한 것을 제어하는 다양한 개념입니다.

293 

294 * **마켓플레이스 소스**: `marketplace.json` 카탈로그 자체를 가져올 위치. 사용자가 `/plugin marketplace add`를 실행하거나 `extraKnownMarketplaces` 설정에서 설정합니다. Git 기반 마켓플레이스 소스는 `ref`(분기/태그)를 지원하지만 `sha`는 지원하지 않습니다.

295 * **플러그인 소스**: 마켓플레이스에 나열된 개별 플러그인을 가져올 위치. `marketplace.json` 내의 각 플러그인 항목의 `source` 필드에 설정됩니다. Git 기반 플러그인 소스는 `ref`(분기/태그)와 `sha`(정확한 커밋) 모두를 지원합니다.

296 

297 예를 들어, `acme-corp/plugin-catalog`에서 호스팅되는 마켓플레이스(마켓플레이스 소스)는 `acme-corp/code-formatter`에서 가져온 플러그인을 나열할 수 있습니다(플러그인 소스). 마켓플레이스 소스와 플러그인 소스는 다양한 저장소를 가리키며 독립적으로 고정됩니다.

298</Note>

299 

300아래의 git 기반 소스 유형은 `github`, `url`, 및 `git-subdir`입니다. `ref`와 `sha`가 모두 설정되면 `sha`가 유효한 핀입니다. Claude Code는 고정된 커밋을 직접 가져오고 체크아웃합니다.

301 

302GitHub, GitLab, Bitbucket을 포함한 대부분의 git 호스트에서 이는 분기 또는 태그가 업스트림에서 삭제되었더라도 커밋이 저장소에서 여전히 도달 가능한 한 설치가 성공함을 의미합니다. AWS CodeCommit과 같은 일부 서버는 SHA로 커밋을 가져오는 것을 지원하지 않습니다. 이러한 서버에서는 `ref`가 여전히 존재해야 하고 고정된 커밋이 이로부터 도달 가능해야 합니다.

303 

304**조직 설정 > 플러그인**을 통해 플러그인을 배포하는 경우 일부 소스 유형만 허용됩니다. [조직 설정을 통해 배포](#distribute-through-organization-settings)를 참조하세요.

305 

306<h3 id="relative-paths">

307 상대 경로

308</h3>

309 

310동일한 저장소의 플러그인의 경우 `./`로 시작하는 경로를 사용합니다:

311 

312```json theme={null}

313{

314 "name": "my-plugin",

315 "source": "./plugins/my-plugin"

316}

317```

318 

319경로는 마켓플레이스 루트(`.claude-plugin/`을 포함하는 디렉터리)에 상대적으로 해석됩니다. 위의 예에서 `./plugins/my-plugin`은 `marketplace.json`이 `<repo>/.claude-plugin/marketplace.json`에 있더라도 `<repo>/plugins/my-plugin`을 가리킵니다. 마켓플레이스 루트 외부로 나가기 위해 `../`를 사용하지 마세요. macOS 및 Linux에서 Claude Code는 선행 `./` 이후 어디든 백슬래시가 있는 항목 경로를 거부하므로 모든 플랫폼에서 구분 기호를 `/`로 작성합니다.

320 

321bare name은 `/`가 없는 단일 디렉터리 이름입니다(예: `"formatter"`). `./` 경로 대신 bare name을 작성하려면 [`metadata.pluginRoot`](#optional-fields)를 이들이 해석되는 디렉터리로 설정합니다. `"pluginRoot": "./plugins"`를 사용하면 Claude Code는 `"source": "formatter"`를 `./plugins/formatter`로 해석합니다. Claude Code v2.1.239 이상 필요합니다.

322 

323`metadata.pluginRoot`는 그 자체로 마켓플레이스 내의 상대 경로여야 합니다. Claude Code는 이미 `./`로 시작하는 소스에 대해 이를 무시합니다. `/`를 포함하는 소스(예: `team-a/formatter`)는 bare name이 아니며 `metadata.pluginRoot`가 설정되어 있더라도 여전히 `./` 접두사가 필요합니다.

324 

325<Note>

326 Claude Code는 마켓플레이스의 로컬 복사본에 대해 상대 경로를 해석하므로 사용자가 git 소스 또는 로컬 디렉터리에서 마켓플레이스를 추가할 때 작동합니다. 사용자가 `marketplace.json` 파일에 대한 직접 URL을 통해 마켓플레이스를 추가하면 상대 경로가 해석되지 않습니다. Claude Code는 해당 파일만 다운로드하기 때문입니다. URL 기반 배포의 경우 대신 다른 [플러그인 소스](#plugin-sources)를 사용합니다. 자세한 내용은 [문제 해결](#plugins-with-relative-paths-fail-in-url-based-marketplaces)을 참조하세요.

327</Note>

328 

329<h3 id="github-repositories">

330 GitHub 저장소

331</h3>

332 

333```json theme={null}

334{

335 "name": "github-plugin",

336 "source": {

337 "source": "github",

338 "repo": "owner/plugin-repo"

339 }

340}

341```

342 

343특정 분기, 태그 또는 커밋에 고정할 수 있습니다:

344 

345```json theme={null}

346{

347 "name": "github-plugin",

348 "source": {

349 "source": "github",

350 "repo": "owner/plugin-repo",

351 "ref": "v2.0.0",

352 "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"

353 }

354}

355```

356 

357| 필드 | 유형 | 설명 |

358| :----- | :----- | :------------------------------------ |

359| `repo` | string | 필수. `owner/repo` 형식의 GitHub 저장소 |

360| `ref` | string | 선택. Git 분기 또는 태그(저장소 기본 분기로 기본값) |

361| `sha` | string | 선택. 정확한 버전에 고정하기 위한 전체 40자 git 커밋 SHA |

362 

363<h3 id="git-repositories">

364 Git 저장소

365</h3>

366 

367```json theme={null}

368{

369 "name": "git-plugin",

370 "source": {

371 "source": "url",

372 "url": "https://gitlab.com/team/plugin.git"

373 }

374}

375```

376 

377특정 분기, 태그 또는 커밋에 고정할 수 있습니다:

378 

379```json theme={null}

380{

381 "name": "git-plugin",

382 "source": {

383 "source": "url",

384 "url": "https://gitlab.com/team/plugin.git",

385 "ref": "main",

386 "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"

387 }

388}

389```

390 

391| 필드 | 유형 | 설명 |

392| :---- | :----- | :-------------------------------------------------------------------------------------------------------------- |

393| `url` | string | 필수. 전체 git 저장소 URL(`https://` 또는 `git@`). `.git` 접미사는 선택 사항이므로 Azure DevOps 및 AWS CodeCommit URL(접미사 없음)이 작동합니다 |

394| `ref` | string | 선택. Git 분기 또는 태그(저장소 기본 분기로 기본값) |

395| `sha` | string | 선택. 정확한 버전에 고정하기 위한 전체 40자 git 커밋 SHA |

396 

397<h3 id="git-subdirectories">

398 Git 하위 디렉터리

399</h3>

400 

401`git-subdir`을 사용하여 git 저장소의 하위 디렉터리 내에 있는 플러그인을 가리킵니다. Claude Code는 희소하고 부분적인 복제를 사용하여 하위 디렉터리만 가져오므로 대규모 모노레포의 대역폭을 최소화합니다.

402 

403```json theme={null}

404{

405 "name": "my-plugin",

406 "source": {

407 "source": "git-subdir",

408 "url": "https://github.com/acme-corp/monorepo.git",

409 "path": "tools/claude-plugin"

410 }

411}

412```

413 

414특정 분기, 태그 또는 커밋에 고정할 수 있습니다:

415 

416```json theme={null}

417{

418 "name": "my-plugin",

419 "source": {

420 "source": "git-subdir",

421 "url": "https://github.com/acme-corp/monorepo.git",

422 "path": "tools/claude-plugin",

423 "ref": "v2.0.0",

424 "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"

425 }

426}

427```

428 

429`url` 필드는 GitHub 단축형(`owner/repo`) 또는 SSH URL(`git@github.com:owner/repo.git`)도 허용합니다.

430 

431| 필드 | 유형 | 설명 |

432| :----- | :----- | :----------------------------------------------------------- |

433| `url` | string | 필수. Git 저장소 URL, GitHub `owner/repo` 단축형 또는 SSH URL |

434| `path` | string | 필수. 플러그인을 포함하는 저장소 내의 하위 디렉터리 경로(예: `"tools/claude-plugin"`) |

435| `ref` | string | 선택. Git 분기 또는 태그(저장소 기본 분기로 기본값) |

436| `sha` | string | 선택. 정확한 버전에 고정하기 위한 전체 40자 git 커밋 SHA |

437 

438<h3 id="npm-packages">

439 npm 패키지

440</h3>

441 

442npm 소스는 공개 npm 레지스트리 또는 팀이 호스팅하는 개인 레지스트리의 모든 패키지를 지정할 수 있습니다. Claude Code는 npm 클라이언트로 패키지를 해석하고 tarball을 다운로드한 후 플러그인 캐시에 압축 해제합니다.

443 

444패키지의 설치 스크립트(예: `preinstall` 또는 `postinstall`)는 절대 실행되지 않으며 종속성은 가져오기 중에 설치되지 않습니다.

445 

446패키지가 `package.json` 옆에 지원되는 lockfile을 제공하면 Claude Code는 스크립트가 비활성화된 상태에서 별도의 단계로 해당 [Node.js 패키지 종속성](/docs/ko/plugins-reference#node-js-package-dependencies)을 설치합니다. 그렇지 않으면 플러그인이 필요한 모든 것이 이미 빌드된 상태로 게시합니다. 다른 패키지가 필요한 MCP 서버는 `npx`를 통해 시작할 수 있으며, 이는 첫 실행 시 설치합니다.

447 

448```json theme={null}

449{

450 "name": "my-npm-plugin",

451 "source": {

452 "source": "npm",

453 "package": "@acme/claude-plugin"

454 }

455}

456```

457 

458특정 버전에 고정하려면 `version` 필드를 추가합니다:

459 

460```json theme={null}

461{

462 "name": "my-npm-plugin",

463 "source": {

464 "source": "npm",

465 "package": "@acme/claude-plugin",

466 "version": "2.1.0"

467 }

468}

469```

470 

471개인 또는 내부 레지스트리에서 설치하려면 `registry` 필드를 추가합니다:

472 

473```json theme={null}

474{

475 "name": "my-npm-plugin",

476 "source": {

477 "source": "npm",

478 "package": "@acme/claude-plugin",

479 "version": "^2.0.0",

480 "registry": "https://npm.example.com"

481 }

482}

483```

484 

485| 필드 | 유형 | 설명 |

486| :--------- | :----- | :------------------------------------------------------------ |

487| `package` | string | 필수. 패키지 이름 또는 범위 지정 패키지(예: `@org/plugin`) |

488| `version` | string | 선택. 버전 또는 버전 범위(예: `2.1.0`, `^2.0.0`, `~1.5.0`) |

489| `registry` | string | 선택. 사용자 정의 npm 레지스트리 URL. 시스템 npm 레지스트리(일반적으로 npmjs.org)로 기본값 |

490 

491<h3 id="zip-archives">

492 Zip 아카이브

493</h3>

494 

495`archive`를 사용하여 Claude Code가 HTTPS를 통해 다운로드하는 zip 파일로 플러그인을 배포합니다. 따라서 사용자의 머신에 git 또는 npm 없이 설치가 작동합니다. S3 버킷, Artifactory 일반 저장소 또는 nginx와 같은 정적 파일 서버 또는 아티팩트 저장소에서 파일을 호스팅합니다. Claude Code v2.1.224 이상 필요합니다. v2.1.120부터 v2.1.223까지의 버전에서는 플러그인 설치가 `This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.`으로 실패합니다. 더 오래된 버전에서는 `archive` 항목을 포함하는 마켓플레이스가 완전히 로드되지 않습니다.

496 

497이 항목은 아티팩트 서버의 zip 파일에서 플러그인을 설치합니다:

498 

499```json theme={null}

500{

501 "name": "my-plugin",

502 "source": {

503 "source": "archive",

504 "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip"

505 }

506}

507```

508 

509zip을 빌드할 때 플러그인의 내용을 직접 압축하거나 플러그인 폴더 자체를 압축할 수 있습니다. Claude Code는 아카이브의 맨 위에서 `.claude-plugin/`을 찾은 다음 단일 최상위 폴더 내에서 찾으므로 두 레이아웃 모두 설치됩니다:

510 

511```text theme={null}

512my-plugin.zip my-plugin.zip

513├── .claude-plugin/ └── my-plugin/

514│ └── plugin.json ├── .claude-plugin/

515└── commands/ │ └── plugin.json

516 └── commands/

517```

518 

519Claude Code는 한 폴더보다 더 깊게 찾지 않으므로 더 아래에 중첩된 플러그인은 설치되지 않습니다. Claude Code는 256 MiB보다 큰 아카이브를 거부합니다.

520 

521정확한 파일을 고정하려면 아카이브의 다이제스트와 함께 `sha256` 필드를 추가합니다:

522 

523```json theme={null}

524{

525 "name": "my-plugin",

526 "source": {

527 "source": "archive",

528 "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip",

529 "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"

530 }

531}

532```

533 

534다운로드된 파일이 핀과 일치하지 않으면 Claude Code는 설치를 거부하고 [`Plugin archive integrity check failed`](/docs/ko/errors#plugin-archive-integrity-check-failed)를 보고합니다.

535 

536아카이브 소스는 다음 필드를 허용합니다:

537 

538| 필드 | 유형 | 설명 |

539| :------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |

540| `url` | string | 필수. zip 아카이브의 HTTPS URL. Claude Code는 `http://` URL과 loopback, link-local 및 cloud-metadata 호스트를 거부합니다. 모든 리디렉션 홉은 동일한 규칙을 만족해야 하거나 Claude Code는 다운로드를 거부합니다 |

541| `sha256` | string | 선택. 아카이브의 SHA-256 다이제스트(64개의 16진 문자, 대문자 또는 소문자). Claude Code는 모든 다운로드를 이에 대해 검증하고 불일치 시 설치를 거부합니다 |

542 

543`sha256` 다이제스트는 `plugin.json` 또는 마켓플레이스 항목이 버전을 선언하지 않을 때 플러그인의 버전으로도 작동합니다. [버전 관리](/docs/ko/plugins-reference#version-management)를 참조하세요. `version`을 선언하면 해당 버전 문자열이 업데이트 신호이므로 zip과 다이제스트를 변경한 후 버전도 범프하거나 사용자는 캐시된 복사본을 유지합니다.

544 

545<h4 id="authenticate-archive-downloads">

546 아카이브 다운로드 인증

547</h4>

548 

549개인 레지스트리에서의 다운로드와 같은 아카이브 다운로드를 인증하려면 Claude Code가 이를 통해 보내는 HTTP 헤더를 설정합니다. [`extraKnownMarketplaces`](/docs/ko/settings-reference#extraknownmarketplaces) 항목과 같이 마켓플레이스를 등록한 `url` 소스에서 `headers`를 설정합니다. Claude Code v2.1.238 이상에서는 플러그인의 항목에서 `source` 옆에 설정할 수 있습니다.

550 

551`headers`에 넣을 값이 단기간인 경우(예: 레지스트리가 요청 시 발행하는 토큰) 대신 같은 위치에 `headersHelper` 명령어를 설정합니다. Claude Code는 명령어를 실행하고 인쇄하는 JSON 객체를 해당 위치의 헤더로 보냅니다. Claude Code v2.1.238 이상 필요합니다.

552 

553선택한 위치는 어느 다운로드가 헤더를 받고 Claude Code가 명령어를 실행할 때를 결정합니다:

554 

555| 위치 | 헤더를 받는 다운로드 | Claude Code가 `headersHelper` 설정을 실행할 때 |

556| :-------------- | :----------------------------------------------- | :--------------------------------------------------------------------------------------------------------- |

557| 마켓플레이스 `url` 소스 | 마켓플레이스 URL의 원본에서의 아카이브 다운로드. 즉, 동일한 스킴, 호스트 및 포트 | 마켓플레이스의 `marketplace.json`을 가져올 때마다 그리고 해당 원본에서 아카이브를 다운로드할 때마다. Claude Code는 한 번의 실행 출력을 최대 60초 동안 재사용합니다 |

558| 플러그인 항목 | 해당 항목의 다운로드만 | 사용자가 해당 플러그인 하나를 설치하거나 업데이트하고 [명령어를 수락](#how-users-accept-a-headershelper-command)할 때만 |

559 

560두 위치 모두 동일한 이름의 헤더를 설정하면 Claude Code는 항목의 값을 보냅니다. 한 위치 내에서 명령어가 인쇄하는 헤더는 동일한 이름의 `headers`에 나열된 헤더를 재정의합니다.

561 

562<h5 id="add-a-headershelper-to-a-plugin-entry">

563 플러그인 항목에 headersHelper 추가

564</h5>

565 

566이 항목은 `source` 옆에 `headersHelper`를 설정합니다. 또한 `"strict": false`를 설정하며, Claude Code는 `headersHelper`를 설정하는 `marketplace.json` 항목에 이를 요구합니다. [`"strict": false`](#strict-mode)를 사용하면 마켓플레이스 항목이 플러그인의 전체 정의이므로 사용자는 명령어를 수락하기 전에 플러그인에 포함된 내용을 검토할 수 있습니다:

567 

568```json theme={null}

569{

570 "name": "my-plugin",

571 "description": "Formatting commands for internal services",

572 "strict": false,

573 "commands": "./commands",

574 "source": {

575 "source": "archive",

576 "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"

577 },

578 "headersHelper": "/opt/bin/mint-registry-token.sh"

579}

580```

581 

582항목을 확인하려면 `claude plugin install my-plugin@your-marketplace`를 실행합니다. Claude Code는 명령어와 아카이브 URL을 표시하고 수락 후 zip을 다운로드합니다.

583 

584v2.1.238 이전에는 Claude Code가 항목의 아카이브를 `headers` 또는 `headersHelper` 없이 다운로드했으므로 이들에 의존하는 설치가 `HTTP 401 while downloading plugin archive from`으로 실패했으며, 그 뒤에 URL이 있고 레지스트리의 상태 코드가 401 대신 있었습니다.

585 

586<h4 id="write-the-headershelper-command">

587 headersHelper 명령어 작성

588</h4>

589 

590마켓플레이스의 `url` 소스 또는 플러그인 항목에 `headersHelper`를 설정하든 명령어를 다음 요구 사항을 충족하도록 작성합니다:

591 

592* **명령어 텍스트**: 최대 500자의 인쇄 가능한 ASCII. 4개 이상의 공백이 연속되지 않음.

593* **출력**: stdout에 헤더 이름과 문자열 값의 JSON 객체 하나를 인쇄한 후 10초 내에 종료 코드 0으로 종료합니다.

594* **셸 및 작업 디렉터리**: Claude Code는 구성 디렉터리(`~/.claude` 또는 [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars#variables))에서 `sh` 또는 Windows의 `cmd.exe`를 통해 명령어를 실행합니다. 상대 경로가 해당 디렉터리에 대해 해석되므로 절대 경로 또는 `PATH`의 명령어를 제공합니다. 사용자의 프로젝트가 아닙니다.

595* **Claude Code가 제거하는 변수**: `marketplace.json` 항목 또는 프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`에 설정된 명령어의 환경에서 Claude Code는 `TOKEN`, `SECRET`, `KEY` 또는 `AUTH`와 같은 단어를 포함하는 이름의 모든 변수를 제거합니다. `ANTHROPIC_API_KEY` 포함. Claude Code는 사용자 설정, `--settings` 파일 또는 관리 설정에 설정된 명령어에 이 제거를 적용하지 않습니다.

596* **Claude Code가 설정하는 변수**: `url` 소스의 명령어에 대해 `CLAUDE_CODE_MARKETPLACE_URL` 및 `CLAUDE_CODE_MARKETPLACE_NAME`. 항목의 명령어에 대해 `CLAUDE_CODE_PLUGIN_NAME` 및 `CLAUDE_CODE_PLUGIN_ARCHIVE_URL`. `CLAUDE_CODE_MARKETPLACE_NAME`은 사용자가 URL로 마켓플레이스를 추가한 후 첫 번째 가져오기에서 설정되지 않습니다. 해당 가져오기가 이름을 제공하기 때문입니다.

597 

598bearer 토큰을 발행하는 명령어는 다음과 같은 객체를 인쇄합니다:

599 

600```json theme={null}

601{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

602```

603 

604<h4 id="when-claude-code-skips-a-headershelper-command-or-drops-its-output">

605 Claude Code가 headersHelper 명령어를 건너뛰거나 출력을 삭제할 때

606</h4>

607 

608Claude Code는 `headersHelper` 명령어를 실행하지 않거나 `headers` 또는 명령어의 출력에서 온 헤더를 삭제합니다. 이러한 상황에서:

609 

610* **명령어 실패**: 명령어가 0이 아닌 코드로 종료되거나 10초를 초과하거나 JSON 객체 이외의 것을 인쇄하면 Claude Code는 명령어를 실행한 가져오기 또는 다운로드를 수행하지 않습니다.

611* **마켓플레이스 URL이 `https://`로 시작하지 않음**: Claude Code는 해당 `url` 소스의 명령어를 실행하지 않고 `headers` 필드에 나열된 헤더만 보냅니다.

612* **리디렉션이 원본을 벗어남**: 다운로드가 아카이브 URL의 원본에서 리디렉션될 때 Claude Code는 마켓플레이스 `url` 소스와 플러그인 항목의 `headers` 값과 명령어 출력을 삭제합니다.

613* **항목이 라우팅 또는 ID 헤더를 설정함**: Claude Code는 항목의 `headers` 및 명령어 출력에서 `Host`, `Cookie` 및 `X-Forwarded-*`와 같은 요청 라우팅 및 클라이언트 ID 이름을 삭제하고 `Authorization`과 같은 인증 이름을 유지합니다. Claude Code는 모든 `marketplace.json` 항목을 이 방식으로 필터링하고 [인라인 설정 항목](/docs/ko/settings-reference#extraknownmarketplaces)은 어느 파일이 이를 선언하는지에 따라 다릅니다.

614* **`--add-dir` 디렉터리의 설정에 설정된 명령어**: Claude Code는 이를 무시합니다. `url` 소스 및 [인라인 플러그인 항목](/docs/ko/settings-reference#extraknownmarketplaces) 모두에서 그리고 해당 파일의 `headers`만 보냅니다.

615* **관리 설정이 명령어를 차단함**: [`disableCommandPluginSources`](/docs/ko/settings-reference#disablecommandpluginsources)를 `true`로 설정하면 `headersHelper` 명령어를 차단하고 [`allowManagedHooksOnly`](/docs/ko/settings-reference#allowmanagedhooksonly)도 `disableCommandPluginSources`가 명시적으로 `false`가 아닌 한 이들을 차단합니다. 두 차단 중 하나에서 Claude Code는 여전히 관리 설정 자체가 선언하는 마켓플레이스에 대해 명령어를 실행합니다.

616 

617<h4 id="how-users-accept-a-headershelper-command">

618 사용자가 headersHelper 명령어를 수락하는 방법

619</h4>

620 

621사용자는 플러그인 항목의 명령어를 설치하거나 업데이트할 때마다 해당 플러그인 하나를 설치하거나 업데이트할 때마다 수락합니다. `/plugin`의 플러그인 자신의 보기에서 또는 `claude plugin install` 또는 `claude plugin update`를 사용합니다. Claude Code는 명령어와 아카이브 URL을 표시하고 사용자가 수락한 후에만 명령어를 실행합니다.

622 

623비대화형 셸에서 [`--yes`](/docs/ko/plugins-reference#plugin-install)를 전달하여 수락합니다. 이전 `--json` 실행이 표시한 명령어만 수락하려면 실행이 보고한 `sha256`과 함께 [`--accept-command`](/docs/ko/plugins-reference#plugin-install)를 전달합니다.

624 

625Claude Code는 표시한 명령어만 실행합니다. 표시한 아카이브 URL의 경우. 항목의 명령어 또는 아카이브 URL이 그 사이에 변경되면 Claude Code는 설치 또는 업데이트를 거부합니다. 쿼리 문자열만의 변경은 계산되지 않습니다.

626 

627<h5 id="installs-and-updates-that-refuse-the-command-instead-of-asking">

628 명령어를 거부하는 대신 요청하지 않는 설치 및 업데이트

629</h5>

630 

631다른 작업에서 Claude Code는 항목의 명령어를 실행하거나 아카이브를 다운로드하지 않으므로 플러그인은 설치된 버전에 유지되거나 설치되지 않은 상태로 유지됩니다. 사용자가 보는 것은 작업에 따라 다릅니다:

632 

633* **여러 플러그인을 한 번에 설치하거나 플러그인 제안에서 또는 다른 플러그인의 종속성으로**: Claude Code는 명령어가 있는 플러그인을 거부하고 사용자를 `/plugin`의 해당 플러그인 자신의 보기로 가리킵니다. 대량 설치의 다른 플러그인은 여전히 설치됩니다. 거부된 플러그인에 의존하는 플러그인은 사용자가 거부된 플러그인을 설치할 때까지 설치되지 않습니다.

634* **백그라운드 자동 업데이트 또는 아카이브가 다운로드되지 않은 플러그인의 세션 시작**: Claude Code는 `/plugin` 오류 탭에 플러그인을 나열하므로 사용자는 수동으로 설치하거나 업데이트해야 합니다. 설치된 버전을 찾는 자동 업데이트는 아무것도 나열하지 않습니다.

635 

636<h5 id="when-a-marketplace-url-source’s-command-runs">

637 마켓플레이스 `url` 소스의 명령어가 실행될 때

638</h5>

639 

640마켓플레이스 `url` 소스의 `headersHelper`는 마켓플레이스가 게시하는 카탈로그가 아닌 설정 파일(예: [`extraKnownMarketplaces`](/docs/ko/settings-reference#extraknownmarketplaces) 항목)에 선언되므로 Claude Code는 각 설치 또는 업데이트에서 사용자에게 수락을 요청하지 않습니다. 이를 선언하는 설정 파일은 Claude Code가 실행할 때를 결정합니다:

641 

642| 설정 파일 | Claude Code가 명령어를 실행할 때 |

643| :------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |

644| 사용자 설정, `--settings` 파일 또는 머신의 관리 설정 파일 | 백그라운드 마켓플레이스 새로 고침을 포함하여 요청하지 않고 |

645| 프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json` | 사용자가 해당 폴더 자체에 대한 [작업 공간 신뢰 대화](/docs/ko/permissions#what-runs-before-you-trust-a-folder)를 수락한 후에만. `-p` 또는 SDK 세션은 이를 수락하는 것으로 계산되지 않으며 부모 폴더에 부여된 신뢰도 계산되지 않습니다 |

646| 서버 관리 설정 | 사용자가 [보안 승인 대화](/docs/ko/server-managed-settings#security-approval-dialogs)에서 전달된 설정을 승인한 후에만 |

647 

648`-p` 또는 SDK 세션에서 Claude Code는 보안 승인 대화를 표시할 수 없습니다. 다른 전달된 설정을 적용하지만 마켓플레이스 가져오기 및 명령어가 필요한 아카이브 다운로드는 사용자가 대화형 세션에서 승인할 때까지 실패합니다.

649 

650이러한 파일 중 하나의 [인라인 플러그인 항목](/docs/ko/settings-reference#extraknownmarketplaces)의 경우 Claude Code는 해당 파일의 마켓플레이스 수준 명령어와 동일한 폴더 신뢰 또는 설정 승인을 요구하며 사용자는 각 설치 또는 업데이트에서 항목의 명령어를 수락합니다.

651 

652<h3 id="command-sources">

653 명령어 소스

654</h3>

655 

656로컬로 설치된 도구가 플러그인 디렉터리를 생성할 때 `command`를 사용합니다. 예를 들어 현재 선택된 도구 체인에 대해 플러그인을 렌더링하는 IDE. Claude Code는 사용자가 플러그인을 설치할 때 명령어를 실행하고 백그라운드에서 세션당 한 번 다시 실행하므로 사용자는 도구의 변경된 출력을 다시 설치하지 않고 선택합니다. Claude Code v2.1.229 이상 필요합니다. v2.1.120부터 v2.1.228까지에서는 플러그인 설치가 `This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.`으로 실패하고 더 오래된 버전에서는 전체 마켓플레이스가 로드되지 않습니다.

657 

658이 항목은 도구가 인쇄하는 모든 디렉터리에서 플러그인을 설치합니다:

659 

660```json theme={null}

661{

662 "name": "my-plugin",

663 "source": {

664 "source": "command",

665 "command": "my-tool claude-plugin-path"

666 }

667}

668```

669 

670Claude Code는 사용자의 홈 디렉터리에서 플랫폼 셸(macOS 및 Linux의 `sh` 또는 Windows의 `cmd.exe`)을 통해 명령어를 실행합니다. 명령어는 stdout에 정확히 한 줄을 인쇄하고 코드 0으로 종료해야 합니다. 해당 줄은 명령어가 종료될 때까지 완전한 플러그인을 포함하는 디렉터리의 절대 경로이며 경로는 실행 간에 변경될 수 있습니다.

671 

672Claude Code는 `timeout` 초보다 오래 실행되는 명령어를 중지하고 설치 또는 업데이트가 실패합니다. Claude Code는 또한 이러한 경우에 인쇄된 경로를 거부하고 설치 또는 업데이트가 동일한 방식으로 실패합니다:

673 

674* 디렉터리의 최상위 수준에 플러그인 콘텐츠가 없습니다. 예를 들어 `.claude-plugin/` 디렉터리 또는 `skills/`, `commands/`, `agents/` 또는 `hooks/` 디렉터리

675* 디렉터리는 Claude Code가 시작된 디렉터리 또는 그 부모 중 하나입니다

676* Windows에서 경로는 UNC 경로입니다

677 

678명령어 소스는 다음 필드를 허용합니다:

679 

680| 필드 | 유형 | 설명 |

681| :-------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------- |

682| `command` | string | 필수. 플러그인 디렉터리의 절대 경로를 stdout의 단일 줄로 인쇄하고 0으로 종료하는 셸 명령어. 인쇄 가능한 ASCII여야 하며 최대 500자이고 4개 이상의 공백이 연속되지 않아야 하므로 사용자는 수락하도록 요청받는 전체 명령어를 검토할 수 있습니다 |

683| `timeout` | number | 선택. 명령어를 포기하기 전에 대기할 전체 초 수(기본값: 60, 최대값: 600) |

684| `mode` | string | 선택. `"copy"`(기본값)는 인쇄된 디렉터리를 플러그인 캐시에 복사합니다. `"link"`는 인쇄된 디렉터리를 제자리에서 사용합니다. [복사 모드 및 링크 모드](#copy-mode-and-link-mode)를 참조하세요 |

685 

686<h4 id="copy-mode-and-link-mode">

687 복사 모드 및 링크 모드

688</h4>

689 

690기본 `"mode": "copy"`를 사용하면 Claude Code는 인쇄된 디렉터리를 버전 관리 플러그인 캐시에 복사하고 디렉터리 내용의 해시에서 [플러그인 버전](/docs/ko/plugins-reference#version-management)을 파생합니다. 도구는 명령어가 종료된 후 디렉터리를 삭제하거나 다시 쓸 수 있으며 동일한 내용을 생성하는 다시 실행은 최신 상태로 계산됩니다. Claude Code는 256 MiB보다 크거나 20,000개 이상의 항목을 포함하는 디렉터리 설치를 거부합니다.

691 

692렌더링된 SDK 내보내기와 같이 복사되지 않아야 하는 대규모 플러그인 디렉터리에 대해 `"mode": "link"`를 설정합니다. Claude Code는 인쇄된 디렉터리의 각 최상위 항목에 대한 링크로 플러그인의 캐시 항목을 채우고 제자리에서 파일을 사용하므로 아무것도 복사되지 않고 파일 내용이 해시되지 않으며 크기 제한이 적용되지 않습니다. 최상위 항목이 인쇄된 디렉터리 외부를 가리키는 심볼릭 링크인 경우 설치가 실패합니다. Claude Code는 또한 링크 모드 플러그인에 대해 [Node.js 패키지 종속성 설치](/docs/ko/plugins-reference#node-js-package-dependencies)를 건너뛰므로 플러그인이 필요한 모든 `node_modules`을 이미 포함하는 디렉터리를 인쇄합니다.

693 

694플러그인이 설치된 상태로 유지되는 동안 인쇄된 디렉터리를 제자리에 유지합니다. Claude Code는 모든 시작 시 해당 링크를 통해 플러그인을 로드하기 때문입니다. Claude Code는 파일 내부가 아닌 인쇄된 디렉터리의 실제 경로 및 최상위 항목에서 [플러그인 버전](/docs/ko/plugins-reference#version-management)을 파생합니다. 따라서 새 콘텐츠를 신호하려면 다른 경로를 인쇄합니다. 인쇄된 디렉터리 또는 그 아래 어디서나 시작된 세션에서 Claude Code는 플러그인을 로드하지 않습니다.

695 

696Claude Code는 Windows에서 링크 모드를 지원하지 않으며 거기에 링크 모드 플러그인 설치를 거부합니다. 대신 `"mode": "copy"`를 선언합니다.

697 

698<h4 id="how-users-accept-the-command">

699 사용자가 명령어를 수락하는 방법

700</h4>

701 

702Claude Code는 사용자의 머신에서 명령어를 실행하므로 모든 실행을 사용자의 명시적 수락에 바인딩합니다:

703 

704* 사용자가 `/plugin`의 세부 정보 화면에서 플러그인을 설치하거나 대화형 터미널에서 `claude plugin install` 또는 `claude plugin update`를 사용하여 설치하거나 업데이트할 때 Claude Code는 먼저 정확한 명령어 문자열을 표시하고 해당 설치에 대해 수락된 명령어를 기록합니다. 동일한 명령어의 수락으로 진행할 수 있는 `claude plugin update`는 아무것도 표시하지 않습니다.

705* 비대화형 셸(예: 프로비저닝 스크립트)에서 `claude plugin install` 또는 `claude plugin update`에 `--yes`를 전달하여 인쇄하는 명령어를 수락합니다. 이전 `--json` 실행이 표시한 명령어만 수락하려면 실행이 보고한 `sha256`과 함께 [`--accept-command`](/docs/ko/plugins-reference#plugin-install)를 전달합니다.

706* 다른 모든 경로는 사용자가 이미 수락한 명령어만 실행합니다. 여기에는 `/plugin`에서 시작된 업데이트 및 [Claude Code가 명령어를 다시 실행할 때](#when-claude-code-re-runs-the-command)에 설명된 백그라운드 실행이 포함됩니다. 아무것도 수락되지 않으면 Claude Code는 명령어 실행을 거부하고 사용자에게 검토 방법을 알려줍니다. Claude Code는 다른 플러그인의 종속성으로 명령어 소스 플러그인을 설치하지 않으므로 사용자는 먼저 설치합니다.

707* 항목의 `command`를 변경하거나 `mode`를 전환하면 사용자는 이미 가진 버전을 유지하고 Claude Code는 명령어 다시 실행을 중지합니다. 대화형 세션에서 `/plugin` 오류 탭은 사용자가 `claude plugin update <plugin>@<marketplace>`를 실행하여 검토하고 수락할 때까지 새 명령어를 표시합니다.

708 

709관리자는 관리 설정 [`disableCommandPluginSources`](/docs/ko/settings-reference#disablecommandpluginsources)를 사용하여 조직 전체에서 명령어 소스를 차단할 수 있습니다. 조직이 [`allowManagedHooksOnly`](/docs/ko/settings-reference#allowmanagedhooksonly)를 설정하면 Claude Code는 기본적으로 명령어 소스를 차단합니다.

710 

711<h4 id="when-claude-code-re-runs-the-command">

712 Claude Code가 명령어를 다시 실행할 때

713</h4>

714 

715인쇄된 디렉터리는 명령어가 실행된 시점의 도구 상태를 반영하므로 Claude Code는 다음 시간에 명령어를 다시 실행합니다:

716 

717* 사용자가 플러그인을 설치하거나 업데이트할 때마다

718* 활성화된 각 명령어 소스 플러그인에 대해 세션당 한 번. 백그라운드에서 세션이 시작된 직후. 이 실행은 마켓플레이스 자동 업데이트를 거치지 않으므로 마켓플레이스의 [자동 업데이트 설정](/docs/ko/discover-plugins#configure-auto-updates)에 따라 다르지 않습니다

719* 시작 또는 `/reload-plugins`에서 활성화된 플러그인의 설치된 버전이 플러그인 캐시에서 누락된 경우

720 

721사용자가 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/ko/env-vars)를 설정하면 Claude Code는 두 백그라운드 실행을 건너뜁니다. 명시적 설치 및 업데이트는 여전히 해당 변수 집합으로 명령어를 실행합니다.

722 

723명령어의 해시된 출력이 변경되면 Claude Code는 결과를 새 버전으로 설치하고 실행 중인 대화형 세션에서 다시 로드합니다. [`/reload-plugins`가 전환하는 동일한 구성 요소](/docs/ko/plugins-reference#environment-variables)를 전환합니다. 사용자는 플러그인이 다시 로드되었다는 알림을 봅니다. 제자리에서 다시 로드하면 세션의 프롬프트 캐시가 무효화되면 Claude Code는 대신 사용자에게 `/reload-plugins`를 실행하도록 요청합니다. 이는 [캐시 비용에 대해 경고하고 `--force`로 다시 실행할 때 적용됩니다](/docs/ko/prompt-caching#enabling-or-disabling-a-plugin).

724 

725<h3 id="advanced-plugin-entries">

726 고급 플러그인 항목

727</h3>

728 

729이 예제는 명령어, 에이전트, hooks 및 MCP 서버의 사용자 정의 경로를 포함하여 많은 선택적 필드를 사용하는 플러그인 항목을 보여줍니다:

730 

731```json theme={null}

732{

733 "name": "enterprise-tools",

734 "source": {

735 "source": "github",

736 "repo": "company/enterprise-plugin"

737 },

738 "description": "Enterprise workflow automation tools",

739 "version": "2.1.0",

740 "author": {

741 "name": "Enterprise Team",

742 "email": "enterprise@example.com"

743 },

744 "homepage": "https://docs.example.com/plugins/enterprise-tools",

745 "repository": "https://github.com/company/enterprise-plugin",

746 "license": "MIT",

747 "keywords": ["enterprise", "workflow", "automation"],

748 "category": "productivity",

749 "commands": [

750 "./commands/core/",

751 "./commands/enterprise/",

752 "./commands/experimental/preview.md"

753 ],

754 "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],

755 "hooks": {

756 "PostToolUse": [

757 {

758 "matcher": "Write|Edit",

759 "hooks": [

760 {

761 "type": "command",

762 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"

763 }

764 ]

765 }

766 ]

767 },

768 "mcpServers": {

769 "enterprise-db": {

770 "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",

771 "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]

772 }

773 },

774 "strict": false

775}

776```

777 

778주목할 주요 사항:

779 

780* **`commands` 및 `agents`**: 여러 디렉터리 또는 개별 파일을 지정할 수 있습니다. 경로는 플러그인 루트에 상대적이며 그 내에 유지되어야 합니다.

781 * Claude Code는 `./../shared.md`와 같이 플러그인 디렉터리 외부로 해석되는 경로를 [`path escapes plugin directory`](/docs/ko/errors#path-escapes-plugin-directory) 오류로 거부하고 여전히 해당 구성 요소 없이 플러그인을 로드합니다

782* **`${CLAUDE_PLUGIN_ROOT}`**: hook 명령어 및 MCP 서버 구성에서 이 변수를 사용하여 플러그인의 설치 디렉터리 내의 파일을 참조합니다.

783 * 서버 유형별로 어느 구성 필드가 이를 대체하는지에 대한 [대체 테이블](/docs/ko/plugins-reference#environment-variables)을 참조하세요

784 * 플러그인 업데이트를 통해 유지되어야 하는 종속성 또는 상태의 경우 [`${CLAUDE_PLUGIN_DATA}`](/docs/ko/plugins-reference#persistent-data-directory)를 대신 사용합니다

785* **`strict: false`**: 이것이 false로 설정되어 있으므로 플러그인은 자신의 `plugin.json`이 필요하지 않습니다. 마켓플레이스 항목이 모든 것을 정의합니다. 아래의 [Strict 모드](#strict-mode)를 참조하세요.

786 

787기본적으로 플러그인의 skills는 해당 `source` 아래의 `skills/` 디렉터리에서 로드됩니다. `skills` 필드에 나열된 경로는 해당 스캔에 추가됩니다:

788 

789```json theme={null}

790"skills": ["./skills/", "./extra-skills/"]

791```

792 

793여러 플러그인 항목이 마켓플레이스 루트(`source: "./"`)에서 하나의 `skills/` 폴더를 공유할 때 각 항목이 자신의 skills만 로드하도록 특정 하위 디렉터리를 대신 나열합니다:

794 

795```json theme={null}

796"source": "./",

797"skills": ["./skills/code-review", "./skills/docs"]

798```

799 

800마켓플레이스 루트 `source`를 사용하면 나열된 경로가 해당 항목의 완전한 집합이 되며, 공유된 `skills/` 폴더의 다른 디렉터리는 로드되지 않습니다. `./skills/` 자체 또는 플러그인 루트를 나열하면 전체 스캔이 유지됩니다. 나열된 경로 중 어느 것도 존재하지 않으면 기본 스캔이 대신 실행됩니다.

801 

802<h3 id="strict-mode">

803 Strict 모드

804</h3>

805 

806`strict` 필드는 `plugin.json`이 구성 요소 정의(skills, 에이전트, hooks, MCP 서버, 출력 스타일)의 권한인지 여부를 제어합니다.

807 

808| 값 | 동작 |

809| :---------- | :---------------------------------------------------------------------------------- |

810| `true`(기본값) | `plugin.json`이 권한입니다. 마켓플레이스 항목은 추가 구성 요소로 이를 보완할 수 있으며 두 소스가 병합됩니다. |

811| `false` | 마켓플레이스 항목이 전체 정의입니다. 플러그인에 구성 요소를 선언하는 `plugin.json`도 있으면 충돌이 발생하고 플러그인이 로드되지 않습니다. |

812 

813**각 모드를 사용할 때:**

814 

815* **`strict: true`**: 플러그인은 자신의 `plugin.json`을 가지고 있으며 자신의 구성 요소를 관리합니다. 마켓플레이스 항목은 맨 위에 추가 skills 또는 hooks를 추가할 수 있습니다. 이것이 기본값이며 대부분의 플러그인에서 작동합니다.

816* **`strict: false`**: 마켓플레이스 운영자가 완전한 제어를 원합니다. 플러그인 저장소는 원본 파일을 제공하고 마켓플레이스 항목은 이러한 파일 중 어느 것이 skills, 에이전트, hooks 등으로 노출되는지 정의합니다. 마켓플레이스가 플러그인 작성자의 의도와 다르게 플러그인의 구성 요소를 재구성하거나 큐레이션할 때 유용합니다.

817 

818<h2 id="host-and-distribute-marketplaces">

819 마켓플레이스 호스팅 및 배포

820</h2>

821 

822사용자가 git 저장소에서 호스팅되는 마켓플레이스를 추가하거나 이를 나열하는 git 기반 플러그인을 설치할 때 Claude Code는 해당 마켓플레이스 또는 플러그인 저장소를 사용자의 머신에 복제합니다. 복제는 [Git LFS](https://git-lfs.com) 콘텐츠를 다운로드하지 않으므로 LFS 추적 파일은 포인터 파일로 도착합니다. 플러그인이 필요한 파일을 LFS 외부에 유지하세요.

823 

824<h3 id="host-on-github-recommended">

825 GitHub에서 호스팅(권장)

826</h3>

827 

828GitHub는 마켓플레이스를 호스팅하고 배포하는 권장 방법입니다:

829 

8301. **저장소 생성**: 마켓플레이스를 위한 새 저장소 설정

8312. **마켓플레이스 파일 추가**: 플러그인 정의와 함께 `.claude-plugin/marketplace.json` 생성

8323. **팀과 공유**: 사용자가 `/plugin marketplace add owner/repo`로 마켓플레이스를 추가합니다

833 

834**이점**: 기본 제공 버전 제어, 문제 추적 및 팀 협업 기능.

835 

836<h3 id="host-on-other-git-services">

837 다른 git 서비스에서 호스팅

838</h3>

839 

840GitLab, Bitbucket 및 자체 호스팅 서버와 같은 모든 git 호스팅 서비스가 작동합니다. 사용자는 전체 저장소 URL로 추가합니다:

841 

842```shell theme={null}

843/plugin marketplace add https://gitlab.com/company/plugins.git

844```

845 

846<h3 id="private-repositories">

847 개인 저장소

848</h3>

849 

850Claude Code는 개인 저장소에서 플러그인 설치를 지원합니다. [**조직 설정 > 플러그인**](https://claude.ai/admin-settings/plugins)을 통해 마켓플레이스를 배포하는 경우 git 자격 증명이 관련되지 않습니다. 조직 동기화는 조직의 GitHub 또는 GitLab 연결을 통해 claude.ai에서 마켓플레이스 저장소를 읽습니다. 개인 플러그인 소스가 될 수 있는 항목은 [조직 설정을 통해 배포](#distribute-through-organization-settings)를 참조하세요.

851 

852<h4 id="commands-you-run">

853 실행하는 명령어

854</h4>

855 

856`/plugin marketplace add`, `/plugin install`, `/plugin update` 또는 `/plugin marketplace update`를 실행할 때 Claude Code는 기존 git 자격 증명 도우미를 사용하므로 `gh auth login`, macOS Keychain 또는 `git-credential-store`를 통한 HTTPS 액세스는 터미널에서와 동일하게 작동합니다. SSH 액세스는 호스트가 이미 `known_hosts` 파일에 있고 키가 `ssh-agent`에 로드되어 있는 한 작동합니다. Claude Code는 호스트 지문 및 키 암호에 대한 대화형 SSH 프롬프트를 억제하기 때문입니다. GitHub `owner/repo` 단축 소스는 기본적으로 SSH를 통해 복제합니다. 대신 HTTPS를 통해 복제하려면 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/ko/env-vars#variables)을 설정합니다.

857 

858<h4 id="background-auto-updates">

859 백그라운드 자동 업데이트

860</h4>

861 

862백그라운드 새로고침은 마켓플레이스의 원격에서 새 커밋을 확인할 때 구성된 git 자격 증명 도우미를 사용합니다. 실행하는 명령어와 동일합니다. SSH 원격의 경우 `ssh-agent`에 로드된 키가 확인을 인증합니다. Claude Code는 확인을 비대화형으로 실행합니다. git의 터미널 프롬프트 및 askpass 프로그램을 끄고 자격 증명 도우미에 프롬프트하지 않도록 지시합니다. 확인이 HTTPS를 통해 개인 저장소에 인증할 수 있는지 여부는 도우미에 따라 다릅니다:

863 

864* 프롬프트 없이 저장된 자격 증명을 제공할 수 있는 도우미는 확인을 인증합니다. Git Credential Manager, macOS Keychain 도우미 및 `git-credential-store`는 호스트에 대한 자격 증명을 보유하면 이런 식으로 작동합니다.

865* 프롬프트가 필요한 도우미는 백그라운드에서 응답할 수 없습니다. 업데이트가 조용히 실패하고 기존 체크아웃이 제자리에 유지되므로 플러그인은 마지막 동기화된 상태에서 계속 작동합니다. `/plugin marketplace update <name>`을 실행하여 자격 증명으로 마켓플레이스를 새로고칩니다.

866 

867확인이 체크아웃이 최신 상태임을 발견하면 Claude Code는 그대로 둡니다. 확인이 새 커밋을 발견하거나 원격에 도달하거나 인증할 수 없어서 실패하면 Claude Code는 마켓플레이스를 다시 복제하고 새 복제본으로 교체합니다. 해당 복제가 실패하면 기존 체크아웃이 제자리에 유지됩니다. 다시 복제는 [대규모 저장소에서 시간 초과](#git-operations-time-out)될 수 있습니다.

868 

869두 가지 설정이 개인 마켓플레이스를 예측 가능하게 작동하게 합니다:

870 

871* `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1`을 설정하여 백그라운드 확인이 원격에 도달하거나 인증할 수 없을 때 다시 복제를 시도하지 않고 기존 체크아웃을 유지합니다. 플러그인은 마지막 동기화된 상태에서 계속 작동하며 `/plugin marketplace update`를 사용한 수동 업데이트는 여전히 자격 증명으로 인증합니다.

872* git 자격 증명 도우미를 구성합니다. 예를 들어 GitHub의 경우 `gh auth setup-git`을 사용하여 백그라운드 확인과 다시 복제가 프롬프트 없이 인증할 수 있습니다.

873 

874`GITHUB_TOKEN`과 같은 공급자 토큰을 환경에서 설정하는 것만으로는 백그라운드 인증을 활성화하지 않습니다. 토큰은 구성된 자격 증명 도우미(예: `GH_TOKEN` 및 `GITHUB_TOKEN`을 읽는 `gh` CLI의 도우미)를 통해서만 적용됩니다.

875 

876<Note>

877 CI/CD 환경에서는 개인 저장소에서 플러그인을 설치하기 전에 git 자격 증명 도우미를 구성합니다. GitHub Actions에서 마켓플레이스 저장소에 대한 읽기 액세스 권한이 있는 토큰을 `GH_TOKEN`으로 내보낸 다음 `gh auth setup-git`을 실행합니다. 기본 워크플로우 토큰은 워크플로우 자신의 저장소에만 액세스할 수 있으므로 다른 저장소의 개인 마켓플레이스는 개인 액세스 토큰 또는 앱 토큰이 필요합니다.

878</Note>

879 

880<h3 id="distribute-through-organization-settings">

881 조직 설정을 통해 배포

882</h3>

883 

884Team 또는 Enterprise 플랜에서 [**조직 설정 > 플러그인**](https://claude.ai/admin-settings/plugins)을 통해 플러그인을 배포하는 경우 다음 소스 규칙이 적용됩니다:

885 

886* github.com 및 gitlab.com에서 마켓플레이스 저장소는 개인 또는 내부여야 합니다. 조직 동기화는 호스트와 일치하는 연결을 통해 저장소를 읽습니다:

887 * **github.com**: Claude GitHub App

888 * **GitHub Enterprise Server 호스트**: 조직의 [GitHub Enterprise App](/docs/ko/github-enterprise-server#admin-setup)

889 * **gitlab.com 또는 자체 관리 GitLab 인스턴스**: 조직의 [GitLab 구성](#sync-a-gitlab-hosted-marketplace)의 해당 호스트에 대한 액세스 토큰

890* 각 플러그인 소스는 `github`, `url` 또는 `git-subdir` 유형이거나 `./`로 시작하는 [상대 경로](#relative-paths)여야 합니다. `metadata.pluginRoot` 아래에 bare name으로 플러그인을 나열하면 조직 동기화가 이를 지원되지 않는 소스로 거부하므로 경로를 명시적으로 작성합니다(예: `./plugins/deploy-tools`).

891* 플러그인 소스는 세 가지 경우에 개인일 수 있습니다:

892 * 마켓플레이스 저장소의 소유자를 공유하는 github.com 소스

893 * GHE App이 저장소에 설치된 조직의 GitHub Enterprise 호스트의 소스

894 * 마켓플레이스 저장소와 동일한 GitLab 호스트의 `url` 또는 `git-subdir` 소스. gitlab.com에서 소스는 마켓플레이스 저장소와 동일한 최상위 그룹 또는 사용자 네임스페이스 아래에 있어야 합니다.

895* 다른 모든 플러그인 소스는 github.com, gitlab.com 또는 bitbucket.org의 공개 저장소여야 하며, 조직 동기화는 자격 증명 없이 가져옵니다. 조직 동기화는 이러한 규칙이 적용되지 않는 호스트의 플러그인 소스를 거부합니다.

896 

897관리 워크플로우는 [조직을 위한 플러그인 관리](https://support.claude.com/en/articles/13837433)를 참조하세요.

898 

899개인 플러그인을 포함하려면 플러그인 폴더를 마켓플레이스 저장소 내에 배치하고 [상대 경로](#relative-paths)로 참조합니다. 조직 동기화는 배포 중에 각 플러그인을 패키징하므로 사용자는 별도의 소스 저장소에 액세스할 필요가 없습니다.

900 

901예를 들어 이 `marketplace.json` 플러그인 항목은 마켓플레이스 저장소의 `plugins/deploy-tools`에 커밋한 플러그인을 참조합니다:

902 

903```json theme={null}

904{

905 "name": "deploy-tools",

906 "source": "./plugins/deploy-tools"

907}

908```

909 

910<h4 id="sync-a-gitlab-hosted-marketplace">

911 GitLab 호스팅 마켓플레이스 동기화

912</h4>

913 

914gitlab.com 또는 자체 관리 GitLab 인스턴스에서 마켓플레이스를 동기화하려면 [Owner](/docs/ko/server-managed-settings#access-control)가 먼저 [**조직 설정 > Claude Code**](https://claude.ai/admin-settings/claude-code)에서 해당 호스트에 대한 GitLab 구성을 추가합니다. GitLab 구성은 공개 베타 상태이며 플러그인 마켓플레이스 동기화에만 적용됩니다. 하나를 추가해도 [웹의 Claude Code](/docs/ko/claude-code-on-the-web#limitations)에서 GitLab 저장소를 사용할 수 없습니다. 설정 단계는 [조직을 위한 플러그인 관리](https://support.claude.com/en/articles/13837433)를 참조하세요.

915 

916마켓플레이스를 추가할 때 프로젝트의 HTTPS URL(예: `https://gitlab.example.com/platform/claude-plugins`)을 입력합니다. 중첩된 하위 그룹의 프로젝트가 작동합니다. 조직 동기화는 프로젝트의 기본 분기를 읽습니다. **자동으로 동기화**를 켜면 기본 분기에 대한 푸시만 동기화를 시작합니다.

917 

918<h4 id="keep-executables-out-of-the-top-level-bin-directory">

919 최상위 bin 디렉터리에서 실행 파일 제외

920</h4>

921 

922조직 설정을 통해 배포하는 모든 플러그인에 최상위 `bin/` 디렉터리를 포함하지 마세요. claude.ai는 마켓플레이스 동기화 또는 직접 업로드를 통해 플러그인이 도착하는지 여부에 관계없이 하나를 가진 플러그인을 거부합니다:

923 

924* **마켓플레이스 동기화**: 조직 동기화는 해당 플러그인을 거부하고 나머지 마켓플레이스를 동기화합니다. 오류 메시지는 `Plugin contains a top-level bin/ directory`로 시작합니다.

925* **직접 업로드**: [**조직 설정 > 플러그인**](https://claude.ai/admin-settings/plugins)에서 플러그인을 업로드하는 경우 claude.ai는 동일한 메시지로 업로드를 거부합니다.

926 

927실행 파일을 `scripts/`와 같은 다른 디렉터리에 유지하고 [skills, hooks 또는 MCP 서버 구성](/docs/ko/plugins-reference#environment-variables)에서 `${CLAUDE_PLUGIN_ROOT}/scripts/<name>`으로 참조합니다.

928 

929<h3 id="require-marketplaces-for-your-team">

930 팀을 위한 마켓플레이스 필수

931</h3>

932 

933프로젝트 폴더를 [신뢰](/docs/ko/permissions#what-runs-before-you-trust-a-folder)할 때 Claude Code가 팀 구성원을 위해 마켓플레이스를 추가하도록 저장소를 구성할 수 있습니다. 별도의 프롬프트 없이 마켓플레이스를 `.claude/settings.json`에 추가합니다:

934 

935```json theme={null}

936{

937 "extraKnownMarketplaces": {

938 "company-tools": {

939 "source": {

940 "source": "github",

941 "repo": "your-org/claude-plugins"

942 }

943 }

944 }

945}

946```

947 

948기본적으로 활성화해야 하는 플러그인을 지정할 수도 있습니다:

949 

950```json theme={null}

951{

952 "enabledPlugins": {

953 "code-formatter@company-tools": true,

954 "deployment-tools@company-tools": true

955 }

956}

957```

958 

959전체 구성 옵션은 [플러그인 설정](/docs/ko/settings-reference#plugin-settings)을 참조하세요.

960 

961<Note>

962 로컬 `directory` 또는 `file` 소스를 상대 경로와 함께 사용하는 경우 경로는 저장소의 주 체크아웃에 대해 해석됩니다. git worktree에서 Claude Code를 실행할 때 경로는 여전히 주 체크아웃을 가리키므로 모든 worktree가 동일한 마켓플레이스 위치를 공유합니다. 마켓플레이스 상태는 프로젝트당이 아니라 사용자당 한 번 `~/.claude/plugins/known_marketplaces.json`에 저장됩니다.

963</Note>

964 

965<h3 id="pre-populate-plugins-for-containers">

966 컨테이너에 대한 플러그인 사전 채우기

967</h3>

968 

969컨테이너 이미지 및 CI 환경의 경우 빌드 시간에 플러그인 디렉터리를 사전 채우므로 Claude Code가 런타임에 아무것도 복제하지 않고도 마켓플레이스 및 플러그인이 이미 사용 가능한 상태로 시작됩니다. `CLAUDE_CODE_PLUGIN_SEED_DIR` 환경 변수를 이 디렉터리를 가리키도록 설정합니다.

970 

971여러 시드 디렉터리를 계층화하려면 Unix에서는 `:`로, Windows에서는 `;`로 경로를 구분합니다. Claude Code는 각 디렉터리를 순서대로 검색하고 주어진 마켓플레이스 또는 플러그인 캐시를 포함하는 첫 번째 시드를 사용합니다.

972 

973시드 디렉터리는 `~/.claude/plugins`의 구조를 미러링합니다:

974 

975```

976$CLAUDE_CODE_PLUGIN_SEED_DIR/

977 known_marketplaces.json

978 marketplaces/<name>/...

979 cache/<marketplace>/<plugin>/<version>/...

980```

981 

982시드 디렉터리를 구축하려면 이미지 빌드 중에 Claude Code를 한 번 실행하고, 필요한 플러그인을 설치한 다음, 결과 `~/.claude/plugins` 디렉터리를 이미지에 복사하고 `CLAUDE_CODE_PLUGIN_SEED_DIR`을 가리킵니다.

983 

984복사 단계를 건너뛰려면 빌드 중에 `CLAUDE_CODE_PLUGIN_CACHE_DIR`을 대상 시드 경로로 설정하여 플러그인이 직접 설치되도록 합니다:

985 

986```bash theme={null}

987CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins

988CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins

989```

990 

991그런 다음 런타임 환경에서 `CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed`를 설정하여 Claude Code가 시작 시 시드에서 읽도록 합니다.

992 

993시작 시 Claude Code는 시드의 `known_marketplaces.json`에서 찾은 마켓플레이스를 기본 구성에 등록하고 `cache/` 아래에서 찾은 플러그인 캐시를 다시 복제하지 않고 사용합니다. 이는 대화형 모드와 `-p` 플래그를 사용한 비대화형 모드 모두에서 작동합니다.

994 

995동작 세부 정보:

996 

997* **읽기 전용**: Claude Code는 시드 디렉터리에 절대 쓰지 않습니다.

998* **자동 업데이트 비활성화**: 시드 마켓플레이스는 자동 업데이트되지 않습니다.

999* **시드 항목이 우선합니다**: 시드에서 선언된 마켓플레이스는 각 시작 시 사용자 구성의 일치하는 항목을 덮어씁니다. 시드 플러그인을 거부하려면 마켓플레이스를 제거하는 대신 `/plugin disable`을 사용합니다.

1000* **경로 해석**: Claude Code는 시드의 JSON 내에 저장된 경로를 신뢰하지 않고 런타임에 `$CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/`을 탐색하여 마켓플레이스 콘텐츠를 찾습니다. 이는 시드가 빌드된 위치와 다른 경로에 마운트된 경우에도 시드가 올바르게 작동함을 의미합니다.

1001* **변경 차단**: 시드 관리 마켓플레이스에 대해 `/plugin marketplace remove` 또는 `/plugin marketplace update`를 실행하면 시드 이미지를 업데이트하도록 관리자에게 문의하라는 지침과 함께 실패합니다.

1002* **설정과 구성**: `extraKnownMarketplaces` 또는 `enabledPlugins`이 시드에 이미 존재하는 마켓플레이스를 선언하면 Claude Code는 복제하는 대신 시드 복사본을 사용합니다.

1003 

1004<h3 id="managed-marketplace-restrictions">

1005 관리되는 마켓플레이스 제한

1006</h3>

1007 

1008플러그인 소스에 대한 엄격한 제어가 필요한 조직의 경우 관리자는 관리되는 설정에서 [`strictKnownMarketplaces`](/docs/ko/settings-reference#strictknownmarketplaces) 설정을 사용하여 사용자가 추가할 수 있는 플러그인 마켓플레이스를 제한할 수 있습니다. 단일 실행을 위해 플러그인, 에이전트 및 MCP 서버를 사이드로드하는 CLI 플래그를 거부하려면 [`disableSideloadFlags`](/docs/ko/settings-reference#disablesideloadflags)와 쌍을 이룹니다. 컨텍스트 설치 제안으로 나타날 수 있는 마켓플레이스의 플러그인을 허용 목록으로 지정하려면 [`pluginSuggestionMarketplaces`](/docs/ko/settings-reference#pluginsuggestionmarketplaces)를 설정합니다.

1009 

1010`strictKnownMarketplaces`는 플러그인이 오는 마켓플레이스와 일치하므로 사용자는 여전히 허용된 마켓플레이스에서 [`command` 소스](#command-sources)를 가진 플러그인을 설치할 수 있습니다. 명령 소스도 차단하려면 [`disableCommandPluginSources`](/docs/ko/settings-reference#disablecommandpluginsources)를 설정합니다.

1011 

1012`strictKnownMarketplaces`가 관리되는 설정에서 구성되면 제한 동작은 값에 따라 달라집니다:

1013 

1014| 값 | 동작 |

1015| ------------ | ---------------------------------------------------- |

1016| 정의되지 않음(기본값) | 제한 없음. 사용자는 모든 마켓플레이스를 추가할 수 있습니다 |

1017| 빈 배열 `[]` | 완전한 잠금. 공식 Anthropic 마켓플레이스를 포함한 모든 마켓플레이스 소스를 차단합니다 |

1018| 소스 목록 | 허용 목록 적용. 사용자는 항목과 일치하는 마켓플레이스만 추가할 수 있습니다 |

1019 

1020<h4 id="common-configurations">

1021 일반적인 구성

1022</h4>

1023 

1024공식 Anthropic 마켓플레이스를 포함한 모든 마켓플레이스 추가 비활성화:

1025 

1026```json theme={null}

1027{

1028 "strictKnownMarketplaces": []

1029}

1030```

1031 

1032Claude Code는 [claude.ai에서 동기화된](/docs/ko/plugins-reference#synced-plugins) 플러그인을 마켓플레이스가 아닌 계정에서 다운로드하므로 이 잠금은 이를 포함하지 않습니다. 이를 중지하려면 관리되는 설정에서 [`syncClaudeAiPlugins`](/docs/ko/settings-reference#syncclaudeaiplugins)를 `false`로 설정하거나 claude.ai에서 조직의 Skills를 끕니다.

1033 

1034공식 Anthropic 마켓플레이스만 허용합니다. 단일 저장소 항목에 대한 일치는 정확하므로 이 항목은 동일한 저장소의 `ref` 또는 `path` 변형을 포함하지 않습니다:

1035 

1036```json theme={null}

1037{

1038 "strictKnownMarketplaces": [

1039 {

1040 "source": "github",

1041 "repo": "anthropics/claude-plugins-official"

1042 }

1043 ]

1044}

1045```

1046 

1047이 항목을 사용하면 Claude Code는 이미 등록된 공식 마켓플레이스를 사용 가능하게 유지하고 새 머신에서 Claude Code를 처음 대화형으로 시작할 때 마켓플레이스를 자동으로 등록합니다.

1048 

1049자동 등록은 모든 머신을 포함하지 않습니다. 가장 일반적으로 누락되는 경우:

1050 

1051* 머신의 첫 번째 대화형 시작 전에 실행되는 비대화형 환경.

1052* 마켓플레이스를 차단한 정책(예: 빈 배열 잠금)에서 Claude Code가 이미 대화형으로 실행된 머신. Claude Code는 차단된 시도를 기록하고 정책이 변경된 후 다시 시도하지 않습니다.

1053 

1054이러한 머신에서 동일한 `managed-settings.json`의 [`extraKnownMarketplaces`](/docs/ko/settings-reference#extraknownmarketplaces)에 마켓플레이스를 추가하여 Claude Code가 자동으로 등록하도록 하거나 `claude plugin marketplace add anthropics/claude-plugins-official`을 실행합니다.

1055 

1056특정 마켓플레이스만 허용:

1057 

1058```json theme={null}

1059{

1060 "strictKnownMarketplaces": [

1061 {

1062 "source": "github",

1063 "repo": "acme-corp/approved-plugins"

1064 },

1065 {

1066 "source": "github",

1067 "repo": "acme-corp/security-tools",

1068 "ref": "v2.0"

1069 },

1070 {

1071 "source": "url",

1072 "url": "https://plugins.example.com/marketplace.json"

1073 }

1074 ]

1075}

1076```

1077 

1078[owner-wildcard](/docs/ko/settings-reference#owner-wildcards) 항목을 사용하여 GitHub 조직 아래의 모든 마켓플레이스 저장소를 허용합니다. Owner 와일드카드는 Claude Code v2.1.223 이상이 필요합니다.

1079 

1080```json theme={null}

1081{

1082 "strictKnownMarketplaces": [

1083 {

1084 "source": "github",

1085 "repo": "acme-corp/*"

1086 }

1087 ]

1088}

1089```

1090 

1091호스트에 대한 정규식 패턴 일치를 사용하여 내부 git 서버의 모든 마켓플레이스 허용. 이는 [GitHub Enterprise Server](/docs/ko/github-enterprise-server#plugin-marketplaces-on-ghes) 또는 자체 호스팅 GitLab 인스턴스에 권장되는 방법입니다:

1092 

1093```json theme={null}

1094{

1095 "strictKnownMarketplaces": [

1096 {

1097 "source": "hostPattern",

1098 "hostPattern": "^github\\.example\\.com$"

1099 }

1100 ]

1101}

1102```

1103 

1104경로에 대한 정규식 패턴 일치를 사용하여 특정 디렉터리의 파일 시스템 기반 마켓플레이스 허용:

1105 

1106```json theme={null}

1107{

1108 "strictKnownMarketplaces": [

1109 {

1110 "source": "pathPattern",

1111 "pathPattern": "^/opt/approved/"

1112 }

1113 ]

1114}

1115```

1116 

1117`pathPattern`으로 모든 파일 시스템 경로를 허용하면서 `hostPattern`으로 네트워크 소스를 제어하려면 `".*"`를 `pathPattern`으로 사용합니다.

1118 

1119<Note>

1120 `strictKnownMarketplaces`는 사용자가 추가할 수 있는 것을 제한하지만 자체적으로 마켓플레이스를 등록하지는 않습니다. 허용된 마켓플레이스를 자동으로 등록하려면 동일한 `managed-settings.json`에서 [`extraKnownMarketplaces`](/docs/ko/settings-reference#extraknownmarketplaces)에 추가합니다.

1121 

1122 공식 Anthropic 마켓플레이스는 Claude Code가 자체적으로 등록하는 유일한 마켓플레이스이며 허용 목록이 이를 허용할 때만 등록합니다. 자동 등록은 비대화형 환경 및 이전 정책이 이를 차단한 머신과 같은 일부 머신도 누락합니다. 이러한 머신을 포함하려면 공식 마켓플레이스를 `extraKnownMarketplaces`에도 추가합니다. 두 설정을 나란히 보려면 [`strictKnownMarketplaces` 참조](/docs/ko/settings-reference#strictknownmarketplaces)를 참조하세요.

1123</Note>

1124 

1125<h4 id="how-restrictions-work">

1126 제한 작동 방식

1127</h4>

1128 

1129제한은 네트워크 또는 파일 시스템 작업이 발생하기 전에 확인됩니다. 확인은 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로고침 및 자동 업데이트 시 실행됩니다. 마켓플레이스가 정책 구성 전에 추가되었고 해당 소스가 더 이상 허용 목록과 일치하지 않으면 Claude Code는 해당 마켓플레이스에서 플러그인을 설치하거나 업데이트하기를 거부합니다. 동일한 적용이 `blockedMarketplaces`에도 적용됩니다.

1130 

1131두 목록이 적용되는 위치는 설정 위치에 따라 다릅니다:

1132 

1133* **Claude.ai 관리 콘솔**: Claude Code는 [서버 관리 설정을 읽는](/docs/ko/managed-settings#where-and-when-a-policy-applies) 세션에서 두 목록을 모두 적용합니다. claude.ai는 또한 조직의 누군가가 claude.ai에서 git 저장소의 새 마켓플레이스를 추가하거나 Claude Desktop 앱의 Code 탭 외부에서 **사용자 정의**에서 추가할 때 이를 확인합니다. 이는 구성원이 자신의 계정을 위해 추가한 마켓플레이스와 [**조직 설정 > 플러그인**](https://claude.ai/admin-settings/plugins) 아래의 전체 조직을 위해 추가된 마켓플레이스를 포함합니다. claude.ai는 허용 목록이 허용하지 않거나 차단 목록이 명명하는 저장소를 거부합니다. 목록을 설정하기 전에 두 위치 중 하나에서 추가된 마켓플레이스를 다시 확인하지 않으며 업로드된 플러그인을 확인하지 않습니다.

1134* **관리 설정 파일, OS 수준 정책 또는 기타 관리 소스**: Claude Code는 해당 소스를 읽는 위치에서 두 목록을 모두 적용합니다. claude.ai는 이를 읽지 않습니다.

1135 

1136GitHub 소유자 아래의 모든 마켓플레이스 저장소를 차단하려면 `blockedMarketplaces` 항목에서 owner-wildcard 형식을 사용합니다: `{ "source": "github", "repo": "untrusted-org/*" }`. Claude Code v2.1.223 이상이 필요합니다. 일치 규칙(차단 목록과 허용 목록 간에 다름)은 [Owner 와일드카드](/docs/ko/settings-reference#owner-wildcards)를 참조하세요.

1137 

1138사용자가 Claude Code가 [복제하는 `https://` 저장소 URL](/docs/ko/discover-plugins#add-from-other-git-hosts)(예: 단순 `github.com` 또는 `gitlab.com` 저장소 URL)을 추가할 때 Claude Code는 `blockedMarketplaces`의 `url` 항목에 대해서도 확인합니다. Claude Code는 항목이 동일한 URL을 명명하면 추가를 차단합니다. 해당 비교에서 Claude Code는 `.git` 접미사 및 사용자가 `#` 뒤에 추가하는 모든 ref를 무시합니다. Claude Code v2.1.232 이상이 필요합니다. v2.1.232 이전에는 Claude Code가 호스팅된 `marketplace.json` 파일로 가져온 URL에 대해서만 `url` 항목과 일치했습니다.

1139 

1140허용 목록은 owner-wildcard `github` 항목을 제외하고 대부분의 소스 유형에 대해 정확한 일치를 사용합니다. 마켓플레이스가 허용되려면 지정된 모든 필드가 일치해야 합니다:

1141 

1142* GitHub 소스의 경우: `repo`는 필수이며 단일 저장소를 명명하거나 owner-wildcard 형식 `owner/*`를 사용하여 해당 소유자 아래의 모든 저장소를 포함합니다. 와일드카드 항목이 일치하는 방식(대소문자 규칙 포함)은 [Owner 와일드카드](/docs/ko/settings-reference#owner-wildcards)를 참조하세요. 단일 저장소 항목의 경우 `ref`는 정확히 일치하거나 마켓플레이스 소스 및 허용 목록 항목 모두에서 없어야 하며 동일한 규칙이 `path`에 적용됩니다

1143* URL 소스의 경우: 전체 URL이 정확히 일치해야 합니다

1144* `hostPattern` 소스의 경우: 마켓플레이스 호스트가 정규식 패턴과 일치합니다

1145* `pathPattern` 소스의 경우: 마켓플레이스의 파일 시스템 경로가 정규식 패턴과 일치합니다

1146 

1147허용 목록의 정확한 일치는 후행 슬래시, `.git` 접미사 또는 `ssh://` 및 `https://` 체계만 다른 URL을 다른 값으로 취급합니다. 조직의 마켓플레이스를 둘 이상의 URL 형식으로 복제할 수 있는 경우 `https://`, `ssh://` 및 `user@host:path` 형식이 모두 일치하도록 리터럴 URL보다 `hostPattern` 항목을 선호합니다.

1148 

1149[claude.ai에서 호스팅되는 마켓플레이스](/docs/ko/discover-plugins#add-from-claude-ai)는 호스트로 일치합니다: `claude.ai`와 일치하는 `hostPattern` 항목은 `strictKnownMarketplaces` 및 `blockedMarketplaces`에서 이를 관리합니다. 허용 목록에서 이러한 항목은 구성원의 개인 claude.ai 업로드를 허용하지 않습니다. Claude Code v2.1.273 이상이 필요합니다.

1150 

1151`strictKnownMarketplaces`는 [관리되는 설정](/docs/ko/managed-settings)에서 설정되므로 개별 사용자 및 프로젝트 구성은 이러한 제한을 재정의할 수 없습니다.

1152 

1153전체 구성 세부 정보(지원되는 모든 소스 유형 및 `extraKnownMarketplaces`와의 비교 포함)는 [strictKnownMarketplaces 참조](/docs/ko/settings-reference#strictknownmarketplaces)를 참조하세요.

1154 

1155<h3 id="version-resolution-and-release-channels">

1156 버전 해석 및 릴리스 채널

1157</h3>

1158 

1159플러그인 버전은 캐시 경로 및 업데이트 감지를 결정합니다. 해석된 버전이 사용자가 이미 가지고 있는 것과 일치하면 `/plugin update` 및 자동 업데이트는 플러그인을 건너뜁니다. git 기반 소스의 경우 `version`을 생략하면 Claude Code는 소스의 해석된 커밋 SHA를 사용하므로 사용자는 해당 커밋이 변경될 때마다 업데이트를 받습니다. 이는 내부 또는 활발하게 개발 중인 플러그인에 대한 가장 간단한 설정입니다. 전체 해석 순서(예: `archive` 소스 포함)는 [버전 관리](/docs/ko/plugins-reference#version-management)를 참조하세요.

1160 

1161<Warning>

1162 `version`을 설정하면 [`command`](#command-sources)를 제외한 모든 소스 유형에 대해 플러그인이 고정됩니다. 이 경우 버전은 항상 명령이 생성한 것의 해시를 포함합니다. 마켓플레이스에서 로드된 플러그인도 [제자리에서](/docs/ko/plugins-reference#plugin-caching-and-file-resolution) 로드되지 않습니다. `plugin.json`에서 `"version": "1.0.0"`을 선언하고 해당 문자열을 변경하지 않고 새 커밋을 푸시하면 기존 사용자는 캐시된 복사본을 유지합니다. Claude Code가 동일한 버전을 보고 캐시된 복사본을 유지하기 때문입니다. 모든 릴리스에서 필드를 범프하거나 해석된 버전으로 폴백하도록 생략합니다.

1163 

1164 `plugin.json` 및 마켓플레이스 항목 모두에서 `version`을 설정하지 마세요. `plugin.json` 값이 항상 자동으로 우선하므로 오래된 매니페스트 버전이 `marketplace.json`에서 설정한 버전을 숨길 수 있습니다.

1165</Warning>

1166 

1167<h4 id="set-up-release-channels">

1168 릴리스 채널 설정

1169</h4>

1170 

1171플러그인에 대한 "stable" 및 "latest" 릴리스 채널을 지원하려면 동일한 저장소의 다양한 refs 또는 SHA를 가리키는 두 개의 마켓플레이스를 설정할 수 있습니다. 그런 다음 관리되는 설정을 통해 각 사용자 그룹에 자신의 마켓플레이스를 제공할 수 있습니다:

1172 

1173* 각 그룹의 장치에 별도의 [엔드포인트 관리 설정](/docs/ko/managed-settings#delivery-mechanisms)(예: 관리 설정 파일 또는 MDM 프로필)을 배포합니다. [Claude Code가 관리되는 소스를 결합하는 방식](/docs/ko/managed-settings#precedence-within-the-managed-tier)은 그룹별 파일 또는 프로필이 마켓플레이스를 읽는 장치에도 적용되는지 여부를 나타냅니다.

1174* 그룹당 하나의 [Claude 앱 게이트웨이 정책](/docs/ko/claude-apps-gateway-config#managed)을 정의합니다. 게이트웨이는 일치 규칙이 사용자에게 맞는 첫 번째 정책을 적용하므로 각 사용자가 자신의 그룹 정책에 도달하도록 정책을 정렬합니다. 그룹 정책의 `extraKnownMarketplaces`는 catch-all 정책의 맵과 병합하지 않고 대체하므로 그룹이 필요한 모든 마켓플레이스를 그룹의 정책에 나열합니다.

1175 

1176관리 콘솔의 서버 관리 설정은 [조직의 모든 사용자에게 적용](/docs/ko/server-managed-settings#current-limitations)되므로 그룹별 할당을 수행할 수 없습니다.

1177 

1178<Warning>

1179 각 채널은 다른 버전으로 해석되어야 합니다. 명시적 버전을 사용하는 경우 `plugin.json`은 각 고정된 ref에서 다른 `version`을 선언해야 합니다. `version`을 생략하면 서로 다른 커밋 SHA가 이미 채널을 구분합니다. 두 refs가 동일한 버전 문자열로 해석되면 Claude Code는 이들을 동일한 것으로 취급하고 업데이트를 건너뜁니다.

1180</Warning>

1181 

1182<h5 id="example">

1183 예제

1184</h5>

1185 

1186```json theme={null}

1187{

1188 "name": "stable-tools",

1189 "plugins": [

1190 {

1191 "name": "code-formatter",

1192 "source": {

1193 "source": "github",

1194 "repo": "acme-corp/code-formatter",

1195 "ref": "stable"

1196 }

1197 }

1198 ]

1199}

1200```

1201 

1202```json theme={null}

1203{

1204 "name": "latest-tools",

1205 "plugins": [

1206 {

1207 "name": "code-formatter",

1208 "source": {

1209 "source": "github",

1210 "repo": "acme-corp/code-formatter",

1211 "ref": "latest"

1212 }

1213 }

1214 ]

1215}

1216```

1217 

1218<h5 id="assign-channels-to-user-groups">

1219 사용자 그룹에 채널 할당

1220</h5>

1221 

1222[릴리스 채널 설정](#set-up-release-channels) 아래에 설명된 그룹별 엔드포인트 관리 설정 또는 게이트웨이 정책을 통해 각 마켓플레이스를 적절한 사용자 그룹에 할당합니다. 예를 들어 stable 그룹은 다음을 받습니다:

1223 

1224```json theme={null}

1225{

1226 "extraKnownMarketplaces": {

1227 "stable-tools": {

1228 "source": {

1229 "source": "github",

1230 "repo": "acme-corp/stable-tools"

1231 }

1232 }

1233 }

1234}

1235```

1236 

1237early-access 그룹은 대신 `latest-tools`를 받습니다:

1238 

1239```json theme={null}

1240{

1241 "extraKnownMarketplaces": {

1242 "latest-tools": {

1243 "source": {

1244 "source": "github",

1245 "repo": "acme-corp/latest-tools"

1246 }

1247 }

1248 }

1249}

1250```

1251 

1252<h4 id="pin-dependency-versions">

1253 의존성 버전 고정

1254</h4>

1255 

1256플러그인은 의존성에 대한 semver 범위를 제한하여 의존성 업데이트가 종속 플러그인을 손상시키지 않도록 할 수 있습니다. `{plugin-name}--v{version}` git 태그 규칙, 범위 구문 및 동일한 의존성에 대한 여러 제약 조건이 어떻게 결합되는지에 대해서는 [플러그인 의존성 버전 제한](/docs/ko/plugin-dependencies)을 참조하세요.

1257 

1258<h3 id="rename-or-remove-a-plugin">

1259 플러그인 이름 바꾸기 또는 제거

1260</h3>

1261 

1262플러그인의 `name`은 안정적인 식별자입니다. 사용자는 `enabledPlugins`, `pluginConfigs` 및 `/plugin install` 명령에서 이를 참조하므로 변경하면 모든 기존 설치가 손상됩니다. UI에 표시되는 레이블을 설치를 손상시키지 않고 변경하려면 [`displayName`](#optional-plugin-fields)을 설정하고 `name`을 변경하지 않은 상태로 유지합니다.

1263 

1264플러그인의 `name`을 변경하거나 `plugins` 배열에서 플러그인을 제거해야 하는 경우 최상위 `renames` 항목을 추가하여 기존 사용자가 `plugin-not-found` 오류를 보는 대신 마이그레이션하도록 합니다. 자동 마이그레이션에는 Claude Code v2.1.193 이상이 필요합니다. 각 이전 이름을 현재 이름으로 매핑하거나 플러그인이 더 이상 존재하지 않으면 `null`로 매핑합니다. 다음 예제는 `formatter`를 `code-formatter`로 이름을 바꾸고 `legacy-linter`가 제거되었음을 기록합니다:

1265 

1266```json theme={null}

1267{

1268 "name": "acme-tools",

1269 "owner": { "name": "Acme" },

1270 "plugins": [

1271 { "name": "code-formatter", "source": "./plugins/code-formatter" }

1272 ],

1273 "renames": {

1274 "formatter": "code-formatter",

1275 "legacy-linter": null

1276 }

1277}

1278```

1279 

1280사용자가 설정에 여전히 이전 이름이 있는 상태로 Claude Code를 시작하면 Claude Code는 `renames` 맵을 따릅니다:

1281 

1282* 항목이 새 이름을 가리키면 Claude Code는 플러그인을 새 이름으로 로드하고 `"acme-tools" 마켓플레이스에서 "code-formatter"로 이름이 바뀌었습니다`와 같은 한 줄 알림을 표시합니다. 그런 다음 `enabledPlugins` 및 `pluginConfigs` 모두에 대해 사용자, 프로젝트 및 로컬 설정 범위에서 이전 키를 새 키로 다시 작성하므로 알림이 한 번 나타납니다.

1283* `null` 항목의 경우 Claude Code는 이전 키를 삭제하고 알림은 플러그인이 마켓플레이스에서 제거되었음을 보고합니다.

1284* 이름이 바뀐 플러그인이 `github` 또는 `npm`과 같은 원격 소스를 사용하면 Claude Code는 이름 바꾸기 후 `plugin-cache-miss`를 보고하고 사용자는 새 이름으로 가져오기 위해 한 번 `/plugin install`을 실행해야 합니다.

1285 

1286`renames`를 추가 전용 기록으로 취급합니다. 모든 사용자가 마이그레이션했을 것으로 예상한 후에도 이전 항목을 제자리에 유지합니다. Claude Code는 체인을 따르므로 나중에 `code-formatter`를 `formatter-pro`로 이름을 바꾸면 첫 번째 항목을 편집하는 대신 두 번째 항목을 추가합니다. 여전히 원본 `formatter`가 활성화된 사용자는 두 항목을 모두 통해 `formatter-pro`로 해석됩니다.

1287 

1288맵을 편집한 후 `claude plugin validate .`를 실행합니다. 체인이 사이클을 형성하거나 `null` 또는 `plugins`에 나열된 이름으로 종료되지 않는 항목을 거부합니다.

1289 

1290<Note>

1291 관리되는 설정 및 정책 설정은 Claude Code에 대해 읽기 전용이므로 거기에서 활성화된 플러그인은 자동으로 다시 작성될 수 없습니다. 이름이 바뀐 플러그인은 여전히 각 세션에서 로드되지만 관리자가 관리되는 설정 파일의 `enabledPlugins`을 새 이름으로 업데이트할 때까지 이름 바꾸기 알림이 반복됩니다. 동일한 사항이 `--add-dir`과 같은 다른 읽기 전용 소스를 통해 활성화된 플러그인에도 적용됩니다.

1292</Note>

1293 

1294이전 버전의 Claude Code는 `renames` 필드를 무시하고 이전 이름에 대해 `plugin-not-found`를 보고합니다.

1295 

1296<h2 id="validation-and-testing">

1297 검증 및 테스트

1298</h2>

1299 

1300마켓플레이스를 공유하기 전에 테스트합니다. 검증은 파일 구조를 확인합니다. 플러그인이 현실적인 프롬프트에서 Claude의 동작을 변경하는지 테스트하려면 새 버전을 게시하기 전에 [`claude plugin eval`](/docs/ko/plugin-evals)을 사용하여 평가 스위트를 실행합니다.

1301 

1302마켓플레이스 디렉토리에서 JSON 구문을 검증합니다:

1303 

1304```bash theme={null}

1305claude plugin validate .

1306```

1307 

1308또는 Claude Code 내에서:

1309 

1310```shell theme={null}

1311/plugin validate .

1312```

1313 

1314테스트를 위해 마켓플레이스를 추가합니다:

1315 

1316```shell theme={null}

1317/plugin marketplace add ./path/to/marketplace

1318```

1319 

1320모든 것이 작동하는지 확인하기 위해 테스트 플러그인을 설치합니다:

1321 

1322```shell theme={null}

1323/plugin install test-plugin@marketplace-name

1324```

1325 

1326전체 플러그인 테스트 워크플로우는 [플러그인을 로컬에서 테스트](/docs/ko/plugins#test-your-plugins-locally)를 참조하세요. 기술적 문제 해결은 [플러그인 참조](/docs/ko/plugins-reference)를 참조하세요.

1327 

1328<h2 id="manage-marketplaces-from-the-cli">

1329 CLI에서 마켓플레이스 관리

1330</h2>

1331 

1332Claude Code는 스크립팅 및 자동화를 위한 비대화형 `claude plugin marketplace` 하위 명령어를 제공합니다. 이는 대화형 세션 내에서 사용 가능한 `/plugin marketplace` 명령어와 동일합니다.

1333 

1334<h3 id="plugin-marketplace-add">

1335 플러그인 마켓플레이스 추가

1336</h3>

1337 

1338GitHub 저장소, git URL, 원격 URL 또는 로컬 경로에서 마켓플레이스를 추가합니다.

1339 

1340```bash theme={null}

1341claude plugin marketplace add <source> [options]

1342```

1343 

1344**인수:**

1345 

1346* `<source>`: GitHub `owner/repo` 단축형, git URL, `marketplace.json` 파일에 대한 원격 URL 또는 로컬 디렉터리 경로. 분기 또는 태그에 고정하려면 GitHub 단축형에 `@ref`를 추가하거나 git URL에 `#ref`를 추가합니다

1347 

1348URL은 스킴을 포함해야 합니다. Claude Code v2.1.196부터 `gitlab.example.com/team/plugins`와 같이 스킴 없이 입력된 호스트는 잘못된 `owner/repo` 단축형으로 거부되며, 오류 메시지에서 `https://`를 추가하거나 로컬 경로의 경우 `./`를 사용하도록 지시합니다. 이전 버전에서는 이를 GitHub 저장소 경로로 잘못 읽고 GitHub 찾을 수 없음 오류로 클론 시간에 실패합니다.

1349 

1350**옵션:**

1351 

1352| 옵션 | 설명 | 기본값 |

1353| :-------------------- | :------------------------------------------------------------------------------------------------------------------- | :----- |

1354| `--scope <scope>` | 마켓플레이스를 선언할 위치: `user`, `project` 또는 `local`. [플러그인 설치 범위](/docs/ko/plugins-reference#plugin-installation-scopes) 참조 | `user` |

1355| `--sparse <paths...>` | git sparse-checkout을 통해 특정 디렉터리로 체크아웃 제한. 모노레포에 유용 | |

1356| `--claudeai` | 인수를 소스 대신 [claude.ai에서 호스팅되는 마켓플레이스](/docs/ko/discover-plugins#add-from-claude-ai)의 이름으로 읽습니다. Claude Code v2.1.273 이상 필요 | |

1357 

1358GitHub에서 `owner/repo` 단축형을 사용하여 마켓플레이스 추가:

1359 

1360```bash theme={null}

1361claude plugin marketplace add acme-corp/claude-plugins

1362```

1363 

1364`@ref`를 사용하여 특정 분기 또는 태그에 고정:

1365 

1366```bash theme={null}

1367claude plugin marketplace add acme-corp/claude-plugins@v2.0

1368```

1369 

1370비 GitHub 호스트의 git URL에서 추가:

1371 

1372```bash theme={null}

1373claude plugin marketplace add https://gitlab.example.com/team/plugins.git

1374```

1375 

1376`marketplace.json` 파일을 직접 제공하는 원격 URL에서 추가:

1377 

1378```bash theme={null}

1379claude plugin marketplace add https://example.com/marketplace.json

1380```

1381 

1382테스트를 위해 로컬 디렉터리에서 추가:

1383 

1384```bash theme={null}

1385claude plugin marketplace add ./my-marketplace

1386```

1387 

1388마켓플레이스를 프로젝트 범위에서 선언하여 `.claude/settings.json`을 통해 팀과 공유:

1389 

1390```bash theme={null}

1391claude plugin marketplace add acme-corp/claude-plugins --scope project

1392```

1393 

1394모노레포의 경우 플러그인 콘텐츠를 포함하는 디렉터리로 체크아웃 제한:

1395 

1396```bash theme={null}

1397claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

1398```

1399 

1400`claude plugin marketplace list`의 `From claude.ai:` 섹션에 인쇄된 이름으로 [claude.ai에서 호스팅되는 마켓플레이스](/docs/ko/discover-plugins#add-from-claude-ai) 추가:

1401 

1402```bash theme={null}

1403claude plugin marketplace add --claudeai claudeai-organization-library

1404```

1405 

1406`--claudeai`를 사용하면 명령어는 `--scope`와 `--sparse`를 거부합니다. 마켓플레이스는 계정에 대해 호스팅되며 설정 파일에 선언되지 않으므로 프로젝트의 `.claude/settings.json`을 통해 공유할 수 없습니다.

1407 

1408<h3 id="plugin-marketplace-list">

1409 플러그인 마켓플레이스 목록

1410</h3>

1411 

1412구성된 모든 마켓플레이스를 나열합니다.

1413 

1414```bash theme={null}

1415claude plugin marketplace list [options]

1416```

1417 

1418**옵션:**

1419 

1420| 옵션 | 설명 |

1421| :------- | :-------- |

1422| `--json` | JSON으로 출력 |

1423 

1424`--json`을 사용하면 각 항목에는 `name`, `source`, 마켓플레이스가 저장된 로컬 캐시 경로가 있는 `installLocation` 필드 및 소스별 필드가 포함됩니다: GitHub 소스의 경우 `repo`, git 및 URL 소스의 경우 `url`, 로컬 소스의 경우 `path`. GitHub 및 git 소스는 마켓플레이스가 고정된 분기 또는 태그로 추가된 경우 `ref` 필드도 포함합니다.

1425 

1426추가된 [claude.ai 마켓플레이스](/docs/ko/discover-plugins#add-from-claude-ai)는 로컬 클론이 없으므로 해당 항목은 `installLocation` 대신 claude.ai 식별자인 `marketplaceId`와 `organizationUuid`를 포함합니다.

1427 

1428[플러그인이 claude.ai 계정에서 동기화되는](/docs/ko/plugins-reference#synced-plugins) 터미널 세션에서 텍스트 목록은 추가한 마켓플레이스 이상으로 계정에 대해 claude.ai가 나열하는 항목의 이름을 지정하는 `From claude.ai:` 섹션으로 끝납니다. 그 중 하나를 추가하려면 [claude.ai에서 추가](/docs/ko/discover-plugins#add-from-claude-ai)를 참조하세요. `--json` 출력은 구성된 마켓플레이스만 포함하고 해당 섹션을 제외합니다. Claude Code v2.1.273 이상 필요합니다.

1429 

1430<h3 id="plugin-marketplace-remove">

1431 플러그인 마켓플레이스 제거

1432</h3>

1433 

1434구성된 마켓플레이스를 제거합니다. 별칭 `rm`도 허용됩니다.

1435 

1436```bash theme={null}

1437claude plugin marketplace remove <name> [options]

1438```

1439 

1440**인수:**

1441 

1442* `<name>`: `claude plugin marketplace list`에 표시된 마켓플레이스 이름을 제거합니다. 이는 `add`에 전달한 소스가 아니라 `marketplace.json`의 `name`입니다

1443 

1444**옵션:**

1445 

1446| 옵션 | 설명 | 기본값 |

1447| :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |

1448| `--scope <scope>` | 제거를 단일 설정 범위로 제한: `user`, `project` 또는 `local`. [플러그인 설치 범위](/docs/ko/plugins-reference#plugin-installation-scopes) 참조. 생략하면 모든 편집 가능한 범위에서 선언이 제거됩니다. 지정하면 해당 범위의 선언만 제거되고, 마켓플레이스가 다른 범위에서 여전히 선언된 경우 공유 상태, 캐시 및 설치된 플러그인 데이터는 유지됩니다 | (모든 범위) |

1449 

1450<Warning>

1451 마켓플레이스를 마지막 남은 범위에서 제거하면 해당 마켓플레이스에서 설치한 모든 플러그인도 제거됩니다. 설치된 플러그인을 잃지 않고 마켓플레이스를 새로 고치려면 `claude plugin marketplace update`를 대신 사용합니다.

1452</Warning>

1453 

1454<h3 id="plugin-marketplace-update">

1455 플러그인 마켓플레이스 업데이트

1456</h3>

1457 

1458소스에서 마켓플레이스를 새로 고쳐 새 플러그인 및 버전 변경을 검색합니다. 분기 또는 태그 `ref`로 추가된 마켓플레이스는 저장소의 기본 분기가 아니라 해당 ref의 최신 커밋으로 업데이트됩니다.

1459 

1460```bash theme={null}

1461claude plugin marketplace update [name]

1462```

1463 

1464**인수:**

1465 

1466* `[name]`: `claude plugin marketplace list`에 표시된 마켓플레이스 이름을 업데이트합니다. 생략하면 모든 마켓플레이스를 업데이트합니다

1467 

1468`remove`와 `update` 모두 시드 관리 마켓플레이스에 대해 실행할 때 실패합니다. 이는 읽기 전용입니다. 모든 마켓플레이스를 업데이트할 때 시드 관리 항목은 건너뛰고 다른 마켓플레이스는 여전히 업데이트됩니다. 시드 제공 플러그인을 변경하려면 관리자에게 시드 이미지를 업데이트하도록 요청합니다. [컨테이너에 대한 플러그인 사전 채우기](#pre-populate-plugins-for-containers)를 참조하세요.

1469 

1470<h2 id="troubleshooting">

1471 문제 해결

1472</h2>

1473 

1474<h3 id="marketplace-not-loading">

1475 마켓플레이스가 로드되지 않음

1476</h3>

1477 

1478**증상**: 마켓플레이스를 추가할 수 없거나 플러그인을 볼 수 없습니다

1479 

1480**해결책**:

1481 

1482* 마켓플레이스 URL이 액세스 가능한지 확인합니다

1483* `.claude-plugin/marketplace.json`이 지정된 경로에 있는지 확인합니다

1484* `claude plugin validate .` 또는 `/plugin validate .`를 사용하여 JSON 구문이 유효한지 확인합니다. skill, agent 및 command frontmatter를 확인하려면 [매니페스트 없이 플러그인 또는 디렉터리 검증](#validate-a-plugin-or-a-directory-without-a-manifest)을 참조하세요

1485* 개인 저장소의 경우 액세스 권한이 있는지 확인합니다

1486 

1487<h3 id="marketplace-validation-errors">

1488 마켓플레이스 검증 오류

1489</h3>

1490 

1491마켓플레이스 디렉터리에서 `claude plugin validate .` 또는 `/plugin validate .`를 실행하여 문제를 확인합니다. 마켓플레이스 디렉터리를 가리킬 때 검증자는 `marketplace.json`에서 스키마 오류, 중복 플러그인 이름 및 소스 경로 순회를 확인합니다. `source`가 로컬 경로인 각 항목에 대해 해당 플러그인의 `plugin.json`도 검증하고 항목의 `version`이 `plugin.json`의 버전과 일치하지 않을 때 경고합니다. 플러그인의 `plugin.json`에서 발견된 문제는 항목 인덱스 형식인 `plugins[2] plugin.json →`으로 접두사가 붙습니다.

1492 

1493Claude Code v2.1.196부터 항목별 통과는 다음을 포함합니다:

1494 

1495* `source`가 `.`인 플러그인 포함

1496* `marketplace.json`이 `.claude-plugin` 디렉터리 외부에 있을 때 실행되며, 파일 자체의 디렉터리에 대해 소스를 해석합니다

1497* 파일의 다른 부분에 스키마 오류가 있을 때도 각 항목의 문제를 보고합니다

1498 

1499이전 버전은 마켓플레이스 루트의 플러그인을 건너뛰고 `.claude-plugin/marketplace.json`에서만 내려갑니다.

1500 

1501마켓플레이스 디렉터리에서 Claude Code는 플러그인의 skill, agent, command 또는 hook 파일을 열지 않습니다. 이러한 파일의 오류를 찾으려면 [매니페스트 없이 플러그인 또는 디렉터리 검증](#validate-a-plugin-or-a-directory-without-a-manifest)을 참조하세요. 아래 표는 마켓플레이스 디렉터리에서 가장 일반적인 오류와 각각의 원인 및 해결책을 나열합니다:

1502 

1503| 오류 | 원인 | 해결책 |

1504| :------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |

1505| `No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json` | 이름을 지정한 디렉터리에 `.claude-plugin/marketplace.json` 또는 `plugin.json`이 없고, 확인할 skill, agent 또는 command 파일이 없습니다 | 마켓플레이스 루트에서 실행하거나 필수 필드를 사용하여 `.claude-plugin/marketplace.json`을 생성합니다 |

1506| `Invalid JSON syntax: Unexpected token...` | marketplace.json의 JSON 구문 오류 | 누락된 쉼표, 추가 쉼표 또는 인용되지 않은 문자열 확인 |

1507| `Duplicate plugin name "x" found in marketplace` | 두 플러그인이 동일한 이름을 공유합니다 | 각 플러그인에 고유한 `name` 값 지정 |

1508| `plugins[0].source: Path contains ".."` | 소스 경로에 `..` 포함 | 마켓플레이스 루트에 상대적인 경로를 `..` 없이 사용합니다. [상대 경로](#relative-paths) 참조 |

1509| `Marketplace name cannot contain control or bidirectional-formatting characters` | 마켓플레이스 `name`에 이스케이프 또는 줄 바꿈과 같은 유니코드 양방향 형식 문자 또는 제어 문자가 포함되어 있습니다 | 이름에서 문자를 제거합니다. v2.1.247 이전에는 이러한 문자가 `Marketplace name impersonates an official Anthropic/Claude marketplace` 오류를 생성했습니다 |

1510| `Plugin name cannot contain control or bidirectional-formatting characters` | 플러그인 `name`에 유니코드 양방향 형식 문자 또는 이스케이프 또는 줄 바꿈과 같은 제어 문자가 포함되어 있습니다 | 이름에서 문자를 제거합니다. v2.1.247 이전에는 Claude Code가 이 검사를 실행하지 않았습니다 |

1511 

1512**경고**(차단하지 않음):

1513 

1514* `Marketplace has no plugins defined`: `plugins` 배열에 최소한 하나의 플러그인 추가

1515* `No marketplace description provided`: 사용자가 마켓플레이스를 이해하도록 돕기 위해 최상위 `description` 추가

1516* `Plugin name "x" is not kebab-case`: 소문자, 숫자 및 하이픈만 사용하도록 이름을 바꿉니다(예: `my-plugin`). Claude Code는 다른 형식을 허용하지만 claude.ai 마켓플레이스 동기화는 이를 거부합니다.

1517* `Marketplace name "x" is reserved in Claude Desktop`: 마켓플레이스의 이름이 `org`, `org-provisioned` 또는 `unknown`입니다(모든 대소문자). Claude Code는 이러한 이름을 허용하지만 Claude Desktop의 관리형 마켓플레이스 동기화는 전체 마켓플레이스를 거부합니다. 마켓플레이스의 이름을 바꿉니다. v2.1.221 이전에는 `claude plugin validate`가 이 검사를 실행하지 않았습니다.

1518* `Marketplace name "x" is not accepted by Claude Desktop` 또는 `Plugin name "x" is not accepted by Claude Desktop`: Claude Desktop은 문자 또는 숫자로 시작하는 최대 128자의 이름을 허용하며 문자, 숫자, `.`, `_` 및 `-`로 구성됩니다. Claude Code는 다른 형식을 허용하지만 Claude Desktop의 관리형 마켓플레이스 동기화는 이름 검사에 실패한 마켓플레이스를 거부하고 이름이 실패한 플러그인 항목을 자동으로 삭제합니다. 마켓플레이스 또는 플러그인의 이름을 바꿉니다. v2.1.221 이전에는 `claude plugin validate`가 이러한 검사를 실행하지 않았습니다.

1519 

1520<h4 id="validate-a-plugin-or-a-directory-without-a-manifest">

1521 매니페스트 없이 플러그인 또는 디렉터리 검증

1522</h4>

1523 

1524frontmatter가 구문 분석되지 않는 skill, agent 및 command 파일을 찾으려면 `claude plugin validate`를 실행하고 이들을 보유한 디렉터리의 이름을 지정합니다. Claude Code는 이름을 지정한 디렉터리 외부를 보지 않습니다. `plugin.json`이 있는 플러그인에 대한 한 번의 실행을 제외한 모든 실행에는 Claude Code v2.1.233 이상이 필요합니다.

1525 

1526<h5 id="pick-the-directory-to-name">

1527 이름을 지정할 디렉터리 선택

1528</h5>

1529 

1530Claude Code는 이름을 지정한 디렉터리에 따라 다른 파일을 확인합니다. 첫 번째 열에서 확인하려는 항목을 찾고 해당 행의 명령을 실행합니다:

1531 

1532| 확인 대상 | 실행 | Claude Code가 확인하는 항목 |

1533| :------------------------------------------------------------ | :---------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- |

1534| `plugin.json`이 있는 플러그인 | `claude plugin validate ./plugins/my-plugin` | `plugin.json`, `hooks/hooks.json` 및 플러그인 루트의 `skills`, `agents` 및 `commands` 디렉터리 |

1535| 아직 `plugin.json`이 없는 플러그인과 같은 skill, agent 또는 command의 한 디렉터리 | `claude plugin validate .claude/skills`, `~/.claude/agents` 또는 `./my-plugin/agents` | 해당 디렉터리의 모든 skill, agent 또는 command 파일 |

1536| skill이 루트 `SKILL.md`인 폴더 | `claude plugin validate ./skills`를 실행하고 폴더를 보유한 `skills` 디렉터리의 이름을 지정합니다 | 각 폴더의 루트 `SKILL.md`. 보유 디렉터리의 이름은 `skills`여야 합니다. `plugins/`와 같은 다른 이름의 폴더는 루트 `SKILL.md`를 확인하는 실행이 없습니다 |

1537| 프로젝트의 세 디렉터리 한 번에 | `claude plugin validate .claude` 또는 `.claude-plugin/` 매니페스트가 없을 때 프로젝트 루트 | `.claude/skills`, `.claude/agents` 및 `.claude/commands` |

1538| 사용자 수준 디렉터리 | `claude plugin validate ~/.claude` | `~/.claude/skills`, `~/.claude/agents` 및 `~/.claude/commands` |

1539 

1540<h5 id="check-a-plugin-whose-skill-is-its-root-skill-md">

1541 skill이 루트 `SKILL.md`인 플러그인 확인

1542</h5>

1543 

1544플러그인 디렉터리에 대해 `claude plugin validate`를 실행하면 Claude Code는 플러그인 루트의 `SKILL.md`를 확인하지 않습니다. 플러그인이 `skills`라는 이름의 디렉터리에 있을 때 명령을 두 번 실행합니다:

1545 

1546* 플러그인의 루트 `SKILL.md`를 확인하려면 해당 `skills` 디렉터리의 이름을 지정합니다.

1547* 나머지를 확인하려면 플러그인 디렉터리의 이름을 지정합니다.

1548 

1549플러그인이 `plugins/`와 같은 다른 이름 아래에 있을 때 `skills` 디렉터리 실행을 사용할 수 없으며 루트 `SKILL.md`를 확인하는 실행이 없습니다.

1550 

1551<h5 id="check-files-behind-symlinks">

1552 symlink 뒤의 파일 확인

1553</h5>

1554 

1555`claude plugin validate`를 실행하면 Claude Code는 이름을 지정한 디렉터리 내의 symlink를 따르지 않습니다. 링크가 있는 위치에 따라 수행하는 작업이 달라집니다:

1556 

1557* **플러그인 또는 `.claude` 루트 아래의 연결된 `skills`, `agents` 또는 `commands` 디렉터리**: Claude Code는 그 안의 아무것도 읽지 않았다고 경고합니다.

1558* **`skills`, `agents` 또는 `commands` 디렉터리 내의 연결된 항목**: Claude Code는 이를 건너뛰고 디렉터리별로 건너뛴 항목 수를 경고합니다.

1559* **이름을 지정한 `skills`, `agents` 또는 `commands` 디렉터리 자체가 symlink이거나 그 부모 `.claude` 디렉터리가 symlink인 경우**: Claude Code는 오류를 보고하고 그 안의 아무것도 확인하지 않습니다. 대신 실제 디렉터리의 이름을 지정합니다.

1560 

1561두 가지 skill 경우에 실행은 경고와 함께 통과합니다. 연결된 파일을 확인하려면 다시 실행하고 이들을 직접 보유한 디렉터리의 이름을 지정합니다:

1562 

1563* **`skills` 디렉터리가 [형제 플러그인의 skill에 연결된](/docs/ko/plugins-reference#share-files-within-a-marketplace-with-symlinks) 플러그인**: 형제 플러그인의 디렉터리의 이름을 지정합니다.

1564* **`~/.claude/skills` 또는 `.claude/skills`의 [symlinked skill 항목](/docs/ko/skills#where-skills-live)**: Claude Code는 세션에서 항목을 따릅니다. 이를 확인하려면 실제 폴더를 보유한 `skills`라는 디렉터리의 이름을 지정합니다.

1565 

1566<h5 id="read-the-validation-results">

1567 검증 결과 읽기

1568</h5>

1569 

1570깨끗한 실행은 `Validation passed`로 끝납니다.

1571 

1572`No manifest found in directory`는 Claude Code가 거기에서 `plugin.json` 또는 `marketplace.json`을 찾지 못했고 그 아래에서 조사하는 디렉터리에 skill, agent 또는 command 파일이 없음을 의미합니다. 대신 파일을 보유한 `skills`, `agents` 또는 `commands` 디렉터리의 이름을 지정합니다.

1573 

1574Claude Code가 이러한 실행에서 보고하는 두 가지 오류와 각각의 해결책:

1575 

1576* `YAML frontmatter failed to parse: ...`: skill, agent 또는 command 파일의 frontmatter 블록에서 YAML을 수정합니다. 이를 수행할 때까지 세션은 파일에서 frontmatter 필드를 읽지 않습니다

1577* `Invalid JSON syntax: ...` on `hooks/hooks.json`: JSON 구문을 수정합니다. 이를 수행할 때까지 세션은 해당 파일의 hook 없이 플러그인을 로드합니다. Claude Code는 플러그인 실행에서만 이 오류를 보고합니다

1578 

1579플러그인 실행에서 Claude Code는 플러그인 루트의 `CLAUDE.md`에 대해서도 경고합니다. `plugin.json`의 [component path fields](/docs/ko/plugins-reference#component-path-fields)를 통해 설정한 경로의 경우 Claude Code는 각 경로가 존재하는지 확인하지만 거기의 파일을 읽지 않습니다.

1580 

1581<h3 id="plugin-installation-failures">

1582 플러그인 설치 실패

1583</h3>

1584 

1585**증상**: 마켓플레이스가 나타나지만 플러그인 설치가 실패합니다

1586 

1587**해결책**:

1588 

1589* 플러그인 소스 URL이 액세스 가능한지 확인합니다

1590* 플러그인 디렉터리에 필수 파일이 포함되어 있는지 확인합니다

1591* GitHub 소스의 경우 저장소가 공개이거나 액세스 권한이 있는지 확인합니다

1592* 플러그인 소스를 수동으로 복제/다운로드하여 테스트합니다

1593* 소스가 `ref`와 `sha`를 모두 고정하는 경우 삭제된 업스트림 분기 또는 태그는 대부분의 git 호스트(GitHub, GitLab 및 Bitbucket 포함)에서 설치를 차단하지 않습니다. AWS CodeCommit과 같이 SHA로 커밋을 가져오기를 지원하지 않는 서버에서는 `ref`가 여전히 존재해야 하고 고정된 커밋이 이로부터 도달 가능해야 합니다. 설치가 계속 실패하면 고정된 커밋이 저장소에 여전히 존재하는지 확인합니다

1594 

1595<h3 id="private-repository-authentication-fails">

1596 개인 저장소 인증 실패

1597</h3>

1598 

1599**증상**: 개인 저장소에서 플러그인을 설치할 때 인증 오류

1600 

1601**해결책**:

1602 

1603수동 설치 및 업데이트의 경우:

1604 

1605* git 공급자로 인증되었는지 확인합니다(예: GitHub의 경우 `gh auth status` 실행).

1606* 자격 증명 도우미가 구성되었는지 확인합니다: `git config --global credential.helper`

1607* `git ls-remote <marketplace-url>`을 실행하여 git이 자체적으로 인증할 수 있는지 테스트합니다. git이 사용자 이름 또는 암호를 요청하면 먼저 자격 증명을 저장합니다: GitHub over HTTPS의 경우 `gh auth setup-git`을 실행하고, SSH 원격의 경우 `ssh-agent`에 키를 로드합니다

1608 

1609백그라운드 자동 업데이트의 경우:

1610 

1611* 백그라운드 새로 고침은 구성된 git 자격 증명 도우미를 사용하지만 절대 프롬프트하지 않으므로 도우미는 저장된 자격 증명으로 응답할 수 있어야 합니다. `ssh-agent`에 로드된 키가 있는 SSH 원격도 인증합니다

1612* 도우미가 프롬프트해야 하면 백그라운드 업데이트가 조용히 실패하고 기존 체크아웃이 제자리에 유지됩니다. 먼저 도우미에 로그인하여 호스트에 대한 자격 증명을 보유하도록 합니다. GitHub의 경우 `gh auth login`을 실행한 다음 `gh auth setup-git`을 실행합니다

1613* 확인이 새 커밋을 찾거나 원격에 도달하거나 인증할 수 없으면 Claude Code는 동일한 자격 증명으로 마켓플레이스를 다시 복제합니다. 다시 복제는 대규모 저장소에서 시간 초과될 수 있습니다

1614* `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1`을 설정하여 백그라운드 확인이 원격에 도달하거나 인증할 수 없을 때 기존 체크아웃을 유지합니다

1615* 대규모 저장소에서 다시 복제 시간이 초과되면 [`CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`](#git-operations-time-out)를 사용하여 제한을 늘립니다

1616* 또는 자격 증명을 사용하는 `/plugin marketplace update <name>`으로 개인 마켓플레이스를 수동으로 업데이트합니다

1617 

1618v2.1.280 이전에는 백그라운드 확인이 자격 증명 도우미 없이 실행되었고 HTTPS를 통해 개인 저장소에 인증할 수 없었습니다.

1619 

1620<h3 id="marketplace-updates-fail-in-offline-environments">

1621 마켓플레이스 업데이트가 오프라인 환경에서 실패합니다

1622</h3>

1623 

1624**증상**: 오프라인 또는 에어갭 환경에서 백그라운드 마켓플레이스 새로 고침이 원격에 도달할 수 없고 Claude Code가 성공할 수 없는 다시 복제를 반복적으로 시도합니다.

1625 

1626**원인**: 백그라운드 새로 고침은 마켓플레이스의 원격에서 새 커밋을 확인하고, 확인이 원격에 도달할 수 없으면 Claude Code는 마켓플레이스를 다시 복제하려고 시도합니다. 오프라인에서 복제는 동일한 방식으로 실패하고 기존 체크아웃은 제자리에 유지됩니다. v2.1.274 이전에는 새로 고침이 기존 체크아웃에서 `git pull`을 실행했고, pull이 실패하면 체크아웃을 옆으로 이동하여 다시 복제했으며, 그 후 최선의 노력으로 복원했습니다.

1627 

1628새로 고침은 시작 후 백그라운드에서 실행되므로 시작을 지연시키지 않습니다. 각 세션은 여전히 실패한 시도를 반복하고, 각 git 작업은 [120초 시간 초과](#git-operations-time-out)를 기다릴 수 있습니다.

1629 

1630**해결책**: `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1`을 설정하여 확인이 원격에 도달할 수 없을 때 다시 복제 시도를 건너뛰고 기존 체크아웃을 계속 사용합니다:

1631 

1632```bash theme={null}

1633export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

1634```

1635 

1636완전히 오프라인 배포의 경우 저장소에 절대 도달할 수 없으므로 대신 [`CLAUDE_CODE_PLUGIN_SEED_DIR`](#pre-populate-plugins-for-containers)을 사용하여 빌드 시간에 플러그인 디렉터리를 사전 채웁니다.

1637 

1638<h3 id="git-operations-time-out">

1639 Git 작업 시간 초과

1640</h3>

1641 

1642**증상**: 플러그인 설치 또는 마켓플레이스 업데이트가 `Git clone timed out after 120s`와 같은 시간 초과 오류로 실패합니다.

1643 

1644**원인**: Claude Code는 플러그인 저장소 복제 및 마켓플레이스 업데이트를 포함한 모든 git 작업에 120초 시간 초과를 사용합니다. 대규모 저장소 또는 느린 네트워크 연결이 이 제한을 초과할 수 있습니다.

1645 

1646**해결책**: `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` 환경 변수를 사용하여 시간 초과를 늘립니다. 값은 밀리초 단위입니다:

1647 

1648```bash theme={null}

1649export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000 # 5분

1650```

1651 

1652<h3 id="plugins-with-relative-paths-fail-in-url-based-marketplaces">

1653 상대 경로가 있는 플러그인이 URL 기반 마켓플레이스에서 실패합니다

1654</h3>

1655 

1656**증상**: URL을 통해 마켓플레이스를 추가했습니다(예: `https://example.com/marketplace.json`). 하지만 `"./plugins/my-plugin"`과 같은 상대 경로 소스가 있는 플러그인이 `its marketplace entry path does not stay inside the marketplace directory` 오류로 설치되지 않습니다. 이미 설치된 플러그인이 `Plugin source path refused` 오류로 로드되지 않습니다. 두 메시지 모두 [오류 참조 항목](/docs/ko/errors#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory)이 있습니다.

1657 

1658**원인**: URL 기반 마켓플레이스를 추가하면 `marketplace.json` 파일 자체만 다운로드됩니다. Claude Code는 해당 서버에서 플러그인 파일을 상대 경로로 가져오지 않습니다. 마켓플레이스 항목의 상대 경로는 다운로드되지 않은 원격 서버의 파일을 참조합니다.

1659 

1660**해결책**:

1661 

1662* **외부 소스 사용**: 플러그인 항목을 상대 경로 이외의 [플러그인 소스](#plugin-sources)로 변경합니다:

1663 ```json theme={null}

1664 { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }

1665 ```

1666* **Git 기반 마켓플레이스 사용**: 마켓플레이스를 Git 저장소에서 호스팅하고 git URL로 추가합니다. Git 기반 마켓플레이스는 전체 저장소를 복제하므로 상대 경로가 올바르게 작동합니다.

1667 

1668<h3 id="files-not-found-after-installation">

1669 설치 후 파일을 찾을 수 없음

1670</h3>

1671 

1672**증상**: 플러그인이 설치되지만 파일 참조가 실패합니다. 특히 플러그인 디렉터리 외부의 파일

1673 

1674**원인**: Claude Code는 플러그인을 제자리에 로드하지 않는 한 캐시 디렉터리에 복사합니다. [`command` source in link mode](#copy-mode-and-link-mode)는 제자리에 로드되고, [상대 경로 소스](#relative-paths)도 마켓플레이스에서 로컬 디렉터리로 추가된 경우 제자리에 로드됩니다. 복사된 플러그인의 디렉터리 외부의 파일을 참조하는 경로(예: `../shared-utils`)는 해당 파일이 복사되지 않기 때문에 작동하지 않습니다.

1675 

1676**해결책**: symlink 및 디렉터리 재구성을 포함한 해결 방법은 [플러그인 캐싱 및 파일 해석](/docs/ko/plugins-reference#plugin-caching-and-file-resolution)을 참조하세요.

1677 

1678추가 디버깅 도구 및 일반적인 문제는 [디버깅 및 개발 도구](/docs/ko/plugins-reference#debugging-and-development-tools)를 참조하세요.

1679 

1680<h2 id="see-also">

1681 참고 항목

1682</h2>

1683 

1684* [미리 빌드된 플러그인 검색 및 설치](/docs/ko/discover-plugins) - 기존 마켓플레이스에서 플러그인 설치

1685* [플러그인](/docs/ko/plugins) - 자신의 플러그인 생성

1686* [플러그인 참조](/docs/ko/plugins-reference) - 완전한 기술 사양 및 스키마

1687* [플러그인 설정](/docs/ko/settings-reference#plugin-settings) - 플러그인 구성 옵션

1688* [strictKnownMarketplaces 참조](/docs/ko/settings-reference#strictknownmarketplaces) - 관리되는 마켓플레이스 제한