플러그인 레퍼런스

읽는 시간: 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"
          }
        ]
      }
    ]
  }
}

사용 가능한 이벤트:

이벤트	설명
`PreToolUse`	Claude가 도구를 사용하기 전
`PostToolUse`	Claude가 도구를 성공적으로 사용한 후
`PostToolUseFailure`	Claude 도구 실행 실패 후
`PermissionRequest`	권한 대화상자가 표시될 때
`UserPromptSubmit`	사용자가 프롬프트를 제출할 때
`Notification`	Claude Code가 알림을 보낼 때
`Stop`	Claude가 중지를 시도할 때
`SubagentStart`	서브에이전트가 시작될 때
`SubagentStop`	서브에이전트가 중지를 시도할 때
`SessionStart`	세션 시작 시
`SessionEnd`	세션 종료 시
`TeammateIdle`	에이전트 팀 멤버가 유휴 상태가 되려 할 때
`TaskCompleted`	작업이 완료로 표시될 때
`PreCompact`	대화 기록이 압축되기 전

훅 타입:

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"
    }
  }
}

필수 필드:

필드	설명
`command`	실행할 LSP 바이너리 (PATH에 있어야 함)
`extensionToLanguage`	파일 확장자를 언어 식별자에 매핑

선택적 필드:

필드	설명
`args`	LSP 서버의 커맨드라인 인수
`transport`	통신 전송: `stdio` (기본) 또는 `socket`
`env`	서버 시작 시 설정할 환경 변수
`initializationOptions`	초기화 중 서버에 전달되는 옵션
`settings`	`workspace/didChangeConfiguration`을 통해 전달되는 설정
`startupTimeout`	서버 시작 대기 최대 시간 (밀리초)
`shutdownTimeout`	정상 종료 대기 최대 시간 (밀리초)
`restartOnCrash`	충돌 시 서버를 자동으로 재시작할지 여부
`maxRestarts`	포기하기 전 최대 재시작 횟수

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

사용 가능한 LSP 플러그인:

플러그인	언어 서버	설치 명령어
`pyright-lsp`	Pyright (Python)	`pip install pyright` 또는 `npm install -g pyright`
`typescript-lsp`	TypeScript Language Server	`npm install -g typescript-language-server typescript`
`rust-lsp`	rust-analyzer	rust-analyzer 설치 가이드 참조

플러그인 설치 스코프

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

스코프	설정 파일	사용 사례
`user`	`~/.claude/settings.json`	모든 프로젝트에서 사용 가능한 개인 플러그인 (기본값)
`project`	`.claude/settings.json`	버전 컨트롤을 통해 공유되는 팀 플러그인
`local`	`.claude/settings.local.json`	프로젝트별 플러그인, gitignore 처리
`managed`	`managed-settings.json`	관리형 플러그인 (읽기 전용, 업데이트만 가능)

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

.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이 유일한 필수 필드입니다.

필드	타입	설명	예시
`name`	string	고유 식별자 (kebab-case, 공백 없음)	`"deployment-tools"`

메타데이터 필드

필드	타입	설명	예시
`version`	string	시맨틱 버전	`"2.1.0"`
`description`	string	플러그인 목적의 간략한 설명	`"배포 자동화 도구"`
`author`	object	작성자 정보	`{"name": "Dev Team"}`
`homepage`	string	문서 URL	`"https://docs.example.com"`
`repository`	string	소스 코드 URL	`"https://github.com/user/plugin"`
`license`	string	라이선스 식별자	`"MIT"`, `"Apache-2.0"`
`keywords`	array	발견을 위한 태그	`["deployment", "ci-cd"]`

컴포넌트 경로 필드

필드	타입	설명
`commands`	string\|array	추가 명령어 파일/디렉터리
`agents`	string\|array	추가 에이전트 파일
`skills`	string\|array	추가 스킬 디렉터리
`hooks`	string\|array\|object	훅 설정 경로 또는 인라인 설정
`mcpServers`	string\|array\|object	MCP 설정 경로 또는 인라인 설정
`outputStyles`	string\|array	추가 출력 스타일 파일/디렉터리
`lspServers`	string\|array\|object	코드 인텔리전스를 위한 LSP 설정

환경 변수

${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/ 안이 아닌 플러그인 루트에 있어야 합니다.

파일 위치 레퍼런스

컴포넌트	기본 위치	목적
매니페스트	`.claude-plugin/plugin.json`	플러그인 메타데이터 및 설정 (선택)
명령어	`commands/`	스킬 마크다운 파일
에이전트	`agents/`	서브에이전트 마크다운 파일
스킬	`skills/`	`<name>/SKILL.md` 구조의 스킬
훅	`hooks/hooks.json`	훅 설정
MCP 서버	`.mcp.json`	MCP 서버 정의
LSP 서버	`.lsp.json`	언어 서버 설정
설정	`settings.json`	플러그인 활성화 시 적용되는 기본 설정

CLI 명령어 레퍼런스

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

plugin install

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

claude plugin install <plugin> [options]

옵션:

옵션	설명	기본값
`-s, --scope <scope>`	설치 스코프: `user`, `project`, `local`	`user`
`-h, --help`	도움말 표시

예시:

# 사용자 스코프에 설치 (기본값)
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 서버 초기화

일반적인 문제

문제	원인	해결 방법
플러그인이 로딩되지 않음	잘못된 `plugin.json`	`claude plugin validate`로 JSON 문법 검증
명령어가 나타나지 않음	잘못된 디렉터리 구조	`commands/`가 루트에 있는지 확인
훅이 실행되지 않음	스크립트에 실행 권한 없음	`chmod +x script.sh` 실행
MCP 서버 실패	`${CLAUDE_PLUGIN_ROOT}` 누락	모든 플러그인 경로에 변수 사용
경로 오류	절대 경로 사용	모든 경로는 상대 경로여야 하며 `./`로 시작
LSP `Executable not found in $PATH`	언어 서버 미설치	해당 바이너리 설치 필요

훅 문제 해결

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

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

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

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

버전 관리

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

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

버전 형식: MAJOR.MINOR.PATCH

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

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

다음 단계

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

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

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

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

스킬 (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"
          }
        ]
      }
    ]
  }
}

사용 가능한 이벤트:

이벤트	설명
`PreToolUse`	Claude가 도구를 사용하기 전
`PostToolUse`	Claude가 도구를 성공적으로 사용한 후
`PostToolUseFailure`	Claude 도구 실행 실패 후
`PermissionRequest`	권한 대화상자가 표시될 때
`UserPromptSubmit`	사용자가 프롬프트를 제출할 때
`Notification`	Claude Code가 알림을 보낼 때
`Stop`	Claude가 중지를 시도할 때
`SubagentStart`	서브에이전트가 시작될 때
`SubagentStop`	서브에이전트가 중지를 시도할 때
`SessionStart`	세션 시작 시
`SessionEnd`	세션 종료 시
`TeammateIdle`	에이전트 팀 멤버가 유휴 상태가 되려 할 때
`TaskCompleted`	작업이 완료로 표시될 때
`PreCompact`	대화 기록이 압축되기 전

훅 타입:

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"
    }
  }
}

필수 필드:

필드	설명
`command`	실행할 LSP 바이너리 (PATH에 있어야 함)
`extensionToLanguage`	파일 확장자를 언어 식별자에 매핑

선택적 필드:

필드	설명
`args`	LSP 서버의 커맨드라인 인수
`transport`	통신 전송: `stdio` (기본) 또는 `socket`
`env`	서버 시작 시 설정할 환경 변수
`initializationOptions`	초기화 중 서버에 전달되는 옵션
`settings`	`workspace/didChangeConfiguration`을 통해 전달되는 설정
`startupTimeout`	서버 시작 대기 최대 시간 (밀리초)
`shutdownTimeout`	정상 종료 대기 최대 시간 (밀리초)
`restartOnCrash`	충돌 시 서버를 자동으로 재시작할지 여부
`maxRestarts`	포기하기 전 최대 재시작 횟수

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

사용 가능한 LSP 플러그인:

플러그인	언어 서버	설치 명령어
`pyright-lsp`	Pyright (Python)	`pip install pyright` 또는 `npm install -g pyright`
`typescript-lsp`	TypeScript Language Server	`npm install -g typescript-language-server typescript`
`rust-lsp`	rust-analyzer	rust-analyzer 설치 가이드 참조

플러그인 설치 스코프

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

스코프	설정 파일	사용 사례
`user`	`~/.claude/settings.json`	모든 프로젝트에서 사용 가능한 개인 플러그인 (기본값)
`project`	`.claude/settings.json`	버전 컨트롤을 통해 공유되는 팀 플러그인
`local`	`.claude/settings.local.json`	프로젝트별 플러그인, gitignore 처리
`managed`	`managed-settings.json`	관리형 플러그인 (읽기 전용, 업데이트만 가능)

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

전체 스키마

{
  "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이 유일한 필수 필드입니다.

필드	타입	설명	예시
`name`	string	고유 식별자 (kebab-case, 공백 없음)	`"deployment-tools"`

메타데이터 필드

필드	타입	설명	예시
`version`	string	시맨틱 버전	`"2.1.0"`
`description`	string	플러그인 목적의 간략한 설명	`"배포 자동화 도구"`
`author`	object	작성자 정보	`{"name": "Dev Team"}`
`homepage`	string	문서 URL	`"https://docs.example.com"`
`repository`	string	소스 코드 URL	`"https://github.com/user/plugin"`
`license`	string	라이선스 식별자	`"MIT"`, `"Apache-2.0"`
`keywords`	array	발견을 위한 태그	`["deployment", "ci-cd"]`

컴포넌트 경로 필드

필드	타입	설명
`commands`	string\|array	추가 명령어 파일/디렉터리
`agents`	string\|array	추가 에이전트 파일
`skills`	string\|array	추가 스킬 디렉터리
`hooks`	string\|array\|object	훅 설정 경로 또는 인라인 설정
`mcpServers`	string\|array\|object	MCP 설정 경로 또는 인라인 설정
`outputStyles`	string\|array	추가 출력 스타일 파일/디렉터리
`lspServers`	string\|array\|object	코드 인텔리전스를 위한 LSP 설정

환경 변수

{
  "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/ 안이 아닌 플러그인 루트에 있어야 합니다.

파일 위치 레퍼런스

컴포넌트	기본 위치	목적
매니페스트	`.claude-plugin/plugin.json`	플러그인 메타데이터 및 설정 (선택)
명령어	`commands/`	스킬 마크다운 파일
에이전트	`agents/`	서브에이전트 마크다운 파일
스킬	`skills/`	`<name>/SKILL.md` 구조의 스킬
훅	`hooks/hooks.json`	훅 설정
MCP 서버	`.mcp.json`	MCP 서버 정의
LSP 서버	`.lsp.json`	언어 서버 설정
설정	`settings.json`	플러그인 활성화 시 적용되는 기본 설정

CLI 명령어 레퍼런스

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

plugin install

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

claude plugin install <plugin> [options]

옵션:

옵션	설명	기본값
`-s, --scope <scope>`	설치 스코프: `user`, `project`, `local`	`user`
`-h, --help`	도움말 표시

예시:

# 사용자 스코프에 설치 (기본값)
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 서버 초기화

일반적인 문제

문제	원인	해결 방법
플러그인이 로딩되지 않음	잘못된 `plugin.json`	`claude plugin validate`로 JSON 문법 검증
명령어가 나타나지 않음	잘못된 디렉터리 구조	`commands/`가 루트에 있는지 확인
훅이 실행되지 않음	스크립트에 실행 권한 없음	`chmod +x script.sh` 실행
MCP 서버 실패	`${CLAUDE_PLUGIN_ROOT}` 누락	모든 플러그인 경로에 변수 사용
경로 오류	절대 경로 사용	모든 경로는 상대 경로여야 하며 `./`로 시작
LSP `Executable not found in $PATH`	언어 서버 미설치	해당 바이너리 설치 필요

훅 문제 해결

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

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

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

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

버전 관리

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

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

버전 형식: MAJOR.MINOR.PATCH

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

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

다음 단계

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

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

스킬 (Skills)

에이전트 (Agents)

훅 (Hooks)

MCP 서버

LSP 서버

플러그인 설치 스코프

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

전체 스키마

필수 필드

메타데이터 필드

컴포넌트 경로 필드

환경 변수

플러그인 디렉터리 구조

표준 플러그인 레이아웃

파일 위치 레퍼런스

CLI 명령어 레퍼런스

plugin install

plugin uninstall

plugin enable / disable

plugin update

디버깅 및 개발 도구

디버깅 명령어

일반적인 문제

훅 문제 해결

버전 관리

다음 단계

관련 가이드

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

스킬 (Skills)

에이전트 (Agents)

훅 (Hooks)

MCP 서버

LSP 서버

플러그인 설치 스코프

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

전체 스키마

필수 필드

메타데이터 필드

컴포넌트 경로 필드

환경 변수

플러그인 디렉터리 구조

표준 플러그인 레이아웃

파일 위치 레퍼런스

CLI 명령어 레퍼런스

plugin install

plugin uninstall

plugin enable / disable

plugin update

디버깅 및 개발 도구

디버깅 명령어

일반적인 문제

훅 문제 해결

버전 관리

다음 단계

관련 가이드