마켓플레이스 운영

마켓플레이스는 marketplace.json 파일을 가진 저장소 또는 디렉토리입니다. 팀 또는 조직 단위로 플러그인을 중앙 관리하고 배포할 때 사용합니다.

마켓플레이스 구조

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json    # 마켓플레이스 선언
└── plugins/
    ├── plugin-a/           # 플러그인 디렉토리
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   └── skills/
    └── plugin-b/

marketplace.json 기본 형식

{
  "name": "my-org-plugins",
  "description": "팀 내부 플러그인 마켓플레이스",
  "plugins": [
    {
      "name": "formatter",
      "description": "코드 포맷터 + 린터 자동화",
      "source": "./plugins/formatter"
    },
    {
      "name": "deploy-kit",
      "description": "배포 자동화 도구 모음",
      "source": "https://github.com/my-org/deploy-kit"
    }
  ]
}

플러그인 소스는 로컬 경로, GitHub 저장소 URL, Git URL, 또는 Zip 아카이브 URL 중 하나입니다.

마켓플레이스 로컬 테스트

로컬에서 마켓플레이스를 추가하고 검증합니다:

# 로컬 마켓플레이스 추가
/plugin marketplace add ./my-marketplace

# 또는 JSON 파일 직접 지정
/plugin marketplace add ./my-marketplace/.claude-plugin/marketplace.json

등록 후 /plugin Discover 탭에서 해당 마켓플레이스의 플러그인 목록을 확인합니다.

마켓플레이스 호스팅

GitHub 저장소로 호스팅

가장 단순한 방법입니다.

# 마켓플레이스 저장소 추가
/plugin marketplace add your-org/plugins

# 특정 브랜치·태그 고정
/plugin marketplace add your-org/plugins#v2.0.0

HTTPS URL로 마켓플레이스 JSON 호스팅

정적 파일 서버에 marketplace.json을 올리는 방법:

/plugin marketplace add https://cdn.example.com/marketplace.json

Zip 아카이브 배포 (v2.1.224+)

Git 없이 HTTPS로 플러그인을 배포할 때 사용합니다. marketplace.json의 source 필드에 아카이브 URL을 지정합니다:

{
  "name": "internal-toolkit",
  "source": {
    "type": "archive",
    "url": "https://cdn.example.com/plugins/internal-toolkit-v1.2.zip",
    "sha256": "e3b0c44298fc1c149afbf4c8996fb924..."
  }
}

sha256를 지정하면 다운로드 무결성 검사가 이루어집니다.

자동 업데이트 설정

마켓플레이스 수준에서 플러그인 자동 업데이트 여부를 제어할 수 있습니다.

마켓플레이스 종류	자동 업데이트 기본값
Anthropic 공식 (claude-plugins-official 등)	ON
커뮤니티, 서드파티, 로컬	OFF

사용자가 /plugin → Marketplaces 탭에서 수동으로 전환할 수 있습니다.

버전 관리

플러그인 plugin.json에 version 필드를 설정하면 사용자가 해당 버전에 고정됩니다. 릴리스 태그 컨벤션:

{plugin-name}--v{version}

예: secrets-vault--v2.1.0

태그 생성과 동시에 plugin.json과 marketplace.json을 검증하려면:

claude plugin tag --push

플러그인 추천 (relevance, v2.1.152+)

사용자의 작업 맥락과 일치하는 플러그인을 Claude Code가 자동으로 제안하게 할 수 있습니다. marketplace.json의 플러그인 항목에 relevance 블록을 추가합니다:

{
  "name": "terraform-helpers",
  "source": "./plugins/terraform-helpers",
  "relevance": {
    "topic": "Terraform",
    "signals": {
      "cli": ["terraform"],
      "filesRead": ["**/*.tf"]
    }
  }
}

신호(signals) 종류:

신호	설명
cwd	현재 작업 디렉토리 패턴
cli	사용자가 실행한 명령
hosts	접근한 URL 호스트
filesRead	읽은 파일 경로 패턴
manifestDeps	매니페스트 의존성

하나라도 신호가 매칭되면 플러그인 설치를 제안합니다. 신호 매칭은 로컬에서만 발생하며, Anthropic이나 마켓플레이스 운영자에게 신호 정보가 전송되지 않습니다.

활성화 조건

relevance 블록만으로는 제안이 노출되지 않습니다. 관리자가 managed settings의 pluginSuggestionMarketplaces에 마켓플레이스를 허용 목록에 추가해야 합니다.

개인 사용자라면

이 기능은 마켓플레이스 운영자·기업 관리자를 위한 것입니다. 플러그인을 설치만 한다면 플러그인 설치 및 관리를 참조하세요.

플러그인 배포 방법

직접 전달 (소수 대상)

Zip 파일 또는 디렉토리를 직접 전달합니다. 마켓플레이스가 필요 없습니다.

# 수신자가 로컬 경로로 플러그인 로드
claude --plugin-dir ./received-plugin

자체 마켓플레이스 경유

팀원들이 마켓플레이스를 한 번 등록한 뒤 이름으로 설치합니다.

# 마켓플레이스 등록
/plugin marketplace add your-org/plugins

# 이름으로 설치
/plugin install formatter@your-org

Anthropic 공식 디렉토리 제출

공개 사용이 목적이라면 Anthropic의 디렉토리에 제출합니다:

1. README.md 작성
2. 시맨틱 버저닝 적용
3. claude plugin validate ./my-plugin 통과 확인
4. claude.ai/marketplace에서 제출

조직 단위 플러그인 관리

관리자는 managed settings로 플러그인 정책을 강제 적용할 수 있습니다.

{
  "pluginSuggestionMarketplaces": ["your-org-plugins"],
  "allowedPluginMarketplaces": ["claude-plugins-official", "your-org-plugins"],
  "forcedPlugins": ["security-scanner@claude-plugins-official"]
}

• allowedPluginMarketplaces: 허용할 마켓플레이스 목록
• forcedPlugins: 모든 사용자에게 강제 설치·활성화할 플러그인

자세한 정책 설정은 공식 플러그인 조직 관리 문서를 참조하세요.

---

다음 챕터: 플러그인 개요 →