Plugin Authoring Guide¶

이 가이드를 읽고 나면 Bonie 플러그인을 새로 만들고, skill/agent/hook을 구성하고, marketplace에 등록할 수 있다.

What you'll learn¶

플러그인 디렉토리 구조와 plugin.json 작성
Skill SKILL.md description/paths 설계
Agent frontmatter와 system prompt 작성
Hook hooks.json과 스크립트 작성
로컬 테스트 및 marketplace 등록

Prerequisites¶

Contributing Guide — 개발 환경 설정 완료
Component Model — 컴포넌트 역할 이해

Steps¶

Step 1. 플러그인 디렉토리 생성¶

1. 디렉토리 생성¶

# 카테고리에 맞는 위치에 생성
mkdir -p plugins/<category>/<name>/.claude-plugin

2. plugin.json 작성¶

{
  "name": "<name>",
  "description": "<간결한 설명>",
  "version": "0.1.0",
  "author": {
    "name": "pabloism0x",
    "email": "pablo@luxtra.dev"
  },
  "homepage": "https://github.com/luxtradev/bonie",
  "repository": "https://github.com/luxtradev/bonie",
  "keywords": ["<keyword1>", "<keyword2>"]
}

3. 컴포넌트 추가¶

필요한 컴포넌트 디렉토리 생성:

mkdir -p plugins/<category>/<name>/skills/<skill-name>
mkdir -p plugins/<category>/<name>/agents
mkdir -p plugins/<category>/<name>/hooks

Skill 작성¶

기본 구조¶

skills/<skill-name>/
├── SKILL.md               # 필수 — 핵심 가이드
├── reference.md           # 선택 — 상세 레퍼런스
├── examples/              # 선택 — 예시 파일
└── scripts/               # 선택 — 실행 스크립트

SKILL.md 작성 가이드¶

description 작성 규칙¶

핵심 키워드를 front-load: description + when_to_use 합계 1,536자 제한
구체적인 사용 시점 명시: "...할 때 사용"
Claude가 매칭할 수 있는 자연어 표현 포함

# Good
description: |
  TypeScript 에러 핸들링 패턴. try-catch, Result type, 
  Error boundary 구현 시 사용. 에러 처리, 예외 처리 코드 작성 시 자동 적용.

# Bad
description: TypeScript errors  # 너무 짧고 모호

paths 설정 규칙¶

# 특정 확장자만
paths:
  - "**/*.ts"
  - "**/*.tsx"

# 특정 디렉토리만
paths:
  - "src/api/**/*.ts"

# 여러 패턴 조합
paths:
  - "**/*.{ts,tsx}"
  - "**/tsconfig.json"

본문 작성 규칙¶

500줄 이하 유지 (초과시 supporting file 분리)
실제 동작하는 코드 예시 포함
!backtick` 으로 dynamic context 주입 가능
$ARGUMENTS 로 사용자 입력 참조 가능

Invocation 모드 선택¶

상황	설정
Claude가 자동으로 로드	(기본값)
Claude만 호출 가능	`user-invocable: false`
사용자만 호출 가능	`disable-model-invocation: true`

Agent 작성¶

기본 구조¶

agents/<agent-name>.md 파일 하나로 정의.

Frontmatter 필수 필드¶

---
name: agent-name          # kebab-case, 필수
description: |            # 자동 위임 트리거, 필수
  이 agent의 전문 분야 설명.
  Claude가 자동 위임할 수 있도록 구체적으로.
model: sonnet             # sonnet, opus, haiku, inherit
---

여기에 system prompt 작성.

description 작성 규칙¶

자동 위임을 위해 구체적인 사용 시점 명시
Use proactively.를 포함하면 Claude가 적극적으로 위임
도구 제한이 필요하면 tools 또는 disallowedTools 사용

Plugin Agent 제약¶

플러그인 agent에서는 다음을 사용할 수 없음: - hooks — 보안상 제한 - mcpServers — 보안상 제한 - permissionMode — 보안상 제한

이 기능이 필요하면 프로젝트 .claude/agents/에 복사하여 사용.

Hook 작성¶

hooks.json 기본 구조¶

{
  "hooks": {
    "<EventName>": [
      {
        "matcher": "<pattern>",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/<script>.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

스크립트 작성 규칙¶

shebang 필수: #!/bin/bash 또는 #!/usr/bin/env bash
실행 권한 필수: chmod +x scripts/*.sh
stdin으로 JSON 입력 수신: jq 사용 권장
exit code 준수: 0=성공, 2=블로킹, 기타=경고

#!/bin/bash
# scripts/validate.sh

INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if echo "$COMMAND" | grep -q 'rm -rf /'; then
  echo "위험한 명령 차단" >&2
  exit 2
fi

exit 0

경로 참조¶

항상 ${CLAUDE_PLUGIN_ROOT}를 사용:

{
  "command": "${CLAUDE_PLUGIN_ROOT}/scripts/handler.sh"
}

테스트¶

로컬 테스트¶

# 플러그인 단독 로드
claude --plugin-dir ./plugins/<category>/<name>

# 전체 marketplace 로드
claude --plugin-dir .

테스트 항목¶

Skill 테스트:
자동 매칭되는지 확인 (해당 파일 작업 시)
description 기반 호출 확인
supporting file 참조 동작 확인
Agent 테스트:
자동 위임 동작 확인
system prompt 반영 확인
도구 제한 확인
Hook 테스트:
이벤트 트리거 확인
exit code 처리 확인
timeout 동작 확인

디버깅¶

claude --debug

marketplace 등록¶

1. marketplace.json에 entry 추가¶

{
  "name": "<name>",
  "source": "./plugins/<category>/<name>",
  "description": "<설명>",
  "category": "<category>",
  "tags": ["<tag1>", "<tag2>"]
}

2. 버전 업데이트¶

plugin.json 또는 marketplace.json entry에서 version 업데이트.

체크리스트¶

신규 플러그인¶

.claude-plugin/plugin.json 작성
최소 1개 skill 또는 agent 포함
claude --plugin-dir으로 로컬 테스트
/reload-plugins로 변경 반영 확인
marketplace.json에 entry 추가
docs/design/.md에 문서화

Skill 추가¶

description에 핵심 키워드 front-load
paths glob 설정 (auto-loaded skill인 경우)
500줄 이하 유지
코드 예시 포함 및 동작 확인

Agent 추가¶

name, description 필수 필드 작성
model 선택 (비용/성능 고려)
plugin agent 제약사항 확인

Hook 추가¶

스크립트 실행 권한 설정 (chmod +x)
exit code 처리 올바른지 확인
${CLAUDE_PLUGIN_ROOT} 경로 사용

Plugin Authoring Guide¶

What you'll learn¶

Prerequisites¶

Steps¶

Step 1. 플러그인 디렉토리 생성¶

1. 디렉토리 생성¶

2. plugin.json 작성¶

3. 컴포넌트 추가¶

Skill 작성¶

기본 구조¶

SKILL.md 작성 가이드¶

description 작성 규칙¶

paths 설정 규칙¶

본문 작성 규칙¶

Invocation 모드 선택¶

Agent 작성¶

기본 구조¶

Frontmatter 필수 필드¶

description 작성 규칙¶

Plugin Agent 제약¶

Hook 작성¶

hooks.json 기본 구조¶

스크립트 작성 규칙¶

경로 참조¶

테스트¶

로컬 테스트¶

테스트 항목¶

디버깅¶

marketplace 등록¶

1. marketplace.json에 entry 추가¶

2. 버전 업데이트¶

체크리스트¶

신규 플러그인¶

Skill 추가¶

Agent 추가¶

Hook 추가¶

관련 문서¶