플러그인 마켓플레이스

플러그인 마켓플레이스는 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

마켓플레이스 설치 확인

마켓플레이스를 추가한 후:

마켓플레이스 목록: /plugin marketplace list를 실행하여 추가되었는지 확인
플러그인 탐색: /plugin을 사용하여 마켓플레이스에서 사용 가능한 플러그인 확인
설치 테스트: 플러그인을 설치해보고 마켓플레이스가 올바르게 작동하는지 확인

팀 마켓플레이스 구성

.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": "저장 시 자동 코드 포맷팅",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "배포 자동화 도구"
    }
  ]
}

마켓플레이스 스키마

필수 필드

필드	타입	설명
`name`	string	마켓플레이스 식별자 (kebab-case, 공백 없음)
`owner`	object	마켓플레이스 관리자 정보
`plugins`	array	사용 가능한 플러그인 목록

선택적 메타데이터

필드	타입	설명
`metadata.description`	string	간단한 마켓플레이스 설명
`metadata.version`	string	마켓플레이스 버전
`metadata.pluginRoot`	string	상대 플러그인 소스의 기본 경로

플러그인 항목

플러그인 항목은 플러그인 매니페스트 스키마를 기반으로 하며 (모든 필드가 선택사항으로 만들어짐) 마켓플레이스별 필드(source, category, tags, strict)가 추가되고, name이 필수입니다.

필수 필드:

필드	타입	설명
`name`	string	플러그인 식별자 (kebab-case, 공백 없음)
`source`	string\|object	플러그인을 가져올 위치

선택적 플러그인 필드

표준 메타데이터 필드:

필드	타입	설명
`description`	string	간단한 플러그인 설명
`version`	string	플러그인 버전
`author`	object	플러그인 작성자 정보
`homepage`	string	플러그인 홈페이지 또는 문서 URL
`repository`	string	소스 코드 저장소 URL
`license`	string	SPDX 라이선스 식별자 (예: MIT, Apache-2.0)
`keywords`	array	플러그인 발견 및 분류를 위한 태그
`category`	string	조직을 위한 플러그인 카테고리
`tags`	array	검색 가능성을 위한 태그
`strict`	boolean	플러그인 폴더에 plugin.json 필요 (기본값: true) ¹

컴포넌트 구성 필드:

필드	타입	설명
`commands`	string\|array	명령 파일 또는 디렉토리에 대한 사용자 정의 경로
`agents`	string\|array	에이전트 파일에 대한 사용자 정의 경로
`hooks`	string\|object	사용자 정의 훅 구성 또는 훅 파일 경로
`mcpServers`	string\|object	MCP 서버 구성 또는 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": "엔터프라이즈 워크플로우 자동화 도구",
  "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는 가장 쉬운 배포 방법을 제공합니다:

저장소 생성: 마켓플레이스를 위한 새 저장소 설정
마켓플레이스 파일 추가: 플러그인 정의가 포함된 .claude-plugin/marketplace.json 생성
팀과 공유: 팀 구성원이 /plugin marketplace add owner/repo로 추가

장점: 내장된 버전 제어, 이슈 추적, 팀 협업 기능.

다른 git 서비스에서 호스팅

임의의 git 저장소에 대한 URL을 사용하여 모든 git 호스팅 서비스가 마켓플레이스 배포에 작동합니다. 예를 들어, 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

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

다음 단계

마켓플레이스 사용자를 위해

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

마켓플레이스 생성자를 위해

플러그인 컬렉션 구축: 특정 사용 사례를 중심으로 한 테마별 마켓플레이스 생성
버전 관리 설정: 명확한 버전 관리 및 업데이트 정책 구현
커뮤니티 참여: 피드백 수집 및 활발한 마켓플레이스 커뮤니티 유지
문서화: 마켓플레이스 내용을 설명하는 명확한 README 파일 제공

조직을 위해

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

참고 항목

플러그인 - 플러그인 설치 및 사용
플러그인 참조 - 완전한 기술 사양 및 스키마
플러그인 개발 - 자체 플러그인 생성
설정 - 플러그인 구성 옵션

시작하기

Claude Code로 구축하기

Claude Code SDK

배포

관리

구성

참조

리소스

​개요

​전제 조건

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

​GitHub 마켓플레이스 추가

​Git 저장소 추가

​개발용 로컬 마켓플레이스 추가

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

​마켓플레이스 설치 확인

​팀 마켓플레이스 구성

​자체 마켓플레이스 생성

​마켓플레이스 생성을 위한 전제 조건

​마켓플레이스 파일 생성

​마켓플레이스 스키마

​필수 필드

​선택적 메타데이터

​플러그인 항목

​선택적 플러그인 필드

​플러그인 소스

​상대 경로

​GitHub 저장소

​Git 저장소

​고급 플러그인 항목

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

​GitHub에서 호스팅 (권장)

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

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

​마켓플레이스 운영 관리

​알려진 마켓플레이스 목록

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

​마켓플레이스 제거

​마켓플레이스 문제 해결

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

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

​플러그인 설치 실패

​검증 및 테스트

​다음 단계

​마켓플레이스 사용자를 위해

​마켓플레이스 생성자를 위해

​조직을 위해

​참고 항목

개요

전제 조건

마켓플레이스 추가 및 사용

GitHub 마켓플레이스 추가

Git 저장소 추가

개발용 로컬 마켓플레이스 추가

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

마켓플레이스 설치 확인

팀 마켓플레이스 구성

자체 마켓플레이스 생성

마켓플레이스 생성을 위한 전제 조건

마켓플레이스 파일 생성

마켓플레이스 스키마

필수 필드

선택적 메타데이터

플러그인 항목

선택적 플러그인 필드

플러그인 소스

상대 경로

GitHub 저장소

Git 저장소

고급 플러그인 항목

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

GitHub에서 호스팅 (권장)

다른 git 서비스에서 호스팅

개발용 로컬 마켓플레이스 사용

마켓플레이스 운영 관리

알려진 마켓플레이스 목록

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

마켓플레이스 제거

마켓플레이스 문제 해결

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

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

플러그인 설치 실패

검증 및 테스트

다음 단계

마켓플레이스 사용자를 위해

마켓플레이스 생성자를 위해

조직을 위해

참고 항목