[Claude Code] Plugin과 Marketplace 개념 잡기

들어가며

최근에 동료가 만든 “PR 리뷰를 자동으로 해주는 도구”를 Claude Code에서 써보게 됐다. 그런데 그걸 설치하는 방법이 딱 두 줄이었다.

/plugin marketplace add <owner>/<repo>
/plugin install pr-review@pr-review

이 두 줄을 처음 봤을 때 두 가지가 궁금했다. plugin은 뭐고 marketplace는 뭘까? 그리고 왜 pr-review@pr-review처럼 이름이 두 번 반복될까? 이 글은 그 궁금증을 개념 수준에서 정리한 기록이다.

스마트폰으로 비유하면 딱 맞는다

가장 이해하기 쉬운 비유는 스마트폰이다.

스마트폰 세계	Claude Code 세계
앱(App)	플러그인(Plugin)
앱 스토어(App Store)	마켓플레이스(Marketplace)
“이 앱 설치했어”	“이 플러그인 설치했어”
“앱 스토어에서 받았어”	“이 마켓플레이스에서 받았어”

즉 플러그인 = 기능 묶음(앱), 마켓플레이스 = 그 플러그인들을 모아 배포하는 창구(스토어)다. 이 한 줄만 기억해도 절반은 끝난 셈이다.

플러그인(Plugin): 기능을 담은 하나의 꾸러미

Claude Code는 기본만으로도 코드를 읽고 고치고 명령어를 실행한다. 하지만 사람마다, 팀마다 반복하는 고유한 작업들이 있다. “PR 리뷰하기”, “이슈 티켓 만들기”, “배포 상태 확인하기” 같은 것들이다.

이런 맞춤 기능을 한 폴더에 담아 배포 가능한 형태로 묶은 것이 플러그인이다. 플러그인 하나 안에는 여러 종류의 기능이 함께 들어갈 수 있다.

• 스킬(Skill) — “이런 작업은 이런 순서로 해라”라는 작업 매뉴얼
• 커맨드(Command) — /무언가 형태로 부르는 슬래시 명령
• 에이전트(Agent) — 특정 역할에 특화된 하위 AI
• 훅(Hook) — 특정 시점에 자동으로 실행되는 동작
• MCP 서버 — 외부 도구(이슈 트래커, 메신저 등)를 연결하는 설정

실제로 앞서 말한 플러그인을 설치했더니 한 번에 여러 기능이 딸려 왔다.

Reloaded: 1 plugin · 8 skills · 9 agents · 4 hooks

플러그인 하나가 이렇게 여러 기능의 묶음이라는 걸 잘 보여준다.

어떤 폴더가 플러그인이 되려면 안에 신분증 파일 하나가 있어야 한다. .claude-plugin/plugin.json이다.

{
  "name": "pr-review",
  "version": "0.1.0",
  "description": "PR 리뷰 자동화 스킬 모음",
  "author": { "name": "me" }
}

이름, 버전, 설명 — 딱 앱 정보 같다.

마켓플레이스(Marketplace): 플러그인들의 카탈로그

그럼 마켓플레이스는? “이 저장소에는 이런 플러그인들이 있습니다”라고 알려주는 카탈로그다. 보통 git 저장소 하나가 마켓플레이스 하나 역할을 한다.

마켓플레이스에도 신분증 파일이 있다. .claude-plugin/marketplace.json이다.

{
  "name": "pr-review",
  "owner": { "name": "me" },
  "plugins": [
    { "name": "pr-review", "source": "./" }
  ]
}

plugins 목록이 핵심이다. “이 카탈로그에 담긴 플러그인은 이것들이고, 각각 어디에 있다”를 적어둔다. source: "./"는 “플러그인이 이 저장소 루트 그 자체”라는 뜻이다. 하나의 마켓플레이스에 플러그인을 여러 개 담고 싶다면 목록에 항목을 더 넣고 "source": "./plugins/foo"처럼 경로를 나눠주면 된다.

왜 개념이 둘로 나뉘어 있을까? 앱 스토어에 앱이 100개 올라와 있어도 나는 그중 필요한 앱만 골라 설치한다. 마찬가지로 마켓플레이스는 “무엇이 있는지”를 보여주는 목록이고, 플러그인은 “실제로 설치되는 물건”이다. 그래서 등록과 설치가 두 단계로 나뉜다.

pr-review@pr-review의 정체

이제 처음의 궁금증이 풀린다. 설치 명령을 다시 보자.

/plugin install pr-review@pr-review

@ 앞뒤로 이름이 나뉜다.

   pr-review    @    pr-review
   ─────────         ─────────
   플러그인 이름       마켓플레이스 이름
   (설치할 물건)       (어느 카탈로그에서)

즉 “pr-review 마켓플레이스에 있는 pr-review 플러그인을 설치해줘”라는 뜻이다. 이 예시는 마켓플레이스와 플러그인 이름이 우연히 같아서 헷갈리지만, pr-tools@my-marketplace처럼 둘이 다른 게 오히려 일반적이다.

설치는 세 단계다

① /plugin marketplace add <owner>/<repo>
② /plugin install pr-review@pr-review
③ /reload-plugins

• ① 마켓플레이스 등록 — “이 카탈로그를 내 목록에 추가해줘.” 인자로는 GitHub의 소유자/저장소, 전체 URL, 또는 내 컴퓨터의 로컬 폴더 경로도 된다.
• ② 플러그인 설치 — 등록된 카탈로그에서 원하는 플러그인을 고른다.
• ③ 적용 — 방금 설치한 기능을 현재 세션에 반영한다.

설치가 끝나면 플러그인 안의 기능들이 플러그인이름:기능이름 형태로 나타난다. 예를 들어 리뷰 스킬은 /pr-review:review-pr로 불린다. 이 네임스페이스(pr-review:) 덕분에, 다른 플러그인에 이름이 같은 스킬이 있어도 서로 충돌하지 않는다.

그래서, 플러그인은 어떻게 만들까

개념을 알았으니 만드는 흐름도 간단히 정리해두자.

1. 폴더를 만들고, 그 안에 .claude-plugin/plugin.json(플러그인 신분증)을 작성한다.
2. skills/, commands/, agents/ 같은 폴더에 실제 기능을 넣는다.
3. 남들과 공유하려면 .claude-plugin/marketplace.json(카탈로그)을 추가한다.
4. git 저장소로 올린다. 끝.

전체 폴더 구조는 대략 이런 모습이다.

pr-review/                       # git 저장소 = 마켓플레이스
├── .claude-plugin/
│   ├── marketplace.json         # 카탈로그: 이 저장소에 어떤 플러그인이 있나
│   └── plugin.json              # 플러그인 신분증: 이름/버전/설명
├── skills/                      # 실제 기능들
│   ├── review-pr/SKILL.md
│   └── draft-pr-review/SKILL.md
└── README.md

만드는 도중에 테스트하고 싶다면 굳이 원격에 push할 필요도 없다. /plugin marketplace add /내/로컬/폴더경로처럼 로컬 경로를 등록하면 바로 시험해볼 수 있다.

한 가지 더 짚어둘 만한 설계 포인트가 있다. 잘 만든 플러그인은 특정 사람의 디렉토리 구조나 로컬 도구에 의존하지 않도록, 경로나 외부 도구를 환경 변수로 갈아끼울 수 있게 빼둔다. 이렇게 해두면 “내 컴퓨터에서만 동작하는 스킬”이 아니라 “누구 환경에서나 설치해 쓰는 플러그인”이 된다. 공유용 플러그인의 핵심은 바로 이 이식성에 있다.

정리

• 플러그인 = 스킬·커맨드·에이전트·훅을 담은 기능 꾸러미 (스마트폰의 앱)
• 마켓플레이스 = 플러그인들을 모아 배포하는 카탈로그 (스마트폰의 앱 스토어)
• 설치 = 마켓플레이스 등록 → 플러그인 설치 → 적용, 세 단계
• 플러그인@마켓플레이스 = “어느 카탈로그의 어떤 플러그인”을 가리키는 주소

한 사람의 노하우가 문서가 되고, 그 문서가 플러그인이 되어, 이제는 팀 누구나 두 줄로 설치해 쓴다. 개념 하나 익혔을 뿐인데, 지식이 도구로 흐르는 과정이 꽤 근사하게 느껴진다.