메인 콘텐츠로 건너뛰기
플러그인 마켓플레이스는 Claude Code 확장 프로그램을 쉽게 발견, 설치 및 관리할 수 있도록 하는 사용 가능한 플러그인의 카탈로그입니다. 이 가이드는 기존 마켓플레이스를 사용하는 방법과 팀 배포를 위한 자신만의 마켓플레이스를 만드는 방법을 보여줍니다.

​
개요

마켓플레이스는 사용 가능한 플러그인을 나열하고 플러그인을 찾을 수 있는 위치를 설명하는 JSON 파일입니다. 마켓플레이스는 다음을 제공합니다:
  • 중앙 집중식 발견: 한 곳에서 여러 소스의 플러그인 찾아보기
  • 버전 관리: 플러그인 버전을 자동으로 추적 및 업데이트
  • 팀 배포: 조직 전체에서 필수 플러그인 공유
  • 유연한 소스: git 저장소, GitHub 저장소, 로컬 경로 및 패키지 관리자 지원

​
필수 조건

  • Claude Code 설치 및 실행
  • JSON 파일 형식에 대한 기본 이해
  • 마켓플레이스 생성: Git 저장소 또는 로컬 개발 환경

​
마켓플레이스 추가 및 사용

/plugin marketplace 명령을 사용하여 마켓플레이스를 추가하여 다양한 소스의 플러그인에 액세스합니다:

​
GitHub 마켓플레이스 추가

.claude-plugin/marketplace.json을 포함하는 GitHub 저장소 추가
/plugin marketplace add owner/repo

​
Git 저장소 추가

모든 git 저장소 추가
/plugin marketplace add https://gitlab.com/company/plugins.git

​
개발을 위한 로컬 마켓플레이스 추가

.claude-plugin/marketplace.json을 포함하는 로컬 디렉토리 추가
/plugin marketplace add ./my-marketplace
marketplace.json 파일에 대한 직접 경로 추가
/plugin marketplace add ./path/to/marketplace.json
URL을 통해 원격 marketplace.json 추가
/plugin marketplace add https://url.of/marketplace.json

​
마켓플레이스에서 플러그인 설치

마켓플레이스를 추가한 후 플러그인을 직접 설치합니다:
알려진 마켓플레이스에서 설치
/plugin install plugin-name@marketplace-name
대화형으로 사용 가능한 플러그인 찾아보기
/plugin

​
마켓플레이스 설치 확인

마켓플레이스를 추가한 후:
  1. 마켓플레이스 나열: /plugin marketplace list를 실행하여 추가되었는지 확인합니다
  2. 플러그인 찾아보기: /plugin을 사용하여 마켓플레이스에서 사용 가능한 플러그인을 봅니다
  3. 설치 테스트: 플러그인을 설치하여 마켓플레이스가 올바르게 작동하는지 확인합니다

​
팀 마켓플레이스 구성

.claude/settings.json에서 필수 마켓플레이스를 지정하여 팀 프로젝트에 대한 자동 마켓플레이스 설치를 설정합니다: 
{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    },
    "project-specific": {
      "source": {
        "source": "git",
        "url": "https://git.company.com/project-plugins.git"
      }
    }
  }
}
팀 멤버가 저장소 폴더를 신뢰하면 Claude Code는 이러한 마켓플레이스와 enabledPlugins 필드에 지정된 모든 플러그인을 자동으로 설치합니다.

​
자신만의 마켓플레이스 만들기

팀 또는 커뮤니티를 위한 사용자 정의 플러그인 컬렉션을 빌드하고 배포합니다.

​
마켓플레이스 생성을 위한 필수 조건

  • Git 저장소 (GitHub, GitLab 또는 기타 git 호스팅)
  • JSON 파일 형식 이해
  • 배포할 하나 이상의 플러그인

​
마켓플레이스 파일 만들기

저장소 루트에 .claude-plugin/marketplace.json을 만듭니다: 
{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

​
마켓플레이스 스키마

​
필수 필드

필드유형설명
namestring마켓플레이스 식별자 (kebab-case, 공백 없음)
ownerobject마켓플레이스 유지 관리자 정보
pluginsarray사용 가능한 플러그인 목록

​
선택적 메타데이터

필드유형설명
metadata.descriptionstring간단한 마켓플레이스 설명
metadata.versionstring마켓플레이스 버전
metadata.pluginRootstring상대 플러그인 소스의 기본 경로

​
플러그인 항목

플러그인 항목은 플러그인 매니페스트 스키마(모든 필드가 선택적으로 만들어짐)와 마켓플레이스 특정 필드(source, category, tags, strict)를 기반으로 하며, name은 필수입니다.
필수 필드:
필드유형설명
namestring플러그인 식별자 (kebab-case, 공백 없음)
sourcestring|object플러그인을 가져올 위치

​
선택적 플러그인 필드

표준 메타데이터 필드:
필드유형설명
descriptionstring간단한 플러그인 설명
versionstring플러그인 버전
authorobject플러그인 작성자 정보
homepagestring플러그인 홈페이지 또는 문서 URL
repositorystring소스 코드 저장소 URL
licensestringSPDX 라이선스 식별자 (예: MIT, Apache-2.0)
keywordsarray플러그인 발견 및 분류를 위한 태그
categorystring조직을 위한 플러그인 카테고리
tagsarray검색 가능성을 위한 태그
strictboolean플러그인 폴더에서 plugin.json 필요 (기본값: true) 1
컴포넌트 구성 필드:
필드유형설명
commandsstring|array명령 파일 또는 디렉토리에 대한 사용자 정의 경로
agentsstring|array에이전트 파일에 대한 사용자 정의 경로
hooksstring|object사용자 정의 훅 구성 또는 훅 파일 경로
mcpServersstring|objectMCP 서버 구성 또는 MCP 구성 경로
1 - strict: true(기본값)일 때 플러그인은 plugin.json 매니페스트 파일을 포함해야 하며, 마켓플레이스 필드는 해당 값을 보완합니다. strict: false일 때 plugin.json은 선택사항입니다. 누락된 경우 마켓플레이스 항목이 완전한 플러그인 매니페스트로 사용됩니다.

​
플러그인 소스

​
상대 경로

동일한 저장소의 플러그인: 
{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

​
GitHub 저장소

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

​
Git 저장소

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

​
고급 플러그인 항목

플러그인 항목은 기본 컴포넌트 위치를 재정의하고 추가 메타데이터를 제공할 수 있습니다. ${CLAUDE_PLUGIN_ROOT}는 플러그인의 설치 디렉토리로 확인되는 환경 변수입니다 (자세한 내용은 환경 변수 참조): 
{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "[email protected]"
  },
  "homepage": "https://docs.company.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
}
스키마 관계: 플러그인 항목은 모든 필드가 선택적으로 만들어진 플러그인 매니페스트 스키마와 마켓플레이스 특정 필드(source, strict, category, tags)를 사용합니다. 이는 plugin.json 파일에서 유효한 모든 필드를 마켓플레이스 항목에서도 사용할 수 있음을 의미합니다. strict: false일 때 plugin.json이 없으면 마켓플레이스 항목이 완전한 플러그인 매니페스트로 사용됩니다. strict: true(기본값)일 때 마켓플레이스 필드는 플러그인의 자체 매니페스트 파일을 보완합니다.

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

플러그인 배포 요구 사항에 가장 적합한 호스팅 전략을 선택합니다.

​
GitHub에서 호스팅 (권장)

GitHub는 가장 쉬운 배포 방법을 제공합니다:
  1. 저장소 만들기: 마켓플레이스를 위한 새 저장소 설정
  2. 마켓플레이스 파일 추가: 플러그인 정의를 사용하여 .claude-plugin/marketplace.json 만들기
  3. 팀과 공유: 팀 멤버가 /plugin marketplace add owner/repo로 추가
이점: 기본 제공 버전 제어, 문제 추적 및 팀 협업 기능.

​
다른 git 서비스에서 호스팅

모든 git 호스팅 서비스는 임의의 git 저장소에 URL을 사용하여 마켓플레이스 배포에 작동합니다. 예를 들어 GitLab 사용: 
/plugin marketplace add https://gitlab.com/company/plugins.git

​
개발을 위해 로컬 마켓플레이스 사용

배포 전에 로컬에서 마켓플레이스를 테스트합니다:
테스트를 위해 로컬 마켓플레이스 추가
/plugin marketplace add ./my-local-marketplace
플러그인 설치 테스트
/plugin install test-plugin@my-local-marketplace

​
마켓플레이스 작업 관리

​
알려진 마켓플레이스 나열

구성된 모든 마켓플레이스 나열
/plugin marketplace list
소스 및 상태와 함께 구성된 모든 마켓플레이스를 표시합니다.

​
마켓플레이스 메타데이터 업데이트

마켓플레이스 메타데이터 새로 고침
/plugin marketplace update marketplace-name
마켓플레이스 소스에서 플러그인 목록 및 메타데이터를 새로 고칩니다.

​
마켓플레이스 제거

마켓플레이스 제거
/plugin marketplace remove marketplace-name
구성에서 마켓플레이스를 제거합니다.
마켓플레이스를 제거하면 해당 마켓플레이스에서 설치한 모든 플러그인이 제거됩니다.

​
마켓플레이스 문제 해결

​
일반적인 마켓플레이스 문제

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

증상: 마켓플레이스를 추가할 수 없거나 플러그인을 볼 수 없음 해결책:
  • 마켓플레이스 URL이 액세스 가능한지 확인합니다
  • .claude-plugin/marketplace.json이 지정된 경로에 있는지 확인합니다
  • claude plugin validate를 사용하여 JSON 구문이 유효한지 확인합니다
  • 비공개 저장소의 경우 액세스 권한이 있는지 확인합니다

​
플러그인 설치 실패

증상: 마켓플레이스는 나타나지만 플러그인 설치가 실패함 해결책:
  • 플러그인 소스 URL이 액세스 가능한지 확인합니다
  • 플러그인 디렉토리에 필수 파일이 포함되어 있는지 확인합니다
  • GitHub 소스의 경우 저장소가 공개이거나 액세스 권한이 있는지 확인합니다
  • 플러그인 소스를 수동으로 복제/다운로드하여 테스트합니다

​
검증 및 테스트

공유하기 전에 마켓플레이스를 테스트합니다:
마켓플레이스 JSON 구문 검증
claude plugin validate .
테스트를 위해 마켓플레이스 추가
/plugin marketplace add ./path/to/marketplace
테스트 플러그인 설치
/plugin install test-plugin@marketplace-name
완전한 플러그인 테스트 워크플로우는 플러그인을 로컬에서 테스트를 참조하세요. 기술 문제 해결은 플러그인 참조를 참조하세요.

​
다음 단계

​
마켓플레이스 사용자의 경우

  • 커뮤니티 마켓플레이스 발견: GitHub에서 Claude Code 플러그인 컬렉션 검색
  • 피드백 제공: 마켓플레이스 유지 관리자에게 문제 보고 및 개선 제안
  • 유용한 마켓플레이스 공유: 팀이 유용한 플러그인 컬렉션을 발견하도록 도움

​
마켓플레이스 작성자의 경우

  • 플러그인 컬렉션 빌드: 특정 사용 사례 주변에 테마별 마켓플레이스 만들기
  • 버전 관리 설정: 명확한 버전 관리 및 업데이트 정책 구현
  • 커뮤니티 참여: 피드백 수집 및 활성 마켓플레이스 커뮤니티 유지
  • 문서: 마켓플레이스 내용을 설명하는 명확한 README 파일 제공

​
조직의 경우

  • 비공개 마켓플레이스: 독점 도구를 위한 내부 마켓플레이스 설정
  • 거버넌스 정책: 플러그인 승인 및 보안 검토를 위한 지침 수립
  • 교육 리소스: 팀이 유용한 플러그인을 효과적으로 발견하고 채택하도록 지원

​
참고 항목