플러그인 설치 및 관리

플러그인을 설치하면 해당 플러그인의 Skills, Agents, Hooks, MCP 서버가 Claude Code에 추가됩니다. 이 페이지에서는 설치, 마켓플레이스 추가, 업데이트, 삭제까지 전 과정을 다룹니다.

플러그인 설치

Anthropic 공식 마켓플레이스에서 commit-commands 플러그인을 설치하는 예시입니다. 다른 플러그인도 동일한 절차로 설치합니다.

터미널에서 설치

# 세션 안에서 상세 화면을 열고 범위를 선택해 설치
/plugin install commit-commands@claude-plugins-official

명령을 실행하면 플러그인 상세 화면이 열립니다. 여기에서 추가되는 컴포넌트와 컨텍스트 비용을 확인한 뒤 범위를 선택합니다.

설치 완료 메시지 의미:

메시지	의미
Plugin is now active.	현재 세션에 즉시 활성화됨
Run /reload-plugins to activate.	패널이 닫히고 자동으로 리로드 실행
The plugin couldn't be loaded	오류 발생 — /plugin Errors 탭 확인

VS Code에서 설치

1. 프롬프트 박스에 /plugins 입력 → Manage plugins 패널 열기
2. Plugins 탭에서 플러그인 검색 후 Install 클릭
3. 범위 선택 후 완료

변경 사항은 열린 세션에 즉시 반영됩니다 (재시작 불필요).

셸에서 직접 설치 (비인터랙티브)

Claude Code 세션 없이 스크립트에서 설치할 때 사용합니다.

# 기본값은 user scope
claude plugin install commit-commands@claude-plugins-official

# project scope로 설치
claude plugin install formatter@your-org --scope project

마켓플레이스 사전 등록

머신에서 인터랙티브 세션을 한 번도 실행한 적 없다면 공식 마켓플레이스가 등록되어 있지 않습니다. 스크립트에서 설치 전에 아래 명령을 먼저 실행합니다:

claude plugin marketplace add anthropics/claude-plugins-official

설치 범위 선택

범위	기록 위치	적용 대상
User scope (기본)	~/.claude/settings.json	이 머신의 모든 프로젝트
Project scope	.claude/settings.json	이 저장소의 모든 협업자 (git 커밋)
Local scope	.claude/settings.local.json	이 저장소의 나만

Project scope는 settings.json을 커밋하면 협업자에게 플러그인이 활성화되지만, 각 협업자도 머신에 플러그인을 직접 설치해야 합니다.

마켓플레이스 추가

공식 마켓플레이스 외 플러그인(팀 내부, 커뮤니티 등)을 설치하려면 마켓플레이스를 먼저 등록합니다.

# GitHub 저장소
/plugin marketplace add your-org/plugins

# 브랜치·태그 고정
/plugin marketplace add your-org/plugins#v1.2.0

# Git URL (GitLab 등)
/plugin marketplace add https://gitlab.example.com/group/marketplace.git

# 로컬 디렉토리
/plugin marketplace add ./my-marketplace

# 마켓플레이스 추가와 동시에 플러그인 설치 (v2.1.275+)
/plugin install deploy-helper --marketplace your-org/plugins

등록 성공 후 /plugin Discover 탭에서 해당 마켓플레이스의 플러그인을 찾을 수 있습니다.

플러그인 관리

목록 확인

# 세션 안에서
/plugin

# 셸에서
claude plugin list

활성화·비활성화·삭제

# 셸에서
claude plugin enable formatter@your-org
claude plugin disable formatter@your-org
claude plugin uninstall formatter@your-org --scope project

세션 안에서는 /plugin → Installed 탭에서 Space 키로 활성화·비활성화, Enter로 상세 메뉴에서 삭제할 수 있습니다.

설치된 플러그인의 컨텍스트 비용 확인

claude plugin details commit-commands@claude-plugins-official

Always-on 줄에 매 세션마다 플러그인이 추가하는 토큰 수가 표시됩니다.

업데이트

Anthropic 공식 마켓플레이스 플러그인은 세션 시작 시 자동으로 업데이트됩니다. 업데이트 후 현재 세션에 적용하려면 /reload-plugins를 실행합니다.

개별 플러그인을 즉시 업데이트하려면:

# 세션 안에서
/plugin  → Installed 탭 → Update now

# 셸에서
claude plugin update commit-commands@claude-plugins-official

특정 마켓플레이스의 자동 업데이트를 끄려면 /plugin → Marketplaces 탭에서 해당 마켓플레이스를 선택한 뒤 Disable auto-update를 누릅니다.

의존성(Dependencies) 관리

플러그인이 다른 플러그인에 의존하는 경우, 설치 시 의존성이 함께 설치됩니다.

오류	원인	해결
dependency-unsatisfied	의존 플러그인 미설치 또는 비활성화	에러에 표시된 claude plugin install 명령 실행
range-conflict	여러 플러그인이 충돌하는 버전 요구	충돌 플러그인 중 하나를 업데이트 또는 삭제
dependency-version-unsatisfied	설치된 의존성 버전이 범위 밖	claude plugin install <dependency>@<marketplace>로 재해결

의존성으로 자동 설치된 플러그인은 부모 플러그인을 삭제해도 디스크에 남습니다. 정리하려면:

# 사용하지 않는 의존성 나열 후 제거
claude plugin prune

# 삭제와 동시에 의존성 정리
claude plugin uninstall deploy-kit --prune

다음 단계

• 첫 플러그인 직접 만들기 →
• 마켓플레이스 운영 →
• 플러그인 시스템 개요 →