이 글은 교차 게시물입니다 — 원문(및 모든 업데이트)은 broke2builtai.com에서 확인할 수 있습니다.

저의 Claude Code 설정은 구축하는 데 몇 달이 걸렸습니다. 여기에는 리뷰 명령어가 있고, 저기에는 포맷팅 훅 (formatting hook)이 있으며, 데이터베이스를 위한 MCP 서버와 QA를 위한 서브에이전트 (subagent)가 포함되어 있었습니다. 그러다 두 번째 프로젝트를 시작했는데, 이 설정들이 저와 함께 따라오지 않는다는 것을 발견했습니다. 설정들이 첫 번째 리포지토리의 네 가지 설정 영역에 흩어져 있었고, "내 도구 설치하기"라는 말은 제 자신의 dotfiles를 20분 동안 고고학적 발굴하듯 뒤져야 한다는 의미였습니다. 플러그인 (Plugins)은 바로 그 문제에 대한 Claude Code의 해답입니다. 단 하나의 명령어로 설치할 수 있도록 이 모든 것을 하나로 묶어주는 하나의 디렉토리입니다.

플러그인이란 실제로 무엇인가

플러그인은 매니페스트 (manifest)가 포함된 폴더입니다. 그 내부에는 이미 수동으로 연결할 수 있는 것과 동일한 기본 요소들이 함께 이동할 수 있도록 패키징되어 있습니다:

• 기술 (Skills) 및 명령어 (commands) — /name 호출 뒤에 숨겨진 프롬프트 템플릿 (prompt templates)으로, 커스텀 슬래시 명령어 (custom slash command)와 동일한 형식입니다.
• 에이전트 (Agents) — /agents에 나타나는 서브에이전트 (subagent) 정의입니다.
• 훅 (Hooks) — 라이프사이클 이벤트 핸들러 (lifecycle event handlers)로, 설정에 있는 Claude Code hooks와 동일한 스키마를 가지며 단지 hooks/hooks.json에 거주할 뿐입니다.
• MCP 서버 (MCP servers) — 번들링된 .mcp.json을 포함하여, 플러그인을 설치하면 누군가 claude mcp add를 실행할 필요 없이 도구들이 연결됩니다.

플러그인은 또한 코드 인텔리전스 (code intelligence)를 위한 LSP 서버, 백그라운드 모니터, 실행 파일 등을 포함할 수도 있지만, 위에서 언급한 네 가지가 실제로 가장 먼저 패키징하게 될 요소들입니다.

수동으로 연결된 구성 요소와의 유일한 동작 차이점은 **네임스페이싱 (namespacing)**입니다. my-plugin이라는 이름의 플러그인에 있는 hello라는 이름의 기술은 /hello가 아니라 /my-plugin:hello로 호출됩니다. 이는 의도된 설계입니다. 두 개의 플러그인이 충돌 없이 모두 deploy 기술을 제공할 수 있기 때문입니다. 사용자 본인의 독립적인 .claude/ 파일들은 짧은 이름을 그대로 유지합니다.

마켓플레이스에서 2분 만에 설치하기

마켓플레이스 (marketplace)란 플러그인 목록과 이를 가져올 곳을 나열한 카탈로그, 즉 저장소 (repo) 또는 URL을 의미합니다. 마켓플레이스를 사용하는 과정은 두 단계로 이루어집니다. 먼저 카탈로그를 추가한 다음, 그 안에서 개별 플러그인을 설치하는 것입니다. 앱 스토어(app store)를 생각하면 쉽습니다. 스토어를 추가한다고 해서 아무것도 설치되지는 않습니다.

Anthropic의 공식 마켓플레이스 (claude-plugins-official)는 자동으로 등록됩니다. 세션 내에서 /plugin을 실행하면 탭 형식의 관리자가 나타납니다. Tab 키로 Discover (탐색), Installed (설치됨), Marketplaces (마켓플레이스), Errors (오류) 탭을 전환할 수 있습니다. Discover를 탐색하다가 플러그인에서 Enter를 누르면, 상세 창에 해당 플러그인의 내용, 토큰 (tokens) 단위의 컨텍스트 비용 (context cost), 그리고 설치를 확정하기 전의 "설치될 항목 (Will install)" 목록이 표시됩니다.

또는 탐색 과정을 건너뛰고 직접 설치할 수도 있습니다:

/plugin install github@claude-plugins-official

제3자 (third-party) 카탈로그의 경우, 먼저 마켓플레이스를 추가해야 합니다. 검토된 제3자 제출물이 등록되며 각 항목이 특정 커밋 (commit)에 고정되는 커뮤니티 마켓플레이스 (community marketplace)가 자연스러운 다음 단계입니다:

/plugin marketplace add anthropics/claude-plugins-community
/plugin install some-plugin@claude-community

/plugin marketplace add 명령어는 GitHub의 owner/repo 약어, 전체 git URL (https:// 및 .git 포함), 로컬 디렉토리, 또는 호스팅된 marketplace.json의 직접 URL을 허용합니다.

설치 시 **범위 (scope)**를 묻는 프롬프트가 나타납니다:

• user — 모든 프로젝트에 걸쳐 사용자 본인에게 적용 (기본값)
• project — .claude/settings.json에 기록되어, 해당 저장소를 클론 (clone)하는 모든 사람이 이를 갖게 됨
• local — 현재 저장소에만 적용되며, gitignored 처리됨

그 다음, 재시작 없이 활성화합니다:

/reload-plugins

이것이 전체 루프입니다. 이제 플러그인의 기능이 해당 네임스페이스 (namespace) 아래에 나타납니다. 예를 들어 Anthropic의 데모 마켓플레이스에서 commit-commands를 설치하면 /commit-commands:commit 명령어를 사용할 수 있습니다.

설치된 항목 관리하기

일상적으로 사용하는 명령어들:

/plugin list                                # 설치된 항목을 범위별로 그룹화하여 표시
/plugin disable plugin-name@marketplace-name  # 삭제하지 않고 비활성화
/plugin enable plugin-name@marketplace-name
...

또한 모든 기능은 스크립트 및 CI를 위해 셸 명령(claude plugin install formatter@my-marketplace --scope project)으로도 존재합니다. 플러그인을 쌓아두기 전에 알아두어야 할 두 가지 사항이 있습니다. 마켓플레이스 (marketplace)를 제거하면 해당 마켓플레이스에서 받은 모든 플러그인이 삭제되며, 활성화된 모든 플러그인은 모든 세션에 토큰을 추가합니다. claude plugin details <name> 명령어를 통해 예상 비용을 확인할 수 있으며, 이는 항상 켜져 있는 비용(always-on)과 호출 시 발생하는 비용(on-invoke)으로 나뉩니다. 가끔씩 감사(Audit)를 수행하세요. 'Installed' 탭은 몇 주 동안 사용하지 않은 플러그인을 문자 그대로 표시해 줍니다.

플러그인이 각 요소를 직접 연결(hand-wiring)하는 것보다 나은 경우

솔직한 답변은 다음과 같습니다: 항상 그런 것은 아닙니다. 결정 기준은 기능(capability)이 아니라 배포(distribution)에 있습니다. 플러그인이 독립적인 구성 요소들이 할 수 없는 일을 할 수는 없습니다.

직접 연결(Hand-wire)해야 하는 경우: 단일 프로젝트이고, 혼자 작업하며, 여전히 반복적인 수정(iterating) 단계에 있을 때입니다. .claude/ 폴더 내의 파일들은 편집이 더 빠르고, 매니페스트 (manifest)가 필요 없으며, 짧은 이름을 유지할 수 있습니다. 제 설정에 있는 모든 플러그인도 처음에는 제가 계속 만지작거리던 느슨한 기술(skill)이나 훅 (hook)으로 시작되었습니다.

플러그인을 패키징(Package)해야 하는 경우:

• 다른 사람에게 당신의 설정을 공유해야 할 때. 대안은 "이 네 개의 파일을 만들고, 이 JSON을 붙여넣고, 이 세 개의 명령어를 실행하세요"라고 적힌 README 파일뿐입니다. 플러그인은 이를 단 한 번의 설치로 바꿔주며, MCP 서버, 훅, 에이전트 (agents)가 서로 미리 연결된 상태로 제공됩니다.
• 여러 저장소(repo)에서 필요할 때. 사용자 범위(User-scope) 설치를 한 번 수행하는 것이 .claude/ 폴더를 여기저기 복사하며 설정이 어긋나는 것을 지켜보는 것보다 훨씬 낫습니다.
• 버전 관리되는 업데이트를 원할 때. version 필드를 올리면 사용자들이 업데이트를 받게 되지만, 폴더를 복사해서 사용하는 사용자들은 영원히 업데이트를 받을 수 없습니다.
• 구성 요소들이 함께 있을 때만 의미가 있을 때. 배포 훅 (deploy hook)에 의해 보호되는 배포 MCP 서버를 호출하는 배포 기술 (deploy skill)은 세 개의 설정이 아니라 하나의 제품입니다. 이들을 별도로 배포하면 설치가 불완전하게 이루어지는 상황을 초래합니다.

판단 기준은 '두 번째 사용자'의 존재 여부입니다. 팀 동료, 본인의 다른 컴퓨터, 혹은 미래의 자신과 같이 두 번째 사용자가 생기는 순간, 패키징의 가치는 충분히 증명됩니다.

직접 만들기: 구조 (the anatomy)

최소한의 플러그인은 두 개의 파일로 구성됩니다. 매니페스트 (manifest)는 .claude-plugin/plugin.json에 위치합니다:

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
...

name은 유일한 필수 필드이며, 네임스페이스 (namespace) 접두사가 됩니다. version은 선택 사항이지만 매우 중요한 역할을 합니다. 버전을 설정하면 버전을 올렸을 때만 사용자가 업데이트를 받게 되지만, 생략하면 git 커밋 SHA가 버전이 되어 모든 푸시(push)가 업데이트로 배포됩니다. 안정적인 릴리스를 위해서는 버전을 설정하고, 반복적인 개발 단계에서는 생략하세요.

구성 요소들은 .claude-plugin/ 내부가 아니라 플러그인의 **루트 (root)**에 위치해야 합니다. 이는 Anthropic의 공식 문서에서도 언급된 가장 흔한 구조적 실수입니다. 오직 plugin.json만이 그 안에 들어갑니다:

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # 오직 매니페스트 (manifest)만 여기에 위치함
...

skills/는 새로운 플러그인을 위한 권장 레이아웃입니다 (각 스킬은 SKILL.md를 포함하는 폴더 형태). commands/는 이전 방식의 평면적인 마크다운 (Markdown) 파일들을 담습니다. 만약 프로젝트의 .claude/ 디렉토리에 이미 작동 중인 구성 요소가 있다면, 마이그레이션 (migration)은 대부분 cp -r 명령어로 해결됩니다. commands/, agents/, skills/를 복사하고, settings.json에 있던 hooks 객체를 동일한 구조로 hooks/hooks.json으로 옮기기만 하면 됩니다.

디버깅에 소요되는 오후 시간을 아껴줄 한 가지 규칙이 있습니다: 훅 (hook) 커맨드와 MCP 설정 내의 모든 내부 경로에는 반드시 ${CLAUDE_PLUGIN_ROOT}를 사용하세요. 설치된 플러그인은 사용자가 클론 (clone)한 위치가 아니라 ~/.claude/plugins/cache의 캐시로 복사되어 실행됩니다. 따라서 플러그인 디렉토리 외부로 나가는 상대 경로 (../shared-utils)는 설치 후에는 존재하지 않게 됩니다. 이 변수는 플러그인이 실제로 위치한 경로로 항상 해석됩니다.

로컬에서 테스트하고 검증하기

마켓플레이스나 설치 과정 없이, Claude Code가 해당 디렉토리를 가리키도록 설정하세요:

claude --plugin-dir ./my-plugin

스킬을 호출하고 (/my-plugin:hello), /agents에서 에이전트를 확인하며, 훅을 실행해 보세요. 편집하는 동안에는 /reload-plugins를 통해 세션 중간에 변경 사항을 반영할 수 있습니다. 배포하기 전에 전체 구조를 린트 (lint) 하세요:

claude plugin validate ./my-plugin

이 과정은 plugin.json, 스킬(skill) 및 에이전트(agent) 프론트매터(frontmatter), 그리고 hooks/hooks.json의 스키마(schema) 오류를 검사합니다. 이는 Anthropic의 리뷰 파이프라인(review pipeline)이 커뮤니티 제출물에 대해 실행하는 것과 동일한 검사입니다. 또한 claude plugin init my-tool 명령어를 사용할 수 있는데, 이는 ~/.claude/skills/ 아래에 매니페스트(manifest)와 스타터 스킬(starter skill)을 스캐폴딩(scaffold)하며, 다음 세션에서 자동으로 로드됩니다. 이는 아무것도 없는 상태에서 작동 가능한 플러그인 골격(skeleton)을 만드는 가장 빠른 방법입니다.

배포하기: 마켓플레이스는 단 하나의 JSON 파일입니다

공유를 위해서는 카탈로그(catalog)를 게시해야 합니다. 마켓플레이스(marketplace)는 여러분의 플러그인들을 나열하는 .claude-plugin/marketplace.json이 포함된 리포지토리(repo)입니다:

{
  "name": "my-plugins",
  "owner": { "name": "Your Name" },
...

source는 동일한 리포지토리 내부의 상대 경로(단순한 사례: 하나의 리포지토리, plugins/ 폴더, 루트에 있는 카탈로그)가 될 수도 있고, 다른 GitHub 리포지토리를 가리키는 객체(object)가 될 수도 있으므로, 하나의 카탈로그가 어디에 있든 플러그인들을 인덱싱(index)할 수 있습니다. 푸시(push)하기 전에 전체 흐름을 로컬에서 테스트하세요:

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

그 다음 GitHub에 푸시하면 사용자들이 /plugin marketplace add your-name/your-repo를 실행할 수 있습니다. 팀 단위라면 한 단계 더 나아가 보세요. 프로젝트의 .claude/settings.json 내 extraKnownMarketplaces 항목에 마켓플레이스를 추가하면, Claude Code가 해당 리포지토리를 신뢰하는 모든 협업자에게 팀 플러그인을 설치하도록 안내합니다. 이것과 커밋된 CLAUDE.md 파일만 있다면, "새 개발자의 AI 도구 온보딩(onboard)" 문제는 단 두 개의 파일로 해결됩니다.

건너뛰어서는 안 될 보안 문구

플러그인은 사용자의 권한으로 코드를 실행하는 것입니다. 즉, 훅(hooks)은 셸 명령(shell commands)을 실행하고, MCP 서버는 프로세스(processes)이며, 마켓플레이스에서 설치한다는 것은 해당 저장소(repo)를 제어하는 사람과 그들의 향후 푸시(pushes)까지 모두 신뢰한다는 것을 의미합니다. Anthropic은 제3자 소스에 대해 이 중 어떤 것도 검증하지 않습니다. 모든 종속성(dependency)과 동일한 규칙이 적용됩니다: 설치하기 전에 컴포넌트 인벤토리(component inventory)를 확인하고, 커뮤니티 마켓플레이스와 같이 고정된 카탈로그(pinned catalogs)를 선호하며, 플러그인 자체보다 마켓플레이스를 더 까다롭게 선택하십시오. 카탈로그가 업데이트에 포함될 내용을 결정하기 때문입니다.

이것이 위치하는 곳

그리고 패키징(packaging)의 솔직한 한계는 다음과 같습니다: 플러그인은 지침을 '설치 가능(installable)'하게 만들 뿐, '좋게(good)' 만들지는 못합니다. 다섯 개의 저장소로 배포된 나쁜 프롬프트(prompt)는 다섯 배의 나쁜 프롬프트일 뿐입니다. 플러그인 내부의 기술과 에이전트 본체는 시스템 프롬프트(system prompts)이며, 이를 정교하게 작성하는 것은 그 자체로 하나의 기술입니다 — Meta-Prompt + System Prompt Architect ($8.99, 1회 결제)는 거친 의도를 네임스페이스(namespacing)를 지정하고 배포할 가치가 있는 정밀하고 재사용 가능하며 실패를 인지하는(failure-aware) 지침으로 바꾸기 위해 제가 사용하는 기술입니다. 플러그인으로 배선(wiring)을 패키징하십시오; 그리고 그 내부의 내용물이 설치할 가치가 있게 만드십시오.