플러그인과 마켓플레이스

플러그인(plugin)은 앞서 배운 스킬·훅·MCP 같은 확장 요소를 한 상자에 담아 팀과 커뮤니티에 나눠 쓰는 배포 묶음입니다. 혼자 쓸 때는 .claude/ 폴더에 파일을 흩어 놓아도 충분하지만, 같은 워크플로를 여러 프로젝트와 동료에게 반복해서 쓰기 시작하면 “이 스킬과 훅을 한 세트로” 설치하고 버전도 함께 올리고 싶어지는데, 바로 그 필요를 채우는 단위가 플러그인입니다.

배경 참조

이 문서는 MoAI-ADK가 올라타 있는 플랫폼인 Claude Code 자체를 다루는 배경 자료입니다. MoAI-ADK 자체 기능은 사이드바 위쪽 섹션에서 다룹니다.

정보

한 줄 요약: 플러그인은 에이전트·명령·스킬·훅·MCP를 한 폴더에 담아 버전 관리하며 배포하는 “확장 묶음"이고, 마켓플레이스(marketplace)는 그 묶음을 골라 담는 앱 스토어입니다.

플러그인은 Claude Code의 여러 확장 요소를 한 디렉터리에 묶어 공유·재사용·버전 관리할 수 있게 만든 패키지입니다. .claude/ 디렉터리에 직접 두는 단독 설정과 달리, 플러그인은 매니페스트 파일로 자기 정체를 밝히고 마켓플레이스를 타고 다른 프로젝트와 팀으로 퍼집니다.

단독 설정과 플러그인의 차이는 명확합니다.

플러그인의 핵심은 .claude-plugin/plugin.json 매니페스트입니다. 이 파일이 플러그인의 이름·설명·버전을 정의하며, name 필드는 곧 스킬의 네임스페이스 접두사가 됩니다. 매니페스트는 선택 사항이라 없어도 플러그인은 동작하지만, 버전 관리와 마켓플레이스 배포는 매니페스트가 있을 때 훨씬 수월합니다.

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

version은 선택값입니다. 명시하면 이 값을 올릴 때만 사용자에게 업데이트가 전달되고, 생략한 채 git으로 배포하면 커밋 SHA가 버전 역할을 하여 매 커밋이 새 버전으로 취급됩니다.

개발 중에는 claude --plugin-dir ./my-plugin으로 설치 없이 로컬 플러그인을 바로 올려 테스트하고, 고친 뒤에는 /reload-plugins로 재시작 없이 반영합니다.

플러그인 하나가 에이전트·스킬·명령·훅·MCP를 동시에 담을 수 있어, “이 작업에 필요한 모든 확장"을 한 번의 설치로 전달합니다. 플러그인 루트(.claude-plugin/plugin.json이 아닌 플러그인 디렉터리 자체)에 요소별 디렉터리를 둡니다. 주의: .claude-plugin/ 안에는 plugin.json 만 들어가고, 나머지 구성 요소는 모두 플러그인 루트에 위치합니다.

예를 들어 commit-commands 플러그인은 commit·push·PR 생성 스킬을 묶어 제공하고, pr-review-toolkit은 PR 리뷰 전용 에이전트를 함께 배포합니다. 매니페스트의 name이 곧 네임스페이스이므로, 두 플러그인이 같은 이름의 스킬을 담고 있어도 /commit-commands:diff·/pr-review-toolkit:diff처럼 겹치지 않습니다.

마켓플레이스는 누군가 만든 플러그인 목록을 담은 카탈로그입니다. 쓰는 순서는 두 단계입니다. 먼저 카탈로그를 추가해 둘러볼 수 있게 한 뒤, 원하는 플러그인을 하나씩 설치합니다. 앱 스토어를 등록하는 것과 개별 앱을 내려받는 것을 분리해 생각하면 됩니다.

/plugin marketplace add로 여러 출처를 등록할 수 있습니다.

# GitHub 저장소 (owner/repo 형식)
/plugin marketplace add anthropics/claude-plugins-official

# 다른 Git 호스트 (.git 접미사 필수)
/plugin marketplace add https://gitlab.com/company/plugins.git

# 특정 브랜치·태그 고정
/plugin marketplace add https://gitlab.com/company/plugins.git#v1.0.0

# 로컬 경로 / 원격 marketplace.json
/plugin marketplace add ./my-marketplace
/plugin marketplace add https://example.com/marketplace.json

공식 Anthropic 마켓플레이스(claude-plugins-official)는 Claude Code를 켜면 바로 쓸 수 있습니다. 커뮤니티 마켓플레이스는 수동으로 추가합니다.

# 공식 마켓플레이스에서 설치
/plugin install hello@claude-plugins-official

# 커뮤니티 마켓플레이스 추가 후 설치
/plugin marketplace add anthropics/claude-plugins-community
/plugin install <plugin-name>@claude-plugins-community

/plugin을 실행하면 Discover / Installed / Marketplaces / Errors 네 개 탭짜리 플러그인 관리자가 열립니다. Discover 탭의 상세 패널에서는 설치 전에 컨텍스트 비용 (Context cost) 추정치, 최종 업데이트 날짜, 함께 깔릴 명령·에이전트·스킬·훅·MCP·LSP 목록을 미리 볼 수 있습니다.

설치 범위 (scope)는 세 가지입니다.

설치·활성·비활성·제거는 CLI로도 가능합니다.

/plugin install plugin-name@marketplace-name   # 설치 (기본 user 범위)
/plugin disable plugin-name@marketplace-name    # 비활성 (제거 안 함)
/plugin enable  plugin-name@marketplace-name    # 재활성
/plugin uninstall plugin-name@marketplace-name  # 완전 제거
/reload-plugins                                 # 재시작 없이 변경 반영

팀 단위로는 .claude/settings.json의 extraKnownMarketplaces 키에 마켓플레이스를 적어 두면, 협업자가 저장소 폴더를 신뢰할 때 Claude Code가 해당 마켓플레이스와 플러그인 설치를 안내합니다.

코드 인텔리전스 (code intelligence) 플러그인은 LSP (Language Server Protocol)로 Claude Code 내장 코드 인텔리전스 도구를 켭니다. VS Code의 코드 탐색을 뒷받침하는 바로 그 기술입니다. 언어별 플러그인을 설치하고, 해당 언어 서버 바이너리가 시스템에 깔려 있어야 동작합니다.

플러그인이 활성화되면 Claude는 두 가지 능력을 얻습니다.

• 자동 진단 (diagnostics): Claude가 파일을 편집할 때마다 언어 서버가 변경을 분석해 타입 오류·누락된 import·구문 오류를 자동으로 보고합니다. 컴파일러나 린터를 따로 돌리지 않아도 같은 턴에서 오류를 알아채고 바로 고칩니다. “diagnostics found” 표시가 뜰 때 Ctrl+O를 누르면 인라인으로 확인할 수 있습니다.
• 코드 탐색 (navigation): 정의로 이동, 참조 찾기, 호버 타입 정보, 심볼 목록, 구현 찾기, 호출 계층 추적이 가능합니다. grep 기반 검색보다 훨씬 정확한 탐색을 제공합니다.

Executable not found in $PATH 오류가 /plugin Errors 탭에 보이면 위 표의 언어 서버 바이너리를 설치하면 됩니다. rust-analyzer·pyright 등은 규모가 큰 코드베이스에서 메모리를 많이 쓸 수 있으니, 부담되면 해당 플러그인을 비활성화하고 Claude 내장 검색에 의존해도 됩니다.

플러그인과 마켓플레이스는 높은 신뢰가 필요한 구성 요소입니다. 사용자 권한으로 임의 코드를 실행할 수 있기 때문입니다. 신뢰하는 출처에서만 설치하세요.

• Anthropic은 플러그인에 포함된 MCP 서버·파일·소프트웨어를 통제하지 않으며, 의도대로 동작하는지 검증하지 않습니다. 서드파티 플러그인은 설치 전에 홈페이지와 Discover 탭의 “Will install” 목록을 직접 검토하세요.
• 커뮤니티 마켓플레이스 플러그인은 Anthropic의 자동 검증·안전 스크리닝을 통과한 뒤 특정 커밋 SHA에 고정되어 배포됩니다. 그래도 최종 신뢰 판단은 설치자의 몫입니다.
• 조직은 관리 설정 (managed settings)으로 사용자가 추가할 수 있는 마켓플레이스를 제한할 수 있습니다.

플러그인은 ‘높은 신뢰’ 구성 요소로 분류되어, 한 번 신뢰하고 설치하면 권한 검사의 시점이 바뀝니다. 평소 서브에이전트는 상위 세션의 permissionMode (예: 도구를 쓸 때마다 묻는 제한 모드)를 물려받지만, 플러그인이 담고 있는 서브에이전트는 이 제약을 따르지 않습니다.

즉 권한 검사가 매 도구 호출마다 일어나는 게 아니라 플러그인을 설치하는 순간 한 번으로 옮겨 갑니다. 설치 이후에는 플러그인의 에이전트·훅·MCP가 매 호출마다 다시 묻지 않고 움직입니다. 그래서 “어디서 가져왔는지"를 설치 전에 반드시 확인해야 하고, 저장소 폴더를 신뢰할 때 Claude Code가 따로 안내하는 것도 이 때문입니다.

추가로, 플러그인 루트의 settings.json에서 agent 키를 켜면 해당 플러그인의 에이전트가 메인 스레드로 활성화되어 시스템 프롬프트·도구 제한·모델까지 바꿔 버립니다. 신뢰할 수 있는 플러그인에서는 편리한 기능이지만, 출처가 불분명한 플러그인에서는 Claude Code의 기본 동작 자체가 바뀔 수 있으니 주의해야 합니다.

flowchart TD
    A[마켓플레이스 추가
/plugin marketplace add] --> B[플러그인 탐색
/plugin Discover 탭]
    B --> C{출처를
신뢰하는가?}
    C -- 아니오 --> D[설치 보류
홈페이지·Will install 검토]
    C -- 예 --> E[설치 범위 선택
User / Project / Local]
    E --> F[설치 = 신뢰 한 번
/plugin install]
    F --> G[변경 반영
/reload-plugins]
    G --> H[네임스페이스 스킬 사용
/plugin-name:skill]

MoAI-ADK 자체는 플러그인이 아닙니다. moai init이 .claude/ 디렉터리에 하네스 자산(스킬·에이전트·훅·설정)을 직접 풀어 놓는 방식입니다. 그래도 이 페이지의 두 가지는 MoAI-ADK 사용자에게도 곧바로 와닿습니다.

하나는 Discover 탭의 컨텍스트 비용 (Context cost) 추정치입니다. 토크노믹스 감각을 그대로 옮겨 놓은 지표이므로, 확장 하나를 깔 때마다 항시 컨텍스트가 얼마나 늘어나는지 보고 판단하세요. 다른 하나는 코드 인텔리전스 (LSP) 플러그인입니다. MoAI-ADK의 언어별 품질 게이트가 쓰는 진단 신호와 같은 계열이라, 쓰는 언어의 LSP 플러그인을 깔아 두면 편집 직후 타입 오류를 같은 턴에 잡아내는 루프가 훨씬 촘촘해집니다.

• 스킬
• 훅 (Hooks)
• MCP 서버

• Create plugins (code.claude.com)
• Discover and install plugins (code.claude.com)
• What Claude gains from code intelligence plugins

팁

설치하려는 플러그인이 보이지 않으면 마켓플레이스가 오래된 것일 수 있습니다. /plugin marketplace update <marketplace-name>으로 목록을 새로 고친 뒤 다시 설치해 보세요.