Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Claude Code v2.1.139부터 도입된 Plugin Marketplace 기능을 활용하여 Skill, Agent, Hook, MCP Server를 패키지화하는 방법을 설명합니다. 로컬 마켓플레이스 구축 절차와 Node.js 환경에서의 설치 문제 해결 방법을 다룹니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기Claude Code v2.1.139부터 Plugin Marketplace 기능이 추가되었습니다!
Skill, Agent, Hook, MCP Server 설정을 하나로 패키지화하여, 사용자가 간단한 명령어를 입력하는 것만으로 사내 기준이나 특정 표준에 따른 환경을 통째로 재현할 수 있는 메커니즘입니다.
명령어 내용은 아래에 기재되어 있습니다!
이 기사에서는 로컬에서 마켓플레이스를 만들고 테스트하기까지의 절차와, 실제로 겪었던 문제점(ハマりどころ)들을 정리했습니다!
플러그인에 포함할 수 있는 것은 다음 4가지 종류입니다.
| 종류 | 내용 |
|---|---|
| Skill | Claude가 참조하는 지식·절차서 (/aws-review와 같은 슬래시 명령어) |
| Agent | 서브 에이전트(Sub-agent)로 호출할 수 있는 커스텀 에이전트 정의 |
| Hook | 파일 편집 후의 Lint 자동 실행 등, 조작에 연동되어 동작하는 셸(Shell) 명령어 |
| MCP Server 설정 | SharePoint, Confluence 등 외부 도구로의 접속 설정 |
이것들을 하나의 플러그인으로 묶어 GitHub에서 관리하고, 사용자는 설치 명령어를 한 번 실행하는 것만으로 전부 설치할 수 있어, npm의 Claude Code 버전과 같은 느낌으로 사용할 수 있습니다!
Claude Code CLI v2.1.139 이후 버전이 필요합니다 (claude --version으로 확인).
v2.1.139 미만 버전에서는 /plugin 명령어 자체가 존재하지 않으므로 업데이트해 주세요.
claude install
npm install -g가 아니라 claude install이 v2.1.165 이후의 권장 방법입니다.
fnm 등의 Node.js 버전 매니저를 사용하는 환경에서는 npm install -g로 설치한 바이너리가 PATH에 반영되지 않아 이전 버전 그대로 남아 있는 경우가 있습니다. claude install을 사용하면 ~/.local/bin/claude에 네이티브 바이너리가 배치되므로 Node.js 환경에 의존하지 않습니다.
먼저 임의의 디렉토리에 마켓플레이스용 폴더를 생성합니다.
mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/my-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/my-plugin/skills/aws-review
...
완성된 디렉토리 구조는 다음과 같습니다.
my-marketplace/
├── .claude-plugin/
│ └── marketplace.json # 마켓플레이스 정의
...
.claude-plugin/marketplace.json
{
"name": "my-marketplace",
"owner": {
...
plugins/my-plugin/.claude-plugin/plugin.json
{
"name": "my-plugin",
"version": "0.1.0",
...
plugins/my-plugin/skills/aws-review/SKILL.md
---
name: aws-review
description: AWS 설계 리뷰를 실시함
...
plugins/my-plugin/agents/aws-architect.md
---
name: aws-architect
description: AWS 아키텍트 지원 Agent
...
plugins/my-plugin/hooks/hooks.json
{
"hooks": {
"PostToolUse": [
...
plugins/my-plugin/.mcp.json
{
"mcpServers": {
"sharepoint": {
...
플러그인의 동작 확인은 **마켓플레이스 본체와는 별개의 리포지토리(Repository)**에서 진행해 주세요. 마켓플레이스를 만든 디렉토리와 같은 장소에서 테스트하면, 플러그인 파일과 본인의 파일이 혼재되어 파악하기 어려워집니다.
적절한 테스트용 디렉토리를 생성하고, 그곳에서 claude를 실행합니다.
mkdir ~/test-repo && cd ~/test-repo
claude
VS Code 확장 기능의 채팅창에서는 /plugin 명령어를 실행할 수 없습니다.
VS Code 확장 기능은 독자적인 번들 바이너리 (bundled binary)를 사용하고 있어, 터미널의 claude CLI와는 별개로 동작합니다.
터미널에서 claude를 실행하여 진행해 주세요. 설정은 ~/.claude/settings.json에 저장되므로, CLI에서 조작한 내용은 VS Code 확장 기능에도 자동으로 반영됩니다. claude 실행 후, 다음 명령어를 실행합니다.
/plugin marketplace add /path/to/my-marketplace
성공하면 다음과 같이 표시됩니다.
Successfully added marketplace: my-marketplace
/plugin install my-plugin@my-marketplace
설치 범위 (scope)를 선택하는 화면이 나타납니다.
| 범위 (Scope) | 효과 |
|---|---|
| user | 모든 리포지토리에서 유효 (권장) |
| project | 리포지토리 내의 모든 협업자에게 유효 |
| local | 본인의 이 리포지토리에서만 유효 |
/reload-plugins
Reloaded: 1 plugin · 0 skills · 7 agents · 1 hook · 1 plugin MCP server
설치한 스킬 (skill)이나 에이전트 (agent)를 사용할 수 있게 됩니다.
실제로 추가된 스킬 등은 /help 명령어로 확인할 수 있습니다.
실제로 사용해 보면 다음과 같은 느낌입니다.
[IMG:1]
정상적으로 리뷰되고 있음을 확인할 수 있었습니다.
[IMG:2]
로컬 경로를 GitHub URL로 바꾸기만 하면 절차는 완전히 동일합니다.
/plugin marketplace add https://github.com/org/my-marketplace
/plugin install my-plugin@my-marketplace
프라이빗 리포지토리(private repository)의 경우, gh auth login이 완료되어 있다면 추가 설정은 필요 없습니다. 백그라운드 자동 업데이트까지 대응하고 싶다면 환경 변수에 토큰을 설정합니다.
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
설치의 입도 (Granularity)
업데이트
/reload-plugins로 다시 로드합니다./plugin marketplace update를 사용합니다.파일 배치 위치
| 위치 | 역할 |
|---|---|
| 마켓플레이스 디렉토리 | 정의 원본 (편집하는 곳) |
~/.claude/plugins/cache/ | 설치 시의 캐시 (실제로 로드되는 곳) |
Plugin Marketplace는 "Claude Code의 사내 표준 환경을 코드로 관리하여 배포한다"라는 용도에 딱 들어맞는 기능입니다. GitHub에 올려 팀원 모두가 동일한 스킬, 에이전트, Hook을 사용할 수 있는 상태로 만들 수 있습니다.
반면, /plugin 명령어가 CLI 전용이라는 점은 주의가 필요하며, VS Code 확장 기능 사용자에게는 "채팅창에서 입력하면 되겠지"라는 흐름이 막히게 됩니다. 팀에 전개할 때는 이 절차를 명시해 두는 것이 좋습니다.