Cmd. /plugin
스킬·에이전트·훅·MCP 서버를 묶은 플러그인의 설치·활성/비활성·삭제와 마켓플레이스 등록을 Discover/Installed/Marketplaces/Errors 네 탭 UI로 관리하는 명령군. claude plugin CLI로 비대화형 검증도 지원
핵심 요약
- plugin 탐색·설치·enable·disable
- 입력 위치·지원 조건을 확인한 뒤 아래 실행 예를 사용합니다.
역할
plugin 탐색·설치·enable·disable
/plugin [subcommand]사용 조건
| 항목 | 기준 |
|---|---|
| 입력 위치 | 실행 중인 CLI의 입력창 |
| 종류 | 내장 명령 |
| 상태 | 현재 공식 표 |
| 별칭 | — |
| 공식 최소 버전 | 명시되지 않음 |
| 검증 기준 | 2026-09-22 · Claude Code 2.1.278 |
설치본의 명령 메뉴와 계정·조직 설정에 따라 사용할 수 있는 항목이 달라집니다.
사용 예
/plugin list플러그인을 설치하려면 먼저 마켓플레이스를 추가한 뒤(공식 마켓플레이스 claude-plugins-official은 기본 등록), 개별 플러그인을 설치합니다.
/plugin marketplace add anthropics/claude-code/plugin install commit-commands@claude-code-plugins설치는 기본적으로 user scope로 들어갑니다. project나 local scope로 넣으려면 /plugin UI의 Discover 탭에서 Enter로 상세를 연 뒤 고르거나, CLI에서 --scope를 지정합니다.
claude plugin install formatter@your-org --scope project설치·활성/비활성 후에는 재시작 없이 변경을 반영하기 위해 /reload-plugins를 실행합니다.
/reload-plugins배포 전 검증은 CLI로 수행합니다.
claude plugin validate선택 시점
- 신규 플러그인 도입 전
claude plugin validate로 manifest·구성요소 검증 - 환경별 플러그인 활성 정책 분리 (user/project/local scope 활용)
- 장애 발생 플러그인을
/plugin disable <plugin>@<marketplace>로 즉시 비활성화 git-subdirsource type으로 Git 저장소 하위 디렉토리에서 플러그인 로드 (v2.1.69)pathPattern으로 파일/디렉토리 마켓플레이스 소스 regex 매칭 (v2.1.69)bin/실행 파일을 플러그인에 포함해 Bash 도구에서 bare command처럼 호출 (v2.1.91)- 오프라인 환경에서 마켓플레이스 갱신 실패 시 기존 캐시 유지 (v2.1.90)
관련 명령 선택
| 명령어 | 차이점 | 언제 선택 |
|---|---|---|
/plugin | 플러그인 관리 | 확장 기능 수명주기 관리 |
/reload-plugins | 활성 플러그인 재로드 | 재시작 없이 변경 반영 |
/mcp | MCP 서버 관리 | 도구 서버 연결·OAuth 인증 관리 |
/config | 설정 인터페이스 | 테마·모델 등 일반 설정 조정 |
실행 결과와 유지 범위
선택한 플러그인의 설치·활성 상태를 바꿉니다. 설치 결과에 따라 즉시 적용되거나 reload가 필요합니다.
공식 명령어 레퍼런스에서 /plugin은 "Manage Claude Code plugins", 곧 Claude Code 플러그인을 관리하는 명령입니다. 플러그인은 스킬, 에이전트, 훅, MCP 서버를 묶어 프로젝트와 팀 사이에서 공유하는 확장 단위로, /plugin이 설치·활성화/비활성화·삭제부터 마켓플레이스 등록까지 한 명령군에서 다룹니다.
별칭(alias)은 없습니다. 다만 하위 명령에서 marketplace는 market으로, remove는 rm으로 줄여 쓸 수 있습니다(예: /plugin market add ..., /plugin market rm ...).
세션 안에서 쓰는 대화형 /plugin과 별도로, 같은 작업을 비대화형으로 처리하는 claude plugin ... CLI도 제공됩니다(예: claude plugin install, claude plugin uninstall --scope project, claude plugin validate).
plugin 명령
claude plugin install <plugin> --json
claude plugin install <plugin> --accept-command <sha256>
claude plugin update <plugin> --accept-command <sha256>
/plugin install <plugin> --marketplace <source>--accept-command <sha256>(v2.1.271+)은 앞선 --json 출력이 제시한 정확한 명령을 검토한 뒤 승인합니다. install과 update 각각의 출력에 맞는 hash를 사용하세요. v2.1.275의 /plugin install ... --marketplace ...는 marketplace가 필요하면 먼저 추가를 제안합니다. v2.1.277은 사용 중인 동일 plugin version 재설치 실패와 multi-select 실패 표시·설치 상태 정리를 보강했습니다.
CLI 확장
claude plugin install|uninstall|update|enable|disable 각각에 --json이 추가됐습니다(위 |는 대안 표기이며 실행 구문이 아닙니다). claude plugin list --json은 행별 errorDetails·noteDetails도 반환합니다. claude plugin eval --help로 평가 suite 실행 방법을 확인할 수 있으며 결과는 JSON·HTML 보고서입니다.
공식 Changelog · 2026-09-12 KST
주의사항
- 플러그인·마켓플레이스는 사용자 권한으로 임의 코드를 실행하는 고신뢰 구성요소이므로 신뢰하는 출처만 설치·등록합니다. 조직은 managed settings로 허용 마켓플레이스를 제한할 수 있습니다.
- 마켓플레이스를 제거하면 거기서 설치한 플러그인도 함께 제거됩니다.
- 버전 충돌 시 격리 환경 검증 권장.
--plugin-dir로 로드한 로컬 복사본은 같은 이름의 설치된 마켓플레이스 플러그인보다 우선 적용됩니다(단, managed settings에서 강제 활성/비활성된 플러그인은 예외). - v2.1.71에서
/plugin uninstall이.claude/settings.local.json에서 비활성화하도록 개선됨 - v2.1.77에서
claude plugin validate가 스킬, 에이전트, 커맨드 frontmatter와 hooks.json까지 검증 - v2.1.80에서
source: 'settings'로 settings.json에 인라인 플러그인 선언 가능 - v2.1.81에서 ref-tracked 플러그인이 로드 시 자동 재클론으로 항상 최신 유지
- v2.1.90에서
CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1로git pull실패 시 기존 마켓플레이스 캐시 유지 - v2.1.91에서 플러그인이
bin/실행 파일을 배포할 수 있고, Bash 도구에서 bare command 호출 가능 - v2.1.128부터
--plugin-dir가 플러그인 디렉토리의.zip아카이브도 받습니다. 원격 호스팅.zip은--plugin-url로 로드합니다(해당 세션 한정). - v2.1.129부터 plugin manifest의
themes와monitors는"experimental"아래에 선언하는 방식이 권장되며, top-level 선언은 동작하지만 validation warning이 날 수 있습니다.
v2.1.74: 마켓플레이스 및 로컬 플러그인 개선
버그 수정:
/plugin install이 REPL 내부에서 로컬 소스를 가진 마켓플레이스 플러그인 설치에 실패하던 문제 해결- 마켓플레이스 업데이트 시 git submodule 동기화가 누락되던 문제 해결 — submodule에 포함된 플러그인 소스가 업데이트 후 깨지지 않음
동작 변경:
--plugin-dir옵션으로 지정한 로컬 개발 복사본이 동일 이름의 설치된 마켓플레이스 플러그인보다 우선 적용됨 (단, managed settings에서 강제 활성화된 플러그인은 예외)
공식 근거
전체 명령 목록 · 검증 범위 · 이 명령의 변경 기록