읽는 시간: 15분 | 난이도: 고급자

이 레퍼런스는 Claude Code 플러그인 시스템의 완전한 기술 사양을 제공합니다. 컴포넌트 스키마, CLI 명령어, 개발 도구가 모두 포함되어 있습니다.

플러그인이란 Claude Code를 사용자 정의 기능으로 확장하는 독립적인 컴포넌트 디렉터리입니다. 플러그인 컴포넌트에는 스킬, 에이전트, 훅, MCP 서버, LSP 서버가 포함됩니다.

플러그인 컴포넌트 레퍼런스

스킬 (Skills)

플러그인은 Claude Code에 스킬을 추가하여 사용자 또는 Claude가 호출할 수 있는 /name 단축키를 생성합니다.

위치: 플러그인 루트의 skills/ 또는 commands/ 디렉터리

파일 형식: 스킬은 SKILL.md를 포함하는 디렉터리이며, 명령어는 단순한 마크다운 파일입니다.

스킬 구조:

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (선택)
│   └── scripts/ (선택)
└── code-reviewer/
    └── SKILL.md

통합 동작:

• 스킬과 명령어는 플러그인 설치 시 자동으로 발견됩니다.
• Claude는 작업 컨텍스트에 따라 자동으로 호출할 수 있습니다.
• 스킬은 SKILL.md와 함께 지원 파일을 포함할 수 있습니다.

에이전트 (Agents)

플러그인은 특정 작업을 위한 전문 서브에이전트를 제공할 수 있으며, Claude는 적절한 시점에 자동으로 호출합니다.

위치: 플러그인 루트의 agents/ 디렉터리

파일 형식: 에이전트 기능을 설명하는 마크다운 파일

에이전트 구조:

---
name: agent-name
description: 이 에이전트가 전문으로 하는 것과 Claude가 언제 호출해야 하는지
---

에이전트의 역할, 전문성, 동작을 설명하는 상세한 시스템 프롬프트.

통합 포인트:

• 에이전트는 /agents 인터페이스에 표시됩니다.
• Claude는 작업 컨텍스트에 따라 에이전트를 자동으로 호출할 수 있습니다.
• 플러그인 에이전트는 내장 Claude 에이전트와 함께 작동합니다.

훅 (Hooks)

플러그인은 Claude Code 이벤트에 자동으로 응답하는 이벤트 핸들러를 제공할 수 있습니다.

위치: 플러그인 루트의 hooks/hooks.json 또는 plugin.json 내 인라인

형식: 이벤트 매처와 액션을 포함하는 JSON 설정

훅 설정 예시:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

사용 가능한 이벤트:

훅 타입:

• command: 셸 명령어 또는 스크립트 실행
• prompt: LLM으로 프롬프트 평가 (컨텍스트에 $ARGUMENTS 플레이스홀더 사용)
• agent: 복잡한 검증 작업을 위한 에이전트 방식 검증기 실행

MCP 서버

플러그인은 Claude Code와 외부 도구 및 서비스를 연결하는 MCP(Model Context Protocol) 서버를 번들로 제공할 수 있습니다.

위치: 플러그인 루트의 .mcp.json 또는 plugin.json 내 인라인

MCP 서버 설정 예시:

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    }
  }
}

통합 동작:

• 플러그인 MCP 서버는 플러그인이 활성화될 때 자동으로 시작됩니다.
• 서버는 Claude의 도구킷에서 표준 MCP 도구로 나타납니다.
• 플러그인 서버는 사용자 MCP 서버와 독립적으로 설정할 수 있습니다.

LSP 서버

플러그인은 Language Server Protocol(LSP) 서버를 제공하여 Claude가 코드베이스 작업 중 실시간 코드 인텔리전스를 가질 수 있게 합니다.

LSP 통합이 제공하는 기능:

• 즉각적인 진단: 각 편집 후 즉시 오류와 경고를 확인
• 코드 탐색: 정의로 이동, 참조 찾기, 호버 정보 확인
• 언어 인식: 코드 심볼에 대한 타입 정보와 문서

.lsp.json 파일 형식:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

필수 필드:

선택적 필드:

언어 서버 바이너리는 별도로 설치해야 합니다. LSP 플러그인은 Claude Code가 언어 서버에 연결하는 방법을 설정하지만, 서버 자체는 포함하지 않습니다.

사용 가능한 LSP 플러그인:

플러그인 설치 스코프

플러그인을 설치할 때 플러그인이 사용 가능한 위치와 공유 범위를 결정하는 스코프를 선택합니다.

플러그인 매니페스트 스키마

.claude-plugin/plugin.json 파일은 플러그인의 메타데이터와 설정을 정의합니다. 매니페스트는 선택 사항입니다. 생략하면 Claude Code가 기본 위치에서 컴포넌트를 자동 발견하고 디렉터리 이름에서 플러그인 이름을 도출합니다.

전체 스키마

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "플러그인 간략 설명",
  "author": {
    "name": "작성자 이름",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "commands": ["./custom/commands/special.md"],
  "agents": "./custom/agents/",
  "skills": "./custom/skills/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json"
}

필수 필드

매니페스트를 포함하는 경우 name이 유일한 필수 필드입니다.

메타데이터 필드

컴포넌트 경로 필드

환경 변수

${CLAUDE_PLUGIN_ROOT}: 플러그인 디렉터리의 절대 경로를 포함합니다. 훅, MCP 서버, 스크립트에서 이 변수를 사용하여 설치 위치에 관계없이 올바른 경로를 보장합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

플러그인 디렉터리 구조

표준 플러그인 레이아웃

enterprise-plugin/
├── .claude-plugin/           # 메타데이터 디렉터리 (선택)
│   └── plugin.json           # 플러그인 매니페스트
├── commands/                 # 기본 명령어 위치
│   ├── status.md
│   └── logs.md
├── agents/                   # 기본 에이전트 위치
│   ├── security-reviewer.md
│   └── performance-tester.md
├── skills/                   # 에이전트 스킬
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       └── SKILL.md
├── hooks/                    # 훅 설정
│   └── hooks.json
├── .mcp.json                 # MCP 서버 정의
├── .lsp.json                 # LSP 서버 설정
├── scripts/                  # 훅 및 유틸리티 스크립트
└── CHANGELOG.md              # 버전 이력

주의: .claude-plugin/ 디렉터리는 plugin.json 파일만 포함합니다. 다른 모든 디렉터리(commands/, agents/, skills/, hooks/)는 .claude-plugin/ 안이 아닌 플러그인 루트에 있어야 합니다.

파일 위치 레퍼런스

CLI 명령어 레퍼런스

Claude Code는 스크립팅 및 자동화에 유용한 비대화형 플러그인 관리를 위한 CLI 명령어를 제공합니다.

plugin install

사용 가능한 마켓플레이스에서 플러그인을 설치합니다.

claude plugin install <plugin> [options]

옵션:

예시:

# 사용자 스코프에 설치 (기본값)
claude plugin install formatter@my-marketplace

# 프로젝트 스코프에 설치 (팀 공유)
claude plugin install formatter@my-marketplace --scope project

# 로컬 스코프에 설치 (gitignore 처리)
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

설치된 플러그인을 제거합니다. 별칭: remove, rm

claude plugin uninstall <plugin> [options]

plugin enable / disable

플러그인을 활성화 또는 비활성화합니다.

claude plugin enable <plugin> [options]
claude plugin disable <plugin> [options]

plugin update

플러그인을 최신 버전으로 업데이트합니다.

claude plugin update <plugin> [options]

디버깅 및 개발 도구

디버깅 명령어

플러그인 로딩 세부 정보를 확인하려면 claude --debug(또는 TUI 내에서 /debug)를 사용합니다:

• 어떤 플러그인이 로딩되는지
• 플러그인 매니페스트의 오류
• 명령어, 에이전트, 훅 등록
• MCP 서버 초기화

일반적인 문제

훅 문제 해결

훅 스크립트가 실행되지 않는 경우:

1. 스크립트 실행 권한 확인: chmod +x ./scripts/your-script.sh
2. 셔뱅 라인 확인: 첫 줄이 #!/bin/bash 또는 #!/usr/bin/env bash여야 함
3. 경로에 ${CLAUDE_PLUGIN_ROOT} 사용 확인
4. 스크립트를 수동으로 테스트: ./scripts/your-script.sh

훅이 예상 이벤트에서 트리거되지 않는 경우:

1. 이벤트 이름이 올바른지 확인 (대소문자 구분): PostToolUse, postToolUse 아님
2. 매처 패턴이 도구와 일치하는지 확인
3. 훅 타입이 유효한지 확인: command, prompt, agent

버전 관리

플러그인 릴리스에는 시맨틱 버전을 따릅니다:

{
  "name": "my-plugin",
  "version": "2.1.0"
}

버전 형식: MAJOR.MINOR.PATCH

• MAJOR: 호환성이 깨지는 변경 사항
• MINOR: 하위 호환 가능한 새 기능
• PATCH: 하위 호환 가능한 버그 수정

Claude Code는 플러그인 업데이트 여부를 결정하기 위해 버전을 사용합니다. 코드를 변경했지만 버전을 올리지 않으면 기존 사용자들이 변경 사항을 볼 수 없습니다.

다음 단계

• 플러그인 생성하기: 플러그인 가이드에서 스킬, 에이전트, 훅 만들기
• 플러그인 탐색: 플러그인 탐색 가이드에서 설치 방법 확인
• 마켓플레이스 설정: 플러그인 마켓플레이스에서 배포 방법 학습
• 설정 구성: 설정에서 플러그인 관련 설정 확인