Claude Code Plugin Marketplace를 사용해 본 도입 절차와 문제 해결 방법 정리

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

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

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

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

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

종류	내용
Skill	Claude가 참조하는 지식·절차서 (/aws-review와 같은 슬래시 명령어)
Agent	서브 에이전트(Sub-agent)로 호출할 수 있는 커스텀 에이전트 정의
Hook	파일 편집 후의 Lint 자동 실행 등, 조작에 연동되어 동작하는 셸(Shell) 명령어
MCP Server 설정	SharePoint, Confluence 등 외부 도구로의 접속 설정

이것들을 하나의 플러그인으로 묶어 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)를 선택하는 화면이 나타납니다.

범위 (Scope)	효과
user	모든 리포지토리에서 유효 (권장)
project	리포지토리 내의 모든 협업자에게 유효
local	본인의 이 리포지토리에서만 유효

/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를 사용합니다.

파일 배치 위치

위치	역할
마켓플레이스 디렉토리	정의 원본 (편집하는 곳)
~/.claude/plugins/cache/	설치 시의 캐시 (실제로 로드되는 곳)

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

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