실습 튜토리얼과 실용적인 사용법은 플러그인을 참조하세요. 팀과 커뮤니티 전반의 플러그인 관리는 플러그인 마켓플레이스를 참조하세요.
이 참조서는 컴포넌트 스키마, CLI 명령어, 개발 도구를 포함한 Claude Code 플러그인 시스템의 완전한 기술 사양을 제공합니다.

플러그인 컴포넌트 참조

이 섹션은 플러그인이 제공할 수 있는 네 가지 유형의 컴포넌트를 문서화합니다.

명령어

플러그인은 Claude Code의 명령어 시스템과 원활하게 통합되는 사용자 정의 슬래시 명령어를 추가합니다. 위치: 플러그인 루트의 commands/ 디렉토리 파일 형식: frontmatter가 있는 Markdown 파일 플러그인 명령어 구조, 호출 패턴, 기능에 대한 완전한 세부사항은 플러그인 명령어를 참조하세요.

에이전트

플러그인은 Claude가 적절할 때 자동으로 호출할 수 있는 특정 작업을 위한 전문 서브에이전트를 제공할 수 있습니다. 위치: 플러그인 루트의 agents/ 디렉토리 파일 형식: 에이전트 기능을 설명하는 Markdown 파일 에이전트 구조:
---
description: 이 에이전트가 전문으로 하는 것
capabilities: ["task1", "task2", "task3"]
---

# 에이전트 이름

에이전트의 역할, 전문성, Claude가 언제 이를 호출해야 하는지에 대한 자세한 설명.

## 기능
- 에이전트가 뛰어난 특정 작업
- 또 다른 전문 기능
- 다른 에이전트 대신 이 에이전트를 사용해야 하는 경우

## 컨텍스트 및 예시
이 에이전트를 언제 사용해야 하고 어떤 종류의 문제를 해결하는지에 대한 예시를 제공합니다.
통합 지점:
  • 에이전트는 /agents 인터페이스에 나타납니다
  • Claude는 작업 컨텍스트에 따라 에이전트를 자동으로 호출할 수 있습니다
  • 에이전트는 사용자가 수동으로 호출할 수 있습니다
  • 플러그인 에이전트는 내장된 Claude 에이전트와 함께 작동합니다

플러그인은 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가 도구를 사용한 후
  • UserPromptSubmit: 사용자가 프롬프트를 제출할 때
  • Notification: Claude Code가 알림을 보낼 때
  • Stop: Claude가 중지를 시도할 때
  • SubagentStop: 서브에이전트가 중지를 시도할 때
  • SessionStart: 세션 시작 시
  • SessionEnd: 세션 종료 시
  • PreCompact: 대화 기록이 압축되기 전
훅 유형:
  • command: 셸 명령어나 스크립트 실행
  • validation: 파일 내용이나 프로젝트 상태 검증
  • notification: 알림이나 상태 업데이트 전송

MCP 서버

플러그인은 Claude Code를 외부 도구 및 서비스와 연결하기 위해 Model Context Protocol (MCP) 서버를 번들로 제공할 수 있습니다. 위치: 플러그인 루트의 .mcp.json 또는 plugin.json에 인라인 형식: 표준 MCP 서버 구성 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"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}
통합 동작:
  • 플러그인 MCP 서버는 플러그인이 활성화될 때 자동으로 시작됩니다
  • 서버는 Claude의 툴킷에서 표준 MCP 도구로 나타납니다
  • 서버 기능은 Claude의 기존 도구와 원활하게 통합됩니다
  • 플러그인 서버는 사용자 MCP 서버와 독립적으로 구성할 수 있습니다

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

plugin.json 파일은 플러그인의 메타데이터와 구성을 정의합니다. 이 섹션은 지원되는 모든 필드와 옵션을 문서화합니다.

완전한 스키마

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "[email protected]",
    "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/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json"
}

필수 필드

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

메타데이터 필드

필드타입설명예시
versionstring시맨틱 버전"2.1.0"
descriptionstring플러그인 목적에 대한 간단한 설명"Deployment automation tools"
authorobject작성자 정보{"name": "Dev Team", "email": "[email protected]"}
homepagestring문서 URL"https://docs.example.com"
repositorystring소스 코드 URL"https://github.com/user/plugin"
licensestring라이선스 식별자"MIT", "Apache-2.0"
keywordsarray검색 태그["deployment", "ci-cd"]

컴포넌트 경로 필드

필드타입설명예시
commandsstring|array추가 명령어 파일/디렉토리"./custom/cmd.md" 또는 ["./cmd1.md"]
agentsstring|array추가 에이전트 파일"./custom/agents/"
hooksstring|object훅 구성 경로 또는 인라인 구성"./hooks.json"
mcpServersstring|objectMCP 구성 경로 또는 인라인 구성"./mcp.json"

경로 동작 규칙

중요: 사용자 정의 경로는 기본 디렉토리를 보완하며 대체하지 않습니다.
  • commands/가 존재하면 사용자 정의 명령어 경로에 추가로 로드됩니다
  • 모든 경로는 플러그인 루트에 상대적이어야 하며 ./로 시작해야 합니다
  • 사용자 정의 경로의 명령어는 동일한 명명 및 네임스페이스 규칙을 사용합니다
  • 유연성을 위해 여러 경로를 배열로 지정할 수 있습니다
경로 예시:
{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

환경 변수

${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
│   └── compliance-checker.md
├── hooks/                    # 훅 구성
│   ├── hooks.json           # 메인 훅 구성
│   └── security-hooks.json  # 추가 훅
├── .mcp.json                # MCP 서버 정의
├── scripts/                 # 훅 및 유틸리티 스크립트
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # 라이선스 파일
└── CHANGELOG.md             # 버전 히스토리
.claude-plugin/ 디렉토리에는 plugin.json 파일이 포함됩니다. 다른 모든 디렉토리(commands/, agents/, hooks/)는 .claude-plugin/ 내부가 아닌 플러그인 루트에 있어야 합니다.

파일 위치 참조

컴포넌트기본 위치목적
매니페스트.claude-plugin/plugin.json필수 메타데이터 파일
명령어commands/슬래시 명령어 마크다운 파일
에이전트agents/서브에이전트 마크다운 파일
hooks/hooks.json훅 구성
MCP 서버.mcp.jsonMCP 서버 정의

디버깅 및 개발 도구

디버깅 명령어

claude --debug를 사용하여 플러그인 로딩 세부사항을 확인하세요:
claude --debug
이는 다음을 보여줍니다:
  • 로드되고 있는 플러그인
  • 플러그인 매니페스트의 오류
  • 명령어, 에이전트, 훅 등록
  • MCP 서버 초기화

일반적인 문제

문제원인해결책
플러그인이 로드되지 않음잘못된 plugin.jsonJSON 구문 검증
명령어가 나타나지 않음잘못된 디렉토리 구조.claude-plugin/이 아닌 루트에 commands/ 확인
훅이 실행되지 않음스크립트가 실행 가능하지 않음chmod +x script.sh 실행
MCP 서버 실패${CLAUDE_PLUGIN_ROOT} 누락모든 플러그인 경로에 변수 사용
경로 오류절대 경로 사용모든 경로는 상대적이어야 하며 ./로 시작해야 함

배포 및 버전 관리 참조

버전 관리

플러그인 릴리스에는 시맨틱 버전 관리를 따르세요:

## 참고 항목

- [플러그인](/ko/docs/claude-code/plugins) - 튜토리얼 및 실용적인 사용법
- [플러그인 마켓플레이스](/ko/docs/claude-code/plugin-marketplaces) - 마켓플레이스 생성 및 관리
- [슬래시 명령어](/ko/docs/claude-code/slash-commands) - 명령어 개발 세부사항
- [서브에이전트](/ko/docs/claude-code/sub-agents) - 에이전트 구성 및 기능
- [](/ko/docs/claude-code/hooks) - 이벤트 처리 및 자동화
- [MCP](/ko/docs/claude-code/mcp) - 외부 도구 통합
- [설정](/ko/docs/claude-code/settings) - 플러그인 구성 옵션