Claude Code 공식문서 리뷰-Build with Claude Code[3] : Discover and install prebuilt plugins through marketplaces(마켓플레이스를 통해 미리 제작된 플러그인을 찾아 설치하세요.)

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

Claude Code Docs 공식 문서 >> Build with Claude Code 섹션의 내용 중 [Discover and install prebuilt plugins through marketplaces]를 살펴 보려고 합니다.

https://code.claude.com/docs/en/discover-plugins

Discover and install prebuilt plugins through marketplaces - Claude Code Docs

 

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

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

 

 

플러그인 검색 및 설치하기

• 마켓플레이스: 플러그인을 검색하고 설치할 수 있는 카탈로그
• 공식 마켓플레이스: Claude Code 시작 시 자동 설치됨
• 설치 범위: User, Project, Local 세 가지 옵션
• 원본: code.claude.com/docs/en/discover-plugins

 

개요

플러그인은 커스텀 명령, 에이전트, 훅, MCP 서버로 Claude Code를 확장한다. 플러그인 마켓플레이스는 이러한 확장 기능을 직접 만들지 않고도 발견하고 설치할 수 있게 도와주는 카탈로그다.

 

마켓플레이스 작동 방식

마켓플레이스는 다른 사람이 만들어 공유한 플러그인 카탈로그다. 마켓플레이스 사용은 2단계 프로세스다:

1. 마켓플레이스 추가 - Claude Code에 카탈로그를 등록하여 사용 가능한 플러그인 검색
2. 개별 플러그인 설치 - 원하는 플러그인을 선택하여 설치

앱 스토어 추가와 비슷하다고 생각하면 된다. 스토어를 추가하면 컬렉션을 검색할 수 있지만, 어떤 앱을 다운로드할지는 개별적으로 선택한다.

초보자 팁
마켓플레이스를 추가한다고 모든 플러그인이 자동으로 설치되는 것이 아니다. 마켓플레이스는 "카탈로그"일 뿐, 원하는 플러그인을 개별적으로 설치해야 한다.

 

공식 Anthropic 마켓플레이스

공식 Anthropic 마켓플레이스(claude-plugins-official)는 Claude Code를 시작할 때 자동으로 설치된다. /plugin 명령을 실행하고 Discover 탭에서 바로 플러그인을 검색할 수 있다.

 

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

/plugin install plugin-name@claude-plugins-official

 

데모 마켓플레이스 체험하기

Anthropic은 예제 플러그인이 포함된 데모 플러그인 마켓플레이스를 유지관리한다. 공식 마켓플레이스와 달리 이것은 수동으로 추가해야 한다.

 

1단계: 마켓플레이스 추가

/plugin marketplace add anthropics/claude-code

 

2단계: 사용 가능한 플러그인 검색

/plugin을 실행하여 네 개의 탭이 있는 플러그인 관리자를 연다:

탭	설명
Discover	모든 마켓플레이스에서 사용 가능한 플러그인 검색
Installed	설치된 플러그인 보기 및 관리
Marketplaces	마켓플레이스 추가, 제거, 업데이트
Errors	플러그인 로딩 오류 확인

Tab 키로 앞으로, Shift+Tab으로 뒤로 이동한다.

 

3단계: 플러그인 설치

플러그인을 선택하여 세부 정보를 보고, 설치 범위를 선택한다:

범위	설명
User scope	모든 프로젝트에서 자신만 사용
Project scope	이 저장소의 모든 협업자가 사용
Local scope	이 저장소에서 자신만 사용

예시:

/plugin install commit-commands@anthropics-claude-code

 

 

4단계: 새 플러그인 사용

설치 후 플러그인 명령을 바로 사용할 수 있다. 플러그인 명령은 플러그인 이름으로 네임스페이스가 지정된다:

/commit-commands:commit

 

마켓플레이스 추가하기

/plugin marketplace add 명령으로 다양한 소스에서 마켓플레이스를 추가한다.

단축키
/plugin market을 /plugin marketplace 대신, rm을 remove 대신 사용할 수 있다.

 

GitHub에서 추가

owner/repo 형식으로 GitHub 저장소 추가:

/plugin marketplace add anthropics/claude-code

 

다른 Git 호스트에서 추가

전체 URL을 제공하여 모든 git 저장소 추가 (GitLab, Bitbucket, 자체 호스팅):

 

HTTPS 사용:

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

 

SSH 사용:

/plugin marketplace add git@bitbucket.org:company/plugins.git

 

특정 브랜치 또는 태그 지정:

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

 

로컬 경로에서 추가

.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://example.com/marketplace.json

 

플러그인 설치

플러그인 직접 설치 (기본적으로 user 범위로 설치):

/plugin install plugin-name@marketplace-name

다른 설치 범위를 선택하려면 대화형 UI 사용: /plugin 실행, Discover 탭으로 이동, 플러그인에서 Enter 누르기.

중요
플러그인을 설치하기 전에 신뢰할 수 있는지 확인한다. Anthropic은 플러그인에 포함된 MCP 서버, 파일 또는 기타 소프트웨어를 제어하지 않으며 의도대로 작동하는지 검증할 수 없다.

 

설치된 플러그인 관리

/plugin 실행 후 Installed 탭으로 이동하여 플러그인을 보고, 활성화, 비활성화 또는 제거한다.

 

CLI 명령

플러그인 비활성화 (제거하지 않고):

/plugin disable plugin-name@marketplace-name

 

비활성화된 플러그인 재활성화:

/plugin enable plugin-name@marketplace-name

 

 

플러그인 완전 제거:

/plugin uninstall plugin-name@marketplace-name

 

특정 범위 지정:

claude plugin install formatter@your-org --scope project
claude plugin uninstall formatter@your-org --scope project

 

마켓플레이스 관리

대화형 인터페이스 사용

/plugin 실행 후 Marketplaces 탭에서:

• 추가된 모든 마켓플레이스의 소스와 상태 확인
• 새 마켓플레이스 추가
• 마켓플레이스 목록 업데이트하여 최신 플러그인 가져오기
• 더 이상 필요 없는 마켓플레이스 제거

 

CLI 명령 사용

구성된 모든 마켓플레이스 나열:

/plugin marketplace list

 

 

마켓플레이스에서 플러그인 목록 새로고침:

/plugin marketplace update marketplace-name

 

마켓플레이스 제거:

/plugin marketplace remove marketplace-name

주의
마켓플레이스를 제거하면 해당 마켓플레이스에서 설치한 모든 플러그인이 제거된다.

 

자동 업데이트 구성

Claude Code는 시작 시 마켓플레이스와 설치된 플러그인을 자동으로 업데이트할 수 있다.

UI를 통해 개별 마켓플레이스의 자동 업데이트 전환:

1. /plugin을 실행하여 플러그인 관리자 열기
2. Marketplaces 선택
3. 목록에서 마켓플레이스 선택
4. Enable auto-update 또는 Disable auto-update 선택

 

기본 동작:

마켓플레이스 유형	자동 업데이트 기본값
공식 Anthropic 마켓플레이스	활성화
서드파티 및 로컬 개발 마켓플레이스	비활성화

 

모든 자동 업데이트를 완전히 비활성화:

export DISABLE_AUTOUPDATER=1

 

팀 마켓플레이스 구성

팀 관리자는 .claude/settings.json에 마켓플레이스 구성을 추가하여 프로젝트의 자동 마켓플레이스 설치를 설정할 수 있다. 팀원이 저장소 폴더를 신뢰하면 Claude Code가 이러한 마켓플레이스와 플러그인 설치를 요청한다.

실전 팁
팀 프로젝트에서는 .claude/settings.json에 필수 플러그인을 미리 구성해두면 새 팀원이 프로젝트를 클론할 때 자동으로 필요한 플러그인 설치를 안내받을 수 있다.

 

문제 해결

/plugin 명령이 인식되지 않음

"unknown command" 또는 /plugin 명령이 나타나지 않으면:

단계	해결 방법
1. 버전 확인	claude --version 실행. 플러그인은 버전 1.0.33 이상 필요
2. Claude Code 업데이트	Homebrew: brew upgrade claude-code npm: npm update -g @anthropic-ai/claude-code
3. Claude Code 재시작	업데이트 후 터미널을 재시작하고 claude 다시 실행

일반적인 문제

문제	해결 방법
마켓플레이스가 로드되지 않음	URL이 접근 가능하고 경로에 .claude-plugin/marketplace.json이 있는지 확인
플러그인 설치 실패	플러그인 소스 URL이 접근 가능하고 저장소가 공개인지 (또는 접근 권한이 있는지) 확인
설치 후 파일을 찾을 수 없음	플러그인은 캐시에 복사되므로, 플러그인 디렉토리 외부의 파일을 참조하는 경로는 작동하지 않음

 

다음 단계

목적	문서
플러그인 직접 만들기	플러그인 - 커스텀 명령, 에이전트, 훅 생성
마켓플레이스 만들기	플러그인 마켓플레이스 만들기 - 팀이나 커뮤니티에 플러그인 배포
기술 레퍼런스	플러그인 레퍼런스 - 전체 사양

참고 자료

• 공식 문서: Discover Plugins
• 에이전트 스킬 가이드