플러그인 마켓플레이스를 통해 팀이나 커뮤니티에 Claude Code 확장 기능을 중앙에서 배포할 수 있습니다. 마켓플레이스는 플러그인 검색, 버전 추적, 자동 업데이트를 지원하며 Git 저장소, 로컬 경로 등 다양한 소스를 지원합니다.

기존 마켓플레이스에서 플러그인을 설치하려면 플러그인 발견 및 설치 가이드를 참조하세요.

마켓플레이스 개요

마켓플레이스를 만들고 배포하는 과정은 다음과 같습니다.

1. 플러그인 생성: 명령어, 에이전트, 훅, MCP 서버, LSP 서버를 포함한 플러그인을 빌드합니다
2. 마켓플레이스 파일 생성: 플러그인과 해당 위치를 나열하는 marketplace.json을 정의합니다
3. 마켓플레이스 호스팅: GitHub, GitLab 또는 다른 Git 호스트에 푸시합니다
4. 사용자와 공유: 사용자가 /plugin marketplace add로 마켓플레이스를 추가하고 개별 플러그인을 설치합니다

로컬 마켓플레이스 빠른 시작

코드 리뷰용 /review 스킬이 포함된 마켓플레이스를 만드는 예시입니다.

1. 디렉토리 구조 생성

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

2. 스킬 생성

my-marketplace/plugins/review-plugin/skills/review/SKILL.md 파일 생성:

---
description: Review code for bugs, security, and performance
disable-model-invocation: true
---

Review the code I've selected or the recent changes for:
- Potential bugs or edge cases
- Security concerns
- Performance issues
- Readability improvements

Be concise and actionable.

3. 플러그인 매니페스트 생성

my-marketplace/plugins/review-plugin/.claude-plugin/plugin.json 파일 생성:

{
  "name": "review-plugin",
  "description": "Adds a /review skill for quick code reviews",
  "version": "1.0.0"
}

4. 마켓플레이스 파일 생성

my-marketplace/.claude-plugin/marketplace.json 파일 생성:

{
  "name": "my-plugins",
  "owner": {
    "name": "Your Name"
  },
  "plugins": [
    {
      "name": "review-plugin",
      "source": "./plugins/review-plugin",
      "description": "Adds a /review skill for quick code reviews"
    }
  ]
}

5. 설치 및 테스트

/plugin marketplace add ./my-marketplace
/plugin install review-plugin@my-plugins
/review

마켓플레이스 파일 구조

저장소 루트의 .claude-plugin/marketplace.json에 마켓플레이스 파일을 생성합니다.

필수 필드

예약된 이름: claude-code-marketplace, claude-code-plugins, anthropic-marketplace 등의 이름은 Anthropic 공식 사용을 위해 예약되어 있습니다.

완전한 마켓플레이스 파일 예시

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "metadata": {
    "description": "사내 개발 도구 모음",
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "저장 시 자동 코드 포맷팅",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "배포 자동화 도구"
    }
  ]
}

플러그인 소스 유형

GitHub 소스 예시

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

특정 브랜치, 태그 또는 커밋에 고정할 수 있습니다.

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

GitHub에 호스팅 (권장)

1. 마켓플레이스를 위한 새 저장소 생성
2. .claude-plugin/marketplace.json 추가
3. 팀과 공유: owner/repo 형식으로 추가

/plugin marketplace add owner/repo

다른 Git 서비스

GitLab, Bitbucket 등 모든 Git 호스팅 서비스를 사용할 수 있습니다.

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

비공개 저장소

Claude Code는 비공개 저장소의 플러그인 설치를 지원합니다. git clone이 터미널에서 작동한다면 Claude Code에서도 작동합니다.

백그라운드 자동 업데이트를 위해서는 다음 환경 변수를 설정하세요.

팀을 위한 마켓플레이스 설정

프로젝트에 마켓플레이스 포함하기

.claude/settings.json에 마켓플레이스를 추가하면 팀원이 프로젝트 폴더를 신뢰할 때 자동으로 마켓플레이스 설치를 안내받습니다.

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

관리자 마켓플레이스 제한

관리자는 사용자가 추가할 수 있는 플러그인 마켓플레이스를 제한하기 위해 관리 설정의 strictKnownMarketplaces를 사용할 수 있습니다.

모든 마켓플레이스 추가 비활성화:

{
  "strictKnownMarketplaces": []
}

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

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    }
  ]
}

내부 Git 서버의 모든 마켓플레이스 허용:

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

제한은 네트워크 요청이나 파일 시스템 작업이 발생하기 전에 검증됩니다.

릴리스 채널 설정

안정(stable)과 최신(latest) 릴리스 채널을 지원하려면 동일한 저장소의 다른 ref를 가리키는 두 개의 마켓플레이스를 설정합니다.

// stable-marketplace.json
{
  "name": "stable-tools",
  "plugins": [{
    "name": "code-formatter",
    "source": {
      "source": "github",
      "repo": "acme-corp/code-formatter",
      "ref": "stable"
    }
  }]
}

// latest-marketplace.json
{
  "name": "latest-tools",
  "plugins": [{
    "name": "code-formatter",
    "source": {
      "source": "github",
      "repo": "acme-corp/code-formatter",
      "ref": "latest"
    }
  }]
}

중요: 각 ref에서 플러그인의 plugin.json에 다른 version이 선언되어야 합니다. 두 ref의 매니페스트 버전이 같으면 Claude Code가 동일하게 처리하여 업데이트를 건너뜁니다.

검증 및 테스트

배포 전에 마켓플레이스를 검증하세요.

# 명령줄에서 검증
claude plugin validate .

# Claude Code 내에서 검증
/plugin validate .

# 로컬 마켓플레이스 추가 및 테스트
/plugin marketplace add ./path/to/marketplace
/plugin install test-plugin@marketplace-name

일반적인 검증 오류

문제 해결

URL 기반 마켓플레이스에서 상대 경로 실패

URL로 마켓플레이스를 추가하면(https://example.com/marketplace.json) 시스템이 marketplace.json 파일만 다운로드합니다. 상대 경로의 플러그인 파일은 서버에서 다운로드되지 않아 설치에 실패합니다.

해결 방법: GitHub, npm, Git URL 소스를 사용하거나 Git 기반 마켓플레이스를 사용하세요. Git 기반 마켓플레이스는 전체 저장소를 복제하므로 상대 경로가 올바르게 작동합니다.

설치 후 파일을 찾을 수 없음

플러그인은 설치 시 캐시 위치(~/.claude/plugins/cache)에 복사됩니다. 플러그인 디렉토리 외부 파일을 참조하는 경로(../shared-utils 등)는 작동하지 않습니다.

해결 방법: 훅과 MCP 서버 구성에서 ${CLAUDE_PLUGIN_ROOT} 변수를 사용하여 플러그인 설치 디렉토리 내의 파일을 참조하세요.

다음 단계

• 플러그인 설치: 기존 마켓플레이스에서 플러그인을 발견하고 설치하는 방법을 알아봅니다
• 플러그인 생성: 자체 플러그인을 만드는 방법을 확인합니다
• 플러그인 참조: 전체 기술 사양 및 스키마를 검토합니다
• 서버 관리 설정: 관리 설정을 통해 마켓플레이스 접근을 제어합니다
• 권한 관리: 조직의 플러그인 사용 정책을 설정합니다