Claude Code v2.1.139부터 Plugin Marketplace 기능이 추가되었습니다!

Skill, Agent, Hook, MCP Server 설정을 하나로 패키지화하여, 사용자가 간단한 명령어를 입력하는 것만으로 사내 기준이나 특정 표준에 따른 환경을 통째로 재현할 수 있는 메커니즘입니다.

명령어 내용은 아래에 기재되어 있습니다!

이 기사에서는 로컬에서 마켓플레이스를 만들고 테스트하기까지의 절차와, 실제로 겪었던 문제점(ハマりどころ)들을 정리했습니다!

플러그인에 포함할 수 있는 것은 다음 4가지 종류입니다.

이것들을 하나의 플러그인으로 묶어 GitHub에서 관리하고, 사용자는 설치 명령어를 한 번 실행하는 것만으로 전부 설치할 수 있어, npm의 Claude Code 버전과 같은 느낌으로 사용할 수 있습니다!

Claude Code CLI v2.1.139 이후 버전이 필요합니다 (claude --version으로 확인).

v2.1.139 미만 버전에서는 /plugin 명령어 자체가 존재하지 않으므로 업데이트해 주세요.

claude install

npm install -g가 아니라 claude install이 v2.1.165 이후의 권장 방법입니다.

fnm 등의 Node.js 버전 매니저를 사용하는 환경에서는 npm install -g로 설치한 바이너리가 PATH에 반영되지 않아 이전 버전 그대로 남아 있는 경우가 있습니다. claude install을 사용하면 ~/.local/bin/claude에 네이티브 바이너리가 배치되므로 Node.js 환경에 의존하지 않습니다.

먼저 임의의 디렉토리에 마켓플레이스용 폴더를 생성합니다.

mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/my-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/my-plugin/skills/aws-review
...

완성된 디렉토리 구조는 다음과 같습니다.

my-marketplace/
├── .claude-plugin/
│ └── marketplace.json # 마켓플레이스 정의
...

각 파일의 내용 (클릭하여 확장)

.claude-plugin/marketplace.json

{
"name": "my-marketplace",
"owner": {
...

plugins/my-plugin/.claude-plugin/plugin.json

{
"name": "my-plugin",
"version": "0.1.0",
...

plugins/my-plugin/skills/aws-review/SKILL.md

---
name: aws-review
description: AWS 설계 리뷰를 실시함
...

plugins/my-plugin/agents/aws-architect.md

---
name: aws-architect
description: AWS 아키텍트 지원 Agent
...

plugins/my-plugin/hooks/hooks.json

{
"hooks": {
"PostToolUse": [
...

plugins/my-plugin/.mcp.json

{
"mcpServers": {
"sharepoint": {
...

플러그인의 동작 확인은 **마켓플레이스 본체와는 별개의 리포지토리(Repository)**에서 진행해 주세요. 마켓플레이스를 만든 디렉토리와 같은 장소에서 테스트하면, 플러그인 파일과 본인의 파일이 혼재되어 파악하기 어려워집니다.

적절한 테스트용 디렉토리를 생성하고, 그곳에서 claude를 실행합니다.

mkdir ~/test-repo && cd ~/test-repo
claude

VS Code 확장 기능의 채팅창에서는 /plugin 명령어를 실행할 수 없습니다.

VS Code 확장 기능은 독자적인 번들 바이너리 (bundled binary)를 사용하고 있어, 터미널의 claude CLI와는 별개로 동작합니다.

터미널에서 claude를 실행하여 진행해 주세요. 설정은 ~/.claude/settings.json에 저장되므로, CLI에서 조작한 내용은 VS Code 확장 기능에도 자동으로 반영됩니다. claude 실행 후, 다음 명령어를 실행합니다.

/plugin marketplace add /path/to/my-marketplace

성공하면 다음과 같이 표시됩니다.

Successfully added marketplace: my-marketplace

/plugin install my-plugin@my-marketplace

설치 범위 (scope)를 선택하는 화면이 나타납니다.

/reload-plugins

Reloaded: 1 plugin · 0 skills · 7 agents · 1 hook · 1 plugin MCP server

설치한 스킬 (skill)이나 에이전트 (agent)를 사용할 수 있게 됩니다.

실제로 추가된 스킬 등은 /help 명령어로 확인할 수 있습니다.

실제로 사용해 보면 다음과 같은 느낌입니다.

[IMG:1]

정상적으로 리뷰되고 있음을 확인할 수 있었습니다.

[IMG:2]

로컬 경로를 GitHub URL로 바꾸기만 하면 절차는 완전히 동일합니다.

/plugin marketplace add https://github.com/org/my-marketplace
/plugin install my-plugin@my-marketplace

프라이빗 리포지토리(private repository)의 경우, gh auth login이 완료되어 있다면 추가 설정은 필요 없습니다. 백그라운드 자동 업데이트까지 대응하고 싶다면 환경 변수에 토큰을 설정합니다.

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

설치의 입도 (Granularity)

• 마켓플레이스 → 플러그인 단위로 선택 설치
• 플러그인 내부 (Skill/Agent/Hook/MCP)는 개별 선택 불가. 플러그인 단위로 전부 설치됨

업데이트

• 자동 업데이트는 없음 (현 시점)
• 스킬·에이전트를 편집했다면 /reload-plugins로 다시 로드합니다.
• 원격 마켓플레이스를 최신으로 업데이트하려면 /plugin marketplace update를 사용합니다.

파일 배치 위치

Plugin Marketplace는 "Claude Code의 사내 표준 환경을 코드로 관리하여 배포한다"라는 용도에 딱 들어맞는 기능입니다. GitHub에 올려 팀원 모두가 동일한 스킬, 에이전트, Hook을 사용할 수 있는 상태로 만들 수 있습니다.

반면, /plugin 명령어가 CLI 전용이라는 점은 주의가 필요하며, VS Code 확장 기능 사용자에게는 "채팅창에서 입력하면 되겠지"라는 흐름이 막히게 됩니다. 팀에 전개할 때는 이 절차를 명시해 두는 것이 좋습니다.