Install plugins

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 디렉토리에 배치한다.