Claude 플러그인 설치·배포 가이드: Skills와 차이

"스킬 하나는 만들어봤는데, 이걸 팀에 어떻게 배포하지?"

📌 핵심 3줄 요약

• claude code plugin은 스킬·서브에이전트·슬래시 커맨드·MCP를 한 패키지로 묶는 단위다.
• 공식 레포 anthropics/claude-plugins-official(2026-05-10 기준 19k stars, 364 commits)에서 한 줄 명령으로 설치할 수 있다.
• GitHub에 marketplace.json만 두면 팀원이 /plugin marketplace add owner/repo로 즉시 받아 쓴다.

1. Skills vs Plugins, 무엇이 다른가

둘은 자주 헷갈리지만 역할이 다르다. Skill은 SKILL.md 한 폴더로 끝나는 콘텐츠 단위, Plugin은 그 스킬을 포함해 여러 컴포넌트를 묶는 배포 패키지다.

구분	Skills	Plugins
묶는 단위	SKILL.md + references	skills + agents + commands + hooks + MCP
매니페스트	없음 (폴더 자체)	.claude-plugin/plugin.json
배포	파일 복사 / git clone	/plugin install 한 줄
호출 네임스페이스	/<skill-name>	/<plugin>:<skill>

2. 공식 마켓에서 첫 플러그인 설치

설치는 5단계로 끝난다. 슬래시 커맨드만 알면 된다.

# 1) 공식 마켓플레이스 등록
/plugin marketplace add anthropics/claude-plugins-official

# 2) 사용 가능한 플러그인 탐색
/plugin

# 3) 원하는 플러그인 설치 (이름@마켓 형식)
/plugin install code-review@claude-plugins-official

# 4) 변경사항 즉시 반영
/reload-plugins

# 5) 네임스페이스로 호출
/code-review:scan

💡 자주 막히는 지점

• add 인자는 owner/repo·로컬 경로·git URL 모두 가능
• 마켓 갱신은 /plugin marketplace update (자동 아님)
• 스크립트용 비-인터랙티브는 claude plugin marketplace ... 서브커맨드

3. 내 워크플로를 플러그인으로 묶기

로컬 폴더 하나로 바로 테스트 가능하다. 매니페스트는 4개 필드만 채우면 된다.

my-first-plugin/
├── .claude-plugin/
│   └── plugin.json          # 필수
├── skills/
│   └── hello/
│       └── SKILL.md
├── agents/
├── commands/
├── hooks/hooks.json
└── .mcp.json

{
  "name": "my-first-plugin",
  "description": "팀 코드리뷰 자동화 번들",
  "version": "0.1.0",
  "author": "your-name"
}

로컬 검증은 claude --plugin-dir ./my-first-plugin로 띄운 뒤 /my-first-plugin:hello를 호출하면 된다. ZIP 배포본은 --plugin-url로 직접 로드도 가능하다.

4. GitHub로 배포·팀 공유

마켓플레이스도 결국 GitHub 레포 한 개다. 루트에 .claude-plugin/marketplace.json만 두면 된다.

{
  "name": "team-plugins",
  "plugins": [
    { "path": "./my-first-plugin" }
  ]
}

# 팀원이 받는 쪽
/plugin marketplace add yourteam/team-plugins
/plugin install my-first-plugin@team-plugins

레포명은 kebab-case 권장이며, plugins[]에 여러 패키지를 노출할 수 있다. GitLab·자체 git URL도 동일 문법이다.

⚠️ 단점과 주의할 점

• 보안 검증은 사용자 책임 — Anthropic도 외부 플러그인의 MCP·파일을 검증하지 않는다. 신뢰할 수 있는 소스만 설치할 것.
• 슬래시 커맨드 문법은 Claude Code 버전에 따라 달라질 수 있음 — 공식 문서와 CLI 버전을 함께 확인.
• 공식 레포(claude-plugins-official)는 활발히 갱신 중이라 어제의 명령이 오늘 바뀔 수 있다.

🚀 지금 바로 할 일

1. 공식 레포에서 /plugin marketplace add anthropics/claude-plugins-official로 첫 마켓 등록.
2. 관심 있는 플러그인 1개 설치 후 /reload-plugins로 동작 확인.
3. 본인 워크플로 1개를 plugin.json으로 묶어 --plugin-dir로 로컬 테스트.

💬 의견

팀에 플러그인을 배포해본 경험이 있다면 어떤 컴포넌트를 가장 먼저 묶었는지 댓글로 공유 부탁드립니다. 다음 글은 hooks와 MCP 통합 사례를 다룰 예정입니다.

함께 보면 좋은 글

• MCP 시작 가이드 — 외부 API·DB 연동을 Plugins(MCP) 쪽에서 풀고 싶을 때 함께 보면 Skills와의 역할 분담이 분명해진다.
• Cursor 시작 가이드 — 같은 워크플로를 다른 에디터에서 어떻게 만드는지 비교해 보고 싶다면.
• OpenAI Agents SDK 튜토리얼 — 같은 "에이전트 + 도구" 개념을 OpenAI 쪽에서는 어떻게 표현하는지 대조해 볼 수 있다.

참고 자료

• anthropics/claude-plugins-official — 공식 플러그인 디렉터리 (2026-05-10 기준 364 commits)
• Claude Code Plugins 공식 문서
• Plugin Marketplaces 공식 문서

---

작성자: AI 튜토리얼 분야의 한국어 기술 블로거. Claude Code·MCP·LangChain을 매일 실무에 사용하며, 새 기능이 풀릴 때마다 공식 문서와 1차 레포를 직접 따라가 본 뒤 한국 개발자 입장에서 막히는 지점을 정리해 옮깁니다. 본 글은 anthropics/claude-plugins-official 레포와 code.claude.com 공식 가이드를 2026-05-10 기준으로 직접 따라가며 검증했습니다.