플러그인 시스템 개요

플러그인은 Skills, Agents, Hooks, MCP 서버를 한 디렉토리로 패키징한 단위입니다. 마켓플레이스에서 이름 하나로 설치하고 업데이트 받을 수 있으며, 팀 또는 커뮤니티에 배포할 때도 쓸 수 있습니다.

플러그인이 필요한 시점

Skills, Agents, Hooks, MCP 서버는 플러그인 없이도 독립 파일로 동작합니다. 예를 들어 ~/.claude/skills/에 넣은 스킬은 모든 프로젝트에서 작동합니다.

플러그인이 유용한 경우:

• 여러 컴포넌트를 하나의 단위로 묶어 팀원과 공유할 때
• 여러 프로젝트에 동일한 설정을 설치해야 할 때
• 버전 관리와 업데이트가 필요한 배포 대상을 만들 때

개인 워크플로우이거나 단일 프로젝트 전용이라면 .claude/ 하위 독립 파일로 충분합니다.

플러그인 구조

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # 매니페스트 (플러그인 이름과 메타데이터)
├── skills/               # Skills (SKILL.md 파일)
│   └── review/
│       └── SKILL.md
├── agents/               # 커스텀 서브에이전트 (.md 파일)
│   └── reviewer.md
├── hooks/
│   └── hooks.json        # Hook 핸들러 정의
└── .mcp.json             # MCP 서버 설정

위치 규칙

plugin.json만 .claude-plugin/ 안에 넣습니다. skills/, agents/, hooks/ 등 컴포넌트 디렉토리는 플러그인 루트에 배치합니다. .claude-plugin/ 안에 넣은 컴포넌트는 로드되지 않습니다.

활성화된 플러그인이 세션에 미치는 영향

플러그인을 활성화하면 해당 플러그인이 필요한 세션뿐만 아니라 모든 세션에서 항상 로드됩니다. 알아야 할 사항:

• 컨텍스트 비용: Claude가 자동으로 호출할 수 있는 스킬·에이전트의 이름과 설명이 매 턴의 컨텍스트에 포함됩니다. 스킬·에이전트 본문은 실제 사용 시에만 로드됩니다.
• 프로세스: 플러그인이 정의한 MCP 서버가 세션마다 실행됩니다.
• 권한: 플러그인 코드는 사용자 권한으로 실행됩니다.

설치 전 /plugin 패널에서 공식 마켓플레이스 플러그인의 Context cost 추정치를 확인할 수 있습니다. 설치 후 사용하지 않는 플러그인은 /plugin → Installed → Not used recently 목록에서 비활성화하거나 삭제하세요.

마켓플레이스 구조

마켓플레이스는 플러그인 목록과 각 플러그인의 출처를 담은 카탈로그입니다. Claude Code를 처음 실행하면 Anthropic의 공식 마켓플레이스(claude-plugins-official)가 자동 등록됩니다.

flowchart LR
    MKT["마켓플레이스\n(카탈로그)"]
    PKG["플러그인\n(디렉토리 단위)"]
    CC["Claude Code\n(세션 로드)"]
    
    MKT -->|"목록 조회"| PKG
    PKG -->|"/plugin install"| CC
    CC -->|"Skills / Hooks / MCP 제공"| CC

Anthropic의 마켓플레이스는 세 종류입니다:

마켓플레이스	이름	특징
공식	claude-plugins-official	Claude Code 첫 실행 시 자동 등록
커뮤니티	claude-community	수동 추가 필요
데모	claude-code-plugins	예제 플러그인

설치 범위 (Scope)

플러그인을 설치할 때 적용 범위를 선택합니다:

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

같은 플러그인이 여러 범위에 설정된 경우 Local > Project > User 순서로 우선합니다.

공식 플러그인 — Claude Security

Anthropic 공식 마켓플레이스에서 제공하는 대표 플러그인입니다.

• 기능: 코드베이스의 취약점을 다중 에이전트로 스캔하여 아키텍처 파악, 위협 모델 구축, 취약점 탐지, 독립 리뷰 후 보고서 작성
• 설치:

  /plugin install claude-security@claude-plugins-official
  /claude-security

자세한 스캔 옵션은 보안 주의사항을 참조하세요.

다음 단계

• 플러그인 설치 및 관리 →
• 첫 플러그인 직접 만들기 →
• 마켓플레이스 운영 →