플러그인 마켓플레이스 생성 및 배포

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

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

기존 마켓플레이스에서 플러그인을 설치하려고 하시나요? 미리 빌드된 플러그인 검색 및 설치를 참조하세요.

개요

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

1. 플러그인 생성: skills, 에이전트, hooks, MCP 서버 또는 LSP 서버를 사용하여 하나 이상의 플러그인을 빌드합니다. 이 가이드에서는 배포할 플러그인이 이미 있다고 가정합니다. 플러그인 생성 방법에 대한 자세한 내용은 플러그인 생성을 참조하세요.
2. 마켓플레이스 파일 생성: 플러그인을 나열하고 플러그인을 찾을 위치를 정의하는 marketplace.json을 정의합니다(마켓플레이스 파일 생성 참조).
3. 마켓플레이스 호스팅: GitHub, GitLab 또는 다른 git 호스트에 푸시합니다(마켓플레이스 호스팅 및 배포 참조).
4. 사용자와 공유: 사용자가 /plugin marketplace add로 마켓플레이스를 추가하고 개별 플러그인을 설치합니다(플러그인 검색 및 설치 참조).

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

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

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

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

---
description: 버그, 보안 및 성능에 대한 코드 검토
disable-model-invocation: true
---

선택한 코드 또는 최근 변경 사항을 다음 항목에 대해 검토합니다:
- 잠재적 버그 또는 엣지 케이스
- 보안 문제
- 성능 문제
- 가독성 개선

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

{
"name": "quality-review-plugin",
"description": "빠른 코드 리뷰를 위한 quality-review skill 추가",
"version": "1.0.0"
}

{
"name": "my-plugins",
"owner": {
"name": "Your Name"
},
"plugins": [
{
"name": "quality-review-plugin",
"source": "./plugins/quality-review-plugin",
"description": "빠른 코드 리뷰를 위한 quality-review skill 추가"
}
]
}

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

/quality-review-plugin:quality-review

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

마켓플레이스 파일 생성

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

각 플러그인 항목에는 최소한 name과 source(가져올 위치)가 필요합니다. 사용 가능한 모든 필드는 아래의 전체 스키마를 참조하세요.

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "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": "배포 자동화 도구"
    }
  ]
}

마켓플레이스 스키마

필수 필드

소유자 필드

선택적 필드

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

플러그인 항목

plugins 배열의 각 플러그인 항목은 플러그인과 플러그인을 찾을 위치를 설명합니다. 플러그인 매니페스트 스키마의 모든 필드(예: description, version, author, commands, hooks 등)와 이러한 마켓플레이스 특정 필드를 포함할 수 있습니다: source, category, tags 및 strict.

필수 필드

선택적 플러그인 필드

표준 메타데이터 필드:

구성 요소 구성 필드:

플러그인 소스

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

플러그인이 로컬 머신에 복제되거나 복사되면 ~/.claude/plugins/cache의 로컬 버전 관리 플러그인 캐시에 복사됩니다.

git 기반 소스 유형은 아래의 github, url, 및 git-subdir입니다. ref와 sha가 모두 설정되면 sha가 유효한 핀입니다. Claude Code는 고정된 커밋을 직접 가져오고 체크아웃하므로 분기 또는 태그가 업스트림에서 삭제되었더라도 커밋이 저장소에서 여전히 도달 가능한 한 설치가 성공합니다.

상대 경로

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

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

경로는 마켓플레이스 루트(.claude-plugin/을 포함하는 디렉터리)에 상대적으로 해석됩니다. 위의 예에서 ./plugins/my-plugin은 marketplace.json이 <repo>/.claude-plugin/marketplace.json에 있더라도 <repo>/plugins/my-plugin을 가리킵니다. 마켓플레이스 루트 외부로 나가기 위해 ../를 사용하지 마세요.

GitHub 저장소

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

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

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

Git 저장소

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

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

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Git 하위 디렉터리

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

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin"
  }
}

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

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

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

npm 패키지

npm 패키지로 배포되는 플러그인은 npm install을 사용하여 설치됩니다. 이는 공개 npm 레지스트리 또는 팀이 호스팅하는 개인 레지스트리의 모든 패키지에서 작동합니다.

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}

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

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0"
  }
}

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

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

고급 플러그인 항목

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

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "enterprise@example.com"
  },
  "homepage": "https://docs.example.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

주목할 주요 사항:

• commands 및 agents: 여러 디렉터리 또는 개별 파일을 지정할 수 있습니다. 경로는 플러그인 루트에 상대적입니다.
• ${CLAUDE_PLUGIN_ROOT}: hooks 및 MCP 서버 구성에서 이 변수를 사용하여 플러그인의 설치 디렉터리 내의 파일을 참조합니다. 플러그인이 설치될 때 캐시 위치에 복사되기 때문에 필요합니다. 플러그인 업데이트를 통해 유지되어야 하는 종속성 또는 상태의 경우 ${CLAUDE_PLUGIN_DATA}를 대신 사용합니다.
• strict: false: 이것이 false로 설정되어 있으므로 플러그인은 자신의 plugin.json이 필요하지 않습니다. 마켓플레이스 항목이 모든 것을 정의합니다. 아래의 Strict 모드를 참조하세요.

기본적으로 플러그인의 skills는 해당 source 아래의 skills/ 디렉터리에서 로드되며, skills 아래에 나열된 모든 경로가 해당 스캔에 추가됩니다. 예외는 source: "./"와 같은 마켓플레이스 루트 소스이며, 여러 플러그인 항목이 하나의 skills/ 폴더를 공유합니다. 이 경우 skills/ 아래에 특정 하위 디렉터리를 나열하면 해당 목록이 항목의 완전한 집합이 되며, skills/ 아래의 다른 디렉터리는 로드되지 않습니다. skills/ 디렉터리 자체 또는 플러그인 루트를 나열하면 전체 스캔이 유지됩니다. 나열된 경로 중 어느 것도 존재하지 않으면 기본 스캔이 대신 실행됩니다.

Strict 모드

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

각 모드를 사용할 때:

• strict: true: 플러그인은 자신의 plugin.json을 가지고 있으며 자신의 구성 요소를 관리합니다. 마켓플레이스 항목은 맨 위에 추가 skills 또는 hooks를 추가할 수 있습니다. 이것이 기본값이며 대부분의 플러그인에서 작동합니다.
• strict: false: 마켓플레이스 운영자가 완전한 제어를 원합니다. 플러그인 저장소는 원본 파일을 제공하고 마켓플레이스 항목은 이러한 파일 중 어느 것이 skills, 에이전트, hooks 등으로 노출되는지 정의합니다. 마켓플레이스가 플러그인 작성자의 의도와 다르게 플러그인의 구성 요소를 재구성하거나 큐레이션할 때 유용합니다.

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

GitHub에서 호스팅(권장)

GitHub는 가장 쉬운 배포 방법을 제공합니다:

1. 저장소 생성: 마켓플레이스를 위한 새 저장소 설정
2. 마켓플레이스 파일 추가: 플러그인 정의와 함께 .claude-plugin/marketplace.json 생성
3. 팀과 공유: 사용자가 /plugin marketplace add owner/repo로 마켓플레이스를 추가합니다

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

다른 git 서비스에서 호스팅

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

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

개인 저장소

Claude Code는 개인 저장소에서 플러그인 설치를 지원합니다. 수동 설치 및 업데이트의 경우 Claude Code는 기존 git 자격 증명 도우미를 사용합니다. 따라서 HTTPS 액세스는 gh auth login, macOS Keychain 또는 git-credential-store를 통해 터미널에서와 동일하게 작동합니다. SSH 액세스는 호스트가 이미 known_hosts 파일에 있고 키가 ssh-agent에 로드되어 있는 한 작동합니다. Claude Code는 호스트 지문 및 키 암호에 대한 대화형 SSH 프롬프트를 억제하기 때문입니다.

백그라운드 자동 업데이트는 대화형 프롬프트가 Claude Code 시작을 차단하므로 자격 증명 도우미 없이 시작 시 실행됩니다. 개인 마켓플레이스에 대한 자동 업데이트를 활성화하려면 환경에서 적절한 인증 토큰을 설정합니다:

셸 구성(예: .bashrc, .zshrc)에서 토큰을 설정하거나 Claude Code를 실행할 때 전달합니다:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

배포 전에 로컬에서 테스트

공유하기 전에 마켓플레이스를 로컬에서 테스트합니다:

/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace

추가 명령어의 전체 범위(GitHub, Git URL, 로컬 경로, 원격 URL)는 마켓플레이스 추가를 참조하세요.

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

프로젝트 폴더를 신뢰할 때 팀 구성원이 자동으로 마켓플레이스를 설치하도록 저장소를 구성할 수 있습니다. 마켓플레이스를 .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
  }
}

전체 구성 옵션은 플러그인 설정을 참조하세요.

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

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

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

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

$CLAUDE_CODE_PLUGIN_SEED_DIR/
  known_marketplaces.json
  marketplaces/<name>/...
  cache/<marketplace>/<plugin>/<version>/...

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

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

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins

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

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

동작 세부 정보:

• 읽기 전용: 시드 디렉터리는 절대 쓰기되지 않습니다. git pull이 읽기 전용 파일 시스템에서 실패하므로 시드 마켓플레이스에 대해 자동 업데이트가 비활성화됩니다.
• 시드 항목이 우선합니다: 시드에서 선언된 마켓플레이스는 각 시작 시 사용자 구성의 일치하는 항목을 덮어씁니다. 시드 플러그인을 거부하려면 마켓플레이스를 제거하는 대신 /plugin disable을 사용합니다.
• 경로 해석: Claude Code는 시드의 JSON 내에 저장된 경로를 신뢰하지 않고 런타임에 $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/을 탐색하여 마켓플레이스 콘텐츠를 찾습니다. 이는 시드가 빌드된 위치와 다른 경로에 마운트된 경우에도 시드가 올바르게 작동함을 의미합니다.
• 변경 차단: 시드 관리 마켓플레이스에 대해 /plugin marketplace remove 또는 /plugin marketplace update를 실행하면 시드 이미지를 업데이트하도록 관리자에게 문의하라는 지침과 함께 실패합니다.
• 설정과 구성: extraKnownMarketplaces 또는 enabledPlugins이 시드에 이미 존재하는 마켓플레이스를 선언하면 Claude Code는 복제하는 대신 시드 복사본을 사용합니다.

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

플러그인 소스에 대한 엄격한 제어가 필요한 조직의 경우 관리자는 관리되는 설정에서 strictKnownMarketplaces 설정을 사용하여 사용자가 추가할 수 있는 플러그인 마켓플레이스를 제한할 수 있습니다.

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

일반적인 구성

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

{
  "strictKnownMarketplaces": []
}

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

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    }
  ]
}

호스트에 대한 정규식 패턴 일치를 사용하여 내부 git 서버의 모든 마켓플레이스 허용. 이는 GitHub Enterprise Server 또는 자체 호스팅 GitLab 인스턴스에 권장되는 방법입니다:

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

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

{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}

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

제한 작동 방식

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

허용 목록은 대부분의 소스 유형에 대해 정확한 일치를 사용합니다. 마켓플레이스가 허용되려면 지정된 모든 필드가 정확히 일치해야 합니다:

• GitHub 소스의 경우: repo는 필수이며 허용 목록에 지정된 경우 ref 또는 path도 일치해야 합니다
• URL 소스의 경우: 전체 URL이 정확히 일치해야 합니다
• hostPattern 소스의 경우: 마켓플레이스 호스트가 정규식 패턴과 일치합니다
• pathPattern 소스의 경우: 마켓플레이스의 파일 시스템 경로가 정규식 패턴과 일치합니다

정확한 일치는 URL을 정규화하지 않습니다. 후행 슬래시, .git 접미사 또는 ssh:// 대 https:// 형식은 다른 값으로 취급됩니다. 조직의 마켓플레이스를 둘 이상의 URL 형식으로 복제할 수 있는 경우 모든 형식이 일치하도록 리터럴 URL보다 hostPattern 항목을 선호합니다.

strictKnownMarketplaces는 관리되는 설정에서 설정되므로 개별 사용자 및 프로젝트 구성은 이러한 제한을 재정의할 수 없습니다.

전체 구성 세부 정보(지원되는 모든 소스 유형 및 extraKnownMarketplaces와의 비교 포함)는 strictKnownMarketplaces 참조를 참조하세요.

버전 해석 및 릴리스 채널

플러그인 버전은 캐시 경로 및 업데이트 감지를 결정합니다. 해석된 버전이 사용자가 이미 가지고 있는 것과 일치하면 /plugin update 및 자동 업데이트는 플러그인을 건너뜁니다.

Claude Code는 다음 중 설정된 첫 번째 항목에서 플러그인의 버전을 해석합니다:

1. 플러그인의 plugin.json의 version
2. 플러그인의 마켓플레이스 항목의 version
3. 플러그인 소스의 git 커밋 SHA

git 기반 소스 유형 github, url, git-subdir 및 git 호스팅 마켓플레이스 내의 상대 경로의 경우 version을 완전히 생략할 수 있으며 모든 새 커밋은 새 버전으로 취급됩니다. 이는 내부 또는 활발하게 개발 중인 플러그인에 대한 가장 간단한 설정입니다.

릴리스 채널 설정

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

예제

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

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

사용자 그룹에 채널 할당

관리되는 설정을 통해 각 마켓플레이스를 적절한 사용자 그룹에 할당합니다. 예를 들어 stable 그룹은 다음을 받습니다:

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}

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

{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/latest-tools"
      }
    }
  }
}

의존성 버전 고정

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

검증 및 테스트

공유하기 전에 마켓플레이스를 테스트합니다.

마켓플레이스 JSON 구문 검증:

claude plugin validate .

또는 Claude Code 내에서:

/plugin validate .

테스트를 위해 마켓플레이스 추가:

/plugin marketplace add ./path/to/marketplace

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

/plugin install test-plugin@marketplace-name

전체 플러그인 테스트 워크플로우는 플러그인을 로컬에서 테스트를 참조하세요. 기술적 문제 해결은 플러그인 참조를 참조하세요.

CLI에서 마켓플레이스 관리

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

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

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

claude plugin marketplace add <source> [options]

인수:

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

옵션:

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

claude plugin marketplace add acme-corp/claude-plugins

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

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

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

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

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

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

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

claude plugin marketplace add ./my-marketplace

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

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

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

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

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

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

claude plugin marketplace list [options]

옵션:

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

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

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

claude plugin marketplace remove <name> [options]

인수:

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

옵션:

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

소스에서 마켓플레이스를 새로 고쳐 새 플러그인 및 버전 변경을 검색합니다.

claude plugin marketplace update [name]

인수:

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

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

문제 해결

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

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

해결책:

• 마켓플레이스 URL이 액세스 가능한지 확인합니다
• .claude-plugin/marketplace.json이 지정된 경로에 있는지 확인합니다
• claude plugin validate 또는 /plugin validate를 사용하여 JSON 구문이 유효한지 확인합니다. skill, agent 및 command frontmatter를 확인하려면 각 플러그인 디렉터리에 대해 명령을 실행합니다
• 개인 저장소의 경우 액세스 권한이 있는지 확인합니다

마켓플레이스 검증 오류

마켓플레이스 디렉터리에서 claude plugin validate . 또는 /plugin validate .를 실행하여 문제를 확인합니다. 마켓플레이스 디렉터리를 가리킬 때 검증자는 marketplace.json만 확인합니다: 스키마, 중복 플러그인 이름, 소스 경로 순회 및 각 참조된 plugin.json에 대한 버전 불일치.

개별 플러그인의 plugin.json 및 해당 skill, agent, command 및 hook 파일을 검증하려면 플러그인 디렉터리 자체에 대해 명령을 실행합니다(예: claude plugin validate ./plugins/my-plugin). 일반적인 오류:

경고(차단하지 않음):

• Marketplace has no plugins defined: plugins 배열에 최소한 하나의 플러그인 추가
• No marketplace description provided: 사용자가 마켓플레이스를 이해하도록 돕기 위해 최상위 description 추가
• Plugin name "x" is not kebab-case: 플러그인 이름에 대문자, 공백 또는 특수 문자가 포함되어 있습니다. 소문자, 숫자 및 하이픈만 사용하도록 이름을 바꿉니다(예: my-plugin). Claude Code는 다른 형식을 허용하지만 Claude.ai 마켓플레이스 동기화는 이를 거부합니다.

플러그인 설치 실패

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

해결책:

• 플러그인 소스 URL이 액세스 가능한지 확인합니다
• 플러그인 디렉터리에 필수 파일이 포함되어 있는지 확인합니다
• GitHub 소스의 경우 저장소가 공개이거나 액세스 권한이 있는지 확인합니다
• 플러그인 소스를 수동으로 복제/다운로드하여 테스트합니다
• 소스가 ref와 sha를 모두 고정하는 경우 삭제된 업스트림 분기 또는 태그는 설치를 차단하지 않습니다. 설치가 계속 실패하면 고정된 커밋이 저장소에 여전히 존재하는지 확인합니다

개인 저장소 인증 실패

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

해결책:

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

• git 공급자로 인증되었는지 확인합니다(예: GitHub의 경우 gh auth status 실행).
• 자격 증명 도우미가 올바르게 구성되었는지 확인합니다: git config --global credential.helper
• 저장소를 수동으로 복제하여 자격 증명이 작동하는지 확인합니다

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

• 환경에서 적절한 토큰이 설정되었는지 확인합니다: echo $GITHUB_TOKEN
• 토큰에 필수 권한이 있는지 확인합니다(저장소에 대한 읽기 액세스)
• GitHub의 경우 토큰에 개인 저장소에 대한 repo 범위가 있는지 확인합니다
• GitLab의 경우 토큰에 최소한 read_repository 범위가 있는지 확인합니다
• 토큰이 만료되지 않았는지 확인합니다

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

증상: 마켓플레이스 git pull이 실패하고 Claude Code가 기존 캐시를 삭제하여 플러그인을 사용할 수 없게 됩니다.

원인: 기본적으로 git pull이 실패하면 Claude Code는 오래된 복제본을 제거하고 다시 복제를 시도합니다. 오프라인 또는 에어갭 환경에서 다시 복제가 동일한 방식으로 실패하여 마켓플레이스 디렉터리가 비어 있게 됩니다.

해결책: CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1을 설정하여 pull이 실패할 때 기존 캐시를 삭제하는 대신 유지합니다:

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

이 변수가 설정되면 Claude Code는 git pull 실패 시 오래된 마켓플레이스 복제본을 유지하고 마지막으로 알려진 좋은 상태를 계속 사용합니다. 저장소에 절대 도달할 수 없는 완전히 오프라인 배포의 경우 대신 CLAUDE_CODE_PLUGIN_SEED_DIR을 사용하여 빌드 시간에 플러그인 디렉터리를 사전 채웁니다.

Git 작업 시간 초과

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

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

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

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5분

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

증상: URL을 통해 마켓플레이스를 추가했습니다(예: https://example.com/marketplace.json). 하지만 "./plugins/my-plugin"과 같은 상대 경로 소스가 있는 플러그인이 "path not found" 오류로 설치되지 않습니다.

원인: URL 기반 마켓플레이스는 marketplace.json 파일 자체만 다운로드합니다. 서버에서 플러그인 파일을 다운로드하지 않습니다. 마켓플레이스 항목의 상대 경로는 다운로드되지 않은 원격 서버의 파일을 참조합니다.

해결책:

• 외부 소스 사용: 플러그인 항목을 상대 경로 대신 GitHub, npm 또는 git URL 소스를 사용하도록 변경합니다:

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

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

설치 후 파일을 찾을 수 없음

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

원인: 플러그인은 제자리에 사용되지 않고 캐시 디렉터리에 복사됩니다. 플러그인 디렉터리 외부의 파일을 참조하는 경로(예: ../shared-utils)는 해당 파일이 복사되지 않기 때문에 작동하지 않습니다.

해결책: symlink 및 디렉터리 재구성을 포함한 해결 방법은 플러그인 캐싱 및 파일 해석을 참조하세요.

추가 디버깅 도구 및 일반적인 문제는 디버깅 및 개발 도구를 참조하세요.

참고 항목

• 미리 빌드된 플러그인 검색 및 설치 - 기존 마켓플레이스에서 플러그인 설치
• 플러그인 - 자신의 플러그인 생성
• 플러그인 참조 - 완전한 기술 사양 및 스키마
• 플러그인 설정 - 플러그인 구성 옵션
• strictKnownMarketplaces 참조 - 관리되는 마켓플레이스 제한