claude code 플러그인 한 줄 요약
claude code 플러그인은 스킬, 서브에이전트, MCP 서버, 훅, 언어 서버를 한 패키지로 묶어
/plugin에서 설치하는 확장 방식이에요. 공식 마켓플레이스는 기본으로 보이고, 커뮤니티 마켓은 GitHub 저장소나 URL로 붙일 수 있어요. 근데 많이 깔수록 컨텍스트와 보안 리스크가 늘어서, 필요한 것만 켜는 게 맞아요.
Claude Code에 플러그인 몇 개 깔아두고 나면 처음엔 편해요. 근데 claude code 플러그인 검색해서 들어온 사람 대부분이 곧바로 같은 벽을 만나죠. /plugin에는 뭐가 잔뜩 보이는데, 이걸 다 깔아도 되는지 애매해요. 스킬은 자동으로 불리는 것 같고, MCP는 토큰을 먹는다고 하고, 훅은 잘못 두면 내 터미널에서 명령을 돌릴 수 있거든요.
먼저 기준을 잡아야 해요. 개인 실험이면 .claude/에 작게 두고 써보세요. 팀에 나눠야 하면 그때 claude code 플러그인 형태로 묶는 게 깔끔해요. 아직 Claude Code 설치부터 막힌 상태라면 Claude Code 사용법: 설치부터 첫 실행까지 5분 가이드부터 보고 오는 게 빨라요.
여기서는 설치 명령, 쓸 수 있는 환경, 마켓 고르는 법, 컨텍스트 줄이는 법, plugin.json 최소 구조까지 한 번에 잡아요. 보안 쪽은 겁주려고 넣은 게 아니에요. 2025·2026년에 걸쳐 실제 CVE 번호가 붙은 이슈가 있었고, 플러그인은 편의 기능이 아니라 실행 권한을 가진 패키지에 가깝거든요.
플러그인이 뭔가요? 스킬·MCP·훅과 관계
플러그인은 Claude Code 확장 요소를 묶어서 설치하고 끄는 단위예요. 스킬 하나만 담을 수도 있고, MCP 서버나 훅까지 같이 넣을 수도 있어요. 근데 그냥 .claude/에 파일 넣는 거랑 뭐가 다를까요?
플러그인 구성 요소 6가지
| 구성 요소 | 짧게 말하면 | 조심할 점 |
|---|---|---|
| 스킬 | Claude가 필요할 때 쓰는 작업 지침 | 설명이 애매하면 안 불릴 수 있어요 |
| 서브에이전트 | 특정 일을 맡는 보조 에이전트 | 너무 많이 두면 선택이 흐려져요 |
| MCP 서버 | Model Context Protocol, 외부 도구 연결 규격 | 툴 정의와 출력이 컨텍스트를 먹어요 |
| 훅 | 특정 이벤트 때 명령을 돌리는 자동화 | 실행 권한이 있어서 리뷰 필수예요 |
| LSP 서버 | Language Server Protocol, 타입·진단 연결 | 언어별 서버 설치가 필요할 수 있어요 |
bin/ |
플러그인 전용 실행 파일 | PATH에 올라가니 이름 충돌을 체크해야 해요 |
공식 문서 기준으로 플러그인은 스킬, 에이전트, 훅, MCP 서버, LSP 세팅을 담을 수 있어요. 이 구조는 Claude Code Hooks 완벽 가이드 – 자동화 훅 설정법이랑 같이 보면 이해가 빨라요.
어디에서 쓸 수 있나요
쓸 수 있는 환경도 헷갈리죠.
| 사용 환경 | 플러그인 관점에서 볼 점 |
|---|---|
| 터미널 CLI | /plugin 명령으로 설치·비활성화·리로드 |
| Desktop app | 로컬·SSH 세션에서 플러그인 관리 가능, 원격 세션은 제한 있음 |
| Web app·모바일 앱 | claude.ai/code cloud 세션 중심, 로컬 설정이 그대로 적용되지 않아요 |
| VS Code·Cursor | Claude Code 확장 안에서 쓰고, CLI도 같이 접근 가능 |
| JetBrains IDE | 전용 IDE 연결로 쓰되 플러그인 관리는 CLI 흐름 체크 필요 |
| Agent SDK·API | 자동화 앱에서 쓰는 별도 경로라 플러그인 로드 범위 검증 필요 |
| Chrome extension beta·Slack | 코드 세션 주변 기능으로 보고, 플러그인 설치 대상으로 섞지 않는 게 안전해요 |
claude code 플러그인 설치 3가지 방법
claude code 플러그인 설치는 보통 /plugin marketplace add와 /plugin install 두 줄이면 끝나요. 문제는 어디에 깔리는지, 누가 같이 쓰는지예요. 내 컴퓨터 전용인지, 프로젝트 팀원도 같이 쓰는지 먼저 정해야죠?
/plugin 명령으로 마켓플레이스와 설치된 플러그인을 확인·토글할 수 있어요.1. 마켓플레이스 추가 후 설치
# Claude Code 안에서 입력
/plugin marketplace add owner-or-org/plugin-marketplace
# 마켓 이름이 team-tools라면 이런 식으로 설치
/plugin install code-reviewer@team-tools
# 플러그인 수정 후 다시 읽기
/reload-plugins
# 예상 출력
# Reloaded plugins: 1 plugin, 1 skill, 0 agents, 0 hooks
공식 문서의 설치 흐름은 GitHub 저장소, Git URL, 로컬 경로, 원격 marketplace.json URL을 받아요. 여기서 처음 많이 막히는 지점은 저장소 루트에 .claude-plugin/marketplace.json이 있어야 한다는 점이에요.
2. Repomix처럼 커뮤니티 마켓 설치
Repomix는 공식 가이드에서 마켓 추가 뒤 repomix-mcp, repomix-commands, repomix-explorer를 따로 설치하라고 안내해요. 예전 글에서 보이는 repomix@repomix 한 줄은 지금 기준으로 틀릴 수 있어요.
# Repomix 마켓 추가
/plugin marketplace add yamadashy/repomix
# 권장 기반 플러그인
/plugin install repomix-mcp@repomix
# 명령 플러그인
/plugin install repomix-commands@repomix
# 저장소 탐색 플러그인
/plugin install repomix-explorer@repomix
# 예상 출력
# Installed repomix-mcp@repomix
# Installed repomix-commands@repomix
# Installed repomix-explorer@repomix
3. 플랜과 사용 환경 체크
| 플랜 | 공식 가격 기준 | Claude Code 관점 |
|---|---|---|
| Free | $0 | 플러그인 실사용 전 접근 범위 체크 필요 |
| Pro | $20/월, 연간은 월 환산 $17 | 터미널·웹 Claude Code 접근 가능 |
| Max 5x | $100/월 | 사용량 많은 개인 개발자용 |
| Max 20x | $200/월 | 장시간 세션이 많은 쪽 |
| Team Standard | $25/인/월, 연간은 $20 | 팀 관리와 중앙 세팅 확인 |
| Team Premium | $125/인/월, 연간은 $100 | 더 많은 사용량이 필요한 팀원용 |
가격은 Claude 공식 가격 페이지와 Team 플랜 공식 안내 기준으로 다시 봐야 해요. 세금과 지역 표시는 계정마다 다를 수 있거든요.
설치 전 기본 세팅은 MCP 서버 사용법: Claude Code 연결 가이드에서 먼저 잡아두면 덜 헤매요.
claude code 마켓플레이스 고르는 기준
claude code 마켓플레이스는 공식, 커뮤니티, 팀 내부로 나눠 보면 편해요. 이름만 공식에 올라와 있어도 제3자 플러그인이 섞일 수 있으니, “공식 목록에 있다”와 “내가 신뢰해도 된다”는 다른 얘기예요. 이거 그냥 npm 패키지 고르는 일이랑 비슷하지 않나요? 맞아요, 설치 전 체크리스트는 거의 똑같아요. 출처, 최근 커밋, 의존성, 실행 권한을 한 번씩 보고 들이는 거죠.
| 구분 | 설치 경로 | 장점 | 체크할 것 |
|---|---|---|---|
| 공식 마켓 | claude-plugins-official |
Claude Code에서 기본으로 보임 | 외부 플러그인 출처, 최근 커밋 |
| 커뮤니티 마켓 | GitHub repo, Git URL, URL | 빠르고 다양해요 | 훅, MCP, bin/ 파일 |
| 팀 내부 마켓 | 사내 GitHub 또는 Git 서버 | 표준 워크플로 고정 가능 | 관리 주체, 버전 고정 |
| 로컬 마켓 | 내 디렉터리 | 제작 테스트에 좋음 | 배포 전 구조 검증 |
공식 GitHub 저장소 README에도 설치 전 신뢰 여부를 보라고 적혀 있어요. 실제로 공식 마켓 저장소는 내부 플러그인과 외부 플러그인을 나눠 두고, 각 플러그인의 홈을 보게 해요.
고르는 기준은 단순해요.
- 최근 커밋이 살아 있는가
hooks/,.mcp.json,bin/이 무엇을 실행하는가- API 키나 토큰을 요구하는가
- 설치 뒤 끄기 쉬운가
- 같은 일을 하는 플러그인이 이미 있는가
- 팀원이 이해할 README가 있는가
서브에이전트 묶음이 많은 마켓은 특히 조심하세요. 에이전트가 많아질수록 선택 비용도 같이 늘어요. 서브에이전트 구조는 Claude Code 서브에이전트 만들기 실전 가이드: 자동 위임·비용 절감 세팅까지에서 따로 깊게 보는 게 나아요.
플러그인 묶음 대신 별도 에이전트 플랫폼을 비교해보고 싶으면 Replit Agent 사용법: Agent 3 Max Autonomy 200분 빌드도 같이 보세요. 도구를 Claude Code에 묶을지, 아예 다른 에이전트 환경으로 갈지 판단이 빨라져요.
깔기 전에 보는 컨텍스트·보안·충돌
플러그인은 기능보다 비용을 먼저 봐야 해요. 컨텍스트를 먹고, 훅은 명령을 돌릴 수 있고, 이름이 비슷한 스킬은 서로 묻힐 수 있거든요. 설마 마켓에 보이는 걸 전부 깔 생각은 아니죠? 설치 전에 다섯 가지만 빠르게 체크하면 대부분의 사고는 피할 수 있어요.
| 체크 항목 | 봐야 할 것 | 조치 |
|---|---|---|
| 컨텍스트 | 설치 전후 토큰 차이 | 설치 직후 /context 또는 상태 표시로 비교 |
| MCP | 툴 정의와 출력 크기 | Tool Search 기본값과 출력 제한 체크 |
| 훅 | PreToolUse, PostToolUse, SessionStart |
셸 명령과 원격 URL 수동 리뷰 |
| 보안 | CVE, 패치 버전 | 최신 Claude Code로 업데이트 |
| 충돌 | 스킬 이름·역할 중복 | 덜 쓰는 플러그인 비활성화 |
# 버전 보기
claude --version
# MCP 출력이 너무 클 때 제한을 올려서 테스트
export MAX_MCP_OUTPUT_TOKENS=50000
claude
# Tool Search를 끄고 비교 테스트할 때만 사용
ENABLE_TOOL_SEARCH=false claude
Claude Code MCP 문서 기준으로 Tool Search는 기본 켜짐이에요. MCP 툴 정의를 처음부터 다 넣지 않고, 필요할 때 찾는 방식이라 컨텍스트 부담이 줄어요. 예전 자료에서 toolSearch: true라고 본 적이 있다면, 2026년 4월 기준으론 ENABLE_TOOL_SEARCH 환경 변수 쪽을 다시 봐야 해요.
보안은 더 노골적으로 봐야 해요. CVE는 Common Vulnerabilities and Exposures, 공개 취약점 번호예요. Check Point Research와 NVD 기록 기준이에요. CVE-2025-59536은 신뢰 확인 전 코드 실행 문제고, CVE-2026-21852는 ANTHROPIC_BASE_URL 조작으로 API 키가 노출되는 문제예요. NVD에는 각각 1.0.111, 2.0.65에서 패치됐다고 기록돼요.
# 플러그인 훅 파일을 직접 열어보기
find ~/.claude/plugins -path "*/hooks/*" -type f -maxdepth 8
# 의심할 패턴
# curl | bash
# 원격 URL로 토큰 전송
# SessionStart에서 셸 명령 실행
보안 자동화는 Claude Code Hooks 완벽 가이드 – 자동화 훅 설정법을 보고 따로 룰을 잡아두세요. 훅은 편하지만, 리뷰 없이 들여오면 제일 먼저 사고 나는 지점이에요.
claude code 플러그인 만들기 최소 템플릿
claude code 플러그인 만들기는 생각보다 작게 시작하는 게 좋아요. 처음부터 MCP 서버까지 붙이지 말고, 스킬 하나와 plugin.json 하나로 끝내세요. 팀 리뷰 규칙 하나 묶는 정도면 충분하지 않을까요?
# 예제 폴더 만들기
mkdir -p team-review-plugin/.claude-plugin
mkdir -p team-review-plugin/skills/pr-review
# 폴더 구조 보기
tree team-review-plugin
# 예상 출력
# team-review-plugin
# ├── .claude-plugin
# │ └── plugin.json
# └── skills
# └── pr-review
# └── SKILL.md
{
"name": "team-review",
"description": "팀 PR 리뷰 기준을 Claude Code에 넣는 플러그인",
"version": "0.1.0"
}
---
description: PR 변경 내용을 팀 기준으로 리뷰할 때 씁니다.
---
# PR Review
변경 파일을 보고 아래 기준으로 리뷰해요.
- 깨질 만한 흐름
- 테스트가 빠진 곳
- 보안상 위험한 입력
- 리뷰어가 바로 고칠 수 있는 제안
# 로컬 플러그인으로 테스트
claude --plugin-dir ./team-review-plugin
# Claude Code 안에서 실행
/team-review:pr-review 최근 변경 파일 봐줘
# 수정 후 다시 읽기
/reload-plugins
공식 문서에서 자주 강조하는 실수도 여기예요. plugin.json만 .claude-plugin/ 안에 두고, skills/, agents/, hooks/는 플러그인 루트에 둬야 해요. 이걸 틀리면 설치는 된 것 같은데 스킬이 안 보이더라고요.
루틴과 섞어 쓰려면 Claude Code 루틴 실전 가이드: PR 리뷰·배포 검증을 노트북 꺼도 돌리는 법 쪽으로 넘기는 게 나아요. 플러그인은 “묶음”, 루틴은 “나중에 돌아가는 일”에 가까워요.
플러그인 밖에서 콘텐츠 생산 도구를 어떻게 분담하는지 감 잡고 싶으면 NotebookLM 블로그 활용: 인터뷰 녹취를 초안으로 바꾸는 3단계도 같이 보세요. 시각 자료까지 같이 묶으려면 AI 이미지 생성 블로그 활용: 썸네일부터 본문 삽화까지에서 워크플로 분기를 따로 정리해뒀어요.
팀 배포와 추천 플러그인 선별법
팀 배포는 extraKnownMarketplaces로 마켓을 알려주고, enabledPlugins로 켤 플러그인을 지정하는 흐름이 제일 깔끔해요. 강제로 막아야 할 조직이면 strictKnownMarketplaces까지 같이 봐야 하죠. 팀 전체에 같은 걸 깔려면 개인 취향보다 운영 규칙이 먼저예요.
{
"extraKnownMarketplaces": {
"team-tools": {
"source": {
"source": "github",
"repo": "your-org/claude-plugins"
}
}
},
"enabledPlugins": {
"team-review@team-tools": true
}
}
추천 플러그인은 “유명한가”보다 “우리 워크플로에 비용 대비 맞는가”로 봐요.
| 후보 | 쓸 때 | 먼저 볼 것 |
|---|---|---|
| Repomix | 큰 코드베이스를 압축해서 읽을 때 | repomix-mcp부터 설치 |
| LSP 계열 | 타입 에러를 빨리 잡고 싶을 때 | 언어 서버 설치 여부 |
| 코드 리뷰 계열 | PR 리뷰 기준을 맞출 때 | 훅·외부 전송 여부 |
| Superpowers류 워크플로 | 계획→실행 흐름을 강제할 때 | 단계가 팀 속도에 맞는지 |
| Codex 교차 검토류 | 두 도구 의견을 비교할 때 | 토큰과 실행 권한 분리 |
처음엔 팀 공통 플러그인을 2개 이하로 시작하세요. 하나는 코드 리뷰, 하나는 언어 진단 정도면 충분해요. 세부 역할 분리는 Claude Code 서브에이전트 만들기 실전 가이드: 자동 위임·비용 절감 세팅까지를 참고해서 나중에 빼도 늦지 않아요.
자주 묻는 질문
Q1: 플러그인하고 그냥 .claude/ 폴더에 넣는 거하고 뭐가 달라요?
A: 혼자 실험하면 .claude/가 빨라요. 팀 공유, 버전 관리, 마켓 배포가 필요해지면 플러그인으로 옮기세요. 처음부터 플러그인으로 만들면 구조 때문에 손이 더 가요.
Q2: 플러그인 깔았는데 스킬이 /help에 안 떠요. 왜 그래요?
A: 보통 폴더 위치가 틀렸거나 캐시가 꼬인 경우예요. skills/는 .claude-plugin/ 안이 아니라 플러그인 루트에 둬야 해요.
rm -rf ~/.claude/plugins/cache
# Claude Code 안에서
/reload-plugins
Q3: MCP 서버 많이 붙이면 토큰이 진짜 많이 나가요?
A: 네, 나갈 수 있어요. 다만 2026년 4월 기준 공식 문서는 Tool Search가 기본 켜짐이라고 안내해서, 예전처럼 모든 툴 정의를 처음부터 넣는 흐름과 달라졌어요. 정확한 체감은 설치 직후 /context로 전후를 비교하는 게 가장 빨라요.
Q4: 플러그인 설치해도 안전해요?
A: “공식 마켓에 보인다”와 “안전하다”는 같은 말이 아니에요. 훅, MCP, 환경 변수, bin/ 파일을 보고, Claude Code 버전을 최신으로 올린 뒤 설치하세요. CVE-2025-59536과 CVE-2026-21852는 이미 패치 기록이 있지만, 비슷한 구조의 리스크는 계속 남아요.
Q5: 우리 팀 전체에 플러그인을 강제로 깔 수 있어요?
A: 관리 세팅으로 마켓을 알려주고 enabledPlugins를 잡는 방식이 있어요. 보안 조직이면 strictKnownMarketplaces로 허용 마켓만 열어두는 쪽까지 같이 봐야 해요.
다음 단계
최소 템플릿 그대로 team-review-plugin/ 하나 만들고, claude --plugin-dir ./team-review-plugin까지만 해보세요. 직접 만든 플러그인이 있으면 댓글에 마켓 링크를 남겨주세요. 다음 큐레이션 글에서 실제 설치 기준으로 걸러볼게요.
