이 참조서는 컴포넌트 스키마, 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"
}
필수 필드
필드 | 타입 | 설명 | 예시 |
---|
name | string | 고유 식별자 (kebab-case, 공백 없음) | "deployment-tools" |
메타데이터 필드
필드 | 타입 | 설명 | 예시 |
---|
version | string | 시맨틱 버전 | "2.1.0" |
description | string | 플러그인 목적에 대한 간단한 설명 | "Deployment automation tools" |
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
├── 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.json | MCP 서버 정의 |
디버깅 및 개발 도구
디버깅 명령어
claude --debug
를 사용하여 플러그인 로딩 세부사항을 확인하세요:
이는 다음을 보여줍니다:
- 로드되고 있는 플러그인
- 플러그인 매니페스트의 오류
- 명령어, 에이전트, 훅 등록
- MCP 서버 초기화
일반적인 문제
문제 | 원인 | 해결책 |
---|
플러그인이 로드되지 않음 | 잘못된 plugin.json | JSON 구문 검증 |
명령어가 나타나지 않음 | 잘못된 디렉토리 구조 | .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) - 플러그인 구성 옵션