AI/Claude Code Doc(공식문서) 번역본

Claude Code 공식문서 리뷰-Administration[8] : Claude Code 설정 - 플러그인 마켓플레이스(Create and distribute a plugin marketplace)

안녕하세요! 갓대희입니다.

Claude Code Docs 공식 문서 >> [관리] 섹션의 내용 중 [Claude Code 설정 - 플러그인 마켓플레이스(Create and distribute a plugin marketplace)]를 살펴 보려고 합니다.

이번 섹션 부터는 영문, 한글번역본이 모두 공식문서로 존재하는 섹션이니 한글 문서를 편하게 참고 하셔도 될 것 같습니다.

https://code.claude.com/docs/ko/plugin-marketplaces

플러그인 마켓플레이스 - Claude Code Docs

Claude Code 확장 프로그램을 팀과 커뮤니티 전체에 배포하기 위한 플러그인 마켓플레이스를 만들고 관리합니다.

code.claude.com

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다.

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

개요

마켓플레이스: 플러그인을 배포하고 관리하는 중앙 카탈로그
주요 기능: 중앙 집중식 검색, 버전 추적, 자동 업데이트
소스 지원: Git 리포지토리, 로컬 경로, GitHub, GitLab
배포 방식: marketplace.json 파일 기반

플러그인 마켓플레이스는 다른 사람들에게 플러그인을 배포할 수 있는 카탈로그이다. npm이나 PyPI 같은 패키지 레지스트리와 유사한 역할을 하지만, Claude Code 플러그인에 특화되어 있다.

마켓플레이스가 필요한가? - 나에게 맞는 선택 판단하기

먼저 확인하자

마켓플레이스를 직접 만들기 전에, 이미 있는 플러그인을 설치해서 쓰는 것만으로 충분한지 먼저 확인하자. 대부분의 경우 공식 마켓플레이스나 다른 사람이 만든 플러그인으로 해결된다.

마켓플레이스를 만들어야 하는 경우

팀 공통 도구 배포: 회사/팀에서 공통으로 사용하는 플러그인을 중앙에서 관리하고 싶음
오픈소스 공유: 직접 만든 플러그인을 커뮤니티에 공개하고 싶음
버전 관리: 플러그인 업데이트를 체계적으로 배포하고 싶음
엔터프라이즈 통제: 회사 정책에 따라 승인된 플러그인만 사용하도록 제한하고 싶음

마켓플레이스가 필요 없는 경우

개인 사용: 혼자만 쓸 플러그인이라면 로컬 경로로 직접 설치하면 됨
기존 플러그인 설치: 이미 공개된 플러그인을 설치만 할 때는 /plugin install 명령만 사용
일회성 공유: Git 리포지토리 URL만 공유해도 충분함

먼저 알아야 할 것 - 플러그인 기본 명령어

마켓플레이스 만들기 전에 익혀두자

마켓플레이스를 직접 만들기 전에, 기존 마켓플레이스에서 플러그인을 설치하고 사용하는 방법을 먼저 익혀두면 이해가 쉬워진다.

플러그인 검색 및 설치

# 플러그인 검색
/plugin search code-review
/plugin search commit

# 공식 마켓플레이스에서 플러그인 설치
/plugin install commit-commands@claude-plugins-official

# 설치된 플러그인 목록 확인
/plugin list

# 특정 플러그인 상세 정보 확인
/plugin info commit-commands@claude-plugins-official

마켓플레이스 관리

# 새 마켓플레이스 추가 (GitHub)
/plugin marketplace add owner/repo

# 새 마켓플레이스 추가 (다른 Git 서비스)
/plugin marketplace add https://gitlab.com/company/plugins.git

# 로컬 마켓플레이스 추가 (개발/테스트용)
/plugin marketplace add ./my-local-marketplace

# 마켓플레이스 메타데이터 업데이트
/plugin marketplace update

# 마켓플레이스 제거
/plugin marketplace remove marketplace-name

플러그인 이름 형식

플러그인 설치 시 플러그인명@마켓플레이스명 형식을 사용한다. 예: commit-commands@claude-plugins-official

상황별 마켓플레이스 구성 가이드

상황 1: "팀 내부 도구를 배포하고 싶어요"

회사/팀에서만 사용하는 플러그인을 중앙에서 관리하고 싶을 때. 프라이빗 리포지토리로 접근을 제한할 수 있다.

권장 구성

GitHub Private 리포지토리에 마켓플레이스 호스팅
프로젝트 .claude/settings.json에 extraKnownMarketplaces 설정
팀원들은 Git 접근 권한만 있으면 자동으로 플러그인 설치 가능

상황 2: "오픈소스 플러그인을 공유하고 싶어요"

직접 만든 플러그인을 커뮤니티에 공개하고 싶을 때. 누구나 설치할 수 있다.

권장 구성

GitHub Public 리포지토리에 마켓플레이스 호스팅
README에 설치 방법 안내: /plugin marketplace add owner/repo
명확한 라이선스(MIT, Apache-2.0 등) 명시

상황 3: "회사 전체에 플러그인 정책을 적용하고 싶어요"

엔터프라이즈 환경에서 승인된 플러그인만 사용하도록 강제하고 싶을 때.

권장 구성

관리형 설정(Managed Settings)에서 strictKnownMarketplaces 설정
MDM(Mobile Device Management)으로 설정 파일 배포
허용된 마켓플레이스 외에는 추가 불가능하도록 제한

마켓플레이스 생성 및 배포 과정

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

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

1단계: 디렉토리 구조 생성

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

2단계: 플러그인 명령 생성

my-marketplace/plugins/review-plugin/commands/review.md

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 command 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 command for quick code reviews"
    }
  ]
}

5단계: 추가 및 설치

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

6단계: 테스트

/review

초보자 팁

로컬에서 먼저 테스트한 후 GitHub에 푸시하자. 로컬 경로로 마켓플레이스를 추가하면 빠르게 반복 개발할 수 있다.

마켓플레이스 파일 생성

리포지토리 루트에 .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"
    }
  ]
}

마켓플레이스 스키마

필수 필드

필드	타입	설명	예시
`name`	string	마켓플레이스 식별자 (케밥 케이스, 공백 없음)	"acme-tools"
`owner`	object	마켓플레이스 관리자 정보	아래 참조
`plugins`	array	사용 가능한 플러그인 목록	아래 참조

예약된 이름 - 사용 불가

다음 이름들은 Anthropic 공식 용도로 예약되어 있어 사용할 수 없다:

claude-code-marketplace, claude-code-plugins, claude-plugins-official
anthropic-marketplace, anthropic-plugins
agent-skills, life-sciences
공식 마켓플레이스를 사칭하는 이름 (예: official-claude-plugins)

Owner 필드

필드	타입	필수	설명
`name`	string	예	관리자 또는 팀 이름
`email`	string	아니오	관리자 연락처 이메일

선택적 메타데이터

필드	타입	설명
`metadata.description`	string	간단한 마켓플레이스 설명
`metadata.version`	string	마켓플레이스 버전
`metadata.pluginRoot`	string	상대 플러그인 소스 경로 앞에 추가되는 기본 디렉토리

플러그인 항목

필수 필드

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

선택적 플러그인 필드

표준 메타데이터 필드

필드	타입	설명
`description`	string	간단한 플러그인 설명
`version`	string	플러그인 버전
`author`	object	플러그인 작성자 정보
`homepage`	string	플러그인 홈페이지 또는 문서 URL
`repository`	string	소스 코드 리포지토리 URL
`license`	string	SPDX 라이선스 식별자
`keywords`	array	플러그인 검색용 태그
`category`	string	정리용 플러그인 카테고리
`strict`	boolean	플러그인에 자체 plugin.json 파일 필요 여부 (기본값: true)

strict 옵션 이해하기

strict: true (기본값)	플러그인이 자체 `.claude-plugin/plugin.json`을 반드시 가져야 한다. 플러그인 개발자가 명시적으로 메타데이터를 관리하는 정석적인 방식이다.
strict: false	마켓플레이스의 marketplace.json에서 모든 메타데이터를 정의할 수 있다. 간단한 명령 스크립트를 빠르게 배포할 때 유용하다.

컴포넌트 구성 필드

필드	타입	설명
`commands`	string\|array	명령 파일 또는 디렉토리에 대한 커스텀 경로
`agents`	string\|array	에이전트 파일에 대한 커스텀 경로
`hooks`	string\|object	커스텀 훅 구성 또는 훅 파일 경로
`mcpServers`	string\|object	MCP 서버 구성
`lspServers`	string\|object	LSP 서버 구성

플러그인 소스

상대 경로

{
  "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"
  }
}

고급 플러그인 항목 예시

{
  "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.example.com/plugins/enterprise-tools",
  "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
}

${CLAUDE_PLUGIN_ROOT} 변수 이해하기

왜 이 변수가 필요한가?

플러그인이 설치되면 원래 위치가 아닌 캐시 디렉토리로 복사된다. 따라서 hooks나 mcpServers에서 파일을 참조할 때 상대 경로를 사용하면 파일을 찾을 수 없다.

플러그인 설치 경로 변화

원래 위치	`/my-marketplace/plugins/my-plugin/`
설치 후 위치	`~/.config/claude-code/plugins/my-plugin@my-marketplace/`

잘못된 예시

"command": "./scripts/run.sh"

-> 원본 경로를 참조하므로 파일을 찾을 수 없음

올바른 예시

"command": "${CLAUDE_PLUGIN_ROOT}/scripts/run.sh"

-> 설치된 위치를 참조하므로 정상 작동

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

GitHub에 호스팅 (권장)

마켓플레이스용 새 리포지토리 생성
플러그인 정의가 포함된 .claude-plugin/marketplace.json 추가
사용자가 다음으로 마켓플레이스 추가: /plugin marketplace add owner/repo

다른 Git 서비스에 호스팅

GitLab, Bitbucket, 자체 호스팅 서버도 작동한다:

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

배포 전 로컬 테스트

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

팀에 마켓플레이스 필수화

.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
  }
}

보안 고려사항

플러그인은 코드를 실행할 수 있다

플러그인은 hooks, MCP 서버, LSP 서버 등을 통해 시스템에서 코드를 실행할 수 있다. 신뢰할 수 없는 소스의 플러그인은 보안 위험이 될 수 있으므로 주의가 필요하다.

플러그인 설치 전 확인 사항

소스 코드 검토: 설치 전 플러그인 리포지토리의 코드를 확인하자
신뢰할 수 있는 소스: 공식 마켓플레이스나 검증된 개발자의 플러그인만 사용
권한 범위 확인: 플러그인이 어떤 hooks와 MCP 서버를 사용하는지 확인
버전 고정: 중요한 환경에서는 특정 버전을 고정하여 예기치 않은 변경 방지

프라이빗 리포지토리 접근 권한

프라이빗 마켓플레이스는 Git 접근 권한이 있는 사용자만 설치 가능
GitHub의 경우 SSH 키 또는 Personal Access Token 필요
팀원들에게 적절한 리포지토리 접근 권한 부여 필요

엔터프라이즈 마켓플레이스 제한

플러그인 소스를 엄격하게 제어하려면 관리형 설정에서 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"
    }
  ]
}

관리형 설정 위치

strictKnownMarketplaces는 관리형 설정(Managed Settings)에서만 적용된다. MDM 또는 엔터프라이즈 설정 배포 도구를 통해 설정 파일을 배포해야 한다.

검증 및 테스트

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

# CLI에서
claude plugin validate .

# Claude Code 내에서
/plugin validate .

테스트용 마켓플레이스 추가:

/plugin marketplace add ./path/to/marketplace

테스트 플러그인 설치:

/plugin install test-plugin@marketplace-name

트러블슈팅

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

해결책:

마켓플레이스 URL에 접근 가능한지 확인
지정된 경로에 .claude-plugin/marketplace.json이 존재하는지 확인
claude plugin validate 또는 /plugin validate로 JSON 구문이 유효한지 확인
프라이빗 리포지토리의 경우 접근 권한 확인

마켓플레이스 검증 에러

에러	원인	해결책
`File not found: .claude-plugin/marketplace.json`	매니페스트 누락	필수 필드가 포함된 marketplace.json 생성
`Invalid JSON syntax...`	JSON 구문 에러	누락된 쉼표, 따옴표 없는 문자열 확인
`Duplicate plugin name...`	같은 이름 사용	각 플러그인에 고유한 name 값 부여
`Path traversal not allowed`	소스 경로에 .. 포함	마켓플레이스 루트 기준 상대 경로 사용
`Reserved marketplace name`	예약된 이름 사용	다른 마켓플레이스 이름 선택

플러그인 설치 실패

해결책:

플러그인 소스 URL에 접근 가능한지 확인
플러그인 디렉토리에 필요한 파일이 포함되어 있는지 확인
GitHub 소스의 경우 리포지토리가 공개이거나 접근 권한이 있는지 확인
클론/다운로드로 플러그인 소스를 수동 테스트

설치 후 파일을 찾을 수 없음

원인: 플러그인은 제자리가 아닌 캐시 디렉토리로 복사된다. 플러그인 디렉토리 외부 파일을 참조하는 경로(예: ../shared-utils)는 작동하지 않는다.

해결책:

심볼릭 링크 사용 (복사 시 따라감)
공유 디렉토리를 플러그인 소스 경로 안으로 이동
설정에서 ${CLAUDE_PLUGIN_ROOT} 변수 사용

더 알아보기 - 관련 리소스

리소스	언제 유용한가?
플러그인 검색 및 설치	마켓플레이스 만들기 전에 기존 플러그인을 먼저 써보고 싶을 때 공식 플러그인이나 커뮤니티 플러그인을 찾고 설치할 때
플러그인 만들기	마켓플레이스에 등록할 새 플러그인을 개발할 때 commands, agents, hooks 등 플러그인 구성 요소를 이해하고 싶을 때
플러그인 레퍼런스	hooks, mcpServers, lspServers 등 고급 기능을 사용할 때 plugin.json 스키마의 상세한 필드 설명이 필요할 때
플러그인 설정	사용자/프로젝트별 플러그인 설정을 커스터마이징할 때 플러그인 활성화/비활성화를 프로젝트별로 제어할 때
관리형 설정	엔터프라이즈 환경에서 플러그인 사용을 제한할 때 MDM으로 회사 전체에 설정을 배포할 때

핵심 요약 - 마켓플레이스 배포 체크리스트

배포 전 확인 사항

아래 항목들을 모두 확인하면 마켓플레이스 배포 준비가 완료된 것이다.

확인	항목
[ ]	`.claude-plugin/marketplace.json` 파일 생성됨
[ ]	필수 필드 포함: `name`, `owner`, `plugins`
[ ]	모든 플러그인에 `name`과 `source` 필드 있음
[ ]	마켓플레이스 이름이 예약된 이름이 아님
[ ]	`/plugin validate .` 검증 통과
[ ]	로컬에서 `/plugin marketplace add`로 테스트 완료
[ ]	플러그인 설치 및 명령 실행 테스트 완료
[ ]	(GitHub 배포 시) 리포지토리 접근 권한 설정 확인
[ ]	(팀 배포 시) `.claude/settings.json`에 `extraKnownMarketplaces` 추가
[ ]	(오픈소스 시) README에 설치 방법 안내 추가

다음 단계

마켓플레이스 배포가 완료되면 사용자들에게 다음 명령어를 안내하자:

# 마켓플레이스 추가
/plugin marketplace add owner/repo

# 플러그인 목록 확인
/plugin search @marketplace-name

# 플러그인 설치
/plugin install plugin-name@marketplace-name

Claude Code 한국어 문서
번역 기준일: 2026-01-03 | 공식 문서 업데이트: 2025-11-06 | 원본: code.claude.com/docs

저작자표시 비영리 변경금지 (새창열림)

'AI > Claude Code Doc(공식문서) 번역본' 카테고리의 다른 글

Claude Code 공식문서 리뷰-Configuration[2] : 터미널 설정 최적화(Optimize your terminal setup) (2)	2026.01.05
Claude Code 공식문서 리뷰-Configuration[1] : Claude Code 설정(Claude Code settings) (0)	2026.01.05
Claude Code 공식문서 리뷰-Administration[7] : Claude Code 설정 - 분석(Analytics) (0)	2026.01.04
Claude Code 공식문서 리뷰-Administration[6] : Claude Code 설정 - 비용을 효과적으로 관리하기(Manage costs effectively) (0)	2026.01.04
Claude Code 공식문서 리뷰-Administration[5] : Claude Code 설정 - 모니터링(Monitoring) (0)	2026.01.04

Contents

Claude Code 공식문서 리뷰-Administration[8] : Claude Code 설정 - 플러그인 마켓플레이스(Create and distribute a plugin marketplace)

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

개요

마켓플레이스가 필요한가? - 나에게 맞는 선택 판단하기

먼저 알아야 할 것 - 플러그인 기본 명령어

플러그인 검색 및 설치

마켓플레이스 관리

상황별 마켓플레이스 구성 가이드

마켓플레이스 생성 및 배포 과정

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

1단계: 디렉토리 구조 생성

2단계: 플러그인 명령 생성

3단계: 플러그인 매니페스트 생성

4단계: 마켓플레이스 파일 생성

5단계: 추가 및 설치

6단계: 테스트

마켓플레이스 파일 생성

마켓플레이스 스키마

필수 필드

Owner 필드

선택적 메타데이터

플러그인 항목

필수 필드

선택적 플러그인 필드

표준 메타데이터 필드

컴포넌트 구성 필드

플러그인 소스

상대 경로

GitHub 리포지토리

Git 리포지토리

고급 플러그인 항목 예시

${CLAUDE_PLUGIN_ROOT} 변수 이해하기

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

GitHub에 호스팅 (권장)

다른 Git 서비스에 호스팅

배포 전 로컬 테스트

팀에 마켓플레이스 필수화

보안 고려사항

엔터프라이즈 마켓플레이스 제한

일반적인 구성

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

특정 마켓플레이스만 허용

검증 및 테스트

트러블슈팅

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

마켓플레이스 검증 에러

플러그인 설치 실패

설치 후 파일을 찾을 수 없음

더 알아보기 - 관련 리소스

핵심 요약 - 마켓플레이스 배포 체크리스트

'AI > Claude Code Doc(공식문서) 번역본' 카테고리의 다른 글

당신이 좋아할만한 콘텐츠

티스토리툴바