플러그인 직접 만들기
기존 .claude/ 하위 설정을 팀원들과 공유하거나 여러 프로젝트에 적용하고 싶다면 플러그인으로 패키징합니다. 이 페이지에서는 빈 디렉토리에서 첫 플러그인을 만드는 과정과 기존 설정을 변환하는 방법을 다룹니다.
첫 번째 플러그인 만들기
가장 작은 예시입니다 — 스킬 하나짜리 플러그인.
1. 디렉토리와 매니페스트 생성
mkdir -p my-first-plugin/.claude-plugin
my-first-plugin/.claude-plugin/plugin.json 파일을 만듭니다:
{
"name": "my-first-plugin",
"description": "기본 예시 플러그인",
"version": "1.0.0",
"author": {
"name": "팀 이름"
}
}
| 필드 | 필수 | 설명 |
|---|---|---|
name | O | 고유 식별자. 스킬 네임스페이스로도 사용 |
description | - | /plugin 화면에 표시되는 설명 |
version | - | 이 값이 있으면 마켓플레이스 업데이트 시 해당 버전으로 고정 |
author.name | - | 저자 이름 (표시용) |
2. 스킬 추가
mkdir -p my-first-plugin/skills/hello
my-first-plugin/skills/hello/SKILL.md:
---
name: hello
description: 사용자를 반갑게 맞이합니다
disable-model-invocation: true
---
사용자를 반갑게 맞이하고 무엇을 도와드릴지 물어보세요.
disable-model-invocation: true가 있으면 Claude가 자동으로 이 스킬을 호출하지 않고, 사용자가 직접 트리거해야 합니다. 스킬 이름은 플러그인 이름 + :스킬 이름 형식입니다. 예: /my-first-plugin:hello
3. 유효성 검사
claude plugin validate ./my-first-plugin
결과 메시지:
Validation passed→ 정상Validation passed with warnings→ 로드는 되지만--strict모드에서는 실패Validation failed→ 수정 필요
4. 테스트 실행
마켓플레이스 없이 단일 세션에 로드합니다:
claude --plugin-dir ./my-first-plugin
세션 안에서:
/my-first-plugin:hello
--plugin-dir로 로드한 플러그인은 해당 세션에만 적용되며 설정 파일에 기록되지 않습니다.
플러그인 레이아웃
my-plugin/
├── .claude-plugin/
│ └── plugin.json # 매니페스트
├── skills/ # 스킬 (SKILL.md 파일)
├── commands/ # 레거시 커맨드 (.md 파일, 신규는 skills/ 권장)
├── agents/ # 서브에이전트 (.md 파일)
├── hooks/
│ └── hooks.json # Hook 핸들러
├── .mcp.json # MCP 서버 설정
└── .lsp.json # LSP 서버 설정
컴포넌트 패키징
Agents
agents/ 하위에 마크다운 파일을 넣습니다:
---
name: security-reviewer
description: 보안 감사 전문 에이전트
tools: Read, Grep, Glob
model: sonnet
---
OWASP Top 10 기준으로 보안 취약점을 검사하세요.
에이전트 이름도 플러그인 네임스페이스를 가집니다: my-plugin:security-reviewer
Hooks
hooks/hooks.json에 이벤트 핸들러를 정의합니다:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix"
}
]
}
]
}
}
MCP 서버
플러그인 루트에 .mcp.json 파일을 만들거나 plugin.json에 인라인으로 정의합니다:
{
"mcpServers": {
"deploy-api": {
"command": "node",
"args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
}
}
}
${CLAUDE_PLUGIN_ROOT}는 플러그인이 설치된 절대 경로로 자동 치환됩니다.
LSP 서버 (코드 인텔리전스)
언어 서버를 번들로 제공합니다:
{
"lspServers": {
"go": {
"command": "gopls",
"args": ["serve"],
"extensionToLanguage": { ".go": "go" }
}
}
}
사용자 머신에 해당 언어 서버 바이너리(gopls 등)가 설치되어 있어야 합니다.
매니페스트 주요 필드
plugin.json에서 사용 가능한 주요 필드입니다.
| 필드 | 설명 |
|---|---|
defaultEnabled | true(기본)이면 설치 시 즉시 활성화 |
dependencies | 이 플러그인이 의존하는 다른 플러그인 목록 |
userConfig | 설치 시 사용자에게 입력을 요청할 설정 값 |
skills | 기본 skills/ 외에 추가로 스캔할 경로 |
commands | 기본 commands/를 대체할 경로 또는 인라인 정의 |
hooks | hooks/hooks.json 외 추가 Hook 설정 |
사용자 설정 (userConfig)
플러그인 설치 시 사용자에게 값을 요청할 수 있습니다:
{
"userConfig": {
"api_token": {
"type": "string",
"title": "API 토큰",
"description": "배포 API 인증 토큰",
"sensitive": true
}
}
}
sensitive: true이면 입력을 마스킹하고 시스템 보안 저장소에 저장합니다. 스킬·에이전트 파일 안에서는 ${user_config.api_token}으로 참조합니다.
Eval로 플러그인 동작 검증 (v2.1.269+)
claude plugin eval로 플러그인의 동작을 자동 검증합니다. 테스트 케이스별로 실제 모델을 실행하고 결과를 채점합니다.
# Eval 케이스 대화형으로 초기화
claude plugin eval init
# 전체 Eval 실행 (기본 3회 반복)
claude plugin eval .
# CI에서 점수 기준 미달 시 비정상 종료
claude plugin eval . --threshold 0.8 --ci
Eval은 실제 모델 호출을 발생시킵니다. 실행 전 -n 플래그로 예상 비용을 먼저 확인하세요.
기존 .claude/ 설정을 플러그인으로 변환
이미 프로젝트 레벨 .claude/에 Skills, Hooks, MCP 설정이 있다면 그대로 플러그인으로 옮길 수 있습니다.
# 1. 플러그인 구조 생성
mkdir -p my-plugin/.claude-plugin
# 2. 컴포넌트 복사
cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/
cp -r .claude/skills my-plugin/
hooks는 설정 파일의 hooks 객체를 my-plugin/hooks/hooks.json으로 이동합니다.
변환 후 테스트:
claude --plugin-dir ./my-plugin
플러그인의 스킬은 네임스페이스가 붙으므로 /deploy와 /my-plugin:deploy 두 이름 모두 동작합니다. 검증 완료 후 .claude/의 원본 파일을 삭제하세요.
플러그인 초기화 스캐폴드
# ~/.claude/skills/에 플러그인 구조 자동 생성 (v2.1.157+)
claude plugin init my-tool
# 스킬 구조도 함께 생성
claude plugin init my-tool --with skills
~/.claude/skills/ 하위의 플러그인은 별도 설치 없이 모든 세션에서 자동 로드됩니다.
다음 단계
이 챕터를 완료하셨나요?
학습 진도를 체크하여 나의 로드맵 달성률을 높여보세요.