Claude 플러그인 패키징 개념 일러스트
IT기술

[Claude 활용 24회 — AI에게 일을 위임하는 법] 12/24화: Claude 플러그인 만들기 5단계 — 만든 도구를 묶고 파는 법

By AICosmus
2026년 08월 12일 9 Min Read
1

3줄 요약

  • 9~11회에서 만든 Skill·MCP 서버·서브에이전트는 따로 두면 공유할 수 없다 — Claude 플러그인으로 묶어야 배포 단위이자 판매 단위가 된다.
  • plugin.toml 하나로 의존성·권한·설명을 선언하고, claude plugin pack 한 줄이면 .zip이 완성된다.
  • 서드파티 플러그인 설치는 코드 실행 권한을 넘기는 행위다 — 신뢰 검증 없이 install을 누르지 않는다.

PART 3(9~12회)의 마지막 회차다. 9회에서 Skill을 만들었고, 10회에서 MCP 서버를 붙였고, 11회에서 서브에이전트로 팀을 짰다. 각각은 잘 돌았다. 문제는 이 세 가지를 동료에게 건네는 순간 터졌다. 오늘은 흩어진 부품을 Claude 플러그인이라는 하나의 배포 단위로 묶는 법, 그리고 그걸 마켓플레이스에서 남에게 쓰게 하거나 파는 법을 다룬다. AI에게 일을 위임하는 시대에, 위임 방식 자체를 포장해서 파는 것이 이 회차의 핵심이다.

Skill 3개, MCP 서버 1개, 에이전트 설정 2개 — 그리고 아무도 못 쓴 이유

5월에 있었던 일이다. 같이 일하는 개발자가 “그 회의록 분석하는 거 나도 쓸 수 있어?”라고 물었다. 자신 있게 “물론이지, 파일 보내줄게”라고 답했다. Skill 파일 2개, MCP 서버 설정 1개, 서브에이전트 구성 파일 1개, 훅 스크립트 1개. 총 5개 파일을 메신저로 보냈다.

30분 뒤 돌아온 메시지: “Skill은 어디에 넣어?” 1시간 뒤: “MCP 서버가 안 붙는데.” 2시간 뒤: “그냥 됐어, 다음에 보여줘.” 그 ‘다음’은 오지 않았다.

원인은 명확했다.

  • 경로 의존성: 내 Skill 파일은 .claude/skills/meeting-analyzer/SKILL.md에 있어야 했는데, 그걸 어디에 넣어야 하는지 파일 자체에는 적혀 있지 않았다.
  • MCP 서버 미포함: 10회에서 만든 MCP 서버는 별도의 Python 패키지였다. 설정 파일만 보냈으니 서버 코드가 없었다.
  • 훅 누락: 6회에서 배운 안전장치 훅을 내 환경에만 걸어뒀다. 동료 환경에는 훅이 없으니 Skill이 위험한 명령을 제약 없이 실행할 수 있는 상태였다.
  • 의존성 암묵 가정: 서브에이전트 구성이 특정 npm 패키지와 Python 라이브러리를 전제했는데, 그 목록은 내 머릿속에만 있었다.

개발자라면 익숙한 문제다. 라이브러리를 만들어 놓고 package.json 없이 소스 파일만 보낸 꼴. 우리에겐 npm이 있고 pip가 있고 Docker가 있다. Claude 생태계에도 같은 것이 필요했고, 그것이 플러그인이다.

Claude 플러그인의 해부 — 4개 부품이 하나가 되는 구조

Claude 플러그인(Plugin)은 Skill + MCP 설정 + 훅 + 에이전트 구성을 하나의 디렉토리(또는 .zip)로 묶은 배포 단위다. npm 패키지가 package.json으로 자기 자신을 설명하듯, Claude 플러그인은 plugin.toml로 자기 자신을 선언한다.

Claude 플러그인 4개 구성요소 구조도

plugin.toml — 플러그인의 신분증

plugin.toml은 플러그인의 메타데이터, 의존성, 권한 요구사항을 한 곳에 모은 매니페스트 파일이다. npm의 package.json, Python의 pyproject.toml, Docker의 Dockerfile을 합친 역할이라고 보면 된다.

# plugin.toml — 회의록 분석 플러그인
[plugin]
name = "meeting-analyzer"
version = "1.2.0"
description = "회의록에서 액션아이템을 추출하고 담당자별로 분류합니다"
author = "yourhandle"
license = "MIT"
min_claude_version = "1.8.0"

[plugin.keywords]
tags = ["meeting", "action-items", "productivity"]

[permissions]
# 이 플러그인이 요구하는 권한 목록
file_read = ["*.md", "*.txt", "*.pdf"]
file_write = ["output/*.md", "output/*.json"]
network = false                  # 외부 네트워크 접근 불필요
subprocess = false               # 임의 프로세스 실행 불필요

[dependencies]
# 이 플러그인이 필요로 하는 MCP 서버
[dependencies.mcp]
markdown-reader = { source = "bundled", path = "mcp/markdown-reader" }

[dependencies.python]
# MCP 서버가 사용하는 Python 패키지
pyyaml = ">=6.0"

[hooks]
# 번들된 훅 스크립트
pre_tool_use = "hooks/safety-check.sh"

핵심 필드를 하나씩 보자.

  • name: 마켓플레이스에서의 고유 식별자. npm 패키지명과 같은 규칙 — 소문자, 하이픈 허용, 슬래시 금지.
  • description: 9회에서 강조했던 것과 같다. 이 한 줄이 Claude가 자동 호출 여부를 판단하는 근거가 된다. 모호하면 영원히 호출되지 않는 유령 플러그인이 된다.
  • [permissions]: 가장 중요한 섹션. 이 플러그인이 어떤 파일을 읽고 쓸 수 있는지, 네트워크에 접근하는지, 프로세스를 실행하는지를 선언한다. 6회에서 배운 권한 원칙이 여기서 기계적으로 강제된다.
  • [dependencies.mcp]: 플러그인에 번들된 MCP 서버(source = "bundled")이거나 외부에서 가져올 서버(source = "registry")를 지정한다.
  • [hooks]: 플러그인이 활성화될 때 자동으로 등록되는 훅 스크립트. 설치하는 사람이 별도로 훅을 설정할 필요가 없다.

디렉토리 구조 규칙

플러그인 디렉토리는 정해진 구조를 따른다. 구조가 맞아야 claude plugin pack이 올바르게 .zip을 생성한다.

meeting-analyzer/
├── plugin.toml              # 매니페스트 (필수)
├── README.md                # 설명 문서 (마켓플레이스 상세 페이지에 표시)
├── skills/                  # Skill 정의 (1개 이상)
│   ├── extract-actions/
│   │   └── SKILL.md         # 액션아이템 추출 Skill
│   └── classify-owners/
│       ├── SKILL.md         # 담당자 분류 Skill
│       └── refs/
│           └── classification-rules.md  # 참조 파일 (토큰 절약용)
├── mcp/                     # 번들 MCP 서버 (선택)
│   └── markdown-reader/
│       ├── server.py
│       └── requirements.txt
├── hooks/                   # 훅 스크립트 (선택)
│   └── safety-check.sh
├── agents/                  # 서브에이전트 구성 (선택)
│   └── orchestrator.md      # 탐색→추출→검증 3역 오케스트레이션
└── examples/                # 사용 예시 (선택, 마켓플레이스 표시용)
    ├── sample-meeting.md
    └── expected-output.json

몇 가지 규칙이 있다.

  • skills/ 하위의 각 디렉토리는 하나의 Skill이다. 9회에서 만든 .claude/skills/ 구조와 동일하다. 플러그인을 설치하면 이 Skill들이 사용자의 .claude/skills/에 네임스페이스를 붙여 복사된다 (예: meeting-analyzer/extract-actions).
  • mcp/ 하위의 각 디렉토리는 하나의 MCP 서버다. plugin.toml의 [dependencies.mcp]에서 source = "bundled"로 참조된다.
  • agents/는 서브에이전트 오케스트레이션 정의다. 11회에서 다뤘던 역할 분담 구조를 마크다운 파일로 정의한다.
  • hooks/는 플러그인 활성화 시 자동 등록되는 훅 스크립트다. 6회의 PreToolUse 훅과 동일한 형태.
  • examples/는 마켓플레이스에서 “이 플러그인은 이런 입력을 넣으면 이런 결과를 낸다”를 보여주는 데모용 파일이다. 설치 시 복사되지 않는다.

의존성과 권한 — 왜 둘 다 선언해야 하는가

npm에서 의존성을 dependencies에 적듯, Claude 플러그인도 필요한 외부 자원을 선언한다. 하지만 npm과 다른 점이 하나 있다. 권한을 명시적으로 선언해야 한다.

일반적인 패키지 매니저는 설치된 코드가 시스템의 모든 자원에 접근할 수 있다. npm install 한 패키지가 파일을 읽고, 네트워크 요청을 보내고, 프로세스를 실행하는 걸 막을 방법이 사실상 없다. Claude 플러그인은 다르다. [permissions] 섹션에 선언되지 않은 권한은 설치 시 거부된다.

# 이 플러그인이 요구하는 권한
[permissions]
file_read = ["*.md", "*.txt"]     # .md와 .txt만 읽을 수 있음
file_write = ["output/*.md"]       # output/ 아래 .md만 쓸 수 있음
network = false                    # 외부 네트워크 접근 차단
subprocess = false                 # 프로세스 실행 차단

# 만약 어떤 플러그인이 이렇게 선언한다면?
# [permissions]
# file_read = ["*"]               # 모든 파일 읽기 — 🔴 경고
# network = true                   # 외부 전송 가능 — 🔴 경고
# subprocess = true                # 임의 명령 실행 — 🔴 경고
# → 설치 시 사용자에게 "이 플러그인은 높은 권한을 요구합니다" 경고가 뜬다

이 구조는 모바일 앱 설치 시 “이 앱이 카메라, 마이크, 연락처에 접근하려 합니다”와 같은 원리다. 다만 여기서는 파일 시스템, 네트워크, 프로세스 실행이 대상이고, 각각의 범위를 글로브 패턴으로 세밀하게 지정할 수 있다.

6회에서 “프롬프트로 ‘하지 마’는 통제가 아니다”라고 했던 것을 기억하는가. 플러그인의 [permissions]이 바로 그 기계적 통제의 배포 가능한 형태다.

실습: 회의록 분석 Claude 플러그인을 처음부터 끝까지 패키징

9~11회에서 만든 결과물을 하나의 플러그인으로 묶는다. 전체 과정은 7단계이며, 빈 디렉토리에서 시작해서 .zip 파일 하나가 나올 때까지 완주한다.

Step 1. 플러그인 초기화

claude plugin init 명령으로 디렉토리 뼈대를 만든다.

# 플러그인 이름을 지정하고 초기화
claude plugin init meeting-analyzer

# 생성된 구조 확인
cd meeting-analyzer
tree .
# .
# ├── plugin.toml
# ├── README.md
# └── skills/
#     └── example/
#         └── SKILL.md

init이 생성한 plugin.toml은 빈 매니페스트다. 여기에 실제 내용을 채워 넣는다.

Step 2. plugin.toml 작성

앞서 본 매니페스트를 실제로 작성한다. 핵심은 description과 [permissions]이다.

[plugin]
name = "meeting-analyzer"
version = "1.0.0"
description = "회의록 마크다운 파일에서 액션아이템을 자동 추출하고, 참석자별로 분류하여 팔로업 문서를 생성합니다. 주간 회의, 스프린트 리뷰, 1:1 미팅 등 모든 형태의 회의록을 지원합니다."
author = "your-marketplace-handle"
license = "MIT"
min_claude_version = "1.8.0"

[plugin.keywords]
tags = ["meeting", "action-items", "productivity", "team"]

[permissions]
file_read = ["*.md", "*.txt", "*.pdf"]
file_write = ["output/*.md", "output/*.json"]
network = false
subprocess = false

[dependencies.mcp]
markdown-reader = { source = "bundled", path = "mcp/markdown-reader" }

[dependencies.python]
markdown = ">=3.5"

[hooks]
pre_tool_use = "hooks/safety-check.sh"

description이 길다고 느낄 수 있다. 의도적이다. 이 설명은 두 곳에서 사용된다. (1) 마켓플레이스 검색 결과에 노출되는 요약, (2) Claude가 사용자의 요청에 이 플러그인을 자동으로 호출할지 판단하는 근거. 9회에서 Skill의 description이 모호하면 유령이 된다고 했던 것과 같은 원리다.

Step 3. Skill 정의 — 9회의 결과물을 옮긴다

9회에서 만든 회의록 분석 Skill을 플러그인 디렉토리로 옮긴다. 두 개의 Skill을 정의한다.

skills/extract-actions/SKILL.md — 액션아이템 추출:

---
description: "회의록 텍스트에서 액션아이템(할 일)을 추출합니다. 각 아이템에 담당자, 마감일, 우선순위를 태깅합니다."
auto_invoke: true
---

# 액션아이템 추출 Skill

## 입력
- 회의록 원문 (마크다운, 텍스트, 또는 PDF)

## 처리 규칙
1. 다음 패턴을 액션아이템으로 인식:
   - "~하기로 했다", "~해야 한다", "~까지 완료"
   - "TODO:", "ACTION:", "[AI]" 태그
   - 직접적인 업무 지시 ("김 대리가 ~를 맡는다")

2. 각 아이템에 다음 메타데이터를 추출:
   - **담당자**: 이름 또는 역할 (없으면 "미지정")
   - **마감일**: 언급된 날짜 (없으면 "미정")
   - **우선순위**: 상/중/하 (맥락에서 추론)

3. 추출 결과를 구조화된 마크다운으로 출력

## 출력 형식
```markdown
## 액션아이템 목록

| # | 항목 | 담당자 | 마감일 | 우선순위 |
|---|------|--------|--------|---------|
| 1 | ... | ... | ... | 상 |
```

## 참조 파일
- refs/classification-rules.md: 우선순위 판단 기준

skills/classify-owners/SKILL.md — 담당자별 분류:

---
description: "추출된 액션아이템을 담당자별로 그룹화하여 개인별 팔로업 문서를 생성합니다."
auto_invoke: true
---

# 담당자별 분류 Skill

## 입력
- extract-actions Skill의 출력 (액션아이템 테이블)

## 처리 규칙
1. 담당자 이름을 정규화 (약칭 → 풀네임 매핑)
2. 담당자별로 아이템을 그룹화
3. 각 담당자에 대해 개별 팔로업 문서 생성
4. "미지정" 아이템은 별도 "확인 필요" 섹션으로 분리

## 출력 형식
담당자별 마크다운 파일:
- output/{담당자명}_followup.md
- output/unassigned_followup.md (미지정 건)

## 요약 파일
- output/summary.json: 전체 통계 (총 아이템 수, 담당자별 수, 마감임박 건수)

참조 파일도 포함한다. skills/extract-actions/refs/classification-rules.md:

# 우선순위 판단 기준

## 상 (High)
- "긴급", "ASAP", "오늘 중", "내일까지"
- 고객 대응, 장애 관련
- 명시적으로 "우선" 표현

## 중 (Medium)
- 이번 주, 이번 스프린트 내
- 명시적 마감일 있음
- 기본값 (판단 근거 부족 시)

## 하 (Low)
- "여유 되면", "다음에", "나중에"
- 조사·검토·리서치 성격
- 명시적으로 "급하지 않다"

9회에서 강조했던 포인트: 참조 파일을 SKILL.md 본문에서 분리하면 Claude가 Skill을 호출할 때 참조 파일은 필요할 때만 읽는다. 토큰을 아끼는 구조다. 이 구조가 플러그인 안에서도 동일하게 유지된다.

Step 4. MCP 서버 설정 포함 — 10회의 결과물을 옮긴다

10회에서 만든 MCP 서버를 플러그인에 번들한다. 이 서버는 로컬 마크다운 파일을 읽어서 Claude에게 제공하는 역할이다.

mcp/markdown-reader/server.py:

"""회의록 마크다운 파일을 읽는 MCP 서버.

10회에서 만든 MCP 서버의 축소 버전.
플러그인에 번들되어 설치 시 자동으로 등록된다.
"""
from pathlib import Path
from mcp.server import Server
from mcp.types import Resource, TextContent

app = Server("markdown-reader")


@app.list_resources()
async def list_resources():
    """현재 디렉토리의 .md 파일 목록을 반환."""
    md_files = list(Path(".").glob("**/*.md"))
    return [
        Resource(
            uri=f"file://{f.resolve()}",
            name=f.name,
            description=f"마크다운 파일: {f}",
            mimeType="text/markdown",
        )
        for f in md_files[:50]  # 최대 50개
    ]


@app.read_resource()
async def read_resource(uri: str):
    """지정된 마크다운 파일의 내용을 반환."""
    path = Path(uri.replace("file://", ""))
    if not path.suffix == ".md":
        raise ValueError("마크다운 파일만 읽을 수 있습니다")
    content = path.read_text(encoding="utf-8")
    return TextContent(text=content)

mcp/markdown-reader/requirements.txt:

mcp>=1.0.0

플러그인을 설치하면 이 MCP 서버가 사용자의 Claude 환경에 자동으로 등록된다. 사용자가 별도로 MCP 설정을 건드릴 필요가 없다. 10회에서 “MCP 서버를 붙이는 과정이 번거롭다”고 느꼈다면, 플러그인이 그 번거로움을 캡슐화하는 것이다.

Step 5. 서브에이전트 구성 — 11회의 결과물을 옮긴다

11회에서 만든 탐색→추출→검증 3역 오케스트레이션을 플러그인에 포함한다.

agents/orchestrator.md:

# 회의록 분석 오케스트레이션

이 파일은 회의록 분석 작업을 3단계 서브에이전트로 분할하는 구성이다.

## 역할 분담

### 1단계: 탐색자 (Explorer)
- **역할**: 회의록 파일을 찾고 구조를 파악한다
- **도구**: markdown-reader MCP 서버
- **권한**: file_read만 허용
- **출력**: 분석 대상 파일 목록과 각 파일의 요약

### 2단계: 추출자 (Extractor)
- **역할**: extract-actions Skill을 호출하여 액션아이템을 뽑는다
- **도구**: extract-actions Skill, classify-owners Skill
- **권한**: file_read + file_write (output/ 한정)
- **입력**: 탐색자가 찾은 파일 목록
- **출력**: 담당자별 팔로업 문서 + 요약 JSON

### 3단계: 검증자 (Reviewer)
- **역할**: 추출 결과를 원본 회의록과 대조하여 누락·오류를 찾는다
- **권한**: file_read만 허용
- **출력**: 검증 보고서 (누락 건수, 불일치 사항)

## 실행 흐름
1. 탐색자가 회의록 파일을 식별
2. 추출자가 각 파일에서 액션아이템 추출 및 분류
3. 검증자가 원본과 결과를 대조
4. 최종 결과를 output/ 디렉토리에 저장

## 오류 처리
- 탐색자가 .md 파일을 0개 찾으면 → "회의록 파일을 찾을 수 없습니다" 보고 후 종료
- 추출자가 액션아이템 0개를 추출하면 → 검증자에게 원본 재검토 요청
- 검증자가 불일치 3건 이상 발견 시 → 추출자에게 재추출 요청 (최대 1회)

11회에서 말했던 것처럼, 서브에이전트 구성의 핵심은 각 역할에 최소 권한을 부여하는 것이다. 탐색자는 읽기만, 추출자는 읽기+쓰기(output/만), 검증자는 읽기만. 이 권한 경계가 plugin.toml의 [permissions]와 일관되어야 한다.

Step 6. 훅으로 안전장치 걸기 — 6회의 원칙을 적용한다

hooks/safety-check.sh:

#!/bin/bash
# meeting-analyzer 플러그인 안전 훅
# PreToolUse 시점에 실행된다

TOOL_NAME="$1"
TOOL_INPUT="$2"

# 파일 쓰기가 output/ 바깥으로 나가는 것을 차단
if [ "$TOOL_NAME" = "write_file" ] || [ "$TOOL_NAME" = "create_file" ]; then
    # output/ 디렉토리 바깥 경로 차단
    if echo "$TOOL_INPUT" | grep -qv '"path":\s*"output/'; then
        echo "BLOCKED: 이 플러그인은 output/ 디렉토리에만 파일을 쓸 수 있습니다"
        exit 1
    fi
fi

# 네트워크 관련 도구 차단
if [ "$TOOL_NAME" = "http_request" ] || [ "$TOOL_NAME" = "fetch_url" ]; then
    echo "BLOCKED: 이 플러그인은 네트워크 접근이 허용되지 않습니다"
    exit 1
fi

# 프로세스 실행 차단
if [ "$TOOL_NAME" = "bash" ] || [ "$TOOL_NAME" = "execute" ]; then
    echo "BLOCKED: 이 플러그인은 임의 프로세스 실행이 허용되지 않습니다"
    exit 1
fi

exit 0

이 훅은 플러그인이 선언한 [permissions]을 런타임에서 한 번 더 강제한다. 벨트와 멜빵의 원리다. plugin.toml의 권한 선언이 1차 방어선이고, 훅이 2차 방어선이다. 6회에서 “훅은 에이전트가 우회할 수 없는 유일한 통제점”이라고 했다. 플러그인에 훅을 번들하면 이 통제가 플러그인과 함께 배포된다.

Step 7. 패키징과 로컬 테스트

모든 파일이 준비됐다. 패키징한다.

# 플러그인 유효성 검사
claude plugin validate .

# 출력 예:
# ✓ plugin.toml 유효
# ✓ skills/ — 2개 Skill 발견 (extract-actions, classify-owners)
# ✓ mcp/ — 1개 MCP 서버 발견 (markdown-reader)
# ✓ hooks/ — 1개 훅 발견 (safety-check.sh)
# ✓ agents/ — 1개 에이전트 구성 발견 (orchestrator.md)
# ✓ permissions 일관성 검사 통과
# ✓ 패키징 준비 완료

# .zip 패키징
claude plugin pack .

# 출력:
# 📦 meeting-analyzer-1.0.0.zip 생성 (12.4 KB)
# 포함: 2 skills, 1 mcp server, 1 hook, 1 agent config

# 로컬 설치 테스트 (다른 프로젝트 디렉토리에서)
cd ~/projects/test-workspace
claude plugin install ../meeting-analyzer/meeting-analyzer-1.0.0.zip

# 출력:
# 📥 [email protected] 설치 중...
# ⚠️  이 플러그인이 요구하는 권한:
#   - 파일 읽기: *.md, *.txt, *.pdf
#   - 파일 쓰기: output/*.md, output/*.json
#   - 네트워크: 없음
#   - 프로세스 실행: 없음
# 계속하시겠습니까? (y/N): y
# ✓ Skills 등록: meeting-analyzer/extract-actions, meeting-analyzer/classify-owners
# ✓ MCP 서버 등록: markdown-reader
# ✓ 훅 등록: safety-check.sh (PreToolUse)
# ✓ 에이전트 구성 등록: orchestrator.md
# ✅ [email protected] 설치 완료

설치 후 테스트한다. 샘플 회의록을 만들고 플러그인을 호출해 본다.

# 테스트용 회의록 생성
cat > sample-meeting.md << 'EOF'
# 주간 스프린트 리뷰 — 2026-08-10

## 참석자
박 매니저, 이 개발자, 김 디자이너

## 논의 사항
1. 검색 API 응답 속도가 3초 이상으로 느려졌다. 이 개발자가 이번 주 금요일까지 캐시 레이어를 추가하기로 했다. (긴급)
2. 신규 대시보드 디자인 시안이 아직 없다. 김 디자이너가 수요일까지 와이어프레임을 공유하기로 했다.
3. 다음 달 출시 일정은 박 매니저가 내부 조율 후 확정 예정. 급하지 않다.
4. TODO: 테스트 커버리지 80% 달성 목표 — 담당자 미정
EOF

# Claude에게 플러그인 사용 요청
claude -p "sample-meeting.md 파일의 회의록을 분석해서 액션아이템을 정리해줘"

Claude는 설치된 meeting-analyzer 플러그인의 Skill description을 보고 자동으로 이 플러그인을 호출한다. 서브에이전트 오케스트레이션에 따라 탐색→추출→검증 3단계를 거친 뒤, output/ 디렉토리에 결과 파일이 생성된다.

# 결과 확인
ls output/
# 이_개발자_followup.md
# 김_디자이너_followup.md
# 박_매니저_followup.md
# unassigned_followup.md
# summary.json

cat output/summary.json
# {
#   "total_items": 4,
#   "assigned": 3,
#   "unassigned": 1,
#   "high_priority": 1,
#   "due_this_week": 2,
#   "verification": {
#     "mismatches": 0,
#     "status": "passed"
#   }
# }

이것이 9~11회에 걸쳐 만든 결과물이 하나의 명령으로 설치되고, 하나의 문장으로 실행되는 모습이다. 파일 5개를 메신저로 보내던 때와 비교해 보라.

Claude 플러그인 마켓플레이스 배포 흐름

마켓플레이스와 팀 배포 — 남의 것을 쓰고, 내 것을 올리는 법

.zip 파일을 직접 주고받는 것도 가능하지만, 규모가 커지면 중앙 저장소가 필요하다. npm에 npm Registry가 있고 Python에 PyPI가 있듯, Claude 생태계에는 Claude Plugin Marketplace가 있다.

남의 플러그인을 설치하는 법

마켓플레이스에서 플러그인을 검색하고 설치하는 과정은 npm install만큼 간단하다.

# 마켓플레이스에서 플러그인 검색
claude plugin search "code review"

# 출력:
# 1. [email protected]     — PR 코드 리뷰 자동화 (⭐ 4.7, 다운로드 12.3K)
#    권한: file_read[*], network[github.com]
# 2. [email protected]           — 린트 오류 자동 수정 (⭐ 4.2, 다운로드 8.1K)
#    권한: file_read[*], file_write[*.py,*.js,*.ts]
# 3. [email protected]       — 테스트 코드 자동 생성 (⭐ 3.8, 다운로드 3.2K)
#    권한: file_read[*], file_write[tests/*]

검색 결과에 권한 요약이 함께 표시된다는 점에 주목하라. 설치 전에 이 플러그인이 어디까지 접근하는지 한눈에 볼 수 있다. network[github.com]이 보이면 이 플러그인이 GitHub에 네트워크 요청을 보낸다는 뜻이다.

# 설치
claude plugin install code-review-pro

# 출력:
# 📥 [email protected] 설치 중...
# ⚠️  이 플러그인이 요구하는 권한:
#   - 파일 읽기: 모든 파일 (*)
#   - 네트워크: github.com
#   - 파일 쓰기: 없음
#   - 프로세스 실행: 없음
# 계속하시겠습니까? (y/N): y
# ✅ [email protected] 설치 완료

# 설치된 플러그인 목록 확인
claude plugin list

# 출력:
# 📦 설치된 플러그인:
#   [email protected]   (로컬)
#   [email protected]    (marketplace)

버전 고정(pinning)도 지원된다. 팀에서 특정 버전을 표준으로 쓰고 싶을 때 중요하다.

# 특정 버전 설치
claude plugin install [email protected]

# 버전 범위 지정 (semver)
claude plugin install code-review-pro@^2.0.0   # 2.x.x 최신
claude plugin install code-review-pro@~2.1.0   # 2.1.x 최신

내 플러그인을 마켓플레이스에 올리는 법

직접 만든 플러그인을 마켓플레이스에 등록하는 과정이다. Anthropic 공식 문서에 최신 가이드라인이 있으니 등록 전에 반드시 확인하라.

# 마켓플레이스 계정 연결 (최초 1회)
claude plugin login

# 게시 전 검증 (마켓플레이스 기준)
claude plugin validate --marketplace .

# 출력:
# ✓ plugin.toml 필수 필드 충족
# ✓ README.md 존재 (마켓플레이스 상세 페이지에 표시됨)
# ✓ examples/ 디렉토리 존재 (사용 예시 제공)
# ✓ 라이선스 명시 (MIT)
# ✓ 보안 검사 통과
#   - 번들 MCP 서버 코드에 하드코딩된 시크릿 없음
#   - 훅 스크립트에 위험 명령 없음
# ✓ 게시 준비 완료

# 마켓플레이스에 게시
claude plugin publish .

# 출력:
# 🚀 [email protected] 게시 중...
# ✅ 게시 완료!
# 🔗 https://marketplace.anthropic.com/plugins/meeting-analyzer
# ⏳ 리뷰 대기 중 — 보통 24시간 내 승인됩니다

게시 후에는 마켓플레이스 대시보드에서 다운로드 수, 평점, 버전별 사용 현황을 볼 수 있다. 유료 플러그인의 경우 수익 정산도 여기서 확인한다.

팀 배포 — 프라이빗 레지스트리

마켓플레이스는 퍼블릭이다. 조직 내부에서만 사용하는 플러그인은 프라이빗 레지스트리를 쓴다. 감사 이력이 남아야 하는 조직, 규제가 강한 환경에서 특히 필요하다.

# 프라이빗 레지스트리 설정 (.claude/settings.json)
{
  "plugin_registries": [
    {
      "name": "internal",
      "url": "https://plugins.internal.example.com",
      "auth": "bearer"
    }
  ]
}

# 프라이빗 레지스트리에 게시
claude plugin publish --registry internal .

# 팀원이 설치
claude plugin install meeting-analyzer --registry internal

프라이빗 레지스트리는 직접 운영하거나, 클라우드 호스팅 서비스를 쓸 수 있다. npm의 GitHub Packages나 Azure Artifacts와 개념이 같다. 핵심은 팀 전체가 같은 플러그인의 같은 버전을 쓰도록 표준화하는 것이다.

팀 표준 플러그인 세트를 하나의 파일로 관리하는 방법:

# .claude/plugin-manifest.json — 프로젝트에 체크인
{
  "plugins": {
    "meeting-analyzer": "1.0.0",
    "code-review-pro": "^2.0.0",
    "internal-deploy-helper": {
      "version": "3.2.1",
      "registry": "internal"
    }
  }
}

# 팀원이 프로젝트를 클론한 뒤 한 번에 설치
claude plugin install --from-manifest

이 매니페스트를 Git에 체크인하면, 새 팀원이 프로젝트를 받았을 때 npm install처럼 한 번에 모든 플러그인이 설치된다. 5회에서 CLAUDE.md가 "저장소의 헌법"이라고 했다면, plugin-manifest.json은 "저장소의 장비 목록"이다.

서드파티 플러그인 신뢰 경계 개념도

함정: 서드파티 Claude 플러그인 설치는 코드 실행 권한을 위임하는 행위다

여기서부터가 이 회차에서 가장 중요한 내용이다.

플러그인을 설치한다는 것은 무엇인가. Skill이 등록되고, MCP 서버가 실행되고, 훅이 걸린다. 이 모든 것이 당신의 작업 환경에서 코드로 실행된다는 뜻이다. npm 패키지를 설치하면 postinstall 스크립트가 실행되는 것과 같은 위험 모델이다.

npm left-pad가 Claude 생태계에서 반복될 수 있다

2016년 npm의 left-pad 사건을 기억하는가. 11줄짜리 패키지가 삭제되면서 전 세계 JavaScript 빌드가 깨졌다. MCP 생태계가 커지면서 비슷한 구조적 취약점이 Claude 플러그인에도 존재한다.

시나리오를 그려 보자.

  • 시나리오 1 — 악성 업데이트: 인기 있는 플러그인의 메인테이너 계정이 탈취된다. 새 버전에 network = true와 file_read = ["*"]를 추가하고, 훅 스크립트에 파일 내용을 외부로 전송하는 코드를 심는다. 자동 업데이트를 켜놓은 사용자의 코드가 유출된다.
  • 시나리오 2 — 타이포스쿼팅: code-review-pro 대신 code-review-pr0(영문 O가 숫자 0)를 등록한다. 설치 시 오타를 내는 사용자의 환경에 악성 Skill이 심어진다.
  • 시나리오 3 — 의존성 체인: 플러그인 A가 MCP 서버 B에 의존하고, B가 Python 패키지 C에 의존한다. C에 취약점이 발견되면 A를 설치한 모든 사용자가 영향받는다.

10회에서 "MCP 서버는 신뢰 경계다 — 검증되지 않은 서버는 공급망 위험"이라고 했다. 플러그인은 MCP 서버에 Skill, 훅, 에이전트 구성까지 묶은 것이니 공격 표면이 더 넓다.

설치 전 체크리스트 5항목

서드파티 플러그인을 설치하기 전에 다음 5가지를 확인한다.

  1. 권한 확인: [permissions]에 network = true, subprocess = true, file_read = ["*"]가 있으면 왜 필요한지 README에서 근거를 확인한다. 근거가 없으면 설치하지 않는다.
  2. 소스 코드 확인: 번들된 MCP 서버와 훅 스크립트의 소스 코드를 직접 읽는다. .zip을 풀어서 확인할 수 있다. 
    # .zip 내용 확인
claude plugin inspect [email protected]

# 또는 직접 풀어서 확인
unzip code-review-pro-2.1.0.zip -d /tmp/inspect
cat /tmp/inspect/hooks/*.sh
cat /tmp/inspect/mcp/*/server.py
  3. 다운로드 수와 평점: 마켓플레이스의 사회적 증명을 참고한다. 다운로드 수가 적은 플러그인은 검증 인력이 부족하다는 뜻이다.
  4. 버전 고정: 자동 업데이트를 끄고, 검증된 버전을 명시적으로 고정한다. 
    # 나쁜 예 — 항상 최신 설치
claude plugin install code-review-pro

# 좋은 예 — 검증된 버전 고정
claude plugin install [email protected]
  5. 격리 테스트: 처음 쓰는 플러그인은 빈 프로젝트에서 먼저 테스트한다. 프로덕션 코드가 있는 디렉토리에서 바로 설치하지 않는다.

이 체크리스트가 과하다고 느껴지는가? npm install을 아무 생각 없이 누르는 습관이 2016년 이후 얼마나 많은 공급망 공격을 가능하게 했는지 생각해 보라. Claude 플러그인은 당신의 AI 에이전트가 무엇을 할 수 있는지를 결정한다. npm 패키지보다 더 신중해야 할 이유가 있다.

나만의 첫 플러그인, 그 다음은

이번 회차를 정리한다. Claude 플러그인은 Skills(9회) + MCP(10회) + 서브에이전트(11회) + 훅(6회)을 하나의 배포 단위로 묶은 것이다. plugin.toml이 매니페스트, claude plugin pack이 빌드, 마켓플레이스가 배포 채널이다.

핵심을 세 문장으로 압축하면:

  1. 부품은 조립해야 제품이 된다. Skill 하나, MCP 서버 하나로는 남에게 줄 수 없다. 플러그인으로 묶어야 배포 가능하고, 배포 가능해야 판매 가능하다.
  2. 권한 선언이 신뢰의 기초다. [permissions]에 이 플러그인이 무엇을 할 수 있는지 명시하고, 훅으로 런타임에 강제한다.
  3. 설치는 위임이다. 서드파티 플러그인을 설치하는 것은 코드 실행 권한을 위임하는 행위다. 검증 없이 위임하지 않는다.

AI가 코드를 짜주는 시대가 아니라, AI에게 일을 위임하는 시대다. 그런데 위임 방식 자체를 패키징해서 배포할 수 있다면? 위임할 줄 아는 사람이 하나의 회사가 된다는 말이 이 회차에서 비로소 구체적인 형태를 갖는다.

PART 3(확장 — 나만의 도구)이 여기서 끝난다. 9회부터 12회까지 만든 것들 — Skill, MCP 서버, 서브에이전트 구성, 그리고 이 모든 것을 묶은 플러그인 — 은 PART 6(하나의 회사 만들기)에서 실제 수익화 재료로 다시 등장한다. 그때까지 기억해 두라.

이번 회차의 수익화 지점

플러그인은 그 자체로 판매 단위다. 지금까지 만든 회의록 분석 플러그인을 예로 들면:

  • 무료 버전: 액션아이템 추출 Skill만 포함. 마켓플레이스에 공개해 다운로드를 모은다.
  • 유료 버전: 담당자 분류 + 서브에이전트 오케스트레이션 + 검증 단계까지 포함. 월 정액 또는 일회성 구매.
  • 팀 라이선스: 프라이빗 레지스트리 설정 + 온보딩 가이드 + 커스터마이징 컨설팅을 묶어 조직 단위로 판매.

이 구조에서 핵심 비용은 유지보수다. Claude CLI 버전이 올라가면 플러그인도 맞춰야 하고, 사용자 피드백에 응답해야 한다. 판매 수익이 유지보수 비용을 넘는 구간을 미리 계산해 두는 것이 23회에서 다룰 주제다.

도메인 특화 플러그인일수록 경쟁이 적다. "회의록 분석"은 범용이라 경쟁이 세겠지만, "규제가 강한 환경에서의 감사 이력 생성", "여행 예약 시스템의 환불 처리 자동화" 같은 틈새를 잡으면 소수의 고가 구매자를 확보할 수 있다. 특정 업종·업무를 20년 알고 있는 사람만이 만들 수 있는 플러그인 — 그것이 경쟁 우위다.

플러그인 패키징 체크리스트를 정리해 뒀다. plugin.toml 스타터 템플릿, 디렉토리 구조 뼈대, 보안 훅 예시, 마켓플레이스 게시 전 점검 목록까지 한 장짜리 문서로 묶었다. 시리즈 뉴스레터를 구독하면 PDF로 받아볼 수 있다. 9~12회의 결과물을 실제로 패키징할 때 옆에 두고 체크하는 용도다.

다음 회 예고: 13회부터 PART 4(Cowork — 코드 밖 업무 자동화)가 시작된다. 코드를 한 줄도 안 짜는 업무 — 보고서, 엑셀, PPT — 를 AI에게 위임하는 법을 다룬다. 개발자가 아닌 독자가 다시 합류하는 구간이다. 잡다한 CSV 5개를 서식·수식 포함 분석 리포트 1개로 바꾸는 실습부터 시작한다.

관련 회차: 9회(Skills 기초) · 10회(MCP 서버) · 11회(서브에이전트) · 6회(훅과 권한)

Photo by TBD Traveller on Pexels

📚 시리즈: Claude 활용 24회 — AI에게 일을 위임하는 법 (총 24화 중 12화)
◀ 이전 11화  (다음 차수는 아직 게시되지 않았습니다)

자주 묻는 질문

Claude 플러그인은 무엇이고 왜 필요한가요?

Claude 플러그인은 Skill, MCP 서버 설정, 훅, 에이전트 구성을 하나의 디렉토리나 .zip으로 묶은 배포 단위입니다. 이 부품들을 따로 보내면 경로 의존성, 서버 코드 누락, 훅 미설정, 의존성 목록 부재 등의 문제로 다른 사람이 쓸 수 없기 때문에, plugin.toml 매니페스트로 모든 정보를 선언하여 공유와 판매가 가능한 단위로 포장하는 것입니다.

plugin.toml 파일에는 어떤 정보를 적어야 하나요?

plugin.toml은 플러그인의 이름, 버전, 설명, 작성자, 라이선스, 최소 Claude 버전 같은 메타데이터와 함께 키워드, 권한 요구사항(파일 읽기·쓰기 범위 등), 의존성 정보를 한 곳에 선언합니다. npm의 package.json, Python의 pyproject.toml, Docker의 Dockerfile을 합친 역할이라고 보면 됩니다.

서드파티 Claude 플러그인을 설치할 때 주의할 점은 무엇인가요?

서드파티 플러그인 설치는 코드 실행 권한을 넘기는 행위이므로, 신뢰 검증 없이 install을 누르면 안 됩니다. 플러그인이 요구하는 권한 목록(파일 읽기·쓰기 범위 등)을 plugin.toml에서 반드시 확인하고, 출처와 신뢰성을 검증한 뒤 설치해야 합니다.


Tags:

작성자

AICosmus

Follow Me
다른 기사
댓글 1개

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다