Claude 플러그인 등록과 사용.

masonfe-hyunsu

🧵 1. 개요.

Claude Code에도 플러그인(plugin)을 설치해서 쓸 수 있다. 스킬, 훅, MCP를 매번 프롬프트로 설명하지 않고, 한 번 깔아 두고 세션에 실어 둔다.
게다가 플러그인은 남이 만든 것만 쓰는 구조가 아니다. 직접 만들어서 마켓플레이스에 올리고, 팀이나 커뮤니티에 배포할 수도 있다.
이 포스팅에서는 쓰는 쪽(마켓 등록 → 설치 → 세션 반영)을 먼저 잡고, 만들어서 내보낼 때 어디를 보면 되는지만 이어서 정리해 본다.

한 줄로 요약하면, Claude Code 플러그인은 설치해 쓰는 확장이고, 직접 만들어 배포하는 단위이기도 하다.

🗺️ 2. 설치해서 쓰기까지.

남이 공개한 플러그인을 쓰려면 보통 세 단계를 거친다. 카탈로그를 붙이는 일과, 그 안에서 하나를 골라 까는 일은 따로다.

마켓플레이스 등록 — "이 목록을 본다"고 Claude Code에 알려 준다. 아직 플러그인은 안 깔린다.
플러그인 설치 — 목록의 이름@마켓을 골라 실제로 깐다.
세션 반영 — 이미 열어 둔 세션이면 /reload-plugins로 다시 읽힌다.

공식 마켓 claude-plugins-official은 인터랙티브로 처음 켤 때 자동으로 붙는 경우가 많다. 안 보이면 anthropics/claude-plugins-official을 직접 추가한다. (Discover plugins)

커뮤니티나 사내 목록을 쓰려면 마켓을 한 번 더 등록해야 한다. 그다음이 설치다.

📦 3. 마켓플레이스 등록.

마켓플레이스(marketplace)는 설치할 플러그인 목록 카탈로그다. 소스는 대략 아래다.

GitHub owner/repo — 가장 흔하다. 공식, 커뮤니티도 이 패턴이다.
로컬 경로 — ./path로 직접 만든 카탈로그나 사내 마켓을 시험할 때.
Git URL / 원격 marketplace.json — 사내 미러나 별도 호스팅.

claude plugin marketplace add anthropics/claude-plugins-official
claude plugin marketplace add anthropics/claude-plugins-community
claude plugin marketplace add ./my-marketplace

세션 안에서는 /plugin marketplace add …로 같은 일을 할 수 있다. 셸 CLI와 /명령은 같은 개념, 다른 입구다.

등록은 카탈로그만 붙인다. list에 마켓이 보여도 플러그인은 아직 없다.
이름이 안 보이면 오타보다 카탈로그 갱신을 먼저 본다. marketplace update <이름>으로 강제 새로고침한다.
안 쓰는 마켓은 remove로 빼 두면 목록이 덜 지저분해진다.

웹에서 구경만 할 때는 claude.com/plugins도 있다. 설치는 Claude Code 쪽에서 이어간다.

🔌 4. 플러그인 설치와 사용.

설치 식별자는 항상 플러그인@마켓플레이스다. 마켓이 다르면 같은 이름도 다른 소스가 된다.

claude plugin install github@claude-plugins-official

세션에서는 /plugin install …이거나, 터미널 REPL의 /plugin 패널 Discover 탭에서 고른다.

깐 뒤에는 이렇게 확인한다.

plugin list — 설치 여부와 로드 성공/실패
plugin details — command, skill, hook, MCP 같은 구성요소
열린 세션이면 /reload-plugins — 셸에서만 설치하고 세션을 안 다시 읽으면 안 깔린 것처럼 보인다

종류에 따라 체감이 다르다.

워크플로, 스킬형 — commit, PR 리뷰 같은 절차가 세션에 붙는다.
MCP 연동형 — GitHub, Figma, Slack처럼 외부 도구가 연결된다.
LSP / 코드 인텔리전스 — 플러그인만으로는 부족하고, language server 바이너리가 PATH에 있어야 한다.

팀 온보딩, 스크립트에는 셸 claude plugin …이 남기기 좋다. 지금 화면에서 고를 때는 /plugin(REPL) 또는 /plugins(VS Code 확장)를 쓴다.

철자가 비슷해서 환경을 섞지 않는 게 중요하다. REPL에서 /plugins만 치거나, VS Code에서 /plugin만 기대해도 안 된다.

🚀 5. 직접 만들어 배포할 때.

쓰는 쪽과 반대로, 내가 만든 플러그인을 남에게 열려면 검증과 마켓 쪽이 앞에 온다.

로컬에서 claude plugin validate ./plugin-dir로 매니페스트를 통과시킨다. 커뮤니티 제출 전에 거의 필수다. (Create plugins)
배포 단위는 플러그인 폴더이고, 사람들이 설치하려면 그 플러그인이 들어 있는 마켓플레이스에 올라가야 한다.
커뮤니티 마켓(claude-plugins-community)은 자동 검증, 안전 스크리닝을 거친 뒤 카탈로그에 핀된다. 공식 마켓(claude-plugins-official)은 Anthropic이 따로 고른다.
팀 전용이면 공개 커뮤니티 대신 로컬/사내 마켓에 marketplace add로 붙이고, 이름@그마켓으로 설치하게 하면 된다.

개요에서 말한 "직접 만들어 배포"는 이 절이다. 만드는 파일 구조 자체는 공식 Create plugins 문서를 보고, 이 포스팅에서는 어디에 올리고 어떻게 설치 경로가 열리는지만 짚는다.

🔁 6. 막힐 때 되감기.

손이 가는 기본 순서는 등록 → 설치 → 확인 → 세션 반영이다. 막히면 이 순서로 되감는다.

마켓 등록 → list로 확인
이름@마켓 설치
list / details로 로드와 구성요소 확인
열린 세션이면 /reload-plugins

증상별로 보면 이렇다.

마켓이 없다 → marketplace add부터
플러그인을 못 찾는다 → 이름 확인 + marketplace update. 공식 마켓이 비어 있으면 official을 다시 붙인다
설치는 됐는데 세션에 없다 → /reload-plugins. /plugin(REPL)과 /plugins(VS Code)를 섞지 않았는지도 본다
로드 실패 → details와 Errors 탭. LSP면 바이너리, MCP면 인증, 네트워크
내가 만든 걸 배포할 때 → 제출 전 validate 통과 여부부터

클라우드/일부 환경에서는 /plugin이 막힐 수 있다. 그때는 데스크톱 플러그인 브라우저나 .claude/settings.json의 enabledPlugins로 켠다.

✅ 7. 정리.

Claude Code 플러그인은 설치해 쓰는 확장이고, 직접 만들어 배포하는 단위이기도 하다.
쓸 때는 마켓플레이스 등록 → 플러그인 설치 → 세션 반영 순이다. 카탈로그만 붙인다고 깔리지는 않는다.
설치 키는 플러그인@마켓이다. 깐 뒤엔 list로 로드를 보고, 열린 세션엔 **/reload-plugins**를 습관으로 둔다.
만들어 배포할 때는 validate와, 올릴 마켓(커뮤니티/사내/로컬)을 먼저 정한다.
셸 명령은 자동화, 공유용이고 /plugin 계열은 지금 세션 UI용이다. REPL과 VS Code 입구를 섞지 않는다.

명령을 외우기보다, 쓰기(등록→설치→반영)와 배포(검증→마켓 등록) 두 줄기만 구분해 두면 대부분 충분하다.