본문으로 건너뛰기

플러그인 개발 가이드

Claude Code 플러그인을 직접 만들어보자.

플러그인 구조​

plugins/my-plugin/
├── .claude-plugin/
│   └── plugin.json      # 필수: 플러그인 메타데이터
├── hooks/
│   └── hooks.json       # 선택: Hook 정의
├── commands/
│   └── my-command.md    # 선택: 슬래시 명령어
├── hooks-handlers/
│   └── handler.sh       # 선택: Hook 핸들러 스크립트
└── README.md            # 권장: 문서

plugin.json​

플러그인 메타데이터를 정의한다.

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My awesome plugin"
}
필드필수설명
name예플러그인 이름 (영문, 하이픈)
version예시맨틱 버전
description예간단한 설명

Hook 추가하기​

hooks.json 작성​

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/on-stop.sh"
      }]
    }]
  }
}

핸들러 스크립트​

#!/bin/bash
# hooks-handlers/on-stop.sh

# 환경변수 사용
echo "Session: $SESSION_ID"
echo "Plugin root: $CLAUDE_PLUGIN_ROOT"

# 원하는 동작 수행
# ...

주의: 스크립트에 실행 권한 필요

chmod +x hooks-handlers/on-stop.sh

슬래시 명령어 추가​

commands/my-command.md​

---
name: mycommand
description: My custom command
---

# My Command

이 명령어는 다음을 수행합니다:

1. 첫 번째 동작
2. 두 번째 동작

## 사용법

\`\`\`
/mycommand [옵션]
\`\`\`

사용자가 /mycommand를 입력하면 이 마크다운이 컨텍스트로 전달된다.

크로스 플랫폼 지원​

OS 감지​

# Windows Native (Git Bash)
if [ "$OS" = "Windows_NT" ]; then
    # Windows 처리

# WSL - Linux보다 먼저 체크!
elif grep -qi microsoft /proc/version 2>/dev/null; then
    # WSL 처리

# macOS
elif [ "$(uname)" = "Darwin" ]; then
    # macOS 처리

# Linux
else
    # Linux 처리
fi

중요: WSL은 uname이 Linux를 반환하므로 반드시 Linux보다 먼저 체크해야 한다.

WSL에서 Windows 호출​

# 환경변수 전달
export WSLENV="MY_VAR:OTHER_VAR"
export MY_VAR="value"

# PowerShell 실행
powershell.exe -File ./script.ps1

# 경로 변환
WIN_PATH=$(wslpath -w "$LINUX_PATH")

의존성 최소화​

# jq가 없어도 동작하게
json_get() {
    if command -v jq &> /dev/null; then
        echo "$1" | jq -r ".$2"
    else
        echo "$1" | grep -oE "\"$2\":[[:space:]]*\"[^\"]*\"" | \
            sed "s/\"$2\":[[:space:]]*\"\(.*\)\"/\1/"
    fi
}

에러 처리​

조용히 실패하기​

# 나쁜 예: 에러 메시지 출력
if ! command -v notify-send &> /dev/null; then
    echo "Error: notify-send not found" >&2
    exit 1
fi

# 좋은 예: 조용히 종료
if ! command -v notify-send &> /dev/null; then
    exit 0
fi

플러그인이 에러를 내면 사용자 경험이 나빠진다. 가능하면 조용히 넘어가자.

세션 독립성​

여러 터미널에서 동시에 사용될 수 있다. SESSION_ID를 활용하자.

# 세션별 데이터 저장
DATA_FILE="$DATA_DIR/data-${SESSION_ID}.txt"

# 세션 종료 시 정리
rm -f "$DATA_DIR/*-${SESSION_ID}.*"

테스트​

로컬 테스트​

  1. 플러그인 디렉토리 생성
  2. Claude Code 설정에 경로 추가
  3. Claude Code 재시작
  4. 동작 확인

플랫폼별 테스트​

플랫폼테스트 방법
macOS로컬
LinuxDocker 또는 VM
Windows실제 Windows 또는 VM
WSLWSL2

배포​

GitHub 릴리즈​

  1. 버전 태그 생성
  2. 릴리즈 노트 작성
  3. install.sh 스크립트 제공

공식 플러그인 기여​

anthropics/claude-code에 PR을 보낼 수 있다.

  1. plugins/ 디렉토리에 플러그인 추가
  2. 기존 플러그인 스타일 따르기
  3. 테스트 매트릭스 포함
  4. PR 제출

참고 자료​