Plugin 시스템 작성법

Claude Code Plugin 시스템의 구조, 작성법, 배포 방법을 안내합니다.

개요

Plugin은 skills, agents, hooks, MCP 서버, LSP 설정을 하나의 패키지로 번들링하여 배포·설치할 수 있는 확장 단위입니다.

Plugin 구조

my-plugin/
├── .claude-plugin/
│   └── plugin.json       ← 매니페스트 (필수, v1.0.33+)
├── skills/               ← 스킬 정의 (Agent Skills 스탠다드)
│   ├── my-skill/
│   │   ├── skill.md
│   │   └── references/
│   └── another-skill/
│       └── skill.md
├── agents/               ← 에이전트 정의
│   └── my-agent.md
├── hooks/                ← Hook 스크립트
│   ├── hooks.json
│   └── scripts/
│       ├── pre-commit.sh
│       └── auto-format.sh
├── mcp/                  ← MCP 서버 설정
│   └── mcp.json
├── lsp/                  ← LSP 설정
│   └── lsp.json
└── README.md             ← 플러그인 설명

plugin.json 매니페스트

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Plugin 설명",
  "author": "작성자",
  "license": "MIT",
  "claude_code_version": ">=1.0.0",
  "components": {
    "skills": [
      {
        "path": "skills/my-skill",
        "name": "my-skill",
        "description": "스킬 설명"
      }
    ],
    "agents": [
      {
        "path": "agents/my-agent.md",
        "name": "my-agent",
        "description": "에이전트 설명"
      }
    ],
    "hooks": {
      "path": "hooks/hooks.json"
    },
    "mcp": {
      "path": "mcp/mcp.json"
    },
    "lsp": {
      "path": "lsp/lsp.json"
    }
  },
  "dependencies": {
    "mcp_servers": ["tavily"],
    "npm_packages": ["prettier"],
    "python_packages": []
  },
  "config": {
    "schema": {
      "api_key": {
        "type": "string",
        "description": "API 키",
        "required": false,
        "env": "MY_PLUGIN_API_KEY"
      }
    }
  }
}

필수 필드

선택 필드

${CLAUDE_PLUGIN_ROOT} 활용

Plugin 내부에서 자체 파일 경로를 참조할 때 사용합니다:

<!-- skill.md 내에서 -->
참조 파일: ${CLAUDE_PLUGIN_ROOT}/skills/my-skill/references/schema.md

<!-- hooks.json 내에서 -->
{
  "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/auto-format.sh"
}

동작 원리

• 설치 시 실제 설치 경로로 자동 치환
• Plugin이 어디에 설치되든 경로가 올바르게 해결됨

설치 Scope

CLI 명령어

# Plugin 설치 (URL 기반)
claude plugin install https://github.com/user/my-plugin

# Plugin 설치 (로컬 경로)
claude plugin install --local ./my-plugin

# 설치된 Plugin 목록
claude plugin list

# Plugin 제거
claude plugin remove my-plugin

# Plugin 업데이트
claude plugin update my-plugin

# Plugin 정보 확인
claude plugin info my-plugin

Hooks 설정 통합

Plugin의 hooks는 hooks/hooks.json에 정의하고, 스크립트는 hooks/scripts/에 배치합니다:

// hooks/hooks.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/pre-commit.sh \"$TOOL_INPUT\""
          }
        ]
      }
    ]
  }
}

MCP 서버 통합

// mcp/mcp.json
{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/server.js"],
      "env": {
        "API_KEY": "${MY_PLUGIN_API_KEY}"
      }
    }
  }
}

배포 및 공유

GitHub 배포

1. Plugin 디렉토리를 GitHub 레포로 생성
2. plugin.json이 레포 루트에 위치
3. 사용자는 claude plugin install <github-url>로 설치

로컬 공유

1. Plugin 디렉토리를 zip으로 압축
2. 수신자가 압축 해제 후 claude plugin install --local <path>

조직 내부 배포

1. 내부 레지스트리 또는 공유 드라이브에 배치
2. 관리자가 managed scope으로 일괄 배포
3. 사용자 설치 불필요

Best Practices

1. 최소 구성 원칙: 필요한 컴포넌트만 포함
2. 명확한 README: 설치 방법, 사용법, 설정 항목 명시
3. 버전 관리: SemVer 준수, 호환성 범위 명시
4. 설정 스키마: 사용자 입력이 필요한 값은 config.schema에 정의
5. 경로 참조: 항상 ${CLAUDE_PLUGIN_ROOT} 사용
6. 테스트: 설치 전/후 동작 검증 스크립트 포함 권장