install-plugins

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단계를 순서대로 실행한다:

1. Skills -> ~/.claude/skills/에 심링크
2. Agents -> ~/.claude/agents/에 심링크
3. Commands -> ~/.claude/commands/에 심링크
4. 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           # statusline HUD 설정
/minimal:skill-library        # 스킬 카탈로그 관리
/minimal:skill-creator        # 새 스킬 생성 가이드

Step 4: 업데이트

/plugin marketplace update    # marketplace 카탈로그 갱신
/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 디렉토리에 배치한다.