Claude Code 플러그인 마켓플레이스 활용 /plugin으로 팀 공통 도구 일괄 배포하기

이 글에서 사용하는 주요 용어 정의

용어정의

플러그인	스킬·에이전트·훅·MCP를 묶은 확장 패키지
마켓플레이스	플러그인 목록과 소스 경로를 정의한 카탈로그
extraKnownMarketplaces	마켓플레이스 소스를 프로젝트에 선언하는 설정 키

도입

팀 단위로 AI 코딩 에이전트를 도입할 때 환경이 다르면 컨벤션 검사나 도구 활용에 편차가 생깁니다. 개인별 수동 설정은 동일한 작업을 반복하게 만듭니다.

Anthropic의 Claude Code 마켓플레이스 레퍼런스에 따르면, Claude Code는 /plugin 대화형 명령과 마켓플레이스 카탈로그로 도구 일괄 배포를 지원합니다. 스킬과 플러그인의 차이를 짚고, 사내 저장소를 프로젝트 설정에 연결해 팀원에게 자동 배포하는 절차를 정리합니다.

단독 스킬과 플러그인 마켓플레이스의 차이

Claude Code의 확장 방식은 단독 스킬과 플러그인 패키지로 나뉩니다.

구분단독 스킬 (.claude/skills/)플러그인 패키지 (매니페스트: .claude-plugin/)

구성	개별 마크다운 파일	plugin.json, 스킬, 에이전트, 훅, MCP 결합
용도	개인 워크플로 자동화	팀 표준 도구 세트 및 인프라 연동
배포	로컬 디렉터리 복사	Git 기반 마켓플레이스 일괄 배포

단독 스킬이 개인용 명령어라면, 플러그인은 도구를 묶어 팀에 배포하는 패키지입니다. 마켓플레이스는 Git 저장소를 가리키는 카탈로그 역할을 합니다.

/plugin 인터페이스와 설치 스코프

터미널에서 /plugin을 실행하면 대화형 TUI가 열립니다.

• Discover / Installed: 플러그인 검색·설치 및 활성화 토글
• Marketplaces / Errors: 카탈로그 관리 및 충돌 로그 확인

설치 범위(Scope)는 세 가지입니다.

• --scope project: 프로젝트 설정(.claude/settings.json)에 기록되어 Git 공유
• --scope user: 개인 전역 경로(~/.claude/settings.json)에 저장
• --scope local: 로컬 전용 파일(.claude/settings.local.json)에 기록

우선순위는 Managed > Local > Project > User 순입니다.

실전: 사내 마켓플레이스 구축과 프로젝트 일괄 배포

> ※ 아래 설정과 명령어는 공식 사양서 기반의 실행하지 않은 설정 예제(미검증 예제)입니다. 저장소명과 경로는 사내 환경에 맞게 변경해야 합니다.

1단계: 사내 마켓플레이스 카탈로그 작성

사내 도구 저장소 루트에 .claude-plugin/marketplace.json을 작성합니다. 카탈로그 식별자 name, 관리 조직 owner, 플러그인 배열 plugins를 정의하며, source 객체(source: "dir", path)로 상대 경로를 지정합니다.

{
  "name": "company-tools",
  "owner": "Platform Team",
  "plugins": [
    {
      "name": "team-tools",
      "description": "사내 리뷰 에이전트 및 DB 조회 MCP",
      "source": { "source": "dir", "path": "./plugins/team-tools" }
    }
  ]
}

작성 후 claude plugin validate 명령으로 문법과 경로를 검증합니다.

2단계: 프로젝트 저장소 설정 구성

메인 서비스 저장소 루트의 .claude/settings.json에 카탈로그 소스와 플러그인을 선언하고 커밋합니다.

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": { "source": "github", "repo": "my-org/claude-plugins" }
    }
  },
  "enabledPlugins": {
    "team-tools@company-tools": true
  }
}

• extraKnownMarketplaces: 자동 인식할 외부 마켓플레이스 소스 선언
• enabledPlugins: 기본 활성화할 플러그인("plugin@marketplace": true) 지정

3단계: 팀원 자동 온보딩 및 동작 확인

1. 팀원이 저장소를 git clone하고 디렉터리에서 claude를 실행합니다.
2. Claude Code가 .claude/settings.json을 감지해 작업 영역 신뢰(Workspace Trust) 승인을 요청합니다.
3. 신뢰를 승인하면 사내 마켓플레이스가 등록되고 플러그인이 자동 로드되어 수동 입력 없이 도구를 즉시 사용할 수 있습니다.

운영 시 주의할 점

첫째, CI/CD 파이프라인이나 -p(print) 모드 같은 비대화형 환경에서는 작업 영역 신뢰 창이 뜨지 않아 마켓플레이스가 자동 처리되지 않을 수 있습니다. 자동 처리가 안 되는 환경에서는 CI 스크립트에서 claude plugin marketplace add 및 claude plugin install을 명시적으로 실행하는 구성을 검토합니다.

둘째, 사내 프라이빗 저장소 연결 시 Git 인증(SSH 키·자격 증명)을 점검해야 합니다. 권한이 없으면 로드에 실패하므로 /plugin Errors 탭에서 오류를 확인합니다.

셋째, 플러그인 코드 수정 후에는 /reload-plugins 명령으로 즉시 변경 사항을 반영합니다.

마무리

Claude Code 플러그인 마켓플레이스는 도구 설정을 프로젝트 단위로 일원화합니다. 사내 카탈로그를 만들고 프로젝트 설정에 extraKnownMarketplaces와 enabledPlugins를 선언한 뒤 작업 영역 신뢰를 승인하면, 팀원들이 수동 설정 없이 사내 도구를 로드해 활용할 수 있습니다. 프로젝트 설정을 활용해 일관된 협업 환경을 구축해 보시기 바랍니다.

참고 링크

• Claude Code 마켓플레이스 공식 사양서
• Claude Code 플러그인 관리 가이드