| name | install-plugins |
| description | Use when a user asks how to install plugins from this marketplace, needs onboarding to the Claude Code plugin system, or encounters plugin installation errors like "marketplace not found" or "plugin not registered" |
Plugin Marketplace 설치 가이드
개요
Claude Code Plugin은 5가지 구성요소를 하나의 패키지로 묶어 배포하는 단위이다. 설치 스크립트 또는 /plugin 명령어로 Claude, Codex, Gemini, GSD에 동시 설치한다.
플러그인 구성요소
| 구성 요소 | 역할 | 플러그인 내 경로 | 설치 위치 |
|---|
| Skills | 특화된 작업 가이드 (SKILL.md) | skills/<name>/SKILL.md | ~/.{tool}/skills/ |
| Agents | 하위 에이전트 정의 | agents/<name>.md | ~/.{tool}/agents/ |
| Commands | 슬래시 명령어 | commands/<name>.md | ~/.claude/commands/ |
| MCP Servers | 외부 서비스 연동 서버 | mcp-servers/<name>/ | plugin.json 자동 등록 |
| CLI Tools | 커맨드라인 도구 | tools/<name>/ | ~/.claude/tool-cli/ |
도구별 설치 경로 매핑
| 구성요소 | Claude | Codex | Gemini | GSD |
|---|
| Skills | ~/.claude/skills/ | ~/.codex/skills/ | ~/.gemini/skills/ | ~/.gsd/agent/skills/ |
| Agents | ~/.claude/agents/ | ~/.codex/agents/ | ~/.gemini/agents/ | ~/.gsd/agent/agents/ |
| Commands | ~/.claude/commands/ | - | - | - |
| MCP Servers | plugin.json 자동 | 수동 설정 | 수동 설정 | 수동 설정 |
| CLI Tools | ~/.claude/tool-cli/ | - | - | - |
plugin.json 스키마
{
"name": "my-plugin",
"version": "1.0.0",
"description": "Plugin description",
"author": { "name": "Author Name" },
"agents": ["./agents/my-agent.md"],
"commands": "./commands",
"mcpServers": {
"my-server": {
"command": "node",
"args": ["${CLAUDE_PLUGIN_ROOT}/mcp-servers/my-server/dist/index.js"],
"env": { "API_KEY": "${API_KEY}" }
}
}
}
플러그인 카탈로그
| 플러그인 | 카테고리 | Skills | Agents | Commands | 설명 |
|---|
minimal | onboarding | 15 | 6 | 3 | 핵심 스킬만 포함, 외부 연동 없음 |
설치 방법
방법 A: 설치 스크립트 (권장)
Mac/Linux:
git clone https://github.com/cskwork/claude-minimal-plugin.git
cd claude-minimal-plugin
chmod +x install.sh && ./install.sh
설치 스크립트는 4단계를 순서대로 실행한다:
- Skills ->
~/.claude/skills/에 심링크
- Agents ->
~/.claude/agents/에 심링크
- Commands ->
~/.claude/commands/에 심링크
- CLAUDE.md ->
~/.claude/CLAUDE.md 설치 (기존 파일 .bak 백업)
방법 B: Claude Plugin System
Claude Code 전용으로 /plugin 명령어를 사용한다.
Step 1: Marketplace 등록 (최초 1회)
/plugin marketplace add cskwork/claude-minimal-plugin
Step 2: 플러그인 설치
/plugin install minimal
Step 3: 스킬 사용
설치된 스킬은 /<plugin>:<skill> 형식으로 호출한다:
/minimal:install-plugins
/minimal:find-skills
/minimal:agent-browser
/minimal:claude-hud
/minimal:skill-library
/minimal:skill-creator
Step 4: 업데이트
/plugin marketplace update
/plugin update minimal
플러그인에 새 구성요소 추가하기
Commands 추가
plugins/my-plugin/
commands/
my-command.md # --- name: my-command ...frontmatter ---
MCP Server 추가
plugins/my-plugin/
mcp-servers/
my-server/
package.json
src/index.ts
.claude-plugin/
plugin.json # mcpServers 섹션에 등록
CLI Tool 추가
plugins/my-plugin/
tools/
my-tool/
TOOL.md # 사용법 문서
bin/ # 실행 파일
트러블슈팅
| 증상 | 원인 | 해결 |
|---|
marketplace not found | marketplace 미등록 | /plugin marketplace add 실행 |
plugin not found | 플러그인 이름 오타 | 카탈로그 테이블에서 이름 확인 |
| 스킬 호출 무반응 | 플러그인 미설치 | /plugin install <name> 실행 |
| 변경 미반영 | 캐시 문제 | Claude Code 재시작 |
| MCP 서버 연결 실패 | 환경 변수 미설정 | plugin.json의 env 섹션 확인 |
| Windows 심링크 실패 | 권한 부족 | 관리자 실행 또는 Developer Mode 활성화 |
| Codex/Gemini에 agent 안 보임 | agents 디렉토리 없음 | mkdir ~/.codex/agents 후 재설치 |
FAQ
Q: npx skills와 /plugin의 차이는?
npx skills: 외부 오픈소스 생태계 (skills.sh)에서 개별 스킬 검색/설치/plugin: 이 marketplace의 큐레이션된 플러그인 번들 설치
Q: MCP 서버를 Codex/Gemini에서 사용하려면?
MCP 서버는 Claude plugin system에서 자동 등록된다. 다른 도구에서 사용하려면 해당 도구의 설정 파일에 MCP config를 수동으로 추가한다.
Q: 개별 스킬만 설치할 수 있는가?
플러그인은 번들 단위로 설치된다. 개별 스킬이 필요하면 library.yaml의 source URL에서 직접 복사하여 skills 디렉토리에 배치한다.
