Skip to main content

​
Claude Code Plugin System Reference

Source: https://code.claude.com/docs/plugins, https://code.claude.com/docs/discover-plugins, https://code.claude.com/docs/plugins-reference Retrieved: 2026-04-11
이 문서는 vox.ai plugin이 Claude Code에서 동작하기 위한 참고 자료다. TEST.md의 미션 실행 시 참조한다.

​
Plugin 설치 방법

​
방법 1: npx skills add (GitHub 마켓플레이스)

npx skills add https://github.com/vox-public/vox-skills --skill vox-best-practice

​
방법 2: /plugin install (마켓플레이스에서)

/plugin marketplace add owner/repo
/plugin install plugin-name@marketplace-name

​
방법 3: —plugin-dir (로컬 개발용)

claude --plugin-dir ./my-plugin

​
Plugin 구조

my-plugin/
├── .claude-plugin/
│   └── plugin.json           # 매니페스트 (name, version, description)
├── skills/                   # Agent Skills (SKILL.md)
├── agents/                   # Subagent 정의
├── hooks/                    # hooks.json
├── .mcp.json                 # MCP 서버 구성 ← 핵심: 자동 등록
├── .lsp.json                 # LSP 서버 구성
└── settings.json             # 기본 설정
중요: .mcp.json이 plugin 루트에 있으면 plugin 설치 시 MCP 서버가 자동 등록된다. 사용자가 claude mcp add를 수동으로 실행할 필요가 없다.

​
매니페스트 스키마 (plugin.json)

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "설명",
  "author": { "name": "작성자" },
  "skills": "./skills/",
  "mcpServers": "./.mcp.json"
}

​
필수 필드

필드설명
name고유 식별자 (kebab-case). Skill 네임스페이스 접두사로 사용

​
MCP 서버 구성 (.mcp.json)

{
  "mcpServers": {
    "vox": {
      "type": "http",
      "url": "https://mcp.tryvox.co/mcp"
    },
    "vox-docs": {
      "type": "http",
      "url": "https://docs.tryvox.co/mcp"
    }
  }
}

​
Plugin 설치 범위

범위설정 파일용도
user~/.claude/settings.json모든 프로젝트 (기본값)
project.claude/settings.json팀 공유
local.claude/settings.local.json개인, gitignored

​
환경 변수

  • ${CLAUDE_PLUGIN_ROOT} — plugin 설치 디렉토리 절대 경로
  • ${CLAUDE_PLUGIN_DATA} — 영구 데이터 디렉토리 (업데이트 후에도 유지)

​
디버깅

claude --debug           # 플러그인 로딩 세부정보
/plugin                  # Discover / Installed / Marketplaces / Errors 탭
/reload-plugins          # 재시작 없이 변경사항 적용
claude plugin validate   # 매니페스트 검증