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

플러그인 컴포넌트 참조

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

명령어

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

에이전트

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

# 에이전트 이름

에이전트의 역할, 전문성 및 Claude가 이를 호출해야 할 시기에 대한 자세한 설명.

## 기능
- 에이전트가 뛰어난 특정 작업
- 또 다른 특화된 기능
- 이 에이전트를 다른 에이전트와 비교할 때 사용 시기

## 컨텍스트 및 예제
이 에이전트를 사용해야 할 때와 어떤 종류의 문제를 해결하는지에 대한 예제를 제공합니다.
통합 포인트:
  • 에이전트는 /agents 인터페이스에 나타남
  • Claude는 작업 컨텍스트를 기반으로 에이전트를 자동으로 호출할 수 있음
  • 에이전트는 사용자가 수동으로 호출할 수 있음
  • 플러그인 에이전트는 기본 제공 Claude 에이전트와 함께 작동

스킬

플러그인은 Claude의 기능을 확장하는 에이전트 스킬을 제공할 수 있습니다. 스킬은 모델이 호출하며, Claude는 작업 컨텍스트를 기반으로 자율적으로 사용 시기를 결정합니다. 위치: 플러그인 루트의 skills/ 디렉토리 파일 형식: 프론트매터가 있는 SKILL.md 파일을 포함하는 디렉토리 스킬 구조:
skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (선택사항)
│   └── scripts/ (선택사항)
└── code-reviewer/
    └── SKILL.md
통합 동작:
  • 플러그인 스킬은 플러그인이 설치될 때 자동으로 발견됨
  • Claude는 일치하는 작업 컨텍스트를 기반으로 스킬을 자율적으로 호출함
  • 스킬은 SKILL.md와 함께 지원 파일을 포함할 수 있음
SKILL.md 형식 및 완전한 스킬 작성 지침은 다음을 참조하세요:

플러그인은 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를 외부 도구 및 서비스와 연결하기 위해 모델 컨텍스트 프로토콜(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": "간단한 플러그인 설명",
  "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플러그인 목적에 대한 간단한 설명"배포 자동화 도구"
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
├── skills/                   # 에이전트 스킬
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── 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/, skills/, hooks/)는 .claude-plugin/ 내부가 아닌 플러그인 루트에 있어야 합니다.

파일 위치 참조

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

디버깅 및 개발 도구

디버깅 명령어

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

일반적인 문제

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

배포 및 버전 관리 참조

버전 관리

플러그인 릴리스에 대해 의미 있는 버전 관리를 따릅니다:

## 참고 항목

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