이 참조는 컴포넌트 스키마, 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"
}
필수 필드
| 필드 | 유형 | 설명 | 예제 |
name | string | 고유 식별자 (kebab-case, 공백 없음) | "deployment-tools" |
메타데이터 필드
| 필드 | 유형 | 설명 | 예제 |
version | string | 의미 있는 버전 | "2.1.0" |
description | string | 플러그인 목적에 대한 간단한 설명 | "배포 자동화 도구" |
author | object | 작성자 정보 | {"name": "Dev Team", "email": "[email protected]"} |
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 | 추가 명령어 파일/디렉토리 | "./custom/cmd.md" 또는 ["./cmd1.md"] |
agents | string|array | 추가 에이전트 파일 | "./custom/agents/" |
hooks | string|object | 훅 구성 경로 또는 인라인 구성 | "./hooks.json" |
mcpServers | string|object | MCP 구성 경로 또는 인라인 구성 | "./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.json | MCP 서버 정의 |
디버깅 및 개발 도구
디버깅 명령어
claude --debug를 사용하여 플러그인 로딩 세부 정보를 확인합니다:
이는 다음을 표시합니다:
- 로드되는 플러그인
- 플러그인 매니페스트의 오류
- 명령어, 에이전트 및 훅 등록
- MCP 서버 초기화
일반적인 문제
| 문제 | 원인 | 해결책 |
| 플러그인이 로드되지 않음 | 잘못된 plugin.json | JSON 구문 검증 |
| 명령어가 나타나지 않음 | 잘못된 디렉토리 구조 | 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) - 플러그인에 대한 구성 옵션